Hex editing UPK files

From Nexus Mods Wiki
Revision as of 15:06, 25 June 2014 by Dubiousintent (talk | contribs) (Check the changes)
Jump to: navigation, search

Introduction

This tutorial will attempt to cover every aspect regarding hex editing upk files for XCom:Enemy Unknown. It is assumed you are already familiar with the DefaultGameCore.ini file options and that you are aware what changes can be achieved by just editing the ini file and what changes need of hex editing. If you know that, even if you don't know what hex editing is, you're in the right place.

Content

  • Section 2 Programs & Tools offers a brief description of the tools used for hex editing upk files, along with a download link and installation tips.
  • Section 3 Hex editing I: changing single values is a miscellaneous of several procedures to make a simple edit in a hex file organized in the form of a tutorial. It is aimed at beginners but it may contain useful tips for advanced modders.
  • Section 4 Hex editing II: re-writing functions and following are dedicated to advanced hex editing, and they no more take form of tutorial but are rather focused on getting as detailed and precise as possible.



Hex Editing Overview

Hex editing is what we need to do when we want to change something in XCom:Enemy Unknown 2012 that we can't achieve by merely editing the DefaultGameConfig.ini file (DGC.ini from now on). It means accessing the .upk files (Unreal Package files) where the game stores compiled classes and functions (stored as UnrealScript bytecode - similar to machine language - not a table of values like in DGC.ini, although to look at it's not much different), and edit them by means of at least two programs. Unlike with DGC.ini, when editing the upk files we do it via its hex representation, instead of editing readable text.

Hexadecimal format
Hexadecimal (hex for short) is a numbering system where a single digit can take up to 16 values, counting from 0 to 9 and then from A to F, consecutively, so with a single digit we can express a value ranging from 0 (0) to 15 (F). Like decimal counting, when we want to express a value greater than what we can express in a digit, we use more digits!, so to express the number '16' in hex we would write '10' instead, and so on. See Hexadecimal on wikipedia for more info.

Why hex editing
Due to technical limitations on modding XCom it is currently not possible to write in it's native language because we can't actually change the size of the files, so all that we can do is changing bytes of information.

Programs & Tools

See reference Modding Tools - XCOM:EU 2012 for links. Here are short descriptions of the necessary tools.

UE Explorer

An Unreal Engine decompiler. For more information on decompilers in general, see this Decompiler 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.

UPK Decompressor

We need it to de-compress upk files so we can edit them.

XSHAPE

We need it update the XcomGame.exe to run with modified upk files.

UPDATE: XSHAPE is no longer required to modify the SHA values. It has been found that modfiying some string values in the XComGame.exe file will prevent the executable from checking SHA values at all. See thread Finding the first step or the Modding Tools - XCOM:EU 2012 article for more information.

HxD HEX Editor

A general purpose hex editor. This is the program used to actually change the upk files.

Notepad++

Light-weight text editor with good search functionality and other cool stuff that is pretty useful when hex editing.

UPK Extractor

This program lets you extract the files from uncompressed upk files.

WinMerge

WinMerge lets you compare text for differences and such.

JPEXS Flash Decompiler

JPEXS is a useful tool for decompiling actionscript file, once they have been extracted from the upk.

Hex editing I: changing single values

When first attempting to hex editing a upk file, it is strongly recommended that to start by replacing a single value for another value of the same type (i.e. replacing one number with another). This chapter will try cover every step necessary to achieve this; more advanced changes to the upk files will be discussed in later chapters.

A word of advice

Hex editing your upk files is an easy way to screw up your game, so a few things you should know before jumping into it:

  • Making an incorrect change can cause the game to crash on start-up, and it won't show any error message that could tell what is wrong.
  • Making an incorrect change can also cause the game to crash when the changed code is executed. So...
  • Make back-up files before any change.
  • Document every change made so if one change is proven wrong it can be easily reverted.

Failing to do this, and continuing to blindly change hexes without direction will eventually lead the game to a point of no return - where the crash-causing error can no longer be located and the only way to fix it will be re-installing the game and thus loosing the changes made so far. There's no need to reach so far; just keep organized and save yourself a few headaches.

Preparing the ground

Uncompress upk files
Most mods, if not all, edit these two upk files: XComGame.upk and XComStrategyGame.upk. So the first recommendation is to decompress both of them using UPK Decompressor, then make a back-up of both uncompressed files and store them in a safe place (a backups folder is always useful).

Export UPK files
This will allow you to search through all the UPK's content using Notepad++. It is an incredibly powerful tool so it is worth using. To export the UPK files: first open them in UE Explorer; then, for each file, go to the Tools menu >> Exporting >> Export Classes. (Note: there is a second "Tools" menu below the standard Windows Interface)

Browsing UPK files with UE Explorer

Browsing files

UE Explorer Object/Class View
When attempting to make a change to the game we need to know which function we want to edit. More specifically, we need to know the package or file (XComGame.upk or XComStrategyGame.upk most likely), then we need to know the class which has the function we are after. Just knowing the file won't help us much unless we are given a unique hex string (see below). Once we find the data we want to change, open the file with UE Explorer, select the "Objects" tab on the left (see picture below, step 1), and we'll see an unsorted list of classes within that file. Write anything on the search field below to filter results (2), and erase after writing anything to make it sorts the list alphabetically. Once you locate the desired class, click on the "+" icon to expand the class and then to expand functions (3). Clicking on any of them will display it's code on the right screen (4).

However, code can't be changed in UE Explorer - it is a decompiler, not a compiler. We need to get its hex representation and edit the UPK file with the hex editor. Not only do we need to know the hex representation for the numbers we want to change (that could be deduced without the need to look at the code) but we need to get them "in context". This way, when we are actually editing the UPK file we do it with absolute certainty that what we are changing is what we want to change and nothing else.

Getting function hex code
To get the function in hex just right-click on the function name in UE Explorer (4), and select "View Buffer" (5), not Table Buffer. This will open a new window with the hex for the whole function. We'll cover later how to make use of it.

Manipulating hex code

Once we've located the function we want to change and we have its hex code, we'll want that hex code in a place where we can edit it. So while in "View Buffer" in UE Explorer, we click Edit, then Dump Bytes. This copies the hex buffer to the clipboard. Then, open Notepad++ and paste it into a text document. It will show each byte separated by "-", so to make it more readable we can select the whole text (<Ctrl+Home>, then <Shift+Ctrl+End>), and make a search and replace (<Ctrl+H> opens the search-and-replace window). There in "find what" type a hyphen, and in "replace for" enter a blank space. Finally, select replace all and it's done. It may be useful as well to break the code into lines of 16 bytes, to match UE Explorer's buffer view, but beware it may not perform searches as desired because of the line breaks.

Locating a hex value within a function

Now comes the fun part. There are three possible approaches to find a specific value inside a function hex code:

  1. Cracking down the entire function so we know exactly what is what. This isn't recommended if our aim is just to change a single value, and it will require a deeper knowledge of hex editing, but it's definitely possible.
  2. Direct search: we'll need to know the hex representation for the value we're looking for. If it's a number we can use Windows' calculator in programmer mode to get it in hex, and try searching for that number preceded by "2C" or "24" (so if we are looking for the number 17 we'll search in the hex for "2C 11" or "24 11" (If these numbers don't make sense to you check again how hexadecimal works). If we are lucky enough we'll find only one incidence or so few that judging from the order in which they appear and how far each is from the beginning we'll be able to tell which one to change. But beware when searching for such short hex strings, there may be other coincidences that in other contexts may mean a different thing, maybe a "2C 11" if preceeded by "07" or "06" may mean a completely different thing. In these cases where the search outputs many results and it's not easy to tell which one is the good one, we'll have to use next method:
  3. Looking at view buffer table:
    UE Explorer Hex Viewer
    That's right! Sometimes it's the only way we've got to get a proper hex string. Remember we find it by right-clicking on the function name and selecting "View Buffer". There we have two means to get extra info from bytes:
    1. Hovering the mouse over the hex elements: The first three lines can be ignored for now, as they represent the function header (this will be covered in further chapters). Only hex value that are underlined will show display a "pop-up hint" when the mouse is hovered over the hex value. Every few bytes it shows a label giving the decompiled description of the element examined. That is telling you where each element starts, and judging from that you can effectively know how many bytes the element takes. You'll find there are values that take more space than others (this will be covered later), but by now the only thing that matters is locating the value "in it's context".
    2. Selecting a byte: Still in UE Explorer, View Buffer, if clicking on a hex element the columns on the left will show what it could mean depending on the data type it represents, which depends on context, as we will learn.

At this point there aren't many useful tips to give. In the beginning it may convenient to trace the entire function as a way to get used to how things appear in hex (you'll see it's not the same text translated character by character into a numeric coding - it follows its own rules - but it shouldn't be too difficult to follow the function in hex in the view buffer mode (in UE Explorer) while also having the decompiled function in Notepad++ or the main view in UE Explorer). Once we are certain we've found the value we want to change, copy a longer hex string to perform a search within Notepad++ or break the code in Notepad++ into lines of 16 bytes so we can just count the line number.

Whatever the chosen method we use, our final aim is having a hex string long enough to be unique within the whole upk file. A good way to achieve this is to get a single string covering from the beginning of the function (header included) to the value we want to change, so when we search for it in the hex editor, the last highlighted character is the one to replace.

Editing UPK files

At this point it is assumed we already have a unique hex string that will help us locate the value we want to change inside the UPK file with no possibility of finding the wrong hex codes. To edit upk files we'll use a hex editor such as HxD, open the file we want to change, and perform a search (<Ctrl+F>), searching for that unique hex string. Just remember to select "Hex string" instead of "Text". If everything has been done as described here we should now have found the value we were after. Just for precaution hit the right arrow, so cursor positions itself right after the searched code, and perform the same search again. A message telling that it couldn't be found is the confirmation that the hex string was indeed unique (this check isn't necessary if the hex string included function header, since those are unique, but it doesn't hurt to take some precaution). Getting again to the value to change is just a key combo (<Ctrl+Home>, then <Ctrl+F>, then <Enter>).

Remember to make a backup before changing the file!

To actually edit a byte just highlight it selecting it with the mouse or searching for the text, and simply write over it, or <Ctrl+B> to paste-over whatever was copied into the clipboard (useful for replacing long strings), or right click on the selected text and select "Fill selection". This will prompt a window where you can input the replacement code. You'll have to close UE Explorer so the hex editor can save the file.

Check the changes

Time now to check the changes we've made back in UE Explorer. It should be easy to tell if the change has resulted in desired effect or not.

If everything is OK, the last step is removing the companion <UPK filename>.uncompressed_size file and running XSHAPE.bat, which recomputes the checksum for the UPK, and writes the new value into the EXE file - this lets the game run the newly modified UPKs. However, see Disabling Hash checks in Recent Discoveries below, which eliminates the need for XSHAPE at all.

If the game doesn't crash on start up you may be 50% sure your edit will work :p. Now getting serious, when we're sure of the changes we've made and checking UE Explorer shows the code modified as expected it's pretty much 100% certain the edit will work, unless we're changing more than just one value and got into re-writing pieces of functions - that's coming next.

Hex editing IA: changing blocks of hex code

This is essentially the same as changing single values.

To apply blocks of hex-code: Do a search/replace on the entire string block of code. Step-by-step below.
Tip: Blocks of hex-code (anything more than a couple of bytes) should first be placed into a text file, rather than trying to hex enter them byte-by-byte manually. This is the essence of a mod text file.

The following assumes the use of HxD, Notepad++, and UE Explorer.

Remember to make a backup before changing the file!

  1. Open Notepad++ with the mod text file containing the blocks of hex-code.
  2. Triple click on the original hex in your mod file to select the entire block, and copy to the clipboard.
  3. Switch to HxD, Ctrl-F to find, select hex, search all, paste hex from the clipboard into search box, hit search.
    HxD should find and highlight the hex block, indicating that everything is as it should be
  4. Switch to Notepad++, triple click on the new hex to select the entire block, and copy to the clipboard.
  5. Switch to HxD, Ctrl-R to replace, select hex, search all, confirm no.
  6. Paste hex from the clipboard into the replace box (original hex is auto-populated into find box because of the previous find operation)
  7. Click on replace button.
  8. New hex should be colored red indicating it has changed. Ctrl-S to save the changes.
  9. Switch / Open UE Explorer (depending on version).
  10. Reload / Load the UPK and verify that the new file decompiles correctly

Hex editing II: re-writing functions

If you've succeeded at changing several hex values, are already confident doing so, and want to take it one step beyond and change bits of functions or rewrite them entirely: here you'll find the information you need to achieve it.

Please bear in mind this section is still in an early stage of development, and in time it may grow in content and accuracy.

For another tutorial, written from the perspective of someone who had never had prior coding experience before working on XCOM:EU 2012, see the Rewriting Hidden Potential - Tutorial thread in the Nexus XCom Mod Talk Forum. This one walks you through, step-by-step, the process of changing an existing function (the Second Wave: "Hidden Potential" option) to work differently.

UnrealScript

UnrealScript is the Unreal Engine's scripting language. It is a high-level, object-oriented, strongly-typed, event-driven programming language very similar to Java and C++. It uses class single inheritance, it does not have object wrappers for primitive types, and it supports operator overloading, but not method overloading, except for optional parameters.

Programing basic concepts

Please refer to these Wikipedia articles to get started:

Data Types

  1. Primitive types
    1. Int
    2. Byte
    3. Bool
    4. Float: Designated via the 0x1E token. Convert float values to IEEE standard representation with IEEE-754 Floating-Point Conversion
    5. String
    6. Name
    7. Enum: Use XCOM Reverse enum Lookup tool
  2. Reference types
    1. Object
    2. Actor
    3. Interface
    4. Class
    5. Delegate
    6. Pointer
  3. Composite types
    1. Struct
    2. Static array
    3. Dynamic array
    4. Multi-dimensional arrays
    5. Map

Refer to this document for a description of each of these elements.

Hex values

Each "element" in a function code (variables, operators, literals, and other semantical or syntactical elements, such as sentence-ending tokens, etc.) has a hex representation. Some of them, as we'll learn, are represented using one single byte, while some others require additional following bytes to complement them. Those elements, though, always require the same number of bytes (each element type always has the same length) and the additional bytes are always placed after the relevant byte, so the first byte of an element is what allows us to identify it. The remaining bytes, if any, either represent a sort of index (functions and variables most notably) or they represent an offset or an absolute position in the code, which is based on the code's Virtual Size (this will be covered later).

Here's a list of hex values.

According to this data there are elements that show different possible hex values. So far no issues have been found in using any of them.
Most, if not all of the tokens that take several bytes will be explained in detail in this document. Anyway here's a quick reference to the most common elements' hex size. Remember that you can check each token's size for yourself with UE Explorer, hovering the mouse over the hex code in the View Buffer screen, as we'd seen before.

Tokens that take more than one byte:
Remainder of the bytes represent an index:

LocalVariable = 0x00 (+4 bytes)
InstanceVariable = 0x01 (+?? bytes)
DefaultVariable = 0x02 (+?? bytes)
etc

Remainder of the bytes represent an offset or position in the function's virtual size:

Switch = 0x05 (+?? bytes)
Jump = 0x06 (+2 bytes)
JumpIfNot = 0x07 (+2 bytes)
Case = 0x0A (+2 bytes)
etc

Sentences & Operators

Not every element present in a function necessarily appears in the hex code exactly as it is nor in the same order or position we find it in the function. Sentences though come one after another, and in order.

Prefix'd operators

Let's talk now about how the different elements are arranged in a sentence, and we'll start taking as example a simple sum operator. To sum 4 and 5 we'd normally write it like this: 4 + 5 using what in mathematical terms is called infix notation, since the operator (+) is in the middle. But, once compiled, the game engine treats operators differently and places them at the beginning of the expression, using what is called prefix notation, so the same operation as before would be represented as: + 4 5. It is important to understand this because elements in hex code will appear in "prefix order" as a result.

If you want you may think of it as the game engine sort of considering operators like functions, that require exactly 2 parameters. So in hex view there wouldn't be a "sum operation" but there would be a "sum function" which would sum the next two elements.

Multiple operators

The fact that (most) operators "operate" with two elements or values doesn't mean we cannot sum three numbers, we'd just need to use two sum operators to do so; but in no way could we sum three numbers using only 1 sum operator. And this has an important significance when considering the different operations that take place in an expression. In the case of a sum, order doesn't matter, as you well know, but there are other cases where order is of vital importance. If you're already familiar with programming procedures, if using that trick of considering operators like two-parameter functions, you'll find it easy to tell the order you must write elements and operators according to this "prefix" rule. Otherwise it may help you as well to recall that every mathematical operator needs two values, and one or both of those values could in turn be the result of other operations. If that is the case where the value of an element used in an operation depends in turn of the result of another operation, you may consider as if the game stacks each operation LIFO (Last In, First Out) in the order they appear on top of previous pending operations. Once the uppermost operation on the stack has it's two "parameters" it can complete the operation, so that operation and it's parameters are removed from the stack, and the resulting returned value is passed to the next pending operation that is now on top of our imaginary stack as one of it's parameters, and thus until all operations are resolved. We'll expand this a little bit later but now we need to talk about another very common element before we can see some real examples.

EndFunctionParms

The EndFunctionParms token (0x16) is used to indicate that all the required arguments have been passed to a function or operator so it can execute now and retrieve whatever result it may return. This is valid both for class functions and for operators like mathematical or logical operators.

A rule of thumb to know whether some element requires an EndFunctionParams token is using that trick of considering every element a function; if it requires 2 "parameters" it will need an EndFunctionParams token after those, if on the other hand it only takes 1 "parameter" it doesn't use the EndFunctionParams token. For this exercise it may help to think about the 0x2C IntConstByte item as a function that takes 1 parameter and returns an Integer value; as it only takes 1 parameter it doesn't use a 0x16 EndFunctionParams token, unlike a sum. The same is true for 0x07 JumpIfNot token (we'll see this later), etc. There is though an exception to this rule: the Rand (0xA7) native function token, which takes 1 parameter and requires EndFunctionParams token 0x16. {Need confirmation of the reliability of this method.}

While somewhat reliable as a "rule of thumb" the following 'unary' operators all require the 0x16 EndFunctionParams token:

  • Increment operator: "++"
  • Decrement operator: "--"
  • Negation operator: "!"
  • Rand operator: "Rand"

The following tokens do NOT require a 0x16 EndFunctionParams token:

  • Return token: 0x04
  • Switch token: 0x05
  • Jump token: 0x06
  • JumpIfNot token: 0x07
  • Case token: 0x0A
  • Let token: 0x0F
  • Explicit type-cast token: 0x38
  • Ternary token: 0x45
Hex code for an expression with multiple operators

Time now to see some hex code. Let's consider our last example: 4 + 5, which using this "prefix" method becomes + 4 5. Now checking the hex values list we see we can express numbers using hex tokens ByteConst(0x24) or IntConstByte (0x2C) (it isn't truly that easy to guess just looking at the list, but experience have proven those are the items to use). We can also see that we can express the sum operator as 0x92. So the operation in hex would look like: 92 2C 04 2C 05 16.
92 ------> Sum operator. Next two elements (not bytes!) ought to be the numbers to sum
2C ------> Indicates the next byte is an Integer Number
04 ------> Number 4
2C 05 -> Integer Number 5
16 ------> End sum operation, so result is calculated.

Now let's see how we'd write in hex the following expression: 3 * (4 + 5). First we should identify the operations that take place here and the elements involved in each one. In this case there is a sum that involves two elements, which are numbers 4 and 5; and there is another operation, a multiplication, that involves two elements, number 3 and another element which is the result of previous operation. Being aware of this, knowing that operations stack LIFO and that hex code for multiplication is 0x90 we have all we need to write it out in hex, but first let's analyze how to write it in decimal numbers conforming to this "prefix" syntax. It could be written this way:
* 3 + 4 5
Here we first tell the game engine we want to perform a multiplication, so the engine understands the next two elements will be the values to multiply. First we give a 3 as the first element in the multiplication, and where the engine expected the second number to multiply we give it instead a sum operation, so the engine understands the second value that is left to complete the multiplication will have to wait until the next operation (sum) is finished. Now, as usual when a sum operation is started, the engine expects the next two elements to be numbers to sum. In this case we give it two numbers (no more chained operations) so the engine performs the sum, and when it gets the result (9) it passes that to the previous but still pending operation, so the multiplication finally gets the second value it was waiting for and can now complete the operation and multiply 3 by 9.

We could also write it as: * + 4 5 3 which would be expressed as (4 + 5) * 3 but it is exactly the same although quite less clear in the hex. If you look at it closely it is the same operation, we've just swapped the order of the elements in the multiplication, so first element is the sum of 4 and 5, and second element is number 3.

Ok so now let's get back to our previous, clearer version and let's write it in hex. It would be:

Infix: 3 * (4 + 5)
Prefix: * 3 + 4 5
Hex: 90 2C 03 92 2C 04 2C 05 16 16
90 -----> Multiplication token
2C 03 -> Integer Number 3
92 -----> Sum token
2C 04 -> Integer Number 4
2C 05 -> Integer Number 5
16 -----> End sum (4 + 5)
16 -----> End multiplication 3 * 9

Let's see again the other example:
Infix: (4 + 5) * 3
Prefix: * + 4 5 3
Hex: 90 92 2C 04 2C 05 16 2C 03 16
90 -----> Multiplication token
92 -----> Sum token
2C 04 -> Integer Number 4
2C 05 -> Integer Number 5
16 -----> End sum (4 + 5)
2C 03 -> Integer Number 3
16 -----> End multiplication 9 * 3

Lessons Learned

I figured I would point out a couple of potential trouble-spots (which have caused me a lot of headaches in the past) that could cause issues in other situations.

  • Return Values in context statements
This error is really common because UE Explorer doesn't really label or display these.
for example, In XGFacility_Barracks.DismissSoldier say you constructed the line:

//kSoldier.GiveBottomTreePerks()
19 00 73 31 00 00 0B 00 D3 52 00 00 00 1B D1 13 00 00 00 00 00 00 27 16 

which UE Explorer decompiles just fine. However there is a secret bug lurking (in this case it doesn't matter because you aren't using the return value -- in fact, GiveBottomTreePerks doesn't even have a return value!).

The trick is in the D3 52 00 00 references, whose resolved name is : "XGStrategySoldier.HasPsiGift.ReturnValue". If you were actually trying to assign and use the results of the return value this would be a crashing bug. And it's really sneaky / hard to find-or-fix. For this particular example technically you'd set those byte to 00 00 00 00 as that's the value used for a null return. But it runs just fine without it.

I'm sure the real Unreal Compiler automatically inserts the correct ReturnValue reference into the context statement, but since we're modding we have to do it manually. The easiest way to find the ReturnValue of a function is by using the UE Explorer "View Managed Properties" Dialogue for the function. The ReturnValue will be given as a Decimal integer value (which you have to convert to LITTLE_ENDIAN hex).

Update: Actually, it is safe to use null-object references according to Unreal Script Variables:

"Variables that refer to actors always either refer to a valid actor (any actor that actually exists in the level), or they contain the value None. None is equivalent to the C/C++ NULL pointer. However, in UnrealScript, it is safe to access variables and call functions with a None reference; the result is always zero."

  • Differences in types of "==" operators
In XGSoldierUI.DismissSoldierActionCallback, say you disabled a conditional:

//if((GENELABS()) != none)
07 9C 00 77 1B F2 10 00 00 00 00 00 00 16 2A 16 

by changing the 77 token into a 9A token. However 77 is the "!=" operator token for class comparisons, while 9A is the "==" operator for integer comparisons. So this effectively works because the comparison of the GENELABS() class object (as an implicit cast to integer) doesn't equal none (it can't), which results in false, skipping the conditional.

The "==" operator for classes is actually 72, while the "!=" operator for integers is 9B. Floats, strings, vectors all have their own "==" and "!=" operators. Bytes don't have comparison operators, which is why you'll always see them cast to integers before doing a comparison (using 38 3A).

Another effective (if somewhat messy) way to skip conditional is to change the 07 into a 06, changing it from a conditional to an unconditional jump. I use this method all the time when debugging.

  • Removing error checking statement
This one isn't really a byte code error, but suppose in XGFacility_Barracks.DismissSoldier you removed the line:

//if(kSoldier == none)
07 11 00 72 00 73 31 00 00 2A 16 

in order to free up space. While it appears to work, if begin the function by using:

//if (kSoldier.GetStatus() == 0)
07 66 00 9A 38 3A 19 00 73 31 00 00 0A 00 7D 53 00 00 00 1B 51 13 00 00 00 00 00 00 16 38 3A 24 00 16 

This can be the source of maddening intermittent errors that users end up reporting. If the function is ever (for some reason) called with a null kSoldier, the game will crash.

Hex editing III: extending/replacing functions

(The following is derived from the Nexus XCOM Mod Talk Forums Expanding function size in UPK, and UPK Utils threads.)

Prior to Dec 2013, XCOM modders were constrained to making changes to existing functions that did not alter the byte size of the compiled code. However, investigations into the changes brought to the code by the release of Enemy Within led to the discovery by wghost81 that it was possible to alter the parameters of the ExportObjectList table in the UPK Package Header. (See the wiki article UPK File Format - XCOM:EU 2012 for the description of the Package Header.) This permitted adding a new or replacement function to the end of the package, of any size. The vanilla function would be left intact for reference or reversion purposes, and the replacement would be used instead. Object data are extracted by offset in the UPK file. You leave the original data where they are, append new data and change the offset in the ObjectList. You can move any number of functions in this manner, as long as you append the new additions to the end of file and update the ObjectList offsets accordingly. The results are compatible with all existing tools, as only existing UnrealScript methods are utilized.

wghost81 then developed and released a set of UPK Utilities (see Modding Tools - XCOM:EU 2012) for analyzing and patching uncompressed UPK files in this manner. These include a GUI version of the command line PatchUPK tool, which can apply a modfile (similar is structure to a ToolBoks Custom Mod file) to a vanilla OR modified UPK. The C++11 source code is available and common libraries are employed, which should enable the tools to be compiled for other platforms such as the Apple Mac OS.

Super Functions

Super functions are called to invoke the method of an identical name within a child class.

For example: working with the function PrefersLowCover, which is present in the base class XGAIBehavior as well as 3 child classes: XGAIBehavior_Sectoid, XGAIBehavior_ThinMan, and XGAIBehavior_SectoidCommander. In vanilla this function makes Thin Men and Sectoids prefer low cover on Easy and Normal difficulties. The goal is to modify this in general to make all units prefer low cover only if they have the Low Profile perk.

The trick is to not use the 1B virtual token identifier (combined with a simple namelist reference; see ExportObjectList table in the UPK Package Header in the wiki article UPK File Format - XCOM:EU 2012), but instead to use the 1C "final function" token combined with a direct objectlist reference to the specific function.

A virtual call to PrefersLowCover looks like:

// PrefersLowCover()
1B 1F 65 00 00 00 00 00 00 16

Where 0x651F is a namelist index to the string "PrefersLowCover" in the namelist.

To generate a specific call to super.PrefersLowCover() in XGAIBehavior_Sectoid.PrefersLowCover, the format is instead:

// return super(XGAIBehavior).PrefersLowCover()
04 1C E7 9B 00 00 16 

Technically XGAIBehavior_Sectoid is a child of XGAIBehavior_Psi, which is in turn a child of XGAIBehavior, which is why UE Explorer puts in the explicit XGAIBehavior reference.

In this case the 1C token is followed by 0x9BE7, which is an objectlist reference to the specific function XGAIBehavior.PrefersLowCover.

For the case of XGAIBehavior_ThinMan, which is a direct child of XGAIBehavior, UE Explorer decompiles the same hex bytes as:

// return super.PrefersLowCover()
04 1C E7 9B 00 00 16 

With this technique you can change game behavior to use your replacement function instead of a vanilla version.

UPK Utils Modfile

Modfile is a simple human-readable text (.txt) file. PatchUPK is fully compatible with ToolBoks Custom Mods: it can read and implement all the changes found there.

Modfile consists of keys (NAME=VALUE), sections ([SECTION_NAME]) and comments. Comments are begin with a ({) and end with a (}). You may place comments anywhere; they also can be multi-line. Right now PatchUPK is case-sensitive, so be careful!

List of supported keys and their allowed values:

  • MOD_NAME, AUTHOR and DESCRIPTION are self-explanatory. :smile: Value is simple text. Can be multiline.
  • UPK_FILE - name of UPK file to patch.
  • OFFSET - dec or hex (0x) value.
  • FUNCTION - full function name to patch.
  • REL_OFFSET - relative offset, dec or hex (0x) value.
If absolute offset value is set through OFFSET or FUNCTION key, REL_OFFSET is added to that value, so you can patch parts of function code without a need to specify it's full offset.
  • FUNCTION_FILE - file (with path) to read data from. Can be used with OFFSET or FUNCTION or by itself, if file name has Full.Function.Name.Function format.
  • NAMELIST_NAME - change namelist name. Value is of OLDNAME:NEWNAME.
  • EXPAND_FUNCTION - move and expand function by its name. Value is Full.Function.Name:NEWSIZE.

List of supported sections:

  • [MODDED_HEX] - section which contains modded space-separated hex data (as in ToolBoks custom mod).
  • [BEFORE_HEX] and [AFTER_HEX] - hex data for search-and-replace style patching,
  • [/BEFORE_HEX] and [/AFTER_HEX] are permitted, by not used anyway, since parser uses different method to find data blocks.

Command line syntax: PatchUPK modfile.txt [PATH_TO_UPKS]

[PATH_TO_UPKS] is optional (omit the square brackets). If the path parameter is omitted, UPKs are expected to be in the current working directory.

Some examples

Note these are all related to implementing a single function (XGStrategyAI.GetAltWeapon:300) change.

  • Move and expand:

UPK_FILE=XComStrategyGame.upk
EXPAND_FUNCTION=XGStrategyAI.GetAltWeapon:300

  • Find and replace:

UPK_FILE=XComGame.upk
[BEFORE_HEX]
CC 04 00 00 18 03 00 00 0F 00 FF B2 00 00 25
07 C9 04 96 00 FF B2 00 00 2C 04 16 07 51 00
9A 38 3A 35 7A B2 00 00 7C B2 00 00 00 00 1A
00 FF B2 00 00 01 A6 B2 00 00 38 3A 24 10 16
04 0B 06 BB 04 07 BB 04 9A 38 3A 35 7A B2 00
00 7C B2 00 00 00 00 1A 00 FF B2 00 00 01 A6
B2 00 00 38 3A 24 00 16 0F 35 7A B2 00 00 7C
B2 00 00 00 01 1A 00 FF B2 00 00 01 A6 B2 00
00 24 10 07 BF 03 81 2D 01 88 B2 00 00 16 0F
00 FE B2 00 00 25 07 BC 03 96 00 FE B2 00 00
36 35 42 00 00 00 43 00 00 00 00 00 01 95 B2
00 00 16 07 DA 01 9B 38 3A 35 3D 00 00 00 3F
00 00 00 00 00 10 00 FE B2 00 00 35 42 00 00
00 43 00 00 00 00 00 01 95 B2 00 00 38 3A 24
00 16 55 35 7B B2 00 00 7C B2 00 00 00 00 1A
00 FF B2 00 00 01 A6 B2 00 00 7D 00 1B 54 0F
00 00 00 00 00 00 35 3D 00 00 00 3F 00 00 00
00 00 10 00 FE B2 00 00 35 42 00 00 00 43 00
00 00 00 00 01 95 B2 00 00 35 3A 00 00 00 3F
00 00 00 00 00 10 00 FE B2 00 00 35 42 00 00
00 43 00 00 00 00 00 01 95 B2 00 00 16 16 07
C4 02 9B 38 3A 35 3C 00 00 00 3F 00 00 00 00
00 10 00 FE B2 00 00 35 42 00 00 00 43 00 00
00 00 00 01 95 B2 00 00 38 3A 24 00 16 55 35
7B B2 00 00 7C B2 00 00 00 00 1A 00 FF B2 00
00 01 A6 B2 00 00 7D 00 1B 54 0F 00 00 00 00
00 00 35 3C 00 00 00 3F 00 00 00 00 00 10 00
FE B2 00 00 35 42 00 00 00 43 00 00 00 00 00
01 95 B2 00 00 35 39 00 00 00 3F 00 00 00 00
00 10 00 FE B2 00 00 35 42 00 00 00 43 00 00
00 00 00 01 95 B2 00 00 16 16 07 AE 03 9B 38
3A 35 3B 00 00 00 3F 00 00 00 00 00 10 00 FE
B2 00 00 35 42 00 00 00 43 00 00 00 00 00 01
95 B2 00 00 38 3A 24 00 16 55 35 7B B2 00 00
7C B2 00 00 00 00 1A 00 FF B2 00 00 01 A6 B2
00 00 7D 00 1B 54 0F 00 00 00 00 00 00 35 3B
00 00 00 3F 00 00 00 00 00 10 00 FE B2 00 00
35 42 00 00 00 43 00 00 00 00 00 01 95 B2 00
00 35 38 00 00 00 3F 00 00 00 00 00 10 00 FE
B2 00 00 35 42 00 00 00 43 00 00 00 00 00 01
95 B2 00 00 16 16 A5 00 FE B2 00 00 16 06 C5
00 06 B8 04 55 35 7B B2 00 00 7C B2 00 00 00
00 1A 00 FF B2 00 00 01 A6 B2 00 00 2A 00 1B
54 0F 00 00 00 00 00 00 38 3D 35 6A B2 00 00
71 B2 00 00 00 00 01 82 B2 00 00 4A 16 16 55
35 7B B2 00 00 7C B2 00 00 00 00 1A 00 FF B2
00 00 01 A6 B2 00 00 2A 00 1B 54 0F 00 00 00
00 00 00 38 3D 35 69 B2 00 00 71 B2 00 00 00
00 01 82 B2 00 00 4A 16 16 55 35 7B B2 00 00
7C B2 00 00 00 00 1A 00 FF B2 00 00 01 A6 B2
00 00 2A 00 1B 54 0F 00 00 00 00 00 00 38 3D
35 66 B2 00 00 71 B2 00 00 00 00 01 82 B2 00
00 4A 16 16 06 C9 04 A3 00 FF B2 00 00 16 06
0B 00 04
[/BEFORE_HEX]
[AFTER_HEX]
A8 04 00 00 18 03 00 00 0F 00 FF B2 00 00 25
07 89 04 96 00 FF B2 00 00 2C 04 16 07 51 00
9A 38 3A 35 7A B2 00 00 7C B2 00 00 00 00 1A
00 FF B2 00 00 01 A6 B2 00 00 38 3A 24 10 16
04 0B 06 7B 04 07 7B 04 9A 38 3A 35 7A B2 00
00 7C B2 00 00 00 00 1A 00 FF B2 00 00 01 A6
B2 00 00 38 3A 24 00 16 0F 35 7A B2 00 00 7C
B2 00 00 00 01 1A 00 FF B2 00 00 01 A6 B2 00
00 24 10 07 7F 03 81 2D 01 88 B2 00 00 16 0F
00 FE B2 00 00 25 07 7C 03 96 00 FE B2 00 00
36 35 42 00 00 00 43 00 00 00 00 00 01 95 B2
00 00 16 0F 01 98 B2 00 00 38 3A 35 3D 00 00
00 3F 00 00 00 00 00 10 00 FE B2 00 00 35 42
00 00 00 43 00 00 00 00 00 01 95 B2 00 00 07
84 01 97 01 98 B2 00 00 25 16 55 35 7B B2 00
00 7C B2 00 00 00 00 1A 00 FF B2 00 00 01 A6
B2 00 00 7D 00 1B 54 0F 00 00 00 00 00 00 38
3D 01 98 B2 00 00 25 16 16 0F 01 98 B2 00 00
38 3A 35 3C 00 00 00 3F 00 00 00 00 00 10 00
FE B2 00 00 35 42 00 00 00 43 00 00 00 00 00
01 95 B2 00 00 07 79 02 97 01 98 B2 00 00 25
16 0F 00 57 B3 00 00 25 07 79 02 98 00 57 B3
00 00 35 39 00 00 00 3F 00 00 00 00 00 10 00
FE B2 00 00 35 42 00 00 00 43 00 00 00 00 00
01 95 B2 00 00 16 55 35 7B B2 00 00 7C B2 00
00 00 00 1A 00 FF B2 00 00 01 A6 B2 00 00 7D
00 1B 54 0F 00 00 00 00 00 00 38 3D 01 98 B2
00 00 24 00 16 16 A5 00 57 B3 00 00 16 06 E3
01 0F 01 98 B2 00 00 38 3A 35 3B 00 00 00 3F
00 00 00 00 00 10 00 FE B2 00 00 35 42 00 00
00 43 00 00 00 00 00 01 95 B2 00 00 07 6E 03
97 01 98 B2 00 00 25 16 0F 00 57 B3 00 00 25
07 6E 03 98 00 57 B3 00 00 35 38 00 00 00 3F
00 00 00 00 00 10 00 FE B2 00 00 35 42 00 00
00 43 00 00 00 00 00 01 95 B2 00 00 16 55 35
7B B2 00 00 7C B2 00 00 00 00 1A 00 FF B2 00
00 01 A6 B2 00 00 7D 00 1B 54 0F 00 00 00 00
00 00 38 3D 01 98 B2 00 00 24 00 16 16 A5 00
57 B3 00 00 16 06 D8 02 A5 00 FE B2 00 00 16
06 C5 00 06 78 04 55 35 7B B2 00 00 7C B2 00
00 00 00 1A 00 FF B2 00 00 01 A6 B2 00 00 2A
00 1B 54 0F 00 00 00 00 00 00 38 3D 35 6A B2
00 00 71 B2 00 00 00 00 01 82 B2 00 00 4A 16
16 55 35 7B B2 00 00 7C B2 00 00 00 00 1A 00
FF B2 00 00 01 A6 B2 00 00 2A 00 1B 54 0F 00
00 00 00 00 00 38 3D 35 69 B2 00 00 71 B2 00
00 00 00 01 82 B2 00 00 4A 16 16 55 35 7B B2
00 00 7C B2 00 00 00 00 1A 00 FF B2 00 00 01
A6 B2 00 00 2A 00 1B 54 0F 00 00 00 00 00 00
38 3D 35 66 B2 00 00 71 B2 00 00 00 00 01 82
B2 00 00 4A 16 16 06 89 04 A3 00 FF B2 00 00
16 06 0B 00 04 0B 0B 0B 0B 0B 0B 0B 0B 0B 0B
0B 0B 0B 0B 0B 0B 0B 0B 0B 0B 0B 0B 0B 0B 0B
0B 0B 0B
[/AFTER_HEX]

  • Rename function:

UPK_FILE=XComStrategyGame.upk
NAMELIST_NAME=GetAltWeapon:#GetPodProgs

Patch part of the function by relative offset:

UPK_FILE=XComGame.upk
FUNCTION=XGBattleDesc.InitAlienLoadoutInfos
REL_OFFSET=0x28
[AFTER_HEX]
A8 04 00 00 18 03 00 00 0F 00 FF B2 00 00 25 07
89 04 96 00 FF B2 00 00 2C 04 16 07 51 00 9A 38
3A 35 7A B2 00 00 7C B2 00 00 00 00 1A 00 FF B2
00 00 01 A6 B2 00 00 38 3A 24 10 16 04 0B 06 7B
04 07 7B 04 9A 38 3A 35 7A B2 00 00 7C B2 00 00
00 00 1A 00 FF B2 00 00 01 A6 B2 00 00 38 3A 24
00 16 0F 35 7A B2 00 00 7C B2 00 00 00 01 1A 00
FF B2 00 00 01 A6 B2 00 00 24 10 07 7F 03 81 2D
01 88 B2 00 00 16 0F 00 FE B2 00 00 25 07 7C 03
96 00 FE B2 00 00 36 35 42 00 00 00 43 00 00 00
00 00 01 95 B2 00 00 16 0F 01 98 B2 00 00 38 3A
35 3D 00 00 00 3F 00 00 00 00 00 10 00 FE B2 00
00 35 42 00 00 00 43 00 00 00 00 00 01 95 B2 00
00 07 84 01 97 01 98 B2 00 00 25 16 55 35 7B B2
00 00 7C B2 00 00 00 00 1A 00 FF B2 00 00 01 A6
B2 00 00 7D 00 1B 54 0F 00 00 00 00 00 00 38 3D
01 98 B2 00 00 25 16 16 0F 01 98 B2 00 00 38 3A
35 3C 00 00 00 3F 00 00 00 00 00 10 00 FE B2 00
00 35 42 00 00 00 43 00 00 00 00 00 01 95 B2 00
00 07 79 02 97 01 98 B2 00 00 25 16 0F 00 57 B3
00 00 25 07 79 02 98 00 57 B3 00 00 35 39 00 00
00 3F 00 00 00 00 00 10 00 FE B2 00 00 35 42 00
00 00 43 00 00 00 00 00 01 95 B2 00 00 16 55 35
7B B2 00 00 7C B2 00 00 00 00 1A 00 FF B2 00 00
01 A6 B2 00 00 7D 00 1B 54 0F 00 00 00 00 00 00
38 3D 01 98 B2 00 00 24 00 16 16 A5 00 57 B3 00
00 16 06 E3 01 0F 01 98 B2 00 00 38 3A 35 3B 00
00 00 3F 00 00 00 00 00 10 00 FE B2 00 00 35 42
00 00 00 43 00 00 00 00 00 01 95 B2 00 00 07 6E
03 97 01 98 B2 00 00 25 16 0F 00 57 B3 00 00 25
07 6E 03 98 00 57 B3 00 00 35 38 00 00 00 3F 00
00 00 00 00 10 00 FE B2 00 00 35 42 00 00 00 43
00 00 00 00 00 01 95 B2 00 00 16 55 35 7B B2 00
00 7C B2 00 00 00 00 1A 00 FF B2 00 00 01 A6 B2
00 00 7D 00 1B 54 0F 00 00 00 00 00 00 38 3D 01
98 B2 00 00 24 00 16 16 A5 00 57 B3 00 00 16 06
D8 02 A5 00 FE B2 00 00 16 06 C5 00 06 78 04 55
35 7B B2 00 00 7C B2 00 00 00 00 1A 00 FF B2 00
00 01 A6 B2 00 00 2A 00 1B 54 0F 00 00 00 00 00
00 38 3D 35 6A B2 00 00 71 B2 00 00 00 00 01 82
B2 00 00 4A 16 16 55 35 7B B2 00 00 7C B2 00 00
00 00 1A 00 FF B2 00 00 01 A6 B2 00 00 2A 00 1B
54 0F 00 00 00 00 00 00 38 3D 35 69 B2 00 00 71
B2 00 00 00 00 01 82 B2 00 00 4A 16 16 55 35 7B
B2 00 00 7C B2 00 00 00 00 1A 00 FF B2 00 00 01
A6 B2 00 00 2A 00 1B 54 0F 00 00 00 00 00 00 38
3D 35 66 B2 00 00 71 B2 00 00 00 00 01 82 B2 00
00 4A 16 16 06 89 04 A3 00 FF B2 00 00 16 06 0B
00 04 0B 0B 0B 0B 0B 0B 0B 0B 0B 0B 0B 0B 0B 0B
0B 0B 0B 0B 0B 0B 0B 0B 0B 0B 0B 0B 0B 0B 0B 53
[/AFTER_HEX]

There is a fully functional mod example in the Nexus Mod file archive UPK Utils under the TestMod folder called LargerPodsTest.txt.

Control Structures

Jump / Goto

Goto statements are quite simple. They are always 3 bytes long. The jump addresses (the objects of those statements) follow 06, 07, 0A, 58, or 2F tokens. (See Hex values XCOM Modding for each token's purpose.)

Syntax consists of a token such as 0x06 (EX_Jump), followed by a two byte value representing the jump offset. The two byte value is stored "little endian" as are all multi-byte values.

For example, a Jump address of 0x4A2 would be represented in hex as the sequence "06 A2 04".

Jump offsets are computed as offsets relative to the beginning of the current function. Since jump offsets are limited to 2 bytes, a jump offset cannot exceed 65535 bytes, or 64KB.

Jump offsets are measure in VIRTUAL bytes (bytes the code occupies when loaded into memory), not FILE bytes (bytes the code occupies in the file). The most straightforward way of determining jump offsets is to use the "View Tokens" view in UE Explorer.

Bertilsson's Jump Repair Tool is an online tool which will validate and repair jump offsets based on token data provided from UE Explorer 1.2.4.

Instructions how to use:

  • Get UE Explorer 1.2.4 beta or later (older versions are not compatible).
  • Copy modified Hex code and View Tokens data from UE Explorer into the tool.
  • Press Validate and Repair code button to begin validation and repair process.
  • The tool will now provide you with drop down selectors based on object code and high level numbering for any valid or invalid jump reference which will be part of the repair process.
  • When all invalid jump offsets have been corrected you will receive a new set of modified Hex code with recalculated memory jump offsets for 06, 07, 0A, 2F, 58 tokens and the header reference to the end of script.
  • Insert new Hex code from the tool into the UPK file using HxD or any other hex editor.

Limitations and how it works

The tool is basically a data miner that looks at the world as a bunch of view token lines which may or may not contain references to each other.
When user has manually selected a new target for an invalid one, the same offset difference is automatically also applied to the next following jump reference all the way to the end of function. This chain effect is automatically halted whenever it would result in a new invalid jump reference.
The tool is intended to completely and intuitively save you the trouble of recalculating the jump offsets by hand and to repair mistakes you may have done when adding new code.

Known bugs

A bit buggy user interface, currently being improved

The intended way to use the tool is:

  1. Export function (bytes) from UE Explorer into a separate mod file for the function you want to edit.
  2. Modify the mod file using HxD or any other hex-editor.
  3. Import the mod file back into UE Explorer to get new view tokens.
  4. Copy view tokens into the repair tool.
  5. Copy byte code into the repair tool (if you only want to verify valid header and jump offsets you can actually skip this step).
  6. Fix anything broken and adjust jump offsets to liking.
  7. Replace the byte code using HxD or any other hex-editor in the mod file.
  8. Import the new byte code from the mod file back into UE Explorer again.

If you have already done the editing by hand you only have to do step 4 and nothing else.

If you have created a complicated else if/else statement, you can simply verify in the tool that all jump offsets are pointing to valid targets (you will be informed about any identified issue) and then afterwards verify in UE Explorer that the object code looks as intended.

The reason it's recommended exporting/importing to a mod file from within UE Explorer instead just modding the .UPK file directly is:

  • You don't have to bother about file offsets.
  • You can move code around using CTRL + X + V without worrying that you will break the entire .UPK if you make a mistake.
  • You can quickly save and restore different versions of your modifications.
  • You can use CTRL + A to quickly copy and replace the entire function.

For discussion about this tool, see this thread New tool available ....

Conditional statements

If statement / JumpIfNot
Else statement
Switch case statement

For each loop

Data Structures

Arrays

Index accessing
Dynamic arrays

Struct

Objects

Object variables (member token)

Enums

An enum (also enumerated type or enumeration) is a primitive data type in UnrealScript. The possible values of an enum type are a list of identifiers, which can be compared not only for equality, but also for order.

See article Enum Expansion - XCOM:EU 2012.

Recent Discoveries

There have been a couple of recent (April-May 2013) discoveries that affect the need for or use of some of XCOM Modding tools. They are summarized here for reference.

Phoning Home

When using mods, it is necessary to prevent each game from connecting to it's update servers behind your back. However, the DNS entry is clearly for a vendor specific address. This appears to be a vendor verifier (i.e. "Firaxis Verifier", in this case) independent of those patches distributed via Steam. They may not be 'patches' per se, but merely replacements of certain files to ensure consistency. This is informally called 'phoning home' and initially was believed to be intended to be a Steam mechanism to prevent cheating in Multi-Player games. However, it has now been determined to affect single-player games as well.

PatcherGUI (as of v5.2) includes options to "Enable INI loading" and "Disable phoning home" for you. This is the easiest and recommended method.

If you use PatcherGUI, you can skip the rest of this sub-section. It's intended for those who have to deal with this manually.


Those interested in the mechanism involved in this 'phone home' process are referred to the Class: IniLocPatcher - XCOM:EU 2012 article.

This edit to the hosts file is not affected by Steam delivered patches or re-installing Steam and does not affect your ability to get updated when you go back to 'Online' mode for ANY reason (such as connecting to the Steam Store). Note this should be used in conjunction with disabling 'auto-updates' for your XCOM game in the Steam Library. Be aware, however, that since November of 2013 XCOM patches seem to disregard this Steam 'auto-updates' setting and have been known to apply regardless. Having a backup copy of your complete modded XCOM game tree current and available elsewhere is recommended as well.

At present, the EU 'phone home' process is known to overwrite Armors, Characters, and Weapons arrays of the EXE internal resource cache version of the DefaultGameCore.INI file, and the ...\My Documents\My Games\XCOM - Enemy Unknown\ file XComGameCore.INI file which is a merged copy from the DGC.INI and DLC content.

  • My Games\XCOM - Enemy Unknown\XComGame\Logs\EMS\
  • XComDLC.ini (XComGame.XComDLCManager)
  • XComGame.int (XComGame.XComDLCManager)
  • XComGameCore.ini (overwriting Armors, Characters and Weapons arrays)
  • XComMPGame.ini (overwriting a lot of MP related arrays)

These may be in My Games (if you have DLCs installed) or the <Steam install path> equivalent path, or both. If you are having problems with mods that alter one of these files not seeming to 'stick', check that your hosts file has the correct servers disabled according to the Launch.log as described below.

To determine where your game attempts to communicate, you want to examine your \My Games\<Steam Game folder>\Logs\Launch.log file. You are looking for lines similar to these:

The entries marked like so are:

  1. The Server IP address: 65.118.245.165
  2. The Server DNS Name: prod.xcom.firaxis.com

These are what you will place into the hosts file to block attempts to connect.

  • Start Menu > Right click on 'Notepad' (or any text editor), select "Run as Administrator"
    • File > Open > %systemroot%\system32\drivers\etc\hosts. 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. The value of the global environmental variable %systemroot% on your system can be determined by entering 'set' on the Windows command line, or as it's shortcut is called, the Command Prompt. 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. 65.118.245.165]. The '127.0.0.1' IP address is a local loopback address the prevents attempts to connect to either of the other addresses from ever leaving your computer.)

# Prevent XCOM:EU from Phoning Home
127.0.0.1 prod.xcom.firaxis.com
127.0.0.1 65.118.245.165

  • Save the file.

NOTE: The "Enemy Within" (EW) expansion to XCOM:EU 2012 uses it's own DNS and IP address entries:

# Prevent XCOM:EW from Phoning Home
127.0.0.1 prod.xcom-ew.firaxis.com
127.0.0.1 65.118.245.139

However, early reports (13 Nov 2013) that disabling these addresses in hosts will prevent EW from launching have been attributed to other factors, such as failing to also disable 'auto-updates'. Save game synching with Cloud Storage still functions correctly, even with these addresses disabled.

The XCOM-EW expansion is proof that other DNS and IP addresses can be utilized by the same or different games. Care should be taken to check the Launch.log file as outlined above for changes with each patch or major release.

Disabling Hash checks

Enabling INI loading

PatcherGUI (as of v5.2) includes options to "Enable INI loading" and "Disable phoning home" for you. This is the easiest and recommended method. See also the INI Loading Test entry.

The following is provided for background and those interested in the manual method.

Most likely reason for any failure to load the DGC.INI is that (assuming you have the EW version of the game) you modified the DGC.INI in the wrong folder tree. EU is under "XCom-Enemy-Unknown", while EW is under "XCom-Enemy-Unknown\XEW".

INI Loading Test

Try this to test that the loose DGC.INI file is loading:

  • Edit the DGC.INI as follows:
  • Replace the Original 'eItem_Shotgun' line 'Properties[1]=eWPAssault' entry with '=eWP_Anyclass' as shown below. You can just copy and paste this SINGLE line with any text editor. (Save your '.BAK' file to restore the original DGC.INI.)
  • Load any previous save where you are in the XCOM base (the Strategy game phase) or play a new game to that point, go into the Barracks, View Soldiers, and change the Loadout of a Support class (which couldn't without this change and doesn't have any other class restrictions that might prevent it, as is the case with a Heavy). The 'vanilla' DGC.INI that's in the embedded 'Resource cache' only permits an Assault to equip a Shotgun. With this change, any class can that doesn't have other built-in restrictions.
  • Anyone other than an Assault class equipping a Shotgun proves you are loading the DGC from the correct '\config' folder.

INI file size limitations

Increased Load Times

Enemy Within

Extending/Replacing Functions

In 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 Hex editing III: Extending/Replacing Functions for details.

References

Referred to by this article:


That refer to this article: