Wiki menu

Data overrides: interface and text

Mod files for localization, icons, event pictures, map marker art, flags, portraits and HUD trackers.

Last updated for v0.5.35
On this page

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

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,value row 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, \t and \\ 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.

FolderFile nameShown in
icons/buildings/The building id, for example castle.pngBuild menus, the province view, tooltips, research unlock chips
icons/units/The unit idRecruitment, army cards, unit lists
icons/resources/The resource id, for example oil.pngResource panels and tooltips
icons/doctrines/The doctrine’s icon id from doctrines.jsonResearch screen cards, milestones, hidden cards
icons/research/The icon id of a mod research track, node or milestoneMod 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.pngThe event popup’s picture
  • .png, .jpg and .jpeg are read. If one id has both a .png and a .jpg, the .png wins.
  • 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:

NumberNameAlso accepted
0infantry
1armorarmored, tank
2artillery
3special_forcesspecial
4fighter
5bomber
6helicopterattack_helicopter
7droneuav
8destroyer
9frigate
10submarine
11carrier
12patrol_boatpatrol
13amphibious
14mechanized_infantry
15cavalry

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

FileNamed byRules
A country’s flag, a PNGflagPngPath in addCountriesLooked 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 JPGleaderPortraitPath in addCountriesSame lookup and containment rule. See Leader identity.
Portraits for later leadersThe folder portraits/<ISO3>/, files <ISO3>_m_01.jpg, <ISO3>_f_01.jpg and so onUsed for leaders who take over during the game. See Leader identity.
A specialist’s portrait, a PNGportrait in Content/specialists.jsonRelative 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" } ]
} ] }
FieldDefaultDescription
idnoneRequired. 1 to 32 lower-case letters, digits or underscores, unique in the file. Shown when the tracker has no label.
valuenoneRequired. 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.
countryviewerWhose variable or lifetime counter the tracker reads, and whose state visible_when tests: viewer (the local player’s country) or an ISO3 code.
label_keynoneLocalization key of the caps label, from your mod’s own localization rows.
tooltip_keynoneLocalization key of the hover text.
iconnoneA PNG or JPG inside the mod folder, shown before the value. At most 2048 pixels a side and 4 MB.
min0The gauge’s left end.
maxnoneThe gauge’s right end. With a max above min, a compact gauge is drawn under the value. Without one, only the value shows.
formatnumbernumber writes the value, percent writes it with a percent sign, of_max writes value / max.
bandsnoneColour 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.
targetnonelow and high: the shaded band on the gauge where the value should be.
visible_whennoneConditions 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.

FileWhat it doesPage
Content/ui/theme.jsonRecolours and restyles the HUD.HUD theming
Content/ui/layout.jsonReplaces or hides parts of the HUD.HUD layout
The file named by entrypoints.ui in mod.json, usually Content/ui/inject.jsonAdds toolbar buttons and rows to the country and province panels.UI injection
Content/ui/hud_trackers.jsonTop-bar gauges.HUD trackers on this page

entrypoints.ui is described under Manifest fields.

Play Global Protocol: New World Order

Out now in Early Access on Steam, with online multiplayer for 2–8 players.