Modding XCOM:EU 2012

From Nexus Mods Wiki
Jump to: navigation, search



Overview

Creating Mods for XCOM:Enemy Unknown 2012 (XCOM:EU 2012) (at the moment) involves editing the hexadecimal code values of the game executable. The purpose of this page is give you a general understanding of the process and to point you to the locations of the various resources within the XCOM Wiki to enable you to do so. If you haven't yet, please see the Navigating the XCOM Wiki article to understand how this site is organized. If you wish to contribute, please read Guidelines for new posts - XCOM:EU 2012 in the Category: 0 Start here - XCOM as well.

It has recently been discovered that the game contains the Mutator class in the Engine.UPK file. This should permit the inclusion of Mutator packages developed with the Unreal Development Kit (UDK). This methodology is natively supported by the Unreal Engine 3, and should permit more robust mods that are not broken by official Firaxis patches. See the Modding with the UDK - XCOM:EU 2012 article for more on this approach and links to get started. So far (14 Feb 2014), no mods developed from the UDK (UDK Packages or Mutators) have been published.

If your intent is merely to use mods created by others, see Basic Guide to installing mods and the other content within the Category 0 Start here - XCOM. Anyone creating Mods is expected to be familiar with that information as well. However, please finish reading this overview first, as it will help you understand the different types of mods available.

The majority of the available mods for your use are to be found on the XCOM Nexus Mods site. Such mods as exist here on the Wiki are primarily for demonstration and while functional, may not provide all the 'hand-holding' of Mods found on the Nexus site. (They generally assume you understand the basic installation methods and tools, and do not need them described again.) Other than fixing errors (which should be reported to directly to the author or in threads related to the mod in question), do not expect their authors to provide other support (like "how do I install this" or "can you add such and so"). These mods are found in Category: XCOM Mods and are very much "as is" (like a used car).

There are really three levels of mod making going on that all appear to be done the same way. But if you don't understand the differences in which sort of mod you need, then it all appears to be an insane bunch of hex code changes of terrifying complexity. Here is a stab at clarifying the approaches these mods take.

The first modification most people try is to change a simple "configuration setting". These are performed in the DefaultGameCore.ini file (DGC.INI for short), which is found in the <Install path>\XComGame\Config folder. The Enemy Within (EW) DLC moved many "configuration" variables out of the EXE and into the much more accessible INI files. Strategy game elements are now found in the DefaultGameData.ini file.

(Very similar are changes to the language specific versions of text descriptions and dialog, which have the common extension of INT and are collectively called localization files. These are found in the<Install path>\XComGame\Localization folder, and language country-code sub-folders (i.e. ITA, FRA, etc.). Commonly localization changes simply refer to the INT folder, which is the "English language" country code, but translations of such mod changes should be applied as well to local language folders as appropriate. These loose files are used automatically by the game and their changes take effect immediately.)

It took awhile to understand that only certain changes to the DGC.INI file got used. These all affected the Difficulty settings, what are internally called Balance Mode setting for 'Easy' (Tutorial), 'Normal', 'Hard' (Classic), and 'Classic' (Impossible) modes of difficulty. They appear in various locations within the DGC.INI with names like BalanceMod_Easy_<something> for specific elements like particular aliens or abilities or item costs/requirements. For awhile it appeared this limited number of setting were all we could tweak, but then we discovered that by changing the name of some files in a table within the XComGame.EXE file that were prevented from loading, we could get it to read in and use all the settings of the DGC.INI. Apparently only 3 files (DGC.INI, DefaultMPGame.ini, and DefaultLoadouts.ini) are checked and blocked. (See the Recent Discoveries section in Basic Guide to installing mods for information on how to manually unblock these files.) What we are needing at the moment is for someone to provide a simple method to make those embedded file name changes without forcing the non-coder mod-user to perform "scary hex-edit surgery" (it's actually pretty simple to make a single byte change) on the game EXE. (Most of us are hoping Bokauk will implement it in her next release of ToolBoks, but she hasn't committed to that as yet.) A number of the earlier tools (Modpatcher, Custom Mod Builder and Manager, XCOM INI Patcher, etc.) were devoted to changing such text settings within the EXE, but once the DGC.INI file can be fully read all that will be required is a simple text editor. However, you should expect some longer load times as a result. (See the article Modding Tools - XCOM:EU 2012 for a complete list of tools and links to them.)

At this same level of modification (the simplest) is performing single byte-code changes to the game EXE, like changing the first character of an embedded file name to disable hash checking or enable the DGC.INI file to load (described under Recent Discoveries in Modding Tools - XCOM:EU 2012 as well). There are some other similar changes that can be made, but they all require you to use a hex editor or equivalent tool and be able to locate the correct section of code that needs to be changed (the offset location). This is the point most "non-coders" give up because they are not comfortable with the idea of 'code surgery'. It is the point at which we all would like to have tools to make this process simpler by automating it, and which ToolBoks has fulfilled to some degree by making many such single byte 'tweaks' into 'toggles' or 'option pick' check-boxes. But if you are willing to read up on how to make hex changes, then many additional similar modifications become possible immediately. (See the article Hex_editing_UPK_files#Hex editing I: changing single values.)

In general, the only reasons to modify the EXE are as follows:

  • To skip the hash check of certain UPK files by changing the filename (e.g. "XComGame.upk" to "bComGame.upk", etc.) in an internal table so their loose versions can be used instead;
  • Force the game to read the DefaultGameCore.ini from the XCOM folder;
  • Modify the embedded DefaultGameCore.ini in the game EXE file (now depreciated due the discovery above);
  • Modify native functions (e.g. for the developer console, which apparently is the only modified one so far).

The next level of mod replaces sequences of hex code, or byte-code blocks. Typically this is performed on UPK files, which by default are in a compressed, archive like packed format. Such changes need to be made on a decompressed (but still packed) copy of the UPK. The game will load and use any compressed or decompressed, loose UPK file over the embedded version within the EXE. Any of the lengthier mods that change how the game functions or displays require such changes. Often many changes to many different sections of code are required. Such changes are what you see packaged for/with a Mod Installer as Mods on the XCOM Nexus Mods site. Sometimes such mods are released without an Installer but presented as blocks of Find and Replace sections of byte-code, to be installed by a specific tool such as Custom Mods for ToolBoks. Versions of ToolBoks from v1.20 onwards have replaced the Find block with an offset location value and can now be packaged to install many byte-code blocks to different locations in sequence. Earlier Find and Replace versions can be repackaged if the offset location can be determined. A remaining problem is that such offsets must be redetermined after every patch, which is why it is important that mod authors note to which patch their mod is applicable and users read the documentation.

Creating such byte-code blocks does require coding skill, and some understanding of Unreal Script Types as well as the ability to convert decompiled code bytes to hex-code, as found in Hex values XCOM Modding. Implementing such byte-code blocks does not. Rather you must be able to understand and follow the implementation instructions for the mod. Such mods must be patched or merged into the decompressed but packed UPK files for existing byte-code blocks (i.e. ToolBoks Custom Mods).

The final level of mod refactors existing code to a different purpose. This is the most sophisticated form of modding currently being attempted, and definitely requires a thorough understanding of not only coding procedure but also the Unreal Script language. In this type of modding mode, existing code that is deemed not essential (such as debugging code or that used only by the Tutorial/Easy difficulty mode of the game) is reworked to perform a different purpose, but must fit within the existing size of the previous code block. At this time it is not possible to extend the size of the game EXE or UPK files, or expand any of the embedded code segments, so refactoring is a major challenge in not merely re-purposing but also fitting the new code within a limited number of bytes, and then getting it to compile as well as function correctly. Implementation is usually the same as for other blocks of byte-codes, such as Custom Mods. See the article Hex_editing_UPK_files#Hex editing II: re-writing functions.

Most current mods are either plaintext changes to the DGC.INI or patch the loose, decompressed UPK files under the XCOM folder. Texture replacement is currently accomplished by a 'wrapper' program (see TexMod in Modding Tools - XCOM:EU 2012) which intercepts (hooks) the call to images and substitutes certain replacement images in the result.

Patches

It is important to point out in Mod release notes as to which versions of the game they are compatible with. It should NOT be assumed that any given mod is compatible with any version other than it states in it's documentation. This is especially true where offsets are given to locate the position of hex code changes. Patches usually cause changes to offset values.

Game version information comes in three forms: release date, EXE Version from Properties, and Changelist number from the <install folder>\Binaries\Version.txt file. The community has taken to referring to patches by sequential number since the original game release as well, but this is strictly an informal reference.

The Launch.log file located in your ...\My Games\XCOM - Enemy Unknown\XComGame\Logs folder also contains the Changelist number in the 11th line:

Init: FxsChangelist: <changelist number>

This might be worth looking for if you haven't played for a while as the game keeps about 5 backup copies of this file.

XCom:EU Game Version/Patch Table
Patch Version.txt Date EXE Version Changelist Notes Source
0 2012-Oct-09 1.0.0.5443 Live on Steam: 2012-Oct-09 Steam Announcement
1 2012-Oct-10 1.0.0.11052 338732 Live on Steam: 2012-Oct-11 2K Forums
2 2012-Nov-01 1.0.0.14565 342245 Live on Steam: 2012-Nov-08 2K Forums
2.1 2012-Dec-07 1.0.0.19284 346964 Live on Steam: 2012-Dec-07; Slingshot Saves Hot Fix 2K Forums
3 2012-Dec-11 1.0.0.20072 347752 Live on Steam: 2013-Jan-07 2K Forums
4 2013-Feb-20 1.0.0.28586 356266 Live on Steam: 2013-Mar-15 2K Forums
5 2013-Jul-11 1.0.0.55175 382855 Live on Steam: 2013-Nov-14 Steam announcement
6 2013-Nov-25 1.0.0.4963 398179 Live on Steam: 2013-Dec-02 2K Forums
7 2017-Aug-29 1.0.0.4963 3344272 unannounced SteamDB

View "Sources" for what is known about a specific patch.

  • "Patch 0" was the original public release of the game. SteamDB app id: 200510.
  • "Patch 2.1" for Slingshot Saves Hot Fix release note: "Slingshot Content Pack will no longer cause the game to think pre-existing saves are corrupt. All previous saves should now work properly." It appears to have been slipstreamed in without notice by most people, which is why it was given a ".1" patch number when it finally was recognized after patch 3.
  • "Patch 4" was made publicly available via Steam updates on 15 Mar 2013, but beta tested within the Steam Community starting 20 Feb as the "AI Teleport Bug Fix".
  • "Patch 5" was released along with the Enemy Within (EW patch 0) DLC expansion pack for XCOM: Enemy Unknown, on 12 November 2013 in North America, and 15 November 2013 elsewhere. Source: Wikia
  • "Patch 6" was announced and 'slipstream' released at the same time as EW patch 1.1. This appears to have been 'EW patch 1' for regions outside of the US.
  • "Patch 7" was an unannounced 'slipstream' release to apparently the entire current lineup of XCOM games (EU, EW, XCom2, and related DLC). At this time it appears the release was related to a switch in the security certificate provider used to verify the authenticity of the purchased game by the Steam Client, from "Verisign" to "Digicert".

There was a "Downgrade EU to patch 4" mod for compatibility with many older EU mods, especially the original "Long War for EU". However, the unannounced "patch 7" has broken the Steam Client verification of the older versions of the game by way of the current (online mode) or cached (offline mode) credentials, so the game wouldn't launch. Consequently the author has removed the "Downgrade" mod from Nexus to avoid people wasting time with it and to forestall any attempts to circumvent the certificates, which likely would be construed as "piracy".



The XCom: Enemy Within DLC expansion installs to the subfolder XEW under the XCOM <Steam install folder>, so it's Version.txt file is found in <install folder>\XEW\Binaries. The installation creates a complete copy of the loose compressed UPK files independently of those used for the original EU game, which differ in content. Some movie files in the EU folder have been updated and new ones are also found in the XEW folder. However, to prevent duplicating movie files, those movie files re-used from EU appear to have small .txt files that are used to reference the movie file in the root XCom-Enemy-Unknown folder.

XCom:EW Game Version/Patch Table
Patch Version.txt Date EXE Version Changelist Notes Source
0 2013-Oct-01 1.0.0.926 394142 Live on Steam: 2013-Nov-14 Steam announcement
1 2013-Nov-20 1.0.0.926 398180 Live on Steam: 2013-Dec-02 2K Forums
1.1 2013-Dec-02 1.0.0.4964 398180 Live on Steam: 2013-Dec-02; 3 bug fixes, adds Traditional Chinese 2K Forums
1.2 NA NA NA Live on Steam 2014-Jan-08; Multiplayer Balance Update Steam Community
2 2014-Feb-21 1.0.0.8708 401776/401924 Live on Steam 2014-Feb-25; Touch Support 2K Forums
3 2014-Mar-05 1.0.0.9040 401776/402256 Live on Steam 2014-Mar-10; Keybinding Fix 2K Forums
  • "Patch 0" was the initial public release of the Enemy Within DLC expansion pack, and along with "Patch 5" for XCOM: Enemy Unknown, available on 12 November 2013 in North America, and 15 November 2013 elsewhere. Source: Wikia. SteamDB app id: 32206.
  • "Patch 1.1" appears to have been slipstreamed in without notice by most people: "3 bug fixes, adds Traditional Chinese". The Changelist in the Version.txt file is still the same as patch 1. The only known difference is the internal version number and byte size of the XComEW.EXE file: patch 1= 26.3 MB (27645592 bytes); patch 1.1= Size 26.3 MB (27643032 bytes). Based on announcement on 2K Games forum, changed patch date to announcement date. (If the actual date from the Version.txt file is different, please update both the table and this note.) It is not listed on Steam Product Updates. Patch is decimal numbered because it appears to otherwise be identical to patch 1.
  • "Patch 1.2" announced as specific to EW on Steam Community forum as: "Multiplayer Balance Update" which adjusts the costs of units in multiplayer. This update is not like other patches, as it is without a new Version.txt file & Changelist number, or updated EXE or UPKs; replacing only an INI file. It is given a decimal number to indicate sequence following the previous normal patch with a Version.txt file. It updates various costs in XComMPGame.INI, which is delivered into the Logs\EMS folder via the 'phone home' (IniLocPatcher) mechanism.
  • "Patch 2" will change the "Version.txt" Changelist entry after running the Steam 'verify game files' process. The XComGame.EXE for EU date/timestamp will also change to 26-Feb-2014 13:00, but does not appear to have actually changed, and the "Version.txt" file Changelist data is unchanged.
  • "Patch 3" XEW\Version.txt has Changelist: 401776. XEW\Binaries\Win32\Changelist: 402256. No change to EU (398179). Tactical binds in this patch work once again from DefaultInput.ini. [XComGame.XComTacticalInput] section is no longer present in DefaultGame.ini.




XCom:EU/EW Linux Version/Patch Table
Patch Version.txt Date EXE Version Changelist Notes Source
0 2012-Oct-09 1.0 Beta 2 Live on Steam: 2014-Jun-19 Steam Store
  • "Patch 0" was the initial public release of the Linux version by Feral Interactive, and runs on Ubuntu 14.04 and SteamOS. It contains both EU and EW, but has only one Version.txt file. See the "Linux Differences" section of the Basic Guide to installing mods article for folder locations.




Bear in mind that patches replace some "loose" compressed UPK files as well as the game EXE. Since mods typically are made to "loose" decompressed UPK files, they may need to be updated with newly decompressed versions to apply correctly with patched versions of the game. Mod makers are advised to pay attention to the Globally Unique ID (GUID) 16 byte sequence found in the header at byte range 0x45-0x54 (69-84 in decimal) at the beginning of the uncompressed UPK.

XComGame.UPK
Game Patch GUID
EU 4 33 2E 29 6A A5 DD FC 40 B5 CC 57 A5 A7 AA 8C 41
EU 5 01 E9 EB 29 23 F4 DB 4F A8 2B 8E 46 A7 25 E5 D6
EW 0 B1 1A D8 E4 48 29 FC 43 8E C0 7A B0 A3 3E 34 9F
XComStrategyGame.UPK
Game Patch GUID
EU 4 A8 46 50 30 6F 48 84 42 AC 1A 72 B6 8D 2E 6D 23
EU 5 1D EE 33 F1 66 88 FB 49 B1 72 93 44 01 BC 85 39
EW 0 9C F8 70 10 21 38 A0 41 8B 33 A4 2E E8 71 23 00


This information has been included (via Template:Patches - XCOM:EU 2012) in the following articles:

Unreal Engine

It is important to understand that X-COM:EU 2012 is built upon the Epic Games Unreal Engine 3 (UE3), which provides the Unreal Development Kit (UDK) free for noncommercial and educational use. This means there is a LOT of preexisting knowledge about how this engine works. All the fundamentals of the Unreal Engine are present in X-COM:EU 2012. Mod makers should first look for answers to their 'how does it work' questions on the Unreal Developer Network (UDN) and the community developed Unreal Wiki web sites. This site is only focused upon the X-COM game and features unique to it's specific implementations.

Overview

  • UE3 Basics: Exactly that - the basic requirements, general development topics, UDK FAQ, Blog of content related features, and video tutorials
  • Getting Started Overview: an overview of the process of planning, producing, and publishing a game using Unreal Engine 3
  • Technical and Programming: references, technical guides, and tutorials covering setting up the engine, extending the Unreal Editor and creating new tools, and general programming with native code and UnrealScript
  • Getting Started Programming: includes "coding standards and orientation", "UnrealScript Language Features", and "Starter Kits"
  • Content Creation: references, guides, and tutorials covering the creation of art assets and other content such as static meshes, skeletal meshes, materials, etc.
  • Level Editing: references, guides, and tutorials covering the creation of levels and environments including adding scripted gameplay and dynamic interactive animation events
  • Resource Depot: tutorials, example code, downloads , and community links
  • Unreal Script Reference

Gameplay Elements

Gameplay elements in this sense refer to elements such as the gametype (or game rules), the player (including camera and input), and the HUD/UI (Heads Up Display / User Interface).

Functions

Level Creation

Levels, or maps, are collections of items that together form the world or environment in which the game takes place.

Content Creation

Unreal Engine 3 provides both custom tools within UnrealEd as well as pipelines for bringing in content from external applications.

Compiling and Testing

Building and compiling is handled by the Unreal Build System and Unreal Frontend. These automate a great deal of what used to require manual intervention.

Packaging and Distribution

Packaging your game created with Unreal Development Kit is a fairly straightforward process. In the UnrealFrontend application, the Package button on the toolbar starts the packaging process. It allows you to name the file and shortcut of your game then packages Epic's binaries and your cooked content into a standalone installer for distribution.

  • UnrealFrontend: tool that helps perform common multi-step tasks in the Unreal ecosystem through an intuitive graphical interface
  • ContentCooking: Cooking content is how content is converted and massaged into the format that supports consoles (currently Xbox 360 and PS3). PCs, as well, can now use cooked data, which will result in much faster loading speed

Tutorials

These are either HOW TO articles of a general nature, or essential to creating XCOM Mods. Here is a sampling:

Visit the Category Tutorials - XCOM:EU 2012 (bottom of the page) for the complete list.

Subject Articles

These are explanations of our current understanding of how the XCOM game engine functions, and often how to make specific changes to that functioning. Here are a sampling of available articles.

Do not forget to check the XCOM Modding category (bottom of the page) for the complete list and links to related entries!

Mods

The mods presented on this site are primarily for demonstration purposes, but are fully functional. Often they are a collection of related files that taken together perform the function of the traditional Mod. Read their descriptions carefully.

  • Visit the Category XCOM Mods (bottom of the page).

Modding Tools

  • See Modding Tools - XCOM:EU 2012: A list of tools for creating or installing mods. Referenced here are:
    • Decompress
    • Extract
    • UE Explorer
    • HxD
    • ToolBoks
  • Note that the tools listed are for turning compressed files into uncompressed versions that can be edited, or only work with uncompressed files. The game can work with and load modified uncompressed files, but checks for the presence of <X>.upk.uncompressed_size files in XCom-Enemy-Unknown\XComGame\CookedPCConsole. It will not load a matching <X>.upk file if such uncompressed_size files are found, so they must first be moved or renamed. However, the compressed files won't be loaded unless the uncompressed_size files are found again.
  • If you need to make changes directly to something within, or locate new offsets after a patch within the XComGame.EXE file, you have to use a hex-editor. Changes to the unpacked UPK files provided with the game will require disabling the uncompressed_size files (note above) to take effect.

Code Breakdowns

These are a collection of discoveries from investigating the hex code of the game engine. In general they consist of hex code sequences overlaid with the decompiled code statements that produce them. Sometime just the decompiled code is presented, and sometimes both are present but separately instead of as an overlay. Their purpose is to document how the game engine works. Any relationship to other articles or mods on this wiki will be via the internal references provided on each page.

  • Visit the Category Code Breakdowns (bottom of the page).

Basic Procedure (with example)

The following is derived from the procedures described in the Finding the first step thread in the Nexus Forums "Mod Talk" section.

In general, the terms packed and compressed have been used interchangeably in the community. However, here we will make the distinction that an archive file is a collection of separate files packed together into one file, but not compressed. We note that a compressed file is a packed file which has reduced the size of the individual files by applying a compression algorithm ("lzo" in the specific case of XCOM UPK files). Consequently:

  • packed refers to a collection of related files into a single file.
  • compressed refers to a packed file, the content of which have been individually reduced in size.
  • The game EXE file contains compressed versions of the UPK files embedded within it.

It is because they are compressed versions that attempting to directly edit UPK files in the EXE will always fail.

Modifying the scripts found in UPK files is relatively straightforward, though it involves a number of steps.

You need to decide up front HOW you intend to implement each particular mod to a UPK file. Your choices currently are:

  • By directly modifying the XComGame.exe executable file (modify 'native' code), though normally this is only to make single byte-code changes because the UPK content is in compressed format;
or

Note the basic process is the same for modifying ActionScripts or SWF images, typically found in Command1.upk, but different tools are used. See the article Flash SWF Editing.

How to package a Mod for installation with a Mod Installer such as those found in Modding Tools - XCOM:EU 2012 is beyond the scope of this article. It is worth noting however, that most methods, including ToolBoks "Custom Mods", DO NOT directly patch the executable with a compressed form of the modified UPK file. Instead they rely upon patching the loose, decompressed (but still packed) version found in the XCOM folders. Once you master the basics of making such changes manually, it becomes pretty obvious how to package your files for your preferred installer, which handles the patching and placement of the resulting file for you.

The following steps only have to be performed once per mod

You should always work with a fresh copy of the decompressed loose UPK file, to ensure you do not mix different mods intended for later distribution together. Each mod should be created from a 'vanilla' UPK file, unless it is part of the same mod package.

  • Decompress the loose UPK file.
Decompress.exe from Modding Tools - XCOM:EU 2012, which is a commandline tool, and requires
the '-lzo' option for XCOM UPK files. Create a simple batch file in the same folder with the line:
decompress -lzo %1
and from the command line run "<batch filename> XComGame.upk" (or whichever UPK you wish to decompress).
Note that the UPK filename passed to the program is case sensitive. If the UPK file is not present in the same folder as Decompress.exe, then you must provide the complete path as part of the UPK file name. Don't forget to enclose it in quotes if there are any spaces in the path.
The decompressed UPK file will be placed (with the same filename) in the sub-folder "unpacked" (loose use of the term) which the program creates in the same folder it is in.
There is a optional switch (-out=<path>) you can add to the batch file (after the "-lzo" switch) to redirect the output to another path, such as that of the Extract program folder.
Note that the use of an Extract program is optional, as it unpacks the content of the UPK file. At this point we have no means of restoring modified extracted files back into UPK packed files. Hex changes to the decompressed but still packed UPK file are the usual practice instead.

The following steps are performed for each separate UPK mod

  • Open the UPK file using UE Explorer to navigate through the UPK and find the location to change.
  • See the example edit below, and the articles in Category:Tutorials - XCOM:EU 2012 for guidance on making your desired changes.
Note that you may expect to have several programs open at the same time and have to shift between them to locate and determine the nature of the changes required.
  • For simple changes, hex can be copied by hand from the UE Explorer Hex View Buffer.
  • For more complex changes, the entire hex content of a function can be copied from the Hex View in UE Explorer.
  • Hex changes typically involve finding a before/after set of hex changes.
    • These hex sequences must be long enough to be unique within the UPK file -- typically 10 to 12 bytes is sufficient.
  • Note the hex offset starting point of the unique code sequence for your change, and copy the entire change to your clipboard or a plaintext file.
  • Test your changes actually compile by opening the modified UPK file in UE Explorer.
Make sure to delete/rename any uncompressed_size files of the same UPK filename from the game directory to enable the game to load your loose, changed UPK file.
  • Open the executable XComGame.upk or XComStrategyGame.upk (or whichever UPK file is appropriate) in a hex editor, and locate the offset for your change. You should be able to verify you are in the correct place by comparing byte codes there with your clipboard or plaintext file copy containing your change(s).
Check for possible other code segments that match your search pattern. If you find other matches, you need to ensure you have the correct offset or a more unique pattern for the code segment you need to change.
  • Use XSHAPE or ToolBoks to have the SHA hash values in XComGame.exe updated for the edited UPK file(s), or disable the hash checks completely.
  • Test the change takes effect by launching the game.
    • Erroneous code can fail in several ways:
      • The game may crash when launching -- this usually indicates a problem with the memory size in a function header
      • The game may crash when an action is performed -- this usually indicates an error with the modified hex code
      • The game may hang, stutter, exhibit display corruption or other behaviors
Note that when testing with a 'save game', changes may not appear until the next time a new instance occurs.
That is if your change affects a Soldier, it may not appear until a promotion, a new mission is started, or a new soldier is recruited. The code change will not affect saved data, only something 'new'.

Descriptive example of an edit:

From the Nexus Forums "Mod Talk" The next Step thread.
This is an example of applying the article Hex_editing_UPK_files#Hex editing I: changing single values.

  • Decompress XComGame.upk
  • Open it in UE Explorer
  • Go fishing... find the class: XGCharacterGenerator
  • Click on it, then open up the functions list
  • Click on CreateTSoldier
  • Notice the line:
kSoldier.kAppearance.iGender = ((Rand(3) == 0) ? 2 : 1);
What this code means is it rolls a 3 sided die, which results in a random integer number between 0 and 2.
  • If the result is a 0, then kSoldier.kAppearance.iGender = 2;
  • Otherwise, kSoldier.kAppearance.iGender = 1;
If you'd like to read more about the "?" conditional operator: see Learning Java 2 course - ? Operator
kSoldier.kAppearance.iGender = 2 about 33% of the time, so we want that to be 50%. To do that we need to make the line look like this:
kSoldier.kAppearance.iGender = ((Rand(2) == 0) ? 2 : 1);
  • So, we need to realize that we're just changing that 3 into a 2, so that we have Rand(2). Simple, right?
  • Instead of looking for a 3, we're going to look for the bytecode of the Rand() function instead.
Since there's more than one call to Rand() in the function, we need to make sure we know where the one we're interested in appears in the file. Make sure to note down the offset of the correct location.
  • Copy and paste the contents of the decompiled version of the CreateTSoldier function from UE Explorer into a plaintext file.
  • Search the file for the string: "Rand"
We see it comes up 4 times, in the file, and it's the first instance that we're interested in.
Make sure to note down the offset of the correct location found in UE Explorer.
Note that the bytecode for it is A7
  • Start up your favorite hex-editor, and open up the XComGame.upk file in the location where you placed your decompressed UPK files, and look for the CreateTSoldier.Function.
  • Alternatively, the entire body of hex code (in ASCII format) for the CreateTSoldier function can be copied from the UE Explorer Hex Viewer using the Edit/Dump Bytes menu option and pasting the results into a text editor. (This is my preferred method -- amineri)
  • Search for the hex code A7, and note that there are 4 instances of it in the file. This is exactly what we hoped/expected to see. Again, we're interested in the first instance.
Offset(h) 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
00000170 00 00 45 9A A7 2C 03 16 25 16 02 00 2C 02 01 00 ..Eš§,..%...,...
  • Notice that the next two bytes are: 2C 03
The 03 looks interesting. But what does 2C mean? Well, searching Table From UE Explorer(NativesTableList_UDK-2011-08.NTL) or the 'NTL' in UE Explorer again for 2C gets us:
MirrorVectorByNormal
Hmm, that's unhelpful.... but, wait, there's another after that...
IntConstByte
Bingo! So, that byte-code says the next byte is to be treated as an integer. Nice... we Know (with a capital K) we're in the right place now.

From here, we presume you are going to implement the recommended way via changes to the loose, decompressed UPK file.

  • Open UE Explorer, paste the bytecode in your clipboard into the search feature, and make the change directly in the decompressed UPK, and save the file.
  • Reopen the modified UPK file in UE Explorer to verify that the change you intended actually happened:
kSoldier.kAppearance.iGender = ((Rand(2) == 0) ? 2 : 1);
  • To use the modified decompressed UPK file:
Rename the original UPK file and it's .compressed_save companion, and copy the modified decompressed UPK to the \XComGame\CookedPCConsole\ folder.
Run XSHAPE or ToolBoks to fix the file hash if you haven't disabled that check.

That's it! You're done! Now test it out.

Testing

You will want to have looked into How to enable the XCOM developer shell (which lets you switch between Strategic and Tactical game modes as well as select specific maps) and how to use the Developer Console. You can then use Console Commands to change normal game conditions for testing purposes. After you gotten familiar with some console commands, you might find the article on Keybind Commands - XCOM:EU 2012 of assistance as well, as they can also be used during game play.

As an example, here are the steps to use the console command line to check alien pods.

  1. Load a suitable saved game.
  2. While being in base (Strategy Game mode), type:
    • ForceMission_URB_PierA_Terror,
    • Switch to Mission Control and get ready to fly to "Chicago".
  3. Once landed in "Chicago":
    (Disable fog of war)
    • ToggleFOW
    (Reveal all actors)
    • set actor bHidden 0
    (Show alien pod locations)
    • AIDebugPods
    (Show alien unit names)
    • AIShowNames
    (Show cursor location)
    • ShowCursorLoc

Use other console commands as appropriate to your testing purposes.


Need to test through the first Tactical mission to get to the initial base, and don't care about the result? Add the following to your DefaultInput.ini file (see the Keybind Commands - XCOM:EU 2012 wiki article).

[XComGame.XComTacticalInput] .Bindings=(Name="F12", Command="SimCombat" )

Now start a new game and hit F12. The game will automatically determine the mission outcome and end the mission, taking you to the new XCOM Base. You can use it any time you don't care about mission results or simply want to get through them quickly to focus on Strategic level aspects.

It is also worth noting that you can 'click' on the Command Center globe icon, which will display the panic color codes for each country. If you have a game controller connected, you can then simultaneously use the controller to rotate the globe so you can see all countries panic status if your mod affects this display.


References

Referred to by this article:

Unreal Engine references:

 

That refer to this article: