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 id | Contains | Replace | Hide | Elements a replacement must keep |
|---|---|---|---|---|
topbar | Country name and flag, the treasury, GDP, manpower and population values, the date and the speed buttons | yes | no | game-date, btn-pause, btn-play, btn-fast, btn-vfast |
alerts | The alert bar and the priority strip | yes | no | alert-bar, priority-strip |
sidebar | The country panel and the page content inside it | yes | no | tab-content-container, country-name |
rail | The domain rail and its tabs | yes | no | nav-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 |
mapmodes | The map mode buttons | yes | yes | none |
statusbar | The bottom status bar | yes | yes | none |
outliner | The outliner panel | yes | yes | outliner-content |
tooltips | The province and army hover cards | no | no | not applicable |
eventpopup | The event popup | yes | no | event-popup-title, event-popup-description, event-popup-options |
armybar | The army command bar | yes | no | army-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.
| Field | Values | Description |
|---|---|---|
mode | replace, hide, vanilla | replace rebuilds the slot from your layout file and is the default. hide removes the slot from the screen. vanilla leaves it alone. |
file | A path inside the mod folder | For 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>
| Part | Allowed |
|---|---|
| Root | One UXML element. |
| Elements | VisualElement, Label, Button, ScrollView. Any other element makes the layout invalid. |
| Attributes | name, class, text, picking-mode (Position or Ignore), focusable (true or false), style, and hook on a Button. Other attributes are ignored. |
| Size | At 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" }
]
}
]
}
| Field | Required | Description |
|---|---|---|
id | yes | The tracker’s id, unique in the file: lower-case letters, digits and underscores, at most 32 characters. Shown when the tracker has no label. |
value | yes | Where the number comes from. See the list below. |
country | no | Whose 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_key | no | Localization key of the label. Without one the tracker shows its id, and VALIDATE warns. |
tooltip_key | no | Localization key of the hover text. |
icon | no | A PNG or JPG inside the mod folder, at most 4 MB and 2048 pixels a side. |
min | no | The gauge’s left end. Default 0. |
max | no | The gauge’s right end. With a max above min the tracker draws a gauge under its value; without one it shows the value only. |
format | no | number (the default), percent (adds a percent sign) or of_max (value / max; needs max). |
bands | no | Colour 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. |
target | no | A shaded target band on the gauge: { "low": number, "high": number }, with high above low. |
visible_when | no | Conditions 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 withstate_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_wonorwars_lost.wave.<wave id>.<measure>: an invasion wave of this mod, where the measure isremaining,remaining_stacks,spawnedorspawned_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.jsonlarger 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
topbarreplacement 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
sidebarslot 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,topand 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.