AI War 2:Basic Stat Modding

For basic stats, and for creating ship variants or even entirely new ships, you can do everything you need in XML alone -- no need for any code! If you want to mod AI or new features or map types, you need to get into the code, but that's beyond the scope of this document.

What You Need

You'll need some sort of text editor that will maintain formatting as it is (aka something like Notepad, not Wordpad), and ideally that has some syntax highlighting. Any code IDE will work, or you can use Notepad++, which is free and excellent. Your work will go much easier with that. Be sure NOT to use something with a GUI like the Microsoft XML Rditor, or else it will absolutely eat all the formatting in terms of tab indents and newlines.

Where To Find The Files

The files you need are all located inside the game install folder, inside a subfolder tree of

   GameData/Configuration.

The files specifically for ships and their weapons are inside

   GameData/Configuration/GameEntity

There are some other folders prefixed with Balance_ that you can make changes in as well, but you really shouldn't need to. Some of those have good reference values in them, though, so you may want to open them to see what's there.

Warning! Your Changes Will Be Lost!

...if you edit the actual existing XML files that are provided with the game, that is. Next time we push a release, our new version will overwrite all your hard work.

That said, you can make tweaks in there for a while, test things out, and tell us what changes you made so that we can integrate them into the main game if we agree they're an improvement.

Beyond that, you want to only make changes in NEW files that you create yourself. These can replace our own entities, or alter our entities, or just add new ones of your own. It's a good idea to prefix the file with your initials or something else unique to you, so that you don't run the risk of someone else creating a file with the same name and us including that in a future version and blowing away your changes.

How To Make Your Own Files

Easiest thing is to simply copy one of the existing XML files, rename it, and delete the things you don't need out of it. You can copy-paste from another entity and then just change its "name" field to be something unique to you, and that will be all set, too. Note that the "name" field is basically the internal identifier for a unit, and is never seen. So putting your initials or handle name in there can also be a good idea to avoid conflicts, if you're making a mod that has common ship names as part of it.

Where To Make Your Own Files

You can, of course, make your files in the same folder as noted above (GameData/Configuration/GameEntity), which is kind of what we were expecting based on what we described above. But a much cleaner approach is to create your own mod folder. You can create one mod folder that just has all of your stuff in it, or multiple folders for specific types of mod if you're creating more than a single grab-bag mod.

Inside the GameData folder, create an "XMLMods" folder if there is not already one. That IS case-sensitive!

Inside that folder, create a folder with a name of your choosing. That could be "BobsBagOMods" or something like "DarkSpireBase" and "DarkSpireExtended" if you want to have piecemeal mods that players can install separately. If you're just mucking around with stats, then probably just putting your initials or forum name in there is a good way to handle it. East peasy.

Once you have your modding folder, let's say I call mine "x4000", it should look like this:

   GameData/XMLMods/x4000

Inside that folder, you can mirror any folders that you want from the GameData/Configuration/ folder. So, for instance, a really common one to add would be "GameEntity".

To make my own game entities, I'd go in and create a folder tree called:

   GameData/XMLMods/x4000/GameEntity

Then I'd copy a random xml file into there from GameData/Configuration/GameEntity, and start editing it to meed my needs.

Replacing Existing Entities

If there's a base entity named FusionBomber, you should be able to make your own copy of FusionBomber inside your custom folder, and it would just replace the existing one when you play. There may be some complications with that, though, so this isn't super recommended.

Editing Existing Entities

If there's a base entity named FusionBomber, you can definitely make your own entry with that same name, and then add an attribute that says is_partial_record="true" on it. With that in place, you can redefine any fields that you wish and it will overwrite the base data. Very handy! If you want to change balance, this is the best way to do it.

   <entity graphicsdone="true" name="FusionBomber" is_partial_record="true"
        squad_cap="80" ></entity>

Congratulations, the above changes the squad cap -- at mark 1 -- for Fusion Bombers from whatever its default is to 80. The higher marks will auto-increase based on central multipliers. The rest of the ship data is unchanged by this, and your mod won't be erased or upset by future releases.

We have not tested this much with systems and such on ships, but it should work with them. The approach to that would be to do something like this:

   <entity graphicsdone="true" name="FusionBomber" is_partial_record="true" >
       <system name="FusionBomb" is_partial_record="true"  damage_per_shot="8000"></system>
   </entity>

That SHOULD work in order to simply change the base damage per shot from its default value to 8000, but if it has trouble then please let us know.

The important fields are as follows

squad_cap: how many of a unit you can have hull_points, shield_points: control how tanky a unit is. speed: controls how fast a unit is metal_cost/energy consumption: how high a price the player pays to build one of these strength: how high a price the AI (and other minor factions) pay to build one of these armor/albedo/engine/mass: other stats used when handling other weapon types

A unit's weapons are defined as "Systems" on a unit. For a weapon, the most typical balance fields are damage_per_shot range shot_speed rate_of_fire

Copying Existing Entities

Sometimes you want to have a variant of an existing entity, but you don't want to copy everything. That gets to be a pain, since it has to be independently maintained if the base entity changes much.

For those circumstances, you'll be looking for copy_from="NameOfOriginal". You'll notice that we use this some in the game for our own ships, even! One example:

   <entity graphicsdone="true" skip_export="true" copy_from="VWing" name="MarauderVWing"
       self_attritions_X_percent_per_second_if_parent_ship_not_on_planet="0.100"
       starting_mark_level="Mark1" tech_cost="NeverPlayerControlled" built_by="MarauderDrones" ></entity>

As you can see, for the most part we're just copying all the stats and weapons from "VWing" into this entity. But we've added a self-attrition to it, and taken away the tech cost, and changed what build menus it shows up in (Marauders build this new one, human players do not). This can be pretty useful!

If there are any sub-nodes that you don't want to copy over to the new one, you can put in exclude_children_from_copy="NodeType1,NodeType2,etc" on the entity definition. So you could do exclude_children_from_copy="system" if you wanted to skip copying over any weapons and other systems from the base unit.