Desktop Modding Manual

The Desktop Modding Manual is the technical reference for creating and distributing mods for Imperium Sine Fine. Mods can add or replace almost anything in the game — troop types, factions, terrain, technologies, equipment, events, focus trees, national spirits, name pools, and artwork — and the modding system is built so that a mod only needs to include the files it actually changes. Everything else is inherited from the base game automatically.

This page covers the practical side of building and sharing a mod. For the exact column format of every data file and the JSON schema for events, focus trees, and spirits, see CSV and JSON Reference.

⚠ Always back up your saves and settings before enabling new mods. A mod with a syntax error in its data files may prevent the game from loading correctly.

Mod Folder Location

All mods live in the same root folder as saves and settings:

%USERPROFILE%\ImperiumAeternum\mods\

On a typical Windows installation, this expands to C:\Users\<YourName>\ImperiumAeternum\mods\. The full folder layout alongside it:

%USERPROFILE%\ImperiumAeternum settings.dat — game settings mods_config.json — active mods and load order saves\ — save game files (*.sav) mods\ — mod folders (one sub-folder per mod)

Each mod occupies its own sub-folder inside mods\. The folder name itself doesn't matter to the game — the id field inside mod.json is the canonical identifier. The Open Mods Folder button in the Mod Manager opens this location directly.

Mod Folder Structure

A typical mod folder looks like this:

mods\my_mod\
    mod.json                   Required — mod descriptor
    data_troops.csv            Optional — override / extend vanilla troops
    data_factions.csv          Optional — override / extend vanilla factions
    ... (any other data_*.csv) Optional — see CSV and JSON Reference
    config\
        crime_data.json        Optional — tuning overrides for crime system
        combat_data.json       Optional — tuning overrides for combat
        ... (any config file)  Optional — see Game Constants Config Files below
    events\
        general_events.json    Optional — override / extend vanilla events
        my_new_events.json     Optional — entirely new events (any filename)
    focus\
        generic_focus.json     Optional — replaces the generic focus tree
        my_custom_focus.json   Optional — new focus tree (any filename)
    spirits\
        FACTION_1.json         Optional — replaces faction 1 spirit
        MY_SPIRIT.json         Optional — new spirit (any filename)
    i18n\
        strings.properties     Optional — new / override English strings
        strings_de.properties  Optional — German translations
    ui\
        icon_custom.png        Optional — new or replacement UI image
    icons_main1_100.png        Optional — replacement sprite sheet

Two rules govern everything about how mod files load:

• Files sharing the same relative path as a vanilla file override the vanilla version.
• Files with new names, placed in the same directories, load additively — added on top of vanilla rather than replacing anything.

Quick Start — Extract Game Data

The fastest way to begin modding is the Extract Game Data button in the Mod Manager, accessible from the main menu. Clicking it creates a new folder inside mods\ (named new_mod, or new_mod_1, new_mod_2, and so on if that name is taken) and copies every moddable vanilla file into it: every data_*.csv file, every JSON file from events/, focus/, and spirits/, every UI icon and sprite sheet, the full English string table, and a pre-filled mod.json ready to edit. The new mod appears in the Mod Manager list immediately — no restart required.

Recommended workflow:

1. Click Extract Game Data in the Mod Manager.
2. Click Open Mods Folder and navigate into the new folder.
3. Open mod.json and set name, author, and description to something meaningful. Change id to a short, unique string with no spaces (e.g. my_troop_overhaul), and rename the folder to match it.
4. Delete every file you don't intend to change. Unmodified files load from vanilla automatically — keeping unchanged copies just wastes space and makes future game updates harder to apply cleanly.
5. Edit the remaining files.
6. Enable the mod in the Mod Manager and click Apply.
7. Start a new game to see your changes.

mod.json Reference

Every mod folder must contain a mod.json file at its root, describing the mod to the Mod Manager:

{
  "id":           "my_mod",
  "name":         "My Awesome Mod",
  "type":         "mod",
  "version":      "1.0.0",
  "gameVersion":  "3.0.0",
  "author":       "YourName",
  "description":  "A short description shown in the Mod Manager.",
  "scenario":     "my_scenario.sce",
  "dependencies": ["other_mod_id"]
}

Field	Type	Required	Description
id	string	Yes	Unique identifier, no spaces. Never change this across releases.
name	string	Yes	Display name shown in the Mod Manager.
type	string	No	"mod" (default) or "scenario". Scenario mods also appear in the scenario selection screen.
version	string	Yes	Your mod's version, e.g. "1.0.0".
gameVersion	string	No	The game version this mod targets. The Mod Manager shows a warning if it doesn't match.
author	string	No	Your name or handle.
description	string	No	Short description shown in the Mod Manager.
scenario	string	No	Filename of the .sce scenario file inside the mod folder. Its presence makes the mod appear in the scenario selector.
dependencies	string array	No	IDs of mods that must be active for this one to work. The Mod Manager warns if a dependency is missing.

Override vs. Additive Rules

File Type	Same Filename as Vanilla	New Filename
data_*.csv	Merged row-by-row. Mod rows with the same ID override vanilla; new IDs are added.	N/A — CSV files are fixed by type.
events/*.json	Merged event-by-event by id. Same event ID → mod wins; new IDs added.	Entire file loaded additively — every event in it is added.
spirits/*.json	Replaces the spirit with that filename.	New spirit added to the pool.
focus/*.json	Replaces the focus tree with that filename.	New focus tree added; its tree ID is derived from the filename.
i18n/strings*.properties	Merged key-by-key. Mod keys override vanilla; new keys are added.	Keys from any additional .properties file are loaded additively.
ui/*.png and other images	Replaces the vanilla image.	New image available as an additional asset.

When multiple mods provide the same file, the mod appearing later (lower) in the Mod Manager list wins the conflict.

Image Override Guidelines

UI icons — individual PNG files. Match the original pixel dimensions exactly. This covers menu button frames (ui/btn_512_256_active.png and similar), panel icons (ui/icon_*.png), and the main menu's logo, title, and slideshow backgrounds (art/logo.png, art/title.png, art/bg_01.png through bg_07.png).

Sprite sheets (icons_main1_100.png, icons_main2_100.png, icons_main3_100.png, icons_main3_50.png, map_factions2.png, map_ai_actions.png, map_events1.png) are grid-based atlases — each icon occupies a fixed-size cell. Do not resize these files or rearrange icon positions; doing so misaligns every icon in the game. Only the artwork inside each existing cell can change.

All replacement images must be PNG (RGBA or RGB); transparency is supported throughout.

i18n String Overrides

Mods can override or add localised strings by placing a strings.properties file in their i18n\ folder, in the same format as the vanilla file. Apostrophes must be doubled (), since strings are processed by MessageFormat, and {0}, {1}, and so on are used for substitution placeholders. Mod keys override matching vanilla keys; new keys are simply added. To supply translations, add a locale-specific file such as strings_de.properties or strings_fr.properties.

# Override an existing string
tooltip_IMI=My custom Imperial Influence tooltip

# Add a new string (used by a custom event title)
event.my_mod.title=A Legendary Sword is Forged

Load Order and Conflict Resolution

Mods apply in the order shown in the Mod Manager list, from top (lowest priority) to bottom (highest priority) — the last mod in the list always wins when two mods change the same value.

Practical guidelines: a mod that adds new content (new troops, new events) should sit near the top, since other mods are unlikely to conflict with it. A mod that overrides vanilla values should sit near the bottom, so it wins over other mods touching the same data. Drag entries up or down in the Mod Manager to adjust order, and press Apply afterward — CSV data reloads immediately, while events, focus trees, and spirits reload the next time a new game starts.

Mods and Save Game Compatibility

Every save file records which mods were active when it was created (IDs and versions). Loading a save compares that list against the currently active mods and shows a status badge in the Load Game screen:

Badge	Colour	Meaning
(none)	—	Exact match — same mods, same versions, same order. Safe to load.
[!]	Amber	Soft mismatch — a mod version changed, or mods were added/removed. The save will still load, but behaviour may differ from the original session.
[!]	Red	Hard mismatch — a mod active when the save was created is no longer installed. The save is blocked from loading until that mod is reinstalled and enabled.
[I]	Gold	The save was created in Ironman mode — one auto-managed slot, saves are automatic.

Guidance for mod authors: never change your mod's id between releases — doing so makes every save created with the old ID unloadable, since the game treats the old ID as a missing mod entirely. Do increment version whenever you release an update, so players see the informational amber warning rather than a hard block. Changing CSV data or event effects in an update is safe — old saves simply apply the new data going forward — but removing mod-added troops, settlements, or focus nodes that are already present in an active save can cause unexpected behaviour.

Ironman mode is achievement-eligible only when no mods are active — see Difficulty Levels. Starting an Ironman game with any mod enabled works normally, but that run won't count toward achievements.

Scenario Mods

A scenario mod bundles a hand-crafted world (a .sce file, produced by the Scenario Editor) with optional data changes into one distributable mod folder. Scenario mods appear both in the Mod Manager and in the in-game Scenarios screen. The scenario file loads on top of your mod's own data — troops, factions, events, and focus trees defined in the same mod folder are all available during that scenario, so a scenario can freely reference custom content you've built alongside it.

The Scenarios screen shows the same style of compatibility badge as saves do, comparing the active mod configuration against what was recorded when the scenario was saved — an exact match shows nothing, a soft mismatch shows an amber [!], and a hard mismatch (a required mod not installed) shows a red [!] with Play disabled entirely.

Best practices for scenario authors: save the scenario with only your own mod active — any extra mods active during the save get recorded as required for every player, even if they aren't actually needed. Re-save the scenario in the Scenario Editor after updating your data, so the compatibility baseline resets. Increment version in mod.json whenever mod data changes, and never change the mod id between releases — the same rule as saves applies here too.

Sharing Your Mod

Manual distribution: zip the entire mod folder and share it on Discord, NexusMods, or any platform you like. Recipients extract the zip directly into their own mods\ folder. Include your mod's id and version in your release notes, list any dependencies, and note a brief changelog on updates.

Steam Workshop: mods and scenarios can also be published to the Steam Workshop, where players subscribe with one click and the game downloads and loads the mod automatically. Publishing requires a small separate program, the Workshop Uploader — see Workshop Uploader Guide for the full step-by-step process, including tags, preview images, and visibility settings.

Game Constants Config Files

Config files let you override the underlying tuning values that govern game systems — crime rates, loyalty modifiers, combat multipliers, population dynamics, and more. Unlike CSV files, which define game objects (troops, factions, terrain), config files adjust the rules those objects follow.

This is especially powerful for scenario mods: a "hard survival" world can double crime rates and halve grain supply, while a "golden age" scenario can buff loyalty and settlement growth — all without touching a single object definition.

Folder Location

Place config files in a config\ subfolder inside your mod folder — see Mod Folder Structure above.

Available Config Files

Filename	Controls
ai_data.json	AI movement thresholds, army group sizes, deploy distances, multipliers per play-style phase, workshop assignment scoring and re-task pacing, army growth at the army cap
faction_ai_data.json	AI power calculation weights, war-score weights, treaty relation thresholds, garrison sizes and the garrison-hold shortfall guard, hex value factors, resource minimums, project pause timers, the combat reserve (opening work parties, minimum combat armies)
crime_data.json	Crime rates, sprawl factors, garrison and governor modifiers, loyalty penalties — see Crime and Provincial Order
diplomatic_data.json	Gift costs, war declaration delays, influence costs, race relation starting values — see Diplomatic Actions and Relation Values
vassal_data.json	Not yet active — see the note below.
leader_data.json	Leader age/death timing, XP rates, skill levels, training chances, court action costs — see Leader Age and Experience and Imperial Court Actions
population_data.json	Population growth floor, grain supply modifiers, migration thresholds and rates, the manpower/population conversion rate — see Population Growth and Migration
empire_data.json	Imperial Influence generation, government point rewards, recruit fractions, storage capacities (including per-settlement scaling for grain, stone, and horses), progressive degradation rates, the low-stock warning threshold — see Imperial Court Actions and Global Equipment Stock
loyalty_data.json	Loyalty base values, all loyalty modifiers, project and workshop loyalty multipliers — see Loyalty
military_data.json	Army organisation, Combat Readiness, experience rates, honour constants, trait bonuses, disband population return, equipment maintenance wear — see Armies and Military Tradition
outpost_data.json	Outpost storage capacities, birth rate bonuses, assimilation bonuses, resource output — see Outposts
settlement_data.json	Starting population and garrison, resource constants, expansion and workshop limits, the capital grain bonus, workshop staffing per PDL — see Settlement Types and Founding
map_data.json	Map dimensions, terrain generation probabilities (forest, mountain, plains, swamp distributions)
combat_data.json	Combat multipliers, city wall bonuses, damage constants, morale loss rates, siege multipliers — see Combat System and Sieges
movement_data.json	Movement costs, embarkation cycle counts — see Movement
world_data.json	Fog of war distance, race birth/death rates, assimilation rates, difficulty modifiers — see Fog of War, Population Growth, and Difficulty Levels

vassal_data.json exists ahead of a vassalage system planned for the game's first major update, expected roughly a month after release. It isn't part of the game at launch, and this reference will get a proper, full treatment once that update ships.

JSON Format

Each file is a flat JSON object. Keys are exact field names from the game's own constants classes — you only need to include the fields you actually want to change; anything you omit simply uses the built-in default.

Scalar example (config/crime_data.json):

{
  "MAX_CRIME_RATE": 0.60,
  "LOYALTY_CRIME_FACTOR": 0.15,
  "GARRISON_MOD_NONE": 0.30
}

Array example (config/combat_data.json):

{
  "cityWallBonusAV": [0, 2, 4, 6, 8, 10]
}

⚠ Arrays must have exactly the same number of elements as the vanilla default. Check the extracted template (see Quick Start above) to see the expected length before editing an array field.

Getting Started

The fastest way to see every available field and its current default is to click Extract Game Data in the Mod Manager. This creates a config\ folder inside your new mod containing one JSON file per constants class, pre-filled with every moddable field at its current default value.

Recommended workflow:

1. Extract game data (see Quick Start above).
2. Open the config\ folder and find the file for the system you want to tune.
3. Delete every field you don't want to change — keeping only your actual overrides makes the mod lighter and easier to maintain.
4. Edit the remaining values.
5. Enable your mod in the Mod Manager and click Apply.
6. Start a new game.

Load Order

Config files follow the same load order rules as every other mod file — see Load Order and Conflict Resolution below. When multiple active mods provide the same config file, the mod appearing later (higher priority) in the Mod Manager list wins on conflict, but every field override from the lower-priority mod is still applied first; the higher-priority mod then only overwrites the specific fields it also specifies.

When Changes Take Effect

Constants are applied the moment you press Apply in the Mod Manager. If a game is already in progress, restart it to see the effect — the changed constants govern the ongoing simulation, so a running game only picks up the new values from its next cycle onward.

Limitations

• Array lengths are fixed. You can change an array's element values, but you can't add or remove elements — the expected length for each array is shown in the extracted template file.
• ID and enum constants aren't exposed. Fields that identify game object types (race IDs, treaty type IDs, action IDs, and so on) are intentionally locked and won't appear in the template files.
• String fields aren't exposed. Ability names and display label arrays are handled through the i18n system, not through config files.

Troubleshooting

Symptom	Likely Cause	Fix
Mod doesn't appear in the Mod Manager	Missing or malformed mod.json	Verify mod.json sits in the folder root and its id field is present and non-empty.
Extract Game Data creates new_mod_1 instead of new_mod	A folder named new_mod already exists	Rename or delete the existing folder before extracting again.
Mod appears but shows a version warning	gameVersion doesn't match the installed game version	Update gameVersion, or ignore the warning if the mod still works fine.
CSV changes have no effect	Syntax error in the CSV, or the mod isn't enabled	Check each row matches the exact column format — rows that fail are silently skipped.
Event never fires	ID conflicts with another event	Use event IDs above 300,000 to avoid collision with vanilla and other mods.
Focus tree not appearing	Filename not assigned to any faction	Set the focusSet column in data_factions.csv to the filename of your focus JSON, without .json.
Spirit not appearing as an adoptable option	isAdoptableManually is false	Set it to true.
Image override not working	Wrong file path or wrong pixel dimensions	The file must sit at exactly the same relative path as in assets/, matching original dimensions.
Mod causes a crash on data load	Malformed JSON or CSV syntax error	Check for missing commas, unclosed brackets, or wrong column counts; validate JSON files with a validator.
Load order changes not applying	Forgot to click Apply	Always press Apply after changing the mod list.
Save shows a red [!] badge and won't load	A mod active when the save was created is no longer installed	Reinstall and enable the missing mod, then try again.
Scenario doesn't appear in the Scenarios screen	scenario field missing from mod.json, or the mod isn't enabled	Add the scenario field to mod.json and enable the mod.
Scenario loads but custom content is missing	Mod not enabled, or an ID collision with vanilla	Enable the mod and verify custom IDs sit within the recommended mod range below.

ID Ranges — Avoiding Collision

Sticking to these ranges keeps a mod compatible with both future vanilla updates and other mods running alongside it:

Data Type	Vanilla Range	Recommended Mod Range
Troop id	1–199	1000+
Faction id	1–20	100+
Terrain id	10–800	2000+
Technology id	1–99	500+
Equipment id	200–299	1000+
Project id	0–199	500+
Skill id	1–99	500+
Strategy id	1–11	100+
Personality id	0–20	100+
Province development id	1–10	100+
Event id (general)	100001–100999	300001+
Event id (army)	1001–1999	10000+
Event id (settlement)	2001–2999	20000+
Focus node id	1001–1999	5000+

These are guidelines rather than hard enforcement — two mods can still collide if they both happen to pick the same ID within their recommended range. Documenting your own mod's ID range in your release notes makes conflicts far easier for players to spot.

See also

• CSV and JSON Reference
• Workshop Uploader Guide
• Difficulty Levels