SDK reference

A lookup list of everything a mod can declare. To learn how to do it, see the guides linked in each table.

Paths on this page use \. The game is case-insensitive.

1. Mod structure

A mod is a folder in mods\. Folders starting with . or _ are ignored. Without a mod.json, the game creates a basic one (with autoGenerated).

"Gameplay" = every player must have the same mod (README).

• Forbidden extensions: .exe .dll .asi .bat .cmd .com .scr .ps1 .vbs .js .msi .sys .cpl .lnk .reg .jar .hta .wsf .pif. With one of them, the mod doesn't load.
• An extension that isn't a known one, and isn't forbidden, is allowed and never executed.
• If two mods ship the same file, a loose file beats one inside a .pak; between two loose files, or two inside .pak files, the one that comes first in the load order wins. The game works that order out, nobody picks it: first what the mods ask for (a mod goes above the ones it needs in requires and the ones in its loadAfter, and below the ones in its loadBefore); then cosmetic mods go above content (maps, battles, conquest), and content above mods that change gameplay; on a tie, by id. The same mods give the same order on every computer. On each mod's card, the content manager lists the files it shares with other active mods and whose copy of each one is used. If two active mods replace the same gameplay files and neither names the other in requires, loadAfter or loadBefore, it is shown as a problem: use only one, or a compatibility patch (a mod that ships the merged files and has both in its loadAfter). When every file they share is cosmetic (textures, sounds, interface), the player can choose whose files are used; the choice is saved in the profile, only applies to loose files and changes neither the load order nor what counts online. To change a few values of a file that another mod may also change, a patch is better (section 6): patches add up instead of replacing the file.

Test folder <game>\mod\ (no mod needed; it beats all mods):

2. mod.json

A per-language text picks the game's language; if it's missing, English; if that's missing too, the first one.

English aliases the game also reads: name, description, license, redistributable, language (with code, name).

3. civs\<id>.json

Guide: Civilizations.

• race="<id>" in a class's <properties> uses the civilization by its id or its internalName.
• Repeated id or index: the one from the mod that comes first wins; the others are ignored with a warning.
• English aliases: index, name, letter, template, internalName, folder, random, biome, ai, ownAi.

4. specials\*.json

Guide: Unit specials.

• Repeated id or bit: the one from the mod that comes first wins.
• In unit_specials, names are comma-separated; mod ones are case-insensitive. The game ignores the ones it doesn't know.
• English aliases: name, description, icon.

5. options\<id>.json

Guide: Game options.

• A values with fewer than 2 or more than 16 items ignores the whole option.
• Bits: toggle 1; list of 2 values 1; of 3-4, 2; of 5-8, 3; of 9-16, 4. They're taken in alphabetical order of id.
• With a repeated id, the one from the mod that comes first wins.
• English aliases: name, description, values, default.

6. Patches

Guide: Patches. A patch goes in patches\<path of the game file>. Only .xml, .ini and .vs. Order: from the last mod in the load order to the first, so the first one has the last word; mod\patches last.

XML

The patch's first tag is the root (usually called <patch>); its children are the operations, applied in order. Operation, tag and attribute names are case-insensitive.

• select is required. You can't use <set> to set an attribute called select, optional or unset.
• optional: 1, yes, si, sí or true avoid the error if the selector finds nothing.
• <add> and <replace> without content give an error.
• A selector with no results, or an unknown operation, is skipped with an error; the rest go on. If the patch isn't well-formed, no operation is applied.
• The patched file keeps comments and quotes; attributes are collapsed onto one line.

Selector

You can chain conditions ([@a='v'][2]). Nothing else exists (and, contains, text(), ..). Always start with / or //.

INI

Each line of the patch, under a [Seccion] (required before any line):

Keys and sections are case-insensitive. A comment at the end of a patch line isn't stripped.

.vs scripts

Directives start with @ in the first column; the code below each one is what gets inserted.

• TEXTO is a literal piece of a line (case-sensitive). The first line containing it is used, and directives apply in order: they see what the earlier ones inserted.
• Error (and the directive is skipped): unknown directive, @before/@after/@replace without TEXTO, a directive without code (except @replace), TEXTO not found.

7. Script events

Guide: Scripts. File: events\<Event>.vs. Runs on every PC; with several mods, all of them run.

• Except for OnGameStart, they run immediately and can't wait.
• An event that fires inside itself is cut off at 4 levels.
• If the script fails at run time, the log records it up to 5 times per script.
• Only these event names are read. You choose the parameter names.

8. Mod_* functions

Guide: Scripts. The current API is 6; it's part of the multiplayer check.

Script constants: each mod civilization's id with a capital first letter (value = its index) and each mod unit special's id (value = its bit).

9. imperivm-mod.ini

It's in the game folder. It's read at startup.

10. Limits

The guides explain how to do each thing; this is the complete list. Back to the README.