Imperivm Resurrected SDK

Imperivm Resurrected is a mod for Imperivm HD (Great Battles of Rome) that opens the game up to mods that weren't possible before: new civilizations, abilities, items, victory modes, languages, scripts that react to the game, and more. These are the guides and tools for making them. Each guide comes with an example mod in examples/.

Start here

1. Install Imperivm Resurrected: copy its contents into the game folder (...\steamapps\common\Imperivm - Great Battles of Rome HD) and launch the game from Steam.
2. Copy a folder from templates/ into mods\, inside the game folder: it has the exact layout the game expects for what you want to make (see Templates). To see a finished mod, copy one from examples/, for example patches-example.
3. In the main menu, click Additional content and enable the mod in your profile.
4. Restart the game if it didn't restart on its own.
5. Open Logs\imperivm\imperivm-mod.log, in the game folder. It lists your mod's errors and what it loaded.

Before you launch the game, run your mod through the validator.

What a mod looks like

A folder inside mods\ with a mod.json and the files it changes or adds, using the same paths as the game:

mods\
  my-mod\
    mod.json
    data\classes\MyUnit.sc.xml       <- new file, or one that replaces the game's
    loc\english.loc.xml              <- texts added to the game's

Templates

A template is an empty mod with the folders the game reads, a valid mod.json and a README with the steps. Copy the one that matches what you make, rename it, fill in mod.json and put your files where the notes say. Each empty folder has a PUT-YOUR-FILES-HERE.txt note: delete it when you add your files.

Don't include executables or system scripts (.exe .dll .asi .bat .cmd .com .scr .ps1 .vbs .js .msi .sys .cpl .lnk .reg .jar .hta .wsf .pif). If there's one, the mod won't load. A stray .js, like a generator of your own, counts.

mod.json

{
  "id": "my-mod",
  "name": "My mod",
  "version": "1.0",
  "authors": ["Me"],
  "description": "What my mod does.",
  "category": "Gameplay & Balance",
  "redistributable": true
}

Up to 0.31.50 the names of these fields were in Spanish (nombre, autores, descripcion, etiquetas, categoria, redistribuible, licencia, requiere, incompatibleCon, cargarDespuesDe, cargarAntesDe, fuentes, idioma, ordenes…). The old ones are still read, but write the new ones.

Guides

• Languages and texts: change game texts or add a language without replacing the whole file.
• Mod keys: how your mod's commands show up in Controls and how to name them.
• Patches: change part of a game XML, INI or script without replacing it; two mods can touch the same file.
• Scripts: .vs scripts, events and the Mod_... functions.
• Civilizations: declare a new civilization or clone one from the game, with its AI, and play it in the lobby.
• City and village templates: a mod civilization's own starting city and village (create-template.js).
• New units: class, recruit command, images and texts, reusing another unit's model.
• Unit stats: which attribute does what, which ones do nothing and which ones crash the game.
• Unit specials: new unit specials and their effect through scripts.
• Troop abilities: new abilities for units or heroes (a command with button and key, plus a script method).
• New items: hero amulets, herbs and gems.
• New formations: hero formations with their bonuses and button.
• Outposts and buildings: new neutral outposts on random maps (create-outpost.js) and tower, wall and gate classes.
• Victory modes: a script in data\GameScripts adds a mode to the lobby's "Mode" dropdown.
• Starting bonuses: scripts in data\BonusScripts add choices to the "Bonus" column of the lobby.
• Custom game options: new switches in the lobby rules, which scripts read with Mod_GetOption.
• Scenarios, adventures and conquests: the three kinds of map, the files each needs and cutscenes.
• Music, sounds and voices: replace or add audio.
• Random map types: a four-color drawing becomes a new map type (create-random-map.js).
• Custom images: command buttons and unit icons from a PNG.
• Custom graphics: custom sprites for units and buildings (convert-sprite.js, create-entity.js, read-rle.js).
• Validating a mod: check a mod without opening the game, with the file and line of each problem.
• Publishing on GameBanana: categories, tags, uploading, and mods made before the SDK.
• Reference: the full list of what a mod can declare (files, fields, patches, events, functions and limits).

Tools

They're in tools\ and need Node.js. Open a terminal in this folder and run them from here (node tools\validate-mod.js ...). Each one explains its usage when you run it with no arguments, and the topic's guide has examples.

Game data

Several tools ask for the game's DATA folder. extract-data.js extracts it (you need Node.js):

node tools/extract-data.js "<game folder>" <output folder>

It leaves data.pak in <output folder>\DATA. That's the folder that clone-civilization.js, create-outpost.js and validate-mod.js --data ask for.

What counts as gameplay?

In multiplayer, everyone must run the same mods if they change what happens in the game. The game works this out from the folders your mod touches: data/, scenarios/, adventures/, conquests/, civs/, specials/, events/, options/, rules/, modes/, randommap/, randommapsettlements/, the .xml and .pass files in units/, buildings/ and mapobjects/, the .xml files in visuals/, the .bfhp maps in packs/, and patches (depending on the file they patch).

Graphics, sounds, texts (loc/) and languages don't count: each player can use their own.

If something fails

Your mod's errors show on its card in the content manager and in Logs\imperivm\imperivm-mod.log. Each line of the log has the time, a level (I information, W warning, E error) and a tag for the part of the mod it comes from: patch, language, civilizations, specials, script, event. Look at the W and E lines of your mod's tags first.

The log keeps the last five sessions (imperivm-mod.1.log to imperivm-mod.4.log) and, if the game closed badly, imperivm-mod.crashed.log. For more detail about one part, put its tag and a level under [Debug] in imperivm-mod.ini, for example LogChannels=patch:debug; LogLevel=debug does it for everything.

To ask for help, click the heart at the bottom left of the main menu and then Create report. It makes a zip with the logs and your system, without your Windows user name, Steam IDs or IP addresses, and sends nothing: you decide whether to share it.

Version and license

The SDK version and what changed in each one are in Changes. The license is in License.