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 base game install 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:

   ~/AIWar2/XMLMods/x4000 or C:\SteamInstallDir\AIWar2\XMLMods/x4000 (depending on your OS)

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:

   ~/AIWar2/XMLMods/x4000/GameEntity

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

• Nota Bene: you must add the name of your modding folder to

    ~/AIWar2/PlayerData/XMLModdingOrder.txt

So my copy would then contain the entries

_Vanilla

x4000

Replacing Existing Entities

If you just create your own copy of the entity then you'll get a "duplicate entity" error. The surest way to do this safely is to copy the whole entity XML defintion over, then add the line is_partial_record="true", then modify the entries you want to change. You can then try deleting the entries you didn't change, but some of them may be required, so you might start seeing errors if you do that.

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.

Some typical balance fields for an entity are as follows

• squad_cap: how many of a unit you can have, at mark 1 (or markless).
  • Per-planet if set up that way, otherwise galaxy-wide. Higher
  • Higher-mark caps are calculated based on multipliers defined on the Balance_MarkLevel table.
• hull_points: amount of actual health a unit has
• shield_points: amount of shield health a unit has.
  • This specifies bubble forcefields, or personal shields, based on if there is a shield_radius or not.
  • Some units, like bombers, largely skip the shields when doing damage. In general, shields auto-regen when not being damaged.
• speed: controls how fast a unit is
• metal_cost: how high a price the player pays to build one of these
  • For non-player units, this is still important because it determines what sort of rewards players get from destroying them with Metabolization, as one example.
• energy_consumption: how much energy out of your total it takes to run this unit.
  • For non-player units, this is still important because there are some attack bonuses that are based around having high or low energy usage.
• strength: how high a price the AI (and other minor factions) pay to build one of these
  • Non-player units use this instead of metal for determining their budgets.
  • For players this is visual-only, but in all cases this is important because it shows on the UI to tell players how dangerous something is.
• 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: damage of a single bullet from a salvo
• range: how far away the ship can shoot things.
• shot_speed: speed of shots out of this system. It should be fast, or else things will look strange!
• rate_of_fire: number of seconds between salvos of this system.

Note that some of these fields (range, speed, shot_speed in particular) have values defined elsewhere in the XML. To figure out what range "Small4" means, for example, you would look in the Configuration Directory for the correct Balance subdirectory (in this case, Balance_Range) for the definition.

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.