Wiki menu

HUD layout: slots and trackers

Replace or hide parts of the game HUD from a mod with layout.json and slot layout files, and add top-bar gauges with hud_trackers.json.

Last updated for v0.5.35
On this page

A mod can rearrange or remove parts of the in-game interface (the HUD), and add gauges of its own to the top bar. The HUD is split into slots. Content/ui/layout.json says what your mod does with each slot, small layout files describe the replacements, and Content/ui/hud_trackers.json adds the gauges.

The mod needs the InjectUI permission in mod.json. Without it the game ignores these files. Players who do not use the mod see the HUD unchanged.

HUD slots

Each slot is a run of the game’s top-level HUD elements. The generated file StreamingAssets/modding/hud_slots.json is the full contract: every slot, every named element in it with its type and parent, which elements a replacement must keep, and whether the slot can be replaced or hidden.

Slot idContainsReplaceHideElements a replacement must keep
topbarCountry name and flag, the treasury, GDP, manpower and population values, the date and the speed buttonsyesnogame-date, btn-pause, btn-play, btn-fast, btn-vfast
alertsThe alert bar and the priority stripyesnoalert-bar, priority-strip
sidebarThe country panel and the page content inside ityesnotab-content-container, country-name
railThe domain rail and its tabsyesnonav-tab-overview, nav-tab-economy, nav-tab-military, nav-tab-recruit, nav-tab-diplomacy, nav-tab-intel, nav-tab-politics, nav-tab-tech, nav-tab-agenda, nav-tab-provinces
mapmodesThe map mode buttonsyesyesnone
statusbarThe bottom status baryesyesnone
outlinerThe outliner panelyesyesoutliner-content
tooltipsThe province and army hover cardsnononot applicable
eventpopupThe event popupyesnoevent-popup-title, event-popup-description, event-popup-options
armybarThe army command baryesnoarmy-bar-cards, btn-bar-merge, btn-bar-split, btn-bar-cancel-move, btn-bar-deselect

The rail’s nav-tab-sphere, nav-tab-institutions and nav-tab-trade are optional. A replacement can leave them out.

The layout file

{
  "slots": {
    "mapmodes":  { "mode": "replace" },
    "statusbar": { "mode": "hide" },
    "outliner":  { "mode": "replace", "file": "Content/ui/layouts/my_outliner.uxml" }
  }
}

slots maps a slot id to what the mod does with it. A slot that is not listed is left alone.

FieldValuesDescription
modereplace, hide, vanillareplace rebuilds the slot from your layout file and is the default. hide removes the slot from the screen. vanilla leaves it alone.
fileA path inside the mod folderFor replace only: the layout file. Defaults to Content/ui/layouts/<slot id>.uxml.

If an entry is wrong (an unknown slot, a slot that cannot be hidden, a missing or invalid layout file), that slot stays as the game draws it and the other slots still apply. The problem is written to the log with the prefix [ModHud:<mod id>] and listed with the mod’s load errors. When several mods set the same slot, the one later in load order wins and the game logs a warning.

Writing a slot layout

A layout file is a small subset of UXML, Unity’s interface markup.

<ui:UXML xmlns:ui="UnityEngine.UIElements">
  <ui:VisualElement name="mod-mapmodes-column" style="position: absolute; left: 90px; top: 120px; flex-direction: column;">
    <ui:Label text="MAP" style="color: #ffb347;" />
    <ui:Button name="mm-btn-political" />
    <ui:Button name="mm-btn-terrain" />
  </ui:VisualElement>
</ui:UXML>
PartAllowed
RootOne UXML element.
ElementsVisualElement, Label, Button, ScrollView. Any other element makes the layout invalid.
Attributesname, class, text, picking-mode (Position or Ignore), focusable (true or false), style, and hook on a Button. Other attributes are ignored.
SizeAt most 256 KB, 32 levels deep and 2000 elements. No DTD or external references.

Game elements are placed by name. An element whose name is one of the slot’s game element names is a placeholder. The game’s own live element, with everything inside it, takes that place, and keeps working. The placeholder’s text, style and children are ignored; its class values are added to the live element. Each game element can be placed once, and not inside another placed game element.

Your own elements are built fresh. Their names must start with mod-, or be left out. text is a plain string, or @some.key for a localization key. style takes the same properties as the inline style of injected interface, written as property: value; pairs. A Button with a hook attribute raises the on_ui_action hook with that name when clicked.

Required elements must be placed. A replacement must place every required element of its slot, or the game element that contains it. Otherwise the slot stays as the game draws it.

The rest is parked. Game elements your layout does not place are moved into a hidden holder that stays in the interface, so the game can still update them. Hiding a slot parks all of it.

Each top-level element of your layout also gets the classes mod-slot and mod-slot--<slot id>, which a theme rule can select.

Starting from the game’s layout

The game ships its own layout of every replaceable slot as StreamingAssets/modding/hud_slots/<slot id>.uxml. The Mod Builder’s COPY GAME LAYOUT button on the HUD slots page writes that file into your mod. An unmodified copy places every game element of the slot and so reproduces the slot as it is. Edit it by removing, moving and wrapping the placeholders.

HUD trackers

A tracker is a gauge on the top bar, after the treasury, GDP, manpower and population. It shows one number your mod names. Trackers are listed in Content/ui/hud_trackers.json:

{
  "trackers": [
    {
      "id": "invasion",
      "value": "wave.wave_2.remaining",
      "country": "viewer",
      "label_key": "mymod.tracker.invasion",
      "tooltip_key": "mymod.tracker.invasion.desc",
      "icon": "Content/ui/icons/invasion.png",
      "min": 0,
      "max": 100,
      "format": "of_max",
      "bands": [
        { "from": 0, "tone": "bad" },
        { "from": 30, "tone": "warn" },
        { "from": 70, "tone": "good" }
      ],
      "target": { "low": 60, "high": 100 },
      "visible_when": [
        { "type": "has_flag", "flag_name": "invasion_started" }
      ]
    }
  ]
}
FieldRequiredDescription
idyesThe tracker’s id, unique in the file: lower-case letters, digits and underscores, at most 32 characters. Shown when the tracker has no label.
valueyesWhere the number comes from. See the list below.
countrynoWhose number a variable or lifetime counter is, and whose state visible_when tests: viewer (the local player’s country, the default) or an ISO3 code.
label_keynoLocalization key of the label. Without one the tracker shows its id, and VALIDATE warns.
tooltip_keynoLocalization key of the hover text.
iconnoA PNG or JPG inside the mod folder, at most 4 MB and 2048 pixels a side.
minnoThe gauge’s left end. Default 0.
maxnoThe gauge’s right end. With a max above min the tracker draws a gauge under its value; without one it shows the value only.
formatnonumber (the default), percent (adds a percent sign) or of_max (value / max; needs max).
bandsnoColour bands, each { "from": number, "tone": name }, in rising order of from. From a band’s value up to the next, the value and the gauge marker take its tone.
targetnoA shaded target band on the gauge: { "low": number, "high": number }, with high above low.
visible_whennoConditions that must all hold for the tracker to show. Empty means always shown.

value takes one of these forms:

  • mod_state.<key>: a number in the mod’s own saved state, the store a script writes with state_set.
  • variable.<name>: an event variable of the tracker’s country.
  • lifetime.<counter>: a lifetime counter of the tracker’s country: personnel_lost, regiments_lost, ships_lost, aircraft_lost, civilians_affected, provinces_gained, provinces_lost, wars_won or wars_lost.
  • wave.<wave id>.<measure>: an invasion wave of this mod, where the measure is remaining, remaining_stacks, spawned or spawned_stacks.

A band’s tone is one of neutral, good, warn, bad, gold, amber, muted or accent. The theme decides each tone’s colour.

visible_when uses the event condition format, limited to these types: has_flag, not_has_flag, flag_age_months_gt, flag_age_months_lt, variable_gt, variable_lt, variable_eq, lifetime_gt, lifetime_lt, date_after, date_before, wave_eliminated, wave_remaining_gt and wave_remaining_lt.

A tracker with an error is dropped and named in the log; the others stay.

Limits

  • A layout is applied when the player enters a game and undone when they return to the main menu. It is not saved and does not change the simulation.
  • The top bar shows at most three trackers in all. With several mods, the first three in load order show. A hud_trackers.json larger than 64 KB is ignored.
  • Trackers are presentation only. Players with different trackers can share a multiplayer game and see different top bars.
  • If a topbar replacement leaves out the part of the top bar that holds the four values, trackers are not shown.
  • A game style rule that depends on a parent element stops matching an element you moved out from under that parent. Restyle it with a theme rule on a class you add in the layout.
  • The game can still measure or toggle a parked panel. With the sidebar slot replaced, for example, collapsing the sidebar changes a hidden panel and nothing visible.
  • A layout cannot give a slot a different size at different resolutions. Position with the style properties position, left, top and so on.

Checking a layout

VALIDATE in the Mod Builder checks layout.json against mod_ui_layout.schema.json and hud_trackers.json against mod_ui_hud_trackers.schema.json, then applies the slot rules: an unknown slot, a slot that cannot be replaced or hidden, a missing or unreadable layout file, an element name that is neither a game element of the slot nor starts with mod-, a game element placed twice, and a required element left out are errors. A tracker icon that is missing or not a PNG or JPG is a warning. It also warns when the mod lacks InjectUI.

Play Global Protocol: New World Order

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