A mod can recolour and resize the in-game interface (the HUD) with one file, Content/ui/theme.json. The theme is applied when a player enters a game with the mod active and removed when they return to the main menu. Players who do not use the mod never see it.
The mod needs the InjectUI permission in mod.json. Without it the game ignores the file. A mod cannot change fonts.
What a theme can change
The HUD is styled through design tokens: named values such as --surface-1 (a panel colour) or --t-body (the body text size) that the game’s style sheets refer to. A theme redeclares tokens, so everything styled through a token changes at once, including its hover and pressed states. For what tokens do not reach, a theme adds rules: a selector plus the properties it sets.
The token list ships with the game as StreamingAssets/modding/hud_theme_tokens.json. Each entry has:
| Field | Meaning |
|---|---|
name | The token, for example --surface-1. |
kind | color or length: what kind of value the token takes. |
default | The game’s own value. |
alias | true when the token is defined as another token, for example --accent is var(--color-neon-cyan). |
family | What the token is for: accent, gold, amber, danger, severity, buttons, relations, defcon, charts, intel, difficulty, lines, text, surfaces, palette, type, spacing or sizes. |
areas | The places in the game whose styles use it, most used first, such as top_bar, event_popup or economy. |
The Mod Builder’s HUD theme page lists the tokens by family and edits the file for you.
A theme cannot change:
- colours the game sets in code, such as some bars, badges and per-country colours, and the charts;
- the map itself: country colours, borders and labels;
- anything the game styles inline in code, because an inline value beats a style sheet.
Not every screen is styled through tokens. A token you change may recolour only part of a screen, so check the result in a running game and use rules for what the tokens miss.
The theme file
{
"base": "classic",
"tokens": {
"--surface-1": "#1b2230",
"--surface-2": "#232b3d",
"--color-neon-cyan": "#ffb347",
"--t-body": "17px"
},
"rules": [
{ "selector": "#top-bar", "background-color": "#101820", "border-color": "#ffb347" }
]
}
| Field | Type | Description |
|---|---|---|
base | string | Optional. Id of a built-in theme the tokens are applied on top of. The game has one built-in theme, classic, which is the standard look. An id the game does not know is ignored. |
tokens | object | Optional. Token name to value. Names start with --. A token the HUD does not use changes nothing. |
rules | array | Optional. Extra style rules, applied after the tokens, in file order. Each rule is an object with a selector and one or more properties. |
No other top-level field is allowed. Write only what you change: a token you leave out keeps the game’s value.
Values
| Kind | Accepted forms |
|---|---|
| Colour | #rgb, #rrggbb, #rrggbbaa, rgb(r, g, b), rgba(r, g, b, a). Red, green and blue run 0 to 255, alpha 0 to 1. |
| Size | 12px or 50%. |
| Number | A plain number, written as a JSON number or a string. |
| Reference | var(--other-token), accepted wherever a value is. |
A colour token takes a colour and a size token takes a size. If you change a token that aliases point at, the aliases follow.
Rules
The selector is a USS selector, checked by the game’s own selector parser. Use the HUD’s element names and classes (#top-bar, .stat-bar, .nav-tab:hover); Label and Button select by type. A rule can set these properties:
| Group | Properties | Values |
|---|---|---|
| Colour | color, background-color, -unity-background-image-tint-color, border-color, border-top-color, border-right-color, border-bottom-color, border-left-color | A colour. |
| Image | background-image | A path inside the mod folder to a PNG or JPG, at most 4 MB and 2048 pixels a side. |
| Border | border-width and its four sides | 2px or 2. |
| Corners | border-radius, border-top-left-radius, border-top-right-radius, border-bottom-right-radius, border-bottom-left-radius | A size. |
| Text | font-size, letter-spacing | A size. |
| Text style | -unity-font-style | normal, bold, italic, bold-and-italic. |
| Opacity | opacity | A number. |
| Box | margin, padding and the four sides of each; width, height, min-width, min-height, max-width, max-height, left, right, top, bottom | A size, 0 or auto. |
| Layout | display | flex, none. |
| Layout | flex-direction | column, row, column-reverse, row-reverse. |
| Layout | position | relative, absolute. |
Any other property is skipped. Colour properties do not take inherit, initial, unset, auto or none; write the colour.
Examples
A dark gold palette, as the example mod uses. It retints the accent colour, the panel surfaces and the main text through tokens:
{
"base": "classic",
"tokens": {
"--color-neon-cyan": "#d4af37",
"--surface-0": "#120f0c",
"--surface-1": "#1a1511",
"--surface-2": "#251e18",
"--color-text-main": "#f5eedc",
"--color-border": "rgba(150, 122, 77, 0.45)"
}
}
Rules for parts the tokens do not reach, and to hide an element the scenario has no use for:
{
"rules": [
{ "selector": "#top-bar", "background-color": "#181410", "border-color": "#8c734b" },
{ "selector": ".card:hover", "border-color": "#d4af37" },
{ "selector": "#btn-un", "display": "none" }
]
}
A rule on the class of your own injected toolbar restyles it with the rest of the theme:
{
"rules": [
{ "selector": ".mod-toolbar-button", "background-color": "#2a221b", "border-color": "#8c734b" }
]
}
Several mods
Active mods that ship a theme are merged in load order. A later token replaces an earlier one with the same name, rules are added one after another, and the last base wins.
Limits
| Limit | Value |
|---|---|
| File size | 256 KB. A larger file is ignored. |
| Tokens | 600. The rest are ignored. |
| Rules | 200. The rest are ignored. |
| Properties in one rule | 40. |
| Image | PNG or JPG inside the mod folder, at most 4 MB and 2048 pixels a side. |
A theme is presentation only. It does not change the simulation or saved games.
Checking a theme
- VALIDATE in the Mod Builder checks the file against
mod_ui_theme.schema.json, then reports unknown tokens (warning), values of the wrong kind (error), an unknownbase(warning), invalid selectors, unsupported properties and invalid values (errors), and images that are missing, too large or outside the mod folder (warning). It also warns when the mod lacksInjectUI. - When the game loads a theme, an entry it cannot read is dropped and the rest still applies. Each problem is written to the log with the prefix
[ModHud:<mod id>]and listed with the mod’s load errors.