Imperivm Resurrected SDK

Español · English · Italiano

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 examples/ (for example patches-example) into mods\, inside the game folder. To start a mod from scratch, use mod-template/.
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\
  mi-mod\
    mod.json
    data\classes\MiUnidad.sc.xml     <- new file, or one that replaces the game's
    loc\spanish.loc.xml              <- texts added to the game's

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": "mi-mod",
  "name": {"spanish": "Mi mod", "english": "My mod", "italian": "Il mio mod"},
  "version": "1.0",
  "authors": ["Yo"],
  "description": {"spanish": "Qué hace mi mod.", "english": "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.
• Custom game options: new switches in the lobby rules, which scripts read with Mod_GetOption.
• 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. Their messages come out in English; to get Spanish or Italian, add --lang es or --lang it. Each tool accepts its options in all three languages (--name, --nombre, --nome); the guides use the ones for their language.

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/, 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.