This page covers the files a mod ships for what the player reads and sees: localization CSVs, replacement icons and event pictures, map marker art, flags and portraits, and the HUD trackers on the top bar. None of these change the simulation. HUD themes, HUD slot layouts and injected interface have their own pages, linked under Interface overrides.
- Localization
- Icons and event pictures
- Marker art
- Flags and portraits
- HUD trackers
- Interface overrides
Localization
Add one file per language at Content/localization/<language>.csv. The 13 languages the game ships are cz, de, en, es, es-419, fr, ja, ko, pt, pt-br, ru, tr and zh. A file for any other language code is ignored. Keys you define override the base game’s; keys you omit fall back to the shipped string.
File format
- One
key,valuerow per line, UTF-8, with no header row. - A row is split at its first comma, so a value may contain commas and does not need quoting.
- A value wrapped in double quotes has the quotes removed, and
""inside it becomes". \n,\r,\tand\\in a value are unescaped.- Blank lines and lines that start with
#are skipped. - A key must not contain a comma or a line break.
mymod.goal.secure_realm,Secure the realm
mymod.goal.secure_realm.desc,Fill the war chest, then look to the borders.
The game also reads the older location overrides/localization_<language>.csv. Use Content/localization/ for new mods.
There is no fallback between languages for a key only your mod defines. The game applies only the mod CSV of the player’s current language over the base strings. A key you put in en.csv and nowhere else is shown as the raw key, mymod.some.key, to every player not running English. Ship every key you define in all 13 files, even if some values start out as English placeholders.
The Mod Builder’s Translations page edits these files. A key it adds is written to all 13 files at once: English gets your text and the other files get an empty value for a translator to fill in. Rows whose value matches the English one are flagged same as English.
In a multiplayer lobby, differing text files are shown as a difference between players but do not stop the game from starting: translations are presentation.
Content names and descriptions
Names and descriptions from your content rosters fill the building.<id>.name / .description, unit.<id>.name / .description and resource.<Resource>.name / .description rows for every language whose CSV does not define that key. A re-skinned building therefore shows its new name instead of the base game’s text. The name of an addCountries entry that re-skins a base-game country fills country.name.<ISO3> the same way. A row in your CSV wins for its language, and that is where translations of those names go. See Names and descriptions and Reusing a base-game code.
Script popups
ModHookBus.ShowPopup(modId, title, body) (C#) and the show_mod_popup import (WASM) take plain text. A title or body that is exactly a localization key is shown as that key’s text in the player’s language. Text counts as a key when it has no spaces or commas, has at least one dot inside, does not start or end with a dot, and has a non-empty value in the string table. Any other text is shown as written, so literal text works too. The same rule applies to a legacy event’s title, description and option text; see Engine events and legacy events.
Define the key in all 13 files. Players see the key itself in a language you left out, or whose row for it is empty.
ModHookBus.ShowPopup("mymod", "mymod.popup.intro.title", "mymod.popup.intro.body");
For a popup whose text holds values, or for text a script composes itself, use the ABI 4 text calls: the localize and format imports and show_mod_popup_key (WASM), or IModServices.Localize, Format and ShowPopupLocalized (C#). They fill {0}, {1} and so on in a key’s text from arguments. The text differs by each player’s language, so a script shows it and never branches on it. See the WASM scripting page.
// mymod.popup.startup.body = "Strategic briefing: {0}-{1}"
services.ShowPopupLocalized("mymod.popup.startup.title", "mymod.popup.startup.body", new[] { "1450", "5" });
Showing a popup needs the InjectUI permission; see Permissions.
Icons and event pictures
A mod replaces the picture of a building, unit, resource or doctrine by shipping an image named after its id. The game looks for mod icons first and falls back to the base game’s art.
| Folder | File name | Shown in |
|---|---|---|
icons/buildings/ | The building id, for example castle.png | Build menus, the province view, tooltips, research unlock chips |
icons/units/ | The unit id | Recruitment, army cards, unit lists |
icons/resources/ | The resource id, for example oil.png | Resource panels and tooltips |
icons/doctrines/ | The doctrine’s icon id from doctrines.json | Research screen cards, milestones, hidden cards |
icons/research/ | The icon id of a mod research track, node or milestone | Mod research. These are looked up in icons/doctrines/ first, then icons/research/, then loose in icons/. |
images/events/ | An event’s image name, for example atlas_city.png | The event popup’s picture |
.png,.jpgand.jpegare read. If one id has both a.pngand a.jpg, the.pngwins.- Each folder has a twin under
Content/(Content/icons/buildings/,Content/images/events/and so on) that is read after it. - An event picture can use a name of its own, which your events pick with
image, or the name of a base-game picture, which replaces that picture for every event that uses it. See Event fields. - When several active mods ship the same icon or event picture, the mod that loads last wins, the same order as content rosters.
- New ids you add to a roster get their icon the same way.
- Icons and event pictures are presentation only and are not part of the multiplayer lobby check.
- Pictures in
icons/units/are portraits for menus. Map markers are set separately; see Marker art.
Marker art
overrides/military_markers.json sets the pictures units use on the map, per unit subcategory or per unit. The Mod Builder’s Map markers page edits it.
{
"army": { "subcategory_icons": { "infantry": "icons/markers/army_infantry.png" },
"unit_icons": { "war_elephant": "icons/markers/army_unit_war_elephant.png" } },
"fleet": { "subcategory_icons": { "destroyer": "icons/markers/fleet_destroyer.png" } },
"air": { }
}
The file has one section per branch: army, fleet and air. Each section may hold two maps.
subcategory_icons replaces the marker of every unit in that subcategory. Keys are the 16 marker subcategories, by name or by number:
| Number | Name | Also accepted |
|---|---|---|
| 0 | infantry | |
| 1 | armor | armored, tank |
| 2 | artillery | |
| 3 | special_forces | special |
| 4 | fighter | |
| 5 | bomber | |
| 6 | helicopter | attack_helicopter |
| 7 | drone | uav |
| 8 | destroyer | |
| 9 | frigate | |
| 10 | submarine | |
| 11 | carrier | |
| 12 | patrol_boat | patrol |
| 13 | amphibious | |
| 14 | mechanized_infantry | |
| 15 | cavalry |
unit_icons replaces the marker of a stack whose dominant unit is that unit: the strongest one (attack plus defence) for an army, the most numerous one for a fleet or an air wing. A unit icon wins over its subcategory’s. The army section’s unit_icons also gives the unit its picture in menus.
- Paths are relative to the mod folder. They are also looked up under
overrides/andContent/, and must stay inside the mod folder. - A mod with no marker art leaves the map exactly as the base game draws it.
- Validate Mod flags a key that is not a subcategory, a picture that is not in the mod folder, and a unit nobody defines.
Flags and portraits
These files are named by scenario and content fields. The rules for each are on the page that owns the field.
| File | Named by | Rules |
|---|---|---|
| A country’s flag, a PNG | flagPngPath in addCountries | Looked up in the mod folder, then the scenario folder. Must stay inside the mod folder. See Flag file. |
| The starting leader’s portrait, a PNG or JPG | leaderPortraitPath in addCountries | Same lookup and containment rule. See Leader identity. |
| Portraits for later leaders | The folder portraits/<ISO3>/, files <ISO3>_m_01.jpg, <ISO3>_f_01.jpg and so on | Used for leaders who take over during the game. See Leader identity. |
| A specialist’s portrait, a PNG | portrait in Content/specialists.json | Relative to the mod folder and inside it. Without one a placeholder is shown. See Specialists. |
HUD trackers
Content/ui/hud_trackers.json puts up to three gauges of your mod on the top bar, after the four national numbers. It needs the InjectUI permission, like the rest of Content/ui/, and works with or without a scenario. It is presentation only: the file is outside the multiplayer content check, so players with different trackers see different HUDs. The schema is mod_ui_hud_trackers.schema.json, and the Mod Builder’s HUD trackers page edits the file.
{ "trackers": [ {
"id": "invasion", "value": "wave.wave_2.remaining", "country": "viewer",
"label_key": "atlantis.tracker.invasion", "tooltip_key": "atlantis.tracker.invasion.desc",
"icon": "Content/ui/icons/invasion.png",
"min": 0, "max": 24, "format": "of_max",
"bands": [ { "from": 0, "tone": "good" }, { "from": 8, "tone": "warn" }, { "from": 16, "tone": "bad" } ],
"target": { "low": 0, "high": 6 },
"visible_when": [ { "type": "has_flag", "flag_name": "invasion_started" } ]
} ] }
| Field | Default | Description |
|---|---|---|
id | none | Required. 1 to 32 lower-case letters, digits or underscores, unique in the file. Shown when the tracker has no label. |
value | none | Required. Where the number comes from: mod_state.<key>, variable.<name>, lifetime.<counter>, or wave.<wave id>.remaining (also .remaining_stacks, .spawned, .spawned_stacks). The same names as an end-screen row. |
country | viewer | Whose variable or lifetime counter the tracker reads, and whose state visible_when tests: viewer (the local player’s country) or an ISO3 code. |
label_key | none | Localization key of the caps label, from your mod’s own localization rows. |
tooltip_key | none | Localization key of the hover text. |
icon | none | A PNG or JPG inside the mod folder, shown before the value. At most 2048 pixels a side and 4 MB. |
min | 0 | The gauge’s left end. |
max | none | The gauge’s right end. With a max above min, a compact gauge is drawn under the value. Without one, only the value shows. |
format | number | number writes the value, percent writes it with a percent sign, of_max writes value / max. |
bands | none | Colour bands, rising. From each band’s from up to the next one, the value and the gauge marker take its tone: neutral, good, warn, bad, gold, amber, muted or accent. The theme decides the colours. |
target | none | low and high: the shaded band on the gauge where the value should be. |
visible_when | none | Conditions that must all hold for the tracker to show: the victory condition types (has_flag, variable_gt, lifetime_gt, date_after and the rest listed under Scenario victories) and the wave conditions (wave_eliminated, wave_remaining_gt, wave_remaining_lt). See Conditions. |
- A file holds at most three trackers; more are ignored. With several mods, the first three trackers in load order show.
- A file larger than 64 KB is ignored.
- A tracker reads its number once per game tick, or when the viewer or the language changes, and rewrites its text only when the number changed.
- Validate Mod checks the permission, the schema, each tracker, and that each icon exists.
The HUD layout page shows trackers alongside the other top-bar changes a mod can make.
Interface overrides
The rest of a mod’s interface work lives under Content/ui/ and needs the InjectUI permission. Each file has its own page.
| File | What it does | Page |
|---|---|---|
Content/ui/theme.json | Recolours and restyles the HUD. | HUD theming |
Content/ui/layout.json | Replaces or hides parts of the HUD. | HUD layout |
The file named by entrypoints.ui in mod.json, usually Content/ui/inject.json | Adds toolbar buttons and rows to the country and province panels. | UI injection |
Content/ui/hud_trackers.json | Top-bar gauges. | HUD trackers on this page |
entrypoints.ui is described under Manifest fields.