PatcherGUI - a tool to install and maintain modifications for XCOM:EU and EW

============================================================================

The information below is intended for mod-users mostly. If you're a mod developer,
please, consult "PatchUPK_Readme.txt" file, included in the program distribution.
It contains all the information needed to create mod files for use with
PatchUPK/PatcherGUI.

Program features:
=================
- Does not require installation: unpack and use.
- Has graphical interface.
- Can install mods for both XCOM:EU and EW.
- Maintains separate install logs for every game path.
- Writes backup files for every change it makes.
- Automatically reverts to latest backup if something goes wrong with
install/uninstall process.
- Automatically creates uninstall files.
- Automatically unpacks game packages.
- Has an option to disable hash checks for XCOM:EU (Windows only).
- Has an option to enable direct ini loading (Windows only).
- Has an option to disable phoning home (ini re-downloading) (Windows only).
- Can perform batch install and uninstall operations.
- Cross-platform: works with Windows, Linux and Mac XCOM versions
(under Linux and Mac program should be built from source code).

Quick overview:
===============
XCOM doesn't have official modding support, so we have a bit of a problem here.
Actually, more than a bit.

To make some significant changes to the game, we need to alter its packed resources
("packages"). And those are compressed, "cooked" and hashed (for EU). Fortunately,
the PC version can read decompressed packages and hash check can be disabled. But
the problem of packages being "cooked" stays and raises a lot of questions about
inter-patch and inter-mod compatibility.

First, each time Firaxis releases a new patch, those packages get "re-cooked" and
all the prior mods, written for each specific patch, stop working.

Second, we can't simply distribute altered packages, as that would make it

impossible to combine several mods into one game. So, to allow installation of
multiple different mods, we have to distribute changed parts instead of full
packages, which, again, raises inter-patch compatibility questions.

Trying to solve the problem of cooked packages, the XCOM modding community
eventually came to the idea of distributing not a package itself, but rather a set
of instructions on how to modify local user's packages - i.e. distributing a mod's
source code, which can be made compatible to all the game versions.

This approach is a bit less user-friendly than a final GUI tool with sliders and
check-boxes, but modularity and flexibility allows for easier mods creation,
distribution and maintaining: anyone can contribute and the next patch will not
ruin the majority of the hard work of prior mods!

Linux and Mac differences:

==========================
There are no pre-built PatcherGUI binaries for Linux and Mac, so you will have to
build them yourself. Both GUI and core utilities are open-source and are available
via GitHub:
https://github.com/wghost/PatcherGUI
https://github.com/wghost/UPKUtils
Both projects contain README.md file with description and detailed build
instructions.

Both Linux and Mac releases do not perform upk hash check, so disabling it is not
required.

You can disable phoning home (automatic ini re-downloading) by editing hosts file.
For Linux it is usually located at /etc/hosts. Open it (administrator access is
required) and add two following lines inside:
127.0.0.1 prod.xcom.firaxis.com
127.0.0.1 prod.xcom-ew.firaxis.com

Both Linux and Mac versions prioritize XCom*.ini files over default*.ini files.
Thus, if some mod instructs you to edit defaultgamecore.ini, for example, you need
to locate and edit XComGameCore.ini file instead.

Under Linux XCom*.ini files for EU are stored in

~/.local/share/feral-interactive/XCOM/WritableFiles/XComGameCore.ini
And for EW they are stored in
~/.local/share/feral-interactive/XCOM/XEW/WritableFiles/XComGameCore.ini

Under Mac search for XCom*.ini files under

~/Library/Application Support/Feral Interactive/XCOM Enemy Unknown/MacInit
and
~/Library/Application Support/Feral Interactive/XCOM Enemy Unknown/XEW/MacInit

Preparing your game for handling mods:

======================================
First mandatory thing you should do (Windows only): make sure your XCOM game is
installed outside the "C:\Program Files" (or "C:\Program Files (x86)" on 64-bit
Systems) folder. The reason for this is that Windows (since Vista) considers the
"Program Files" folder trees to be restricted areas and will revert all the changes
any mod makes to a saved "shadow" copy. It's explained better in the "Installing
Games on Windows Vista+" wiki article:
http://wiki.tesnexus.com/index.php/Installing_Games_on_Windows_Vista%2B

Second thing you should do is to switch off automatic updates for XCOM in Steam.
Right-click XCOM in the Steam applications list and search it's properties for
"updates" options. Note, that turning auto-updates off will not prevent Steam from
downloading a newly released patch, but it will prevent silent updates running in
the background and breaking your game.

Third thing to do is to stop the game from "phoning home". Each time you launch
XCOM it "calls" to Firaxis' servers and downloads some "ini" files to prevent
multiplayer cheating. If you're planning to make modifications to game "ini" files
(like the "Arc Thrower in Pistol Slot" tweak), you need to disable "phoning home"
feature. You can now do it with PatcherGUI using "Tools -> Disable Phoning Home"
option (Windows only, for Linux and Mac see "Linux and Mac differences" section
above).

For more information on how to install mods for XCOM, please, consult these wiki
articles:
http://wiki.tesnexus.com/index.php/Basic_Guide_to_installing_mods
http://wiki.tesnexus.com/index.php/Steam_and_mods

Making a first step:

====================
Download the latest PatcherGUI distribution and unpack it to any folder without
locale-specific (i.e. "unicode") symbols in the path. "C:\" or "C:\XCOM-Mods-and-
Utils" will do nicely under Windows. Under Linux and Mac you should build the
program (see "Linux and Mac differences" section above) and put it under your home
directory.

Open the folder where you unpacked PatcherGUI and run "PatcherGUI" executable
("PatcherGUI.exe" under Windows). You can create a desktop link to the executable
by the usual OS means if you want.

The very first line of the tool, which has a "Path to XCOM:EU or XCOM:EW" tool-tip
(which appears when you hover your mouse over it for a few seconds), should point
to your actual XCOM install folder. Press the corresponding "Browse" button (one
with a "Set path to XCOM:EU or XCOM:EW" tool-tip) and select the "Path-to-
SteamLibrary\SteamApps\common\XCom-Enemy-Unknown" folder if you're planning to
install EU mods; and the "Path-to-SteamLibrary\SteamApps\common\XCom-Enemy-
Unknown\XEW" folder if you're planning to install mods for EW.

("Path-to-SteamLibrary" is a placeholder for the actual path to your SteamLibrary

folder location, for example, "D:\SteamLibrary" under Windows.)

Now you're ready to install mods.

XCOM: Enemy Unknown — disabling hash check (Windows only):

==========================================================

If you're planning to install EU mods under Windows, you need to disable hash
checks, otherwise the game won't load your modified packages. To do so, click
"Tools -> Disable hash check" in PatcherGUI main menu. If game path is correct (see
"Making a first step" section above), program will patch XComGame.exe and you'll
see "Success!" message. If you'll see an error message, read this file again and
make sure you've followed all the instructions carefully.

You need to do this only once.

Note: "Disable hash check" option disables hash check for the four most commonly
used packages: core.upk, engine.upk, xcomgame.upk and xcomstrategygame.upk. If a
specific mod uses some other package, you need to disable it separately via
"Advanced -> Disable hash..." option in main menu.

Installing a mod:
=================
Download a mod's archive and unpack it. It's not required, but recommended to
unpack all the mods into a "PatcherGUI\Mods" folder. Each mod file is a plain text
file, which usually contains human-readable description at the top followed by a
bunch of utility-specific commands.

Run PatcherGUI and use a second "Browse" button (one with "Open mod file" tool-tip)
to browse for a file you just unpacked. PatcherGUI will load it and display its
contents in it's simple text viewer/editor.

If you haven't yet set a path to your XCOM:EU or XCOM:EW folder, do it now (see
"Making a first step" section above).

If the mod doesn't have any user-editable variables, press the "Apply" button to
install it. If the mod provides some configurable options, consult the mod's
"Readme" file on how to set it up properly.

If installation was successful, close PatcherGUI and run the game. If an error
message appears, read this file and the mod instructions carefully and try to
repeat the installation. If it still fails, report a bug (see "Reporting bugs and
asking questions" section later in this file).

If you're installing a mod for EU under Windows, you need to disable hash check
(see "XCOM: Enemy Unknown — disabling hash check" section above).

Uninstalling a mod:
===================
PatcherGUI automatically creates "uninstall files" for all the installed mods. You
can find the uninstall file in the same folder where the mod file is located. Each
uninstall file is automatically named
"name_of_the_original_mod_file.uninstall.txt".

Multiple subsequent installations of the same mod will create multiple subsequent
uninstall files: "name_of_the_original_mod_file.uninstall1.txt",
"name_of_the_original_mod_file.uninstall2.txt",
and so on. The very first uninstall file
("name_of_the_original_mod_file.uninstall.txt") contains vanilla code, and the
others - previous modded code. So, to completely uninstall a mod use the very first
uninstall file and to undo only the last changes to that mod use the most recent
uninstall file.

Using a log:
============
PatcherGUI writes an install log for each of your game folders (you'll have
separate install logs for EU and EW). You may access that log by pressing the "Show
log" button.

The log window contains info on current install directories and a list of all
installed mods for the current path (names of the corresponding mod files). For
each of the listed mods you can load it's installer or uninstaller file into
PatcherGUI by pressing the corresponding "Load Installer" or "Load Uninstaller"
button.

When you install a mod, it's automatically added to the install list. When you
uninstall a mod, it's automatically removed from the list.

Cleaning things up:

===================
If you want to revert to the vanilla game, go to Steam, right-click XCOM and search
for "verify game cache" under "game properties". Steam will check all the game
files and re-download "broken" (i.e. modded) ones.

To clean up PatcherGUI you need to manually cleanup the "PatcherGUI\Backup" and

"PatcherGUI\Logs" folder. The "Backup" folder contains all the modified files
backups and the "Logs" folder contains install logs for all the game folders.
Enabling ini loading (Windows only):
====================================

PatcherGUI can alter game executable to enable direct loading of

DefaultGameCore.ini and DefaultLoadouts.ini. Click "Tools -> Enable ini loading" in
program main menu. If game path is correct (see "Making a first step" section
above), program will patch current game executable and you'll see "Success!"
message. If you'll see an error message, read this file again and make sure you've
followed all the instructions carefully.

You need to do it once for each install path (EU and EW).

Disabling phoning home (Windows only):

======================================

PatcherGUI can disable phoning home (to stop ini files re-downloading and re-
writing) by altering game executable. Click "Tools -> Disable phoning home" in
program main menu. If game path is correct (see "Making a first step" section
above), program will patch current game executable and you'll see "Success!"
message. If you'll see an error message, read this file again and make sure you've
followed all the instructions carefully.

You need to do it once for each install path (EU and EW).

Using batch install/uninstall functionality:

============================================

PatcherGUI batch files have *.pgui extension and contain a simple list of modfiles
to apply, separated by end of line character. Example (Windows):
L:\Path\To\ModFile1.txt
L:\Path\To\ModFile2.txt

You can generate a batch file using an install log:

1. Click "Show log" button to open current log file.
2. Click "Batch installer" to generate batch install file, containing all the
currently installed mods. A save file dialog will pop up, allowing you to save
batch file and load it into PatcherGUI.
3. Click "Batch uninstaller" to generate batch uninstall file, containing uninstall
file references for all the currently installed mods in reverse order. A save file
dialog will pop up, allowing you to save batch file and load it into PatcherGUI.
4. Click "Apply" button to apply all the mods, listed in batch file. Note, that for
long lists this operation may take some time.

You can edit batch file with PatcherGUI or text editor (like Notepad under Windows)
and create your own batch files.

Reporting bugs and asking questions:

====================================
For Nexus mods you can report bugs and ask questions in the mod-specific topic
which can be accessed via the "POSTS" link on the Nexus Download page.

If you want to report a bug or ask a question about the UPKUtils utility itself,
use the UPKUtils Nexus forum topic:
http://forums.nexusmods.com/index.php?showtopic=1253992

Click "Tools -> Show debug log" in program main menu to open program debug log.
This log contains the output stream of all the utilities involved in a patching
process. If something goes wrong, this information can be extremely helpful, so,
please, copy and paste it into your bugreport.

Acknowledgements:
=================
Eliot van Uytfanghe for UE Explorer
Gildor for Unreal Engine Package Decompressor (decompress.exe)
bokauk for XCOM ToolBoks
Amineri and XMarksTheSpot for UPKModder
Bertilsson, Drakous79, JohnnyLump and all NexusForums authors for helpful info and
discussions
dubiousintent for NexusWiki articles and helpful advices

All trademarks, mentioned herein, are properties of their respective owners.