A mod can add its own pieces to the in-game interface (the HUD): a toolbar of buttons, extra rows in the province and country panels, and popups raised from a script. The buttons and rows are declared in one JSON file, usually Content/ui/inject.json. A click on a button calls your script, and the script decides what happens.
What you can add
| Piece | Where it shows | Declared in |
|---|---|---|
| Toolbar buttons | A small toolbar over the map | toolbarButtons in the injection file |
| Province rows | The Province panel | provinceDetailRows in the injection file |
| Country rows | The Overview page of the country panel | countryPanelRows in the injection file |
| Popups | A popup with your title and body | A script call, see Popups |
The injection file does not add full-screen panels and does not move or hide the game’s own HUD. To rearrange the HUD see HUD layout; to recolour it see HUD theming.
Setting it up
Two entries in mod.json turn injection on:
{
"permissions": ["InjectUI"],
"entrypoints": {
"ui": "Content/ui/inject.json"
}
}
- Without the
InjectUIpermission the game skips the file, and VALIDATE in the Mod Builder warns that none of it is injected. entrypoints.uiis a path inside the mod folder. If it is missing or does not resolve, the game looks forui/panels.jsonin the mod folder.
The Mod Builder edits this file on its Toolbar buttons, Toolbar style, Province rows and Country rows pages.
The injection file
{
"toolbarButtons": [
{
"id": "my_mod.open_ledger",
"iconPath": "Content/ui/icons/ledger.png",
"tooltip": "my_mod.ui.ledger.tooltip",
"hookName": "open_ledger"
}
],
"provinceDetailRows": [
{ "label": "my_mod.ui.province.era", "value": "Late medieval" }
],
"countryPanelRows": [
{ "label": "my_mod.ui.country.standing", "value": "my_mod.ui.country.standing.value" }
],
"style": {
"keys": ["top", "right"],
"values": ["120px", "30px"]
}
}
All four top-level fields are optional.
toolbarButtons
| Field | Required | Description |
|---|---|---|
id | yes | The button’s id, unique within the mod. It becomes the element’s name. |
hookName | yes | The name passed to your script when the button is clicked. A button without one is skipped. |
iconPath | yes | Path inside the mod folder to the icon image. The button is 32 by 32 pixels and the icon is scaled to fit. A button whose icon is missing is drawn blank. |
tooltip | no | Text shown when the player hovers the button: plain text or a localization key. |
VALIDATE warns about a button with no hookName, id or iconPath, a duplicate id, and an icon file that does not exist.
provinceDetailRows and countryPanelRows
Each entry is a static row: a name on the left and a text on the right.
| Field | Required | Description |
|---|---|---|
label | yes | The row’s name: plain text or a localization key. |
value | yes | The text shown beside it, exactly as written, or a localization key. The game does not calculate it. A row with no value shows only its label. |
The game reads no other field of a row. valueExpression, format, iconPath and showWhenZero change nothing, and VALIDATE warns about each one it finds.
style
style moves or restyles the toolbar. It holds two parallel lists, keys and values, applied in order over the toolbar’s default look, so a later entry wins.
| Property | Values |
|---|---|
position | absolute, relative |
left, right, top, bottom | A length |
width, height, min-width, min-height, max-width, max-height | A length |
margin, margin-top, margin-bottom, margin-left, margin-right | A length |
padding, padding-top, padding-bottom, padding-left, padding-right | A length |
display | flex, none |
visibility | visible, hidden |
flex-direction | row, row-reverse, column, column-reverse |
flex-grow, flex-shrink | A number |
flex-wrap | wrap, nowrap |
align-items | center, flex-start, flex-end, stretch |
justify-content | center, flex-start, flex-end, space-between, space-around |
background-color, color, border-color | A hex colour such as #181410 or #181410cc |
border-radius | A length |
font-size | A length |
white-space | normal, nowrap |
text-align, -unity-text-align | left, center, right |
opacity | A number from 0 to 1 |
A length is written 12px, 50% or as a plain number of pixels. A property that is not in the table is ignored, and VALIDATE warns about it.
Styling
By default the toolbar is a horizontal strip near the top of the screen. Its look comes from two classes in the game’s own style sheet: mod-toolbar-panel on the toolbar and mod-toolbar-button on each button. You have two ways to change it:
- the
styleblock above, for the toolbar’s position, size and colours; - a HUD theme rule on
.mod-toolbar-panelor.mod-toolbar-button, including:hover.
The game does not load .uss style sheet files from a mod folder. A .uss file placed under Content/ui/ has no effect.
When injected interface appears and disappears
- The game injects the interface of every active mod when the player enters a game, and removes it when they return to the main menu.
- Injection always clears what an earlier injection left, so entering a game twice does not create two toolbars.
- Each mod’s toolbar is one element named
mod-panel-<mod id>. - The province and country rows are read by their panels when the panels build their content.
Popups
A popup is raised from a script, not from the injection file. It needs the InjectUI permission.
| From | Call |
|---|---|
| WASM | show_mod_popup(title, body), or show_mod_popup_key(title_key, body_key, args) to show text by localization key with arguments |
| C# | ModHookBus.ShowPopup(modId, title, body), or IModServices.ShowPopupLocalized(titleKey, bodyKey, args) |
A title or body that is exactly a localization key is shown in the player’s language. A popup only affects the local screen, so it is allowed from a button click in multiplayer.
Wiring a button to a script
A click raises the on_ui_action hook with two strings: the button’s hookName and your mod’s id.
In a WASM module, export on_ui_action. Only the module of the mod that owns the button is called. This is how the example mod’s AssemblyScript source answers its toolbar buttons (shortened to two of them):
const MOD_ID = "globalprotocol.old_world_order";
const WELCOME_HOOK = "owo.welcome";
const AMBITIONS_HOOK = "owo.ambitions";
export function on_ui_action(
hookNamePtr: i32, hookNameLen: i32,
modIdPtr: i32, modIdLen: i32
): void {
const modId = readString(modIdPtr, modIdLen);
if (modId != MOD_ID) return;
const hookName = readString(hookNamePtr, hookNameLen);
if (hookName == WELCOME_HOOK) {
showPopup("Strategic Briefing: 1450 AD", buildBriefingBody(lastYear, lastMonth));
} else if (hookName == AMBITIONS_HOOK) {
showPopup("Historical Ambitions & Paths to Glory", buildAmbitionsBody());
}
}
readString and showPopup are helpers in the mod’s gp.ts: the first decodes a UTF-8 string from a pointer and a length, the second wraps the show_mod_popup host function.
In C#, subscribe to ModHookBus.OnUiAction or override OnUiAction on ModBase. The event is raised for every mod’s buttons, so check the mod id first:
protected override void OnUiAction(string hookName, string modId)
{
if (modId != "com.myname.mymod") return;
if (hookName == "open_ledger")
ModHookBus.ShowPopup(modId, "Ledger", "Nothing to report.");
}
A click runs on one player’s game only. In a multiplayer session, calls from on_ui_action that would change the game (treasury, events, flags, variables, mod state, diplomacy) are refused. Popups and log lines still work. Make game changes from simulation hooks such as on_economy_tick. Single-player has no such limit.
Text and localization
Every player-visible string in the injection file (tooltips, row labels and values) can be plain text or a localization key. A key your mod or the game defines is shown in the player’s language; any other string is shown as written. Add your keys to Content/localization/<language>.csv, one file per language, as key,value rows. A key with an empty value in a language shows the key itself there.
An example from the example mod
The example mod’s Content/ui/inject.json adds four toolbar buttons, moves the toolbar and gives it a dark panel. This is the first button and the style block:
{
"toolbarButtons": [
{
"id": "owo.welcome_btn",
"iconPath": "Content/ui/icons/welcome.png",
"tooltip": "Strategic Briefing: 1450 AD",
"hookName": "owo.welcome"
}
],
"style": {
"keys": ["position", "top", "right", "flex-direction", "align-items", "background-color", "border-color", "border-radius", "padding", "opacity"],
"values": ["absolute", "58px", "32px", "row", "center", "#181410", "#967a4d", "6px", "4px", "1"]
}
}
The same file adds a country row whose label, mod.ui.country.era_standing, is a localization key defined in the mod’s language files.