XCOM2 Discussion about "How Do I change XXX in the game?"

[Amineri]

There seems to be good progress being made with adding new stuff to the game, like flags, tattoos, etc, but a recurring question I'm seeing is "how do I change XXX in the game?", which is a different sort of question.

 

In the old EU/EW days, we'd simply hack into the hex and make the change directly to the XComGame.upk. However, given how amazingly popular (/s) that was, I don't think we'll be going to that as the default method for XCOM 2. ^_^

 

I'll list below the tools I've found for changing existing gameplay, in rough order of increasing complexity. As others get found/added, I'll try and keep the list updated.

 

----------------------

 

1) Configuration files

 

Config files are those files that end in *.ini. If the thing you want to change has a configuration variable that controls it, you're in luck! These are the easiest things of all to change.

 

To change your own game, you can directly edit the "Default" version of the config file in the XComGame/Config/ folder, but be warned that updates from Firaxis may well overwrite your changes.

 

To make a mod that applies config changes, create a mod with the SDK, and create a new file in the Config folder, named the same as the file you want to change, but with the "Default" prefix changed to "XCom", then use this info (https://udn.epicgames.com/Three/ConfigurationFiles.html) to control adding and removing lines during merge with the Default version.

 

--------------------

 

2) Kismet files

 

If the thing you want to change is handled in Kismet (e.g. Mission timers), then you can find the appropriate *.umap file with the Kismet, make your changes, then add the modified version to your mod project's Content folder, and the mod version will override the one in the game.

 

Pretty simple, but not quite as easy as config files

 

---------------

 

3) Class overrides

 

If you've gotten down here, the easy times are over. This requires some programming abilities.

 

XCOM 2 allows overriding classes when they are created at run-time using new or Spawn. (New is for things derived from Object, Spawn for things derived from Actor). This leaves out a few things, such as archetypes and game states, so it won't work for everything.

 

To override a class, add the following to an XComEngine.ini config file in your mod:

[Engine.Engine]
+ModClassOverrides=(BaseGameClass="ABaseClassName", ModClass="YourModClassName")

The mod class needs to extend the original base game class, using standard OOP inheritence techniques.

 

I've listed this at #3 in difficulty, since it's not too hard, but it's not good for mod compatibility, since only one mod can overwrite a particular class. Since the overrides are in a dynamic array, I'm supposing that it's the first one in the array that the native override code handles, so it's whatever mod that gets loaded first that succeeds at the class override.

 

------------------

 

4) UIScreenListener

 

Despite the name UIScreenListeners can be used for more than just making UI changes. UIScreenListener is a class implemented by Firaxis, which you can create a child class of. The UIScreenListener gets assigned a UIScreen in default properties that determines when the listener is called. If you leave that at none, it will be invoked for every UIScreen.

 

A good example of how to use this is the base game UIStrategyScreenListener. As in that example, you can simply drop some code into the OnInit() event and it will run at least once, and in fact will run whenever a new UIScreen is created, so it's a bit like polling, but controlled by the rate of user UI navigation.

 

------------------

 

5) X2EventManager events

 

Next up is using an event that's already triggered. EventIDs are names, and events are triggered with code that looks like :

`X2EVENTMRG.TriggerEvent('UnitMoveFinished', UnitState, UnitState, NewGameState);

The primary restriction here is that if the function you want to hook into doesn't have a TriggerEvent, there's not much you can do about that. We're limited by the number of TriggerEvent calls added to the base game code.

 

The other tricky bit here is that you have to have something already created to listen to the event. I generally use either a class override or a UIScreenListener to initially instance a game state, but this can also be put into template delegate code (effects, abilities, etc). Once you have that, you can register to listen to the event with code like :

local Object ThisObj;
 
ThisObj = self;
`X2EVENTMGR.RegisterForEvent(ThisObj, 'UnitMoveFinished', OnUnitMoveFinished);
 
function EventListenerReturn OnUnitMoveFinished(Object EventData, Object EventSource, XComGameState GameState, Name EventID)
{
    // YOUR CODE GOES HERE
    return ELR_NoInterrupt;
}

You'll going to want to have your EventListener handler in a gamestate. Gamestates are automatically serialized/deserialized when saving/loading, and as a bonus any registered events are also handled.

 

-------------------------

 

6) Total Replacement

 

This is the end of the line. You couldn't do anything else, so now you have to compile the entire XComGame.upk and replace the whole thing.

 

If you start a DefaultMod, all of the XComGame class files get copied into your mod, so you can just edit them there. When you build, you'll get a new XComGame.u. Unfortunately, that's not the final step, as that has to go through cooking before it can be used in a mod. Cooking isn't part of the regular build process, because it takes a long time. There is a way to run the game uncooked, but that's going to be mostly for development (performance is much worse, and it's really tough to distribute).

 

The really major downside of total replacement is that only one mod can do it.

 

For those of you who want to see how to run uncooked, I'll include the info hidden in this spoiler:

 

 

Setting up uncooked build manually

The following steps details how to set up XCOM 2 to use all uncooked assets, including an uncooked XComGame.u replacement created using the XCOM 2 SDK.

Building replacement XComGame.u

• In ModBuddy, create a new mod
• Select ‘DefaultMod’, name it as desired
• All files in XComGame should be copied over into the mod
• Modify game files as desired, build the mod
• After building, the new XComGame.u will be in 3 locations
• \Steam\steamapps\common\XCOM 2 SDK\XComGame\Script
• This is where the make command deposits script files after they are built
• \Steam\steamapps\common\XCOM 2 SDK\XComGame\Mods\TestFullConversion\Script
• This is where the SDK CompileScript copies the XComGame.u within the SDK folder after make command completes
• \Steam\steamapps\common\XCOM 2\XComGame\Mods\TestFullConversion\Script
• This is where the SDK CompileScript copies the full mod folder from the SDK to the actual game
• For this process, we will be running using the file in location (a)

Configuring game to run uncooked

These steps set up the game to run using mostly assets and scripts from the SDK folder. To avoid a bunch of copying, symlinks are used. Information on symlinks, what they are, and how they can be set up can be found here: http://www.howtogeek.com/howto/16226/complete-guide-to-symbolic-links-symlinks-on-windows-or-linux/. Symlinks are similar to shortcuts, but operate at a “deeper” level, being completely transparent to applications.

• To run XCOM 2 uncooked, 4 symlinks have to be created. A 5th optional one is required if running with a run-time debugger.
• Launch a command prompt, in administrator mode
• Create the symlinks with the following commands, filling out the correct paths
  • mklink /J "D:\Steam\steamapps\common\XCOM 2\XComGame\Content" "D:\Steam\steamapps\common\XCOM 2 SDK\XComGame\Content"
  • mklink /J "D:\Steam\steamapps\common\XCOM 2\XComGame\Script" "D:\Steam\steamapps\common\XCOM 2 SDK\XComGame\Script"
  • mklink /J "D:\Steam\steamapps\common\XCOM 2\Engine\Content" "D:\Steam\steamapps\common\XCOM 2 SDK\Engine\Content"
  • mklink /J "D:\Steam\steamapps\common\XCOM 2\Engine\EditorResources" "D:\Steam\steamapps\common\XCOM 2 SDK\Engine\EditorResources"
• If running with a run-time debugger (more info later), create a symlink
  • mklink /J "D:\Steam\steamapps\common\XCOM 2\Development" "D:\Steam\steamapps\common\XCOM 2 SDK\Development"
• Create a shortcut or batch file to run XCom2.exe found in D:\Steam\steamapps\common\XCOM 2\Binaries\Win64 (or Win32 if running 32 bit version), running with the commandline argument -NOSEEKFREELOADING
• Alternatively, enter the additional commandline argument within Steam, under Properties/General/Set Launch Options
• Launch the game
• It may take a few minutes to initially launch, as some shader caches will have to be rebuilt

Troubleshooting

After the symlinks are created, you should observe what appear to be folder shortcuts within the XComGame folder.

Note that unlike shortcuts, even though the linked folder is in the XCOM 2 SDK directory, even within Windows Explorer the directory appears to be located within the XCOM 2 directory.

Setting up run-time debugging

For run-time debugging I am currently using the debugger included here : https://github.com/Zinggi/UnrealScriptIDE/tree/master/Debugger/UnrealDebugger%2064%20bits

I downloaded the entire UnrealScriptIDE-master repository, but am currently only using the UnrealDebugger portion, although using the IDE in the future may be an avenue to explore.

After unpacking the UnrealScriptIDE, copy all *.dll files from \UnrealScriptIDE-master\Debugger\UnrealDebugger 64 bits\ into \Steam\steamapps\common\XCOM 2\Binaries\Win64.

After installing the UnrealDebugger files into the XCOM 2 game folder, launch the game in debug mode, either by launching from ModBuddy with Debug / Start Debugging (F5), or by launching the ModLauncher with either of the commands :

ModLauncherWPF.exe -allowconsole -log -autodebug

or

XCom2.Exe -allowconsole -log -autodebug -LANGUAGE=INT

In both cases the files run should be from the XCOM 2 (game) directory

However, currently the CompileScript in the SDK only builds .uc files without debugging enabled. Currently it is required to manually run the make command with the -debug commandline option in order to make .uc files that allow for run-time debugging using UnrealDebugger.

Running a make command manually involves executing the XComGame.exe in the XCOM 2 SDK directory (not game), with additional commandline arguments. A typical command looks like :

XComGame.exe make -nopause -mods LW_OfficerPack "D:\Steam\steamapps\common\XCOM 2 SDK\XComGame\Mods\LW_OfficerPack\"

Adding an additional commandline argument -debug to the make command above will build the scripts in run-time debug mode.

Note that this must be done instead of running a build or debug command within the ModBuddy Visual Studio Shell, as doing so will overwrite the .u files created via the manual make command. Doing this manually may require manually building the shader cache for the mod as well. A typical command for that is :

XComGame.exe precompileshaders -nopause platform=pc_sm4 DLC=LW_OfficerPack

 

 

[Zyxpsilon]

Precious infos... please be kind to the recruits, Commander -- they all are eager to realize each of their wonderful ideas for a fantastic Gameplay by Firaxis.

 

The trick i gather should become a wild "Academy" of modders guided by the Nexus membership if & when needed.

 

It's only been a week-end and i already feel our XCom2 Forum should have specific sections like those;

 

-- Projects, R&D, Plans, Actual Coding... etc

-- SDK Help

-- Request for Mods

 

Order in the ClassRoom, visitors... i certainly prefer logic to chaos as should anyone else seeking for Stickies or burried posting jewels! (Like what i've just read above) :D

[FriarChris]

Thanks for this, Amineri. This clears up most everything I was wondering how to do, especially re: total conversions/overhauling original game code.

 

Now just.. how to cook? :blush:

Edited February 7, 2016 by FriarChris

[Drakous79]

Hello Amineri,

 

please can you explain, how to add 2 new muton units and 1 archon unit to the game, when it would be done by 3 different mods? What of your well written points to apply except XComGame recompile?

 

Also I'd like to know, if you have any experience with ini mods changing the same key in the same ini. Which key "wins"?

 

Must admit sometimes direct edits were easier and faster, if it came to changing single integer. And better than locking entire class for other by using override.

 

Edit: Tried to express myself better.

Edited February 13, 2016 by Drakous79

[teebird]

Hey, just a couple quick questions, and here's some context.

 

I'm attempting to change the Hunter's Instinct Perk for Rangers. Currently it only applies to ranged weapons. While it would be easy to simply remove the melee check in the file to make the bonus also apply to melee, this seems boring to me. What I would like to do is grab how far the unit moved on their last move and modify the damage by something like distance/5. However, I have a few issues with that.

 

It appears to me that X2Ability has a function that's called anytime you use slash that already grabs the movement range of a slash attack. My first problem is here. I'm not entirely sure what order of events these things are called in. As the X2Ability function "TypicalMoveEndAbility_BuildInterruptGameState" appears to deal primarily with animations, I would guess that this doesn't do anything before an attack, but as damage estimates are shown BEFORE the attack, I would guess hunters instinct gets called first. Unfortunately this would mean I would need to catch how far a person is about to move with an attack, I haven't seen anywhere I can do that yet.

 

Even if I CAN get the movement from the function above, I'm at a bit of a loss as to how to get this information to the HuntersInstinct section to calculate the damage of the attack. My first thought was to modify the XComGameState_Unit to add a new variable to hold this information to later be accessed by HuntersInstinct. However, you mentioned that I can't override GameState classes. What is the best way to store new variables relating to a specific unit? I have to imagine that this is something that will come up very frequently in modding efforts.

 

Thanks!

[abeclancy]

I don't suppose anyone can assist me with some instructions on what to do with a mod that has an XComGame.u/ModName.u ready-to-go, that needs to be cooked? From Amineri's description, it sounds like it really *should* be cooked for best performance and so that it runs on everyone's systems without needing symlinks and/or the NOSEEKFREELOADING argument.

 

My assumption is that if I was to download the Unreal Engine (around version 3.5), then somewhere I could either find a GUI panel for cooking files, or I could just use one of the exe's that come with the Engine. My hope is that there's something just packed in to the XCOM 2 SDK directory somewhere, maybe in the Unreal Editor that launches from within ModBuddy.

 

The Epic Games Launcher doesn't want to work on my system for some reason (refuses to sign in, so I can't download any engine stuff). Firewall's open all the way, still no go. Hopefully there's a way to cook without necessarily needing *all* the engine files.

 

https://udn.epicgames.com/Three/ContentCooking.html

https://udn.epicgames.com/Three/UnrealFrontend.html

[davidlallen]

Folks, please don't use this thread anymore. Please start new threads in the modding forum next door. Most modders don't look here.

[abeclancy]

I'll do that, actually didn't even realize this wasn't the Mod-specific forum, it's just one of the more useful threads that comes up in Google searches about XCOM 2 modding. Maybe an admin/mod could move the post over to the correct forum. I'll repost my question there, and link that thread here so that if people come here via search they know where to look for further answers on the topic, anyways.

 

Edit: http://forums.nexusmods.com/index.php?/topic/3857145-cooking-u-to-upk

Edited March 1, 2016 by abeclancy

[davidlallen]

Please push the "report" button on your post, and mention this to the moderators. They occasionally take this action.

[Deleted32045420User]

They occasionally take this action.

damn! shots FIRED!