Wiki menu

Adding buttons, rows and popups

Add toolbar buttons, province and country rows and popups to the HUD from a mod with inject.json, style them, and wire them to script hooks.

Last updated for v0.5.35
On this page

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

PieceWhere it showsDeclared in
Toolbar buttonsA small toolbar over the maptoolbarButtons in the injection file
Province rowsThe Province panelprovinceDetailRows in the injection file
Country rowsThe Overview page of the country panelcountryPanelRows in the injection file
PopupsA popup with your title and bodyA 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 InjectUI permission the game skips the file, and VALIDATE in the Mod Builder warns that none of it is injected.
  • entrypoints.ui is a path inside the mod folder. If it is missing or does not resolve, the game looks for ui/panels.json in 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

FieldRequiredDescription
idyesThe button’s id, unique within the mod. It becomes the element’s name.
hookNameyesThe name passed to your script when the button is clicked. A button without one is skipped.
iconPathyesPath 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.
tooltipnoText 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.

FieldRequiredDescription
labelyesThe row’s name: plain text or a localization key.
valueyesThe 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.

PropertyValues
positionabsolute, relative
left, right, top, bottomA length
width, height, min-width, min-height, max-width, max-heightA length
margin, margin-top, margin-bottom, margin-left, margin-rightA length
padding, padding-top, padding-bottom, padding-left, padding-rightA length
displayflex, none
visibilityvisible, hidden
flex-directionrow, row-reverse, column, column-reverse
flex-grow, flex-shrinkA number
flex-wrapwrap, nowrap
align-itemscenter, flex-start, flex-end, stretch
justify-contentcenter, flex-start, flex-end, space-between, space-around
background-color, color, border-colorA hex colour such as #181410 or #181410cc
border-radiusA length
font-sizeA length
white-spacenormal, nowrap
text-align, -unity-text-alignleft, center, right
opacityA 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 style block above, for the toolbar’s position, size and colours;
  • a HUD theme rule on .mod-toolbar-panel or .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.

FromCall
WASMshow_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.

Play Global Protocol: New World Order

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