The comprehensive guide to Modding and the Modmerging System for XCE

[Charon]

Introduction

This is a comprehensive guide to modding and the modmerging system the Xenonauts Community Edition ( short XCE ) introduces. Whether you want to make your own mod, or simply alter a few values there is no way getting past this.

 

Get XCE

The basic framework of this guide is XCE. You need to install it to have access to the features described. Steam users can switch to the community edition over the Beta branch.

Others need to follow the manual installation of XCE here: https://www.goldhawkinteractive.com/forums/index.php?/forum/23-xce-release-announcements/

 

The modloader

This is the modloader.

Mods are getting loaded from the lowest priority to the highest priority. Priority 1 is the highest Priority. Priority is of utmost importance, changing the priority of mods can make or break your game. XCE is not a mod and doesnt obey the same rules explained in this guide. All XCE parts must be at the lowest priority, in the order shown in the image.

 

Other mods

Every mod needs a description in what priority it has to be placed. Usually placing everything else above the XCE parts is enough, except if 2 or more mods alter the same files. Be extremely cautious with mods which alter the same content, or better, only use 1 big mod until you can troubleshoot your own problems after reading and understanding this guide.
The standard activated mods in XCE are troublefree, but the Dreadnaught and Armoured Assault mods would be a first example of where you better choose one over the other, until you understand what you are doing.

 

The Files

There are 2 types of files. Files you need the 2003-2007 Excel for, and text based files. Both files can be edited with a text editor, but excel based files can be worked on more easily with excel.

Excel Files:
This is a complete list of files which can be worked on with excel: aircrafts, aircraftweapons, AM_***, buildings, items, manufactures, researches, vehicles, vehicleweapons, weapons.

You can only use a 2003-2007 Excel program on this, Libre Office does not work. This is how it looks:

Text Based Files:

All other files are considered text based files, and can be worked on with a text program. Notepad is a choice, but it is recommended you use better programs like Sublime Text or Notepad++. All following examples will use either of those programs.

 

Making your own mod

Mods are stored in your Xenonauts\assets\mods folder. Create your own folder in it and alter this blank modinfo.xml file and you are good to go. ( modinfo.xml )

 

You can start by putting blank files into it, by copying over vanilla/xce files and deleting all the content. ( weapons.xml weapons_gc.xml )

You need to activate your mod in your modloader and put it in the right spot.

There you go, the only thing missing is content now.

 

Excel Files

Excel Files are easy to manage. The first column is always the identifier for that entity. If the entity already exists, it will overwrite all specified entries with the values you choose. If the entity doesnt exist, it creates a new entity, which will need everything that type of entitiy needs. But we will talk about that later. In this example we simply change the geoscape weight of the pistol from the standard 2 to 4. ( weapons.xml )

If you create a new entity you will need to fill out every missing blank.

 

Text based files

Text based files are more difficult, as every code opener needs its own MODMERGE command. Code openers usually look like this: <XXX> or <XXX . An example would be: <Weapons> or <props ,for the weapons_gc.xml. A code closure looks like this: </XXX> or /> , </Weapons> or />.

 

3 commands

There are only 3 commands you need to know. Although there is an more indepth guide available here https://www.goldhawkinteractive.com/forums/index.php?/topic/11156-documentation-modular-mods-system/ we will stick to only practical things today.

 

MODMERGE="replace" - This completely replaces an entity with all the code provided. If you miss half of the needed code lines than thats what you get. You can only replace exisiting code lines.
MODMERGE="update" - Updates an existing code line. Only exisiting entities can be updated.
MODMERGE="insert" - Inserts a new entitiy. Only non existent entities can be inserted.

 

Understanding the child

Every new code opener inside of an already existing code bracket is considered a child.

<Weapons>
    <Weapon>

    </Weapon>
</Weapons>

The <Weapon> code bracket inside the <Weapons> code brackets is a child of the <Weapons> code. Thuse <Weapon> is a child of <Weapons>.

<Weapons>
    <Weapon>
        <props  />
    </Weapon>
</Weapons>

<props /> is a child of <Weapon>, which is a child of <Weapons>.

Every code line needs its own MODMERGE command, except the last child, unless the last child needs a different command. There are exceptions though. As a rule of thumb you can say one more correct MODMERGE command does better than nothing.

<Weapons MODMERGE="update">
    <Weapon MODMERGE="replace">
        <props  />
    </Weapon>
</Weapons>

We updated the <Weapons> code and replaced a <Weapon>.

 

The automated modmerge commands

Should a file only contain entities to update, or only entities to insert, the modmerging system will automatically figure out which to use. This is not what we are focusing on here, as we want to make sure everything works even without the game having to guess.

 

Identifier

If an identifier is used, it has to be addressed with the MODMERGEATTRIBUTE command. An identifier is usually the "name". Here the identifier is the name="weapon.pistol".

    <Weapon MODMERGEATTRIBUTE="name" MODMERGE="replace" name="weapon.pistol" bulletType="normal" emptySound="Empty Click 1">

In this example we replaced the weapon.pistol with our own version. ( weapons_gc.xml ). Since we are completely replacing the whole entity, the other children dont need any modmerge commands.

In this example we are updating our weapon.pistol with some new values, updating the <SingleShot> Parent with some new values, and bless its child with a new aim set with the MODMERGE="insert" command. Since we are updating the entity sadly we also have to update <Ammos> and <Ammo> to tell the game what they should be doing with the code. ( weapons_gc.xml )

 

Be concise

If, for instance, you only want to add another aim level and dont change anything else, it is not necessary to copy over everything.

<Weapons MODMERGE="update">

    <Weapon MODMERGEATTRIBUTE="name" MODMERGE="update" name="weapon.pistol">
        <SingleShot MODMERGE="update">
            <Set3 MODMERGE="insert" ap="30" accuracy="100" />
        </SingleShot>
    </Weapon>


</Weapons>

What do we want to do ? We want to update the <Weapons> category. We want to update the <Weapon name="weapon.pistol">. We want to update the <SingleShot> line and we want to insert a new aim level. <Set3> is a child of <SingleShot>, so it needs a modmerge command. <Singleshoot> is a child of the <Weapon>, and <Weapon> is a child of <Weapons>, all need a MODMERGE command. The game needs to know at every step what to do. ( weapons_gc.xml )

 

Mod loading priority

is of utmost importance because of the commands "replace" "update" and "insert". If you are "update"ing an entitiy of another mod, but than deactivate it, the game can no longer find the entity and the merging fails. The modmerging system is a pyramid which starts loading from the base ( XCE ) upwards. So make sure you know what you want the game to know.

 

I want to create/change entity X

Start by simply looking through all files to understand what each entity needs if you want create new ones, or alter only a few lines of code with abilities you have learned so far.

 

Other files, deeper directories

All other files hidden in other folders will need to have the same directory structure to get replaced. If you want to replace an image in Xenonauts\assets\aircraft\aircombat you need to put it into Xenonauts\assets\mods\MyMod\aircraft\aircombat .

Images get replaced. Capital letters matter. "Foxtrot.png" is not "foxtrot.png". Most files which are not in the same directory as the excel files dont need any MODMERGE commands, as they can only be replaced.

 

Another example

<Armours MODMERGE="update">
  <Armour MODMERGEATTRIBUTE="name" MODMERGE="update" name="armour.basic">
    <Resistance kinetic="10" energy="0" chemical="0" incendiary="0" />
    <VisualParams range="18" coneAngle="160" nightRangeBonus="0" />
    <PsionicDefence defence="0" points="0" degradation="0" />
    <Props moveSpeed="350" stairsMoveSpeed="180" vaultMoveSpeed="24" />
  </Armour>
</Armours>

<Armour name="armour.basic" > is an exisitng armour, with an unique identifier and therefore needs a MODMERGE command. All updated children of <Armour> have attributes which exist, and therefore dont need another MODMERGE command.

 

Files without MODMERGE

There are a number of text based files which can be modded without the use of any MODMERGE command. This is an incomplete list of the more important ones: colours, config, gameconfig, psioniceffects_gc, psionicpowers_gc, settings, tilerenderer, xenopedia.
These files mostly contain code which addresses the game itself, and thuse no new things can be added there. This is where the automated MODMERGE system really shines. The xenopedia is a special case, as it gets an excel treatment, although it can only be worked on with text based tools.

 

Troubleshooting

Every time you run the game, there is an logfile.txt created in your AppData\Roaming\Goldhawk Interactive\Xenonauts folder. To fully trigger the check of all files you further need to go into a Ground Combat situation. Then you can look at the logfile. The logfile tells you if you made any big and obvious mistakes during the modmerge process.

 

Clear scripts

Scripts get temporarily saved in your AppData\Roaming\Goldhawk Interactive\Xenonauts\internal folder. Unfortunately the game doesnt update them when you switch mods. To fix this you need to delete the scripts folder in that directory every time you change your modloader priority and/or activate/deactivate mods, if you want to update to the correct script setup. This is not necessary if you know no scripts have been changed.

 

You are done

You can now start to fill your own mod with your changed and new content as you like. You are now also able to read and understand what each mod is doing, and know which program to open each file with.

 

 

 

If you want to dig deeper

 

 

Thank you for reading

 

 

 

 

 

 

Edited May 2, 2019 by Charon

[Rodmar18]

Thank you very much ! (I knew I hadn't to pay for this)

After having read llunak's post, am I right when I say that the

MODMERGEATTRIBUTE="name"

command you don't explain is optional in your example, and only there to take good habits, because the name attribute is used by default to choose what line to merge?

[Charon]

1 hour ago, Rodmar18 said:

Thank you very much ! (I knew I hadn't to pay for this)

After having read llunak's post, am I right when I say that the

MODMERGEATTRIBUTE="name"

command you don't explain is optional in your example, and only there to take good habits, because the name attribute is used by default to choose what line to merge?

The whole point of the guide is to not to rely on the automated merging, but aims at providing you with the tools to make sure the merging system knows at every step what to do.

The answer to your question is: "Who knows ?". If you want to believe fairytales in other peoples threats, go ahead and test out every combination.

The whole paragraph is important to understand, and it says that if an (unique)  identifier exists, it needs a MODMERGEATTRIBUTE. Maybe the automated system takes care of some of them, who knows.

Here is an example of where you might not need it, but as you said, could put it in for good measure. But only testing really can tell.

    <Sound MODMERGEATTRIBUTE="name" MODMERGE="insert" name="XenomorphQueenSound" volume="0.8" group="10" comment="">
      <Wave name="SoundQueen1">audio/sfx/Xenomorph/FinalQueen1.ogg</Wave>
      <Wave name="SoundQueen2">audio/sfx/Xenomorph/FinalQueen2.ogg</Wave>
      <Wave name="SoundQueen3">audio/sfx/Xenomorph/FinalQueen1.ogg</Wave>
      <Wave name="SoundQueen4">audio/sfx/Xenomorph/FinalQueen2.ogg</Wave>
    </Sound>

 

[Rodmar18]

Okay. Let's say that I read "if the MODMERGEATTRIBUTE attribute is not used" where he only writes "if the attribute does not exist". But it was out of excitement.

[Charon]

Updated content:

Files without MODMERGE

There are a number of text based files which can modded without the use of any MODMERGE command. This is an incomplete list of the more important ones: colours, config, gameconfig, psioniceffects_gc, psionicpowers_gc, settings, tilerenderer, xenopedia.
These files mostly contain code which addresses the game itself, and thuse no new things can be added there. This is where the automated MODMERGE system really shines. The xenopedia is a special case, as it gets an excel treatment, although it can only be worked on with text based tools.

Edited March 11, 2018 by Charon