Xcom 2 Modding Tutorial
Contents.OverviewWhile XCOM:EU 2012 installs a number of 'configuration' files (i.e. With file extensions of INI, INT, UPK, BIK, BIN, BMP, HTML, CSS, and CONFIG), the only ones of concern to Mods at this point in time are INI, INT, and UPK extensions; and in the of.SteamsteamappscommonXCom-Enemy-Unknown under the sub-folder BinariesWin32, the game executable:. These are in a mixture of text and hex code.
Despite appearances, when modding it is necessary to extract the UPK and SWF files from the 'cooked' executable and make changes to the extracted versions. Then the altered extract files must be re-compressed into a replacement executable, with a hash code that is used by the Steam game launcher to ensure a correct file structure.
XCOM 2: War of the Chosen released earlier last week, and many players are having a hell of a time fighting Advent.Console commands can be quite useful. Maybe you're testing a mod, or perhaps just goofing around after having completed the game. XCOM 2 is a turn-based strategy game sequel to XCOM: Enemy Unknown by Firaxis Games, released on the 5th of February 2016 on Windows PC, Macintosh and Linux. XCOM 2 has been largely well received by critics with a current Metacritic rating of 88% based on 82 reviews.
(Note this is different than verifying', which is comparing certain files on your computer against the distributed files on the Steam servers.)XCOM EU 2012 is built on version 3 of the Unreal Game Engine. This page is primarily a collection of tools that are known to be useful when examining or modifying associated game files.The term mods can be used in both a broad generic sense, and also to refer to a complete package of changes to the original play of the game. The term modlets has been created to refer to small mods that alter only a very specific portion of the game, and several are frequently required to be applied in combination to produce the overall mod effect. While they might be included in an archive package, each modlet file will need to be installed individually.
Sequence of installation may be significant, so read the accompanying documentation carefully beforehand.Modding ToolsThe tools listed here are not the only ones that can be used for either purpose. They are, however, all free of cost for personal use or open source.XCOM:EU 2012 is build upon the free-for-personal-use Unreal Game Engine, version 3.
General tools and references to that engine are applicable to modding XCOM, though as always specific games do not always utilize the same capabilities of the engine. UPK files are used to load on-demand content while playing a game.
They can be created and edited using the. They come in compressed and uncompressed form. A UPK serves as a file container (similar to an archive like a ZIP file) which includes various types of game files, and may contain 3D models, textures, maps, music files, game settings, SWF sprites & actionscripts, and other files.Unreal Game ToolsA collection of tools that are known to be useful when examining or modifying associated game files.Unreal Development Kit (UDK). is the build and engine version compatible with the Firaxis 'cooked' files for XCOM EU and EW.
Newer versions available on the official site are NOT compatible. is the official game developer tool site.
Free for educational and non-commercial use.See for many UDK articles and resources. UE Explorer.: an UnrealScript decompiler to look through the uncompressed UPK files.Description: An Unreal Engine decompiler. For more information on decompilers in general, see this Wikipedia article. This program lets you see the code almost as their creators wrote it, providing key information you will need to change UPK files, such as getting its hex representation, etc.Installation: Install it anywhere you want. Eliot van Uytfanghe is the author of UE Explorer, the principle generic Unreal Engine investigative tool on the XCOM forums.
His has much useful information, such as:.Eliot has released the source code of his Unreal Library that is part of UE Explorer and is what makes up the whole UnrealScript part of the program (basically anything but its interface). This enables other developers to:. Add custom games support for UE Explorer and other tools. Build your own tools for.UPK files. Enhance the code output in the way that you may like it. The Eliot.UELib.dll can be replaced by your custom one, so long as it doesn't break compatibility.You can fork the source code, and find instructions for use, under the EliotVU/Unreal-Library repository at.
The source code is released under the terms of the. Files of interest:. This is the file that outputs most of the code you see in function blocks. Deserializes the package summary and holds references to all objects within the package. Deserializes all table structures: Names, Exports, Imports, and so on.
Provides an interface of methods to read common unreal data types. Warning: Really messy and hacked together mostly due the wide support of UE1, UE2, UE3, and multiple games all in one.
All recognized unreal bytecode tokens, the numbers may be off and changed at runtime to adjust for UE3 packages!If you've got a question or suggestion for Eliot, please post in the official Nexus Mod Talk Forum release thread. Unreal X-Editor. Editor for creating/editing Unreal Script files. PatcherGUI is currently the recommended tool if you do not feel comfortable hex editing yourself.As these UPKUtils tools no longer use any hard-coded offset locations, mods designed to be installed with them should continue to work even after new game patches are released; unless something is moved from one file to another. 'Changes to offsets' were the primary reason older mods got broken by patches.Installation: As stand-alone applications, these are not 'installed' in the traditional sense. Rather they are placed anywhere, with fully qualified paths in the arguments pointing to the UPK files to be processed (see the examples below).
UPDATE: See the Disabling Hash checks entry in section below. The game's internal check of the SHA hash can be disabled once and for all.XCOM Mod InstallersMod Installers have evolved to apply the various changes created by the XCOM Modding community to the game executable. They can be packaged as part of the mod, or standalone for use with mods designed to be installed by them.Different install tools are used to apply mods to different parts of the game, which correspond to different types of configuration files. Those installers that are used with current mods are for UPK, INI, INT, and texture files.Custom Mod Builder and Manager.: Handles changing settings to INI and INT files. Recommended for players comfortable with editing text files according to general instructions.Long War Mod Manager.: Simplifies the installation and removal of Long War mods and can be used as a replacement for. It also supports some new mod file extensions that allow for the automatic updating of configuration files. This can be used to automatically define keyboard commands, add second wave options, or anything else that involves adding lines to a config file.
NOTE this works with EW only, not EU, as you have to point it to the 'SteamAppscommonXCom-Enemy-UnknownXEW' folder.ModPatcher.: The first tool for directly editing the game executable, and still maintains a healthy following. This tool only makes changes to the embedded DGC.INI file within the EXE. There is a minimum and maximize size of embedded INIs that the EXE can handle; if they are collectively any smaller or larger than this size, the game won't load. For ModPatcher purposes, the maximize size of the embedded DGC.INI file is somewhere very close to 101648 bytes (perhaps a little higher than this).
A workaround was to delete every spare byte - comments, tabs and spaces in the file - and change all the 'none' variable settings (such as eWPNone) to 0.MAINTAINERS: This information is still accurate, and should be retained for reference. UPDATE: There now exists a way around this embedded size limitation, and the need for ModPatcher and the like entirely. See the Enabling INI loading entry in the section, below.Recommended only for mod makers or those comfortable with hex editing.
TexMod.: Utility to find, save, and modify textures in Direct3D 9 applications (such as XCOM:EU 2012). Requires launching TexMod which then launches XCOM and replaces call to vanilla textures with the texture files in the mod package. Recommended for players who can create shortcuts and navigate the folder trees.ToolBoks.: (Link is dead. File no longer available.) Toggles many gameplay features and has the ability to install 'Custom Mods' that make patches to one section of UPK hex code at a time in a sequence. Many mods only found in threads or on this Wiki are published specifically for implementation with this tool. Recommended for all players.
Due to it's popularity, here are some FAQ answers:. Versions 1.6.x and later only work with XCOM 'Enemy Within' (EW).
In order to use ToolBoks with 'Enemy Unknown' (EU), you have to use version 1.5.2. (See the mod.) Currently none of the versions work with EU after patch 4.
(See to determine your patch level.). If a tab or option is grayed out: it was present in earlier versions, but has not yet been updated for the current patch level of the game.
ToolBoks SHOULD be compatible with most other mods, but as always the last mod to change any specific element of the game 'wins'. As ToolBoks only changes very specific things and most mods change numerous other elements, it is recommended you run ToolBoks last. ToolBoks will automatically disable file hash checking and enable INI file loading when first run, so you want to just open and close it once if you plan to test other mods before applying ToolBoks changes. ToolBoks only makes backups of the files it potentially modifies, although it won't check to see if an option you've selected will modify a specific file on the list; it will just backup all of them. It doesn't modify any of the MyGamesConfig files with any of the settings and so will not make backups of them. (DLCs won't recognize some changes if the MyGamesConfig files are not also modified as well.). ToolBoks will automatically decompress any files modified by Custom Mods.
The game will load decompressed 'loose' files right alongside compressed ones if they are different than the embedded versions, and the Enabling INI loading entry (in the section, below) doesn't prevent it. None of the ToolBoks settings are saved in the save file. All the changes are made to the decompressed versions of game files, so it's the current settings in those files that take effect each time the game is loaded, regardless if it's a new or a saved game. As of version 1.2.0, has a built in Perks tree editor, that will work with the UI Mod, which expands the number of perk choices per rank. This is only available in version 1.5.2 at this time.
The perks have to follow the default layout (1, 2, 2, 2, 2, 1, 2), unless you have the installed. In that case you should be able to use a 3, 3, 3, 3, 2, 1, 2 layout. It's currently not possible to change Rank abbreviations via ToolBoks, but you can manually edit them in:XComGameLocalizationINTXComGame.
IN Search for: maRankAbbr0=Rk. There is no Developer Console feature in ToolBoks; only the Developer Shell. The Console was intentionally not included to avoid abuse of it in multi-player games. See the article.
0027.91 DevHTTP: FHttpDownload resolve complete to: 65.118.245.165:80 0027.91 DevHTTP: FHttpDownload resolve complete to: 65.118.245.165:80 0027.91 DevHTTP: FHttpDownload resolve complete to: 65.118.245.165:80. 0028.15 DevHTTP: FHttpDownload::StateParsingHeader: Got unknown status code 503 URL: prod.xcom.firaxis.com:80/News.ashx 0028.19 DevHTTP: FHttpDownload::StateParsingHeader: Got unknown status code 503 URL:The entries marked like so are:. The Server IP address: 65.118.245.165. The Server DNS Name: prod.xcom.firaxis.comThese are what you will place into the hosts file to block attempts to connect. Start Menu Right click on 'Notepad' (or any ), select 'Run as Administrator'. File Open %systemroot%system32driversetchosts. The hosts file has no '.'
Suffix, so make sure you don't add.txt or anything else. Also,%systemroot% on most systems is C:Windows, but the exact folder name may vary by OS version.
Xcom 2 Modding Tutorial Software
The value of the global%systemroot% on your system can be determined by entering 'set' on the Windows command line, or as it's shortcut is called, the. But the variable%systemroot% (including the percent '%' signs) can safely be used without knowing it's actual value. Add these three lines to the hosts file:(The first line is a comment. The next two lines do the actual work, but are specific to XCOM:Enemy Unknown 2012. Other games may have their own DNS names i.e. Prod.xcom.firaxis.com and IP addresses i.e. PatcherGUI (as of v5.2), part of the mod, includes options to 'Enable INI loading' and 'disable phoning home' for you.
It can also find and open the correct config folder for you. So, to install INI modifications, one needs to select the correct game path (XCom or XCom/XEW), 'enable INI loading' and 'disable phoning home', and it will open the config folder and replace the vanilla file with the modified one. This is currently the recommended tool if you do not feel comfortable hex editing yourself. It has recently (20 Apr 2013) that the launcher does not check every UPK file, and that it uses a table in the executable to look-up the files it checks. It then compares the hash with that in the companion '.uncompressedsize' file. By simply changing the names of the UPK files in this look-up table so they are not recognized or found, it will happily load regardless of any other files hash.
This appears to eliminate the need for removal of the companion '.uncompressedsize' file (which consequentially causes the game to use it's internally stored hash value) and XSHAPE (which updates the internal hash), or any other hash fixing.Simply look for the strings 'xcomgame.upk' and 'xcomstrategygame.upk' in the executable using a hex editor (such as HxD, linked below) and change them to some other string. The current version of ToolBoks is now using this technique on both of those files, as well as 'xcomshell.upk'. Mac OSX users need to make these changes to the Hashes.sha file in BinariesWin32, to the filenames located at 0x00D0-0x0120.NOTE: The Enemy Within (EW) expansion does not include these UPK hash checks any longer, and does not need this patch to read in the loose decompressed versions of these files. The original EU EXE with patch 5 still does.The following is taken from the documentation of the XCOMModHelper tool available at.
A recent (24 May 2013) makes it possible to force the game to load the DGC.INI config file from the 'XComGameConfig' folder, thereby eliminating the need to use ModPatcher or make DGC.INI changes to the EXE at all, and avoiding the size limitation on the embedded file. (See the entry note on ModPatcher here about size limitations.)Bear in mind: Loose INI files get read, and thus override mod changes to the internal 'resource cache', after the game EXE starts.Choose your mods intelligently and with understanding. Not all will work together.These hex offsets are for EXE version 1.0.0.28586; patch 4, Changelist 356266, unless otherwise noted. In xcomgame.exe: starting at location 0x157D93A. For Mac OS XCOM Elite Edition: starting at location 0x1D86A70. For Mac OSX Steam version, patch 3 (Jan 8, 2013): starting at location 0x1E7E5E0.
For Mac App Store version 1.0: around offset 0x1BD58D0. Search for '72 00 00 00 65 00 00 00 2E 00 00 00 69 00 00 00 6E 00 00 00 69 00 00 00' (which is 're.ini' in UTF32 Little-Endian).NOTE that these strings are also found as part of disabled debug code, at offset range: 0x156BA82-156BF38. For Mac App Store version 1.0.1: starting at 0x1D86B50.
If searching in a hex editor, look for '44 00 00 00 65 00 00 00 66 00 00 00 61 00 00 00 75 00 00 00 6C 00 00 00 74 00 00 00 47 00 00 00 61 00 00 00 6D 00 00 00 65 00 00 00 43 00 00 00 6F 00 00 00 72 00 00 00 65 00 00 00 2E 00 00 00 69 00 00 00 6E 00 00 00 69 00 00 00'. This is 'DefaultGameCore.ini' in UTF32LE.If you edited version App Store version 1.0, the App Store will not update the game and you will need to delete it and re-download. After editing, the app will need to be code-signed, again (as usual.).Take care with the location of the strings you disable. As always, these locations may change after official game patches are released.There are the three unicode text strings.X.C.o.m.G.a.m.e.C.o.n.f.i.g.D.e.f.a.u.l.t.G.a.m.e.C.o.r.e.i.n.i.X.C.o.m.G.a.m.e.C.o.n.f.i.g.D.e.f.a.u.l.t.M.P.G.a.m.e.i.n.i.X.C.o.m.G.a.m.e.C.o.n.f.i.g.D.e.f.a.u.l.t.L.o.a.d.o.u.t.s.i.n.i. It appears that these three strings are checked to see which files to NOT load from the Config directory. Change the first string to something else.
And behold: the game loads from the (DGC.INI) file in the ' XComGameConfig' directory, even if larger than the embedded version.All the other INI files are read by default. Only these three have to be modded to load.This means that no longer are BALANCE Mode settings the only ones taking effect from the text editable file in 'Config', and that additional items can be added to the DGC.INI file. Of the other files explicitly denied from loading, (believed to be 'multiplayer' related), and (initial equipment for classes of Soldiers and Aliens), are similarly enabled in the same manner.NOTE: The Enemy Within (EW) expansion appears to still need this patch to read in the loose INI files. The original EU EXE definitely still does.For instructions on how to search for the above filenames as unicode strings, with screenshots, see the wiki article.Bear in mind: Search for the following in hex mode for unicode values.The following patches are taken from the documentation of the XCOMModHelper tool available at. There appears to be a minimum and maximum size to the combined total of the three INI files that are prevented by default from being loaded by the game engine:,.
If the combined total size of these three INIs is either smaller or larger than these limits, the game won't load (not a CTD) with the message: 'Failed to start game (app already running)'. This may apply to the combined size of ALL INI files, but has not been tested nor have the combined minimums and maximums been determined. (See the discussion at.)However, interestingly this implies reducing the size of one of these files enables expanding the size of another of them by the same amount.
Xcom 2 Wotc Modding Tutorial
There has been some success with exploiting this for expanding the DGC.INI, but there may be other checks that have not yet been identified. There appears to be an upper limit to the DGC.INI of very close to 101648 bytes.Increased Load Times. This is a purchased expansion to XCOM:EU 2012, released in the USA on 12 Nov 2013. It installs to a XEW subfolder under the main XCOM install path.
Most of the loose files from EU are replicated in this subfolder, which means EU and EW are basically separate games. There is some sharing of movie (.BIK) files. EW adds a launcher app XComLauncher.exe in the XCom-Enemy-UnknownXEWBinariesWin32 folder which is started by Steam and provides the option of which game ( EU or EW) to launch.The actual game executables this launcher runs are:. XCom-Enemy-UnknownBinariesWin32XComGame.exe - launches Enemy Unknown. XCom-Enemy-UnknownXEWBinariesWin32XComEW.exe - launches Enemy WithinEW no longer makes a hash check of the compressed UPK files. So they can simply be decompressed and will be used after modification once the related.uncompressedsize files are removed.However, the mod to force the game to use the loose XEWXCOMGameConfigDefaultGameCore.ini file is still needed.
Hex edit the XComEW.EXE file as follows:Find: (i.e. Key is the 58 in the last line)25 00 64 00 00 00 00 00 49 00 6e 00 69 00 72 00 73 00 69 00 6f 00 6e 00 00 00 00 002e 00 2e 00 5c 00 2e 00 2e 00 5c 00 58 00 43 00Replace: (i.e.
Replace the 58 in the last line with 57.)25 00 64 00 00 00 00 00 49 00 6e 00 69 00 72 00 73 00 69 00 6f 00 6e 00 00 00 00 002e 00 2e 00 5c 00 2e 00 2e 00 5c 00 57 00 43 00EW Update server (i.e. HOSTS file):. 127.0.0.1 prod.xcom-ew.firaxis.com. 127.0.0.1 65.118.245.139These 'phone home' locations update the XComGamecore.INI file in config/loc on game launch, and are needed in addition to the entries for EU. However, early reports that disabling these connections cause the game to freeze are now attributed to other causes, such as not disabling 'auto-updates'. Cloud Synching of save game files still works with these addresses disabled.
(While sometimes referred to as 'the silent patching mechanism', so far there is no evidence that these servers are involved in actual changes to the game code. They still appear to only restore certain vanilla files involved in Multiplayer games, which can disrupt mods touching those same files.)The EW 'phone home' addresses seem to only update XComGameCore.INI in My GamesXCOM - Enemy WithinXComGameLogsEMS at this time.Extending/Replacing FunctionsIn early Dec 2013, wghost81 discovered it was possible to alter the UPK Package information so the game would utilize an expanded or replacement function of any size.
This frees the mod creator from the constraint of keeping their code changes to within the original byte size limitations of the vanilla function, as well as providing the possibility to add new functions exclusive to your own mods. See the Hex editing UPK files article entry for details.ReferencesReferred to by this article:. has much useful information, such as:.
Unreal Game Tools.: Includes the following, but don't forget to check for updated versions of each:. Custom XCOM Mod Tools.: Required. XCOM Mod Installers. (no longer available).
Generic Modding Tools. Flash File Tools. Sound File Tools.That refer to this article:.