# HUD kits (hud.*)

The overlay drawn over a game: health, objectives, mini-map, hero bars. Readable offline: `gripforge docs hud`, or the MCP tool
`gripforge_docs` (topic `hud`). Menus, theme, prompts and the end screen are in `ui-screens`; the HTML page layer is `ui-webui`.

## What it is for

A HUD kit is a view (role `view`): it decides nothing of the game. It publishes which elements to show (`hud.show.<element>`),
keeps the small state of the overlay (a kill feed, a banner) and raises toasts (`hud.notify`); the host application draws it. Each
kit reads the state and events of the kits it is made for and shows an element only when the variables it reads are defined.

| Kit | For | Requires |
| --- | --- | --- |
| `hud.action` | an action roguelike: health, dash, special, boons, boss, room, wave, money, damage numbers, boon offer | `combat.health` |
| `hud.open_world` | an open world: objective, wanted stars, speedometer, interaction prompt, money | `mission.run` |
| `hud.moba` | a lane game: score and clock, hero bar, abilities, items, shop, allied frames, kill feed, announcements | `moba.match` |
| `hud.nameplates` | MOBA hero bars above the characters: name, level, segmented health, mana | `moba.match`, `moba.controls`, `combat.health` |
| `hud.minimap` | a world-space mini-map for any game | nothing besides `game.engine` |
| `hud.tactical` | the editable layout of a team shooter HUD (roster, clock, health, equipment, objectives, results) | nothing besides `game.engine` |

`hud.action`, `hud.open_world` and `hud.moba` are mutually exclusive main HUDs (one per project). `hud.minimap`,
`hud.nameplates` and `hud.tactical` sit beside them.

## Turn it on

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "hud.action" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "hud.action", config: { "healthStyle": "minimal", "lowHealth": 0.25 } }
```

Only the keys that differ from the defaults need to be written. A new game gets the HUD of its genre from the generator; the
full reference of a kit is `gripforge kit api <id>`.

## Settings and defaults

### hud.action

| Key | Default | Meaning |
| --- | --- | --- |
| `show` | every element | elements drawn: `health`, `dash`, `special`, `boons`, `boss`, `room`, `encounter`, `money`, `damage_numbers`, `offer` |
| `lowHealth` | 0.3 | health ratio under which `hud.low_health` is raised |
| `healthStyle` | `bar` | `bar` (built-in plate), `frame` (an image frame), `minimal` (slim themed bars, no panels) |
| `healthLabel` | empty | the line above the bar; `{name}` is the name of this machine's player (`coop.session`) |
| `healthFillRange` | `[0, 1]` | with `frame`: the part of the fill image's width the health covers |
| `party` | `none` | `frame` (with `healthStyle: "frame"`) also draws the other players of a coop party |
| `chapter` | empty | top-left panel `{ eyebrow, title, text }`; with a title, the room line sits under it |
| `actions` | `[]` | buttons at the bottom centre, shown only, never clicked through to the game |
| `hint` | empty | one discreet line of text; never keys or controls (an audit flags and a migration empties it) |
| `moneyFormat` | empty | empty: the money plate at the top right; otherwise a discreet line from this text, `{n}` being the amount |
| `loadingBar` | `false` | a thin bar while `asset.preload` loads the rest of the game behind it |

Elements read vars such as `player.health`, `dash.charges`, `boons.owned`, `boss.*`, `room.*`, `encounter.*`, `run.money`. Toasts
come from `boon.acquired`, `room.cleared`, `door.unlocked`, `encounter.wave`, `boss.phase` and `run.ended`. The boon offer is
answered by the actions `hud.choice_1` to `hud.choice_4` (keys 1 to 4 by default, rebindable) or a click. Service `hud.action`:
`notify(text, { seconds?, style? })`, `shown(element)`, `setShown(element, visible)`, `loading(lang)`, `frame()`.

### hud.open_world

| Key | Default | Meaning |
| --- | --- | --- |
| `show` | `objective`, `wanted`, `speed`, `prompt`, `money` | channels drawn; one whose variable no kit defines stays hidden |
| `layout.elements` | `[]` | chrome elements `{ id, slotId?, label?, anchor, width, height?, inset? }` |

Channels are bound with `state.bind`, so nothing polls: `mission.objective.label`, `wanted.level`, `vehicle.speed` (only while
driving), `interaction.prompt`, `economy.money`. The slot `hud_skin` takes panel chrome. Service `hud.bind` (exclusive):
`channels()`, `notify(text, seconds?, style?)`. Quest markers (instances whose state `quest_available` is true) are listed by
`hud.bind.markers()` and counted in `hud.markers`.

### hud.moba

| Key | Default | Meaning |
| --- | --- | --- |
| `show` | all elements | `score`, `hero`, `abilities`, `items`, `stats`, `shop`, `team`, `feed`, `announcements`, `respawn`, `minimap` |
| `feedSize` | 5 | lines kept in the kill feed |
| `feedSeconds` | 8 | seconds a feed line stays |
| `announceSeconds` | 3.5 | seconds a banner stays |

Ability and item icons are slots `moba_ability_icon:<ability id>` and `moba_item_icon:<item id>`. The shop opens with the input
action `moba.shop`, which the player rebinds. The feed (`hud.moba.feed`, a JSON array of `{ text, team, until }`) and the banner
(`hud.moba.announce`) are saved. Banners come from `moba.wave`, `moba.structure.destroyed`, `moba.hero.killed`, `moba.victory`.

### hud.nameplates

`visible`, `showName`, `showMana`, `showLevel` (all `true`), `width` (160 px, 100 to 240), `healthTicks` (8 segments, 0 for none),
`offsetY` (0.45 m above the hero), `avoidOverlap` (`true`) with `maxShift` (150 px), `playerName` (the local handle, else the
champion name) and the four colours `allyColor`, `enemyColor`, `playerColor`, `manaColor`. Service: `snapshot()` (rows with id, name,
team, level, health and mana) and `setName(entityId, handle)` for a session name (not saved). Dead and stealthed enemies are
omitted; allies in bushes stay visible. Minions and structures keep their simple bars.

### hud.minimap

| Key | Default | Meaning |
| --- | --- | --- |
| `visible` | `true` | draw the map |
| `mode` | `overview` | `overview` of the whole world or `follow` the player |
| `orientation` | `north` | `north` up or `player` heading up |
| `shape` | `circle` | `circle` or `square` |
| `zoom`, `range` | 1, 100 | zoom 0.5 to 4; metres across the view in follow mode at zoom 1 |
| `playerTag` | `player` | tag of the entity drawn as the player |
| `markerTags` | `racer`, `objective`, `marker` | tags of the entities drawn as markers |
| `playerColor`, `markerColor` | `#ff934b`, `#fff3d9` | colours |
| `zone` | `false` | draw the zone of a zone kit (the storm edge now and where it goes) |

Routes are documents of `minimap_layers`: `{ id, points: [{ x, z }…], closed?, color?, width? }`. An entity becomes a marker with the
component `map_marker` `{ kind: "actor" | "objective", color?, label? }`. Service (exclusive): `snapshot()`, `configure(options)`,
`setLayer` / `removeLayer`, `setMarker` / `removeMarker`, `follow(entity)`, `click(x, z, button)`. A click is told to the game as
`minimap.clicked` (camera jumps, orders).

### hud.tactical

`themeId` (`harbor`, `gothic`, `neon`, `minimal`; default `minimal`) and `document` (a HUD Studio v2 document; empty uses the
tactical template). `brief`, `conceptItem`, `conceptHash` and `studioHud` hold the optional concept image and the Studio document it
came from. Service: `document()` returns the layout, `concept()` the concept image id or null. It owns no rule: the page fills the
document with the match snapshot, and widgets the game does not support stay hidden.

## Scenes

A scene whose `ui.hud` names another HUD kit turns this one off (`hud.active` false and every `hud.show.*` false).
`layers["hud.action"].show` (or the same for `hud.open_world`, `hud.moba`) lists the elements of one scene over the config.
`hud.scene` holds the scene title (through `i18n.text` when it is a key), else its id. Entering a scene clears the MOBA feed and
banner.

## Hooks and modding

The HUD kits are views, so none declares a hook: the decisions behind what they show (damage, a tower falling, a purchase) have
their own hooks in the kits that take them. Texts and toast durations are not config: the texts go through `i18n.text`
(`hud.action.<key>`, `hud.open_world.<key>`), which a game translates or rewrites. A mod may override the config keys (all listed
above, except `hud.nameplates` `playerName`) and add documents to `minimap_layers`.

```json
{ "schema": "gripforge.mod/1", "id": "slim_hud", "name": "Slim HUD", "version": "1.0.0",
  "requires": { "hud.action": "^1" }, "config": { "hud.action": { "healthStyle": "minimal", "show": ["health", "boss", "money"] } } }
```

## Engines

| Kit | Where it is drawn |
| --- | --- |
| `hud.action`, `hud.open_world`, `hud.minimap` | the web player (React overlay), and the native player, Godot, Unity and Unreal deliveries |
| `hud.moba`, `hud.nameplates`, `hud.tactical` | web and native player |

## When it does not do what you expect

| Symptom | Cause and fix |
| --- | --- |
| An element does not show | the vars it reads are not defined by any installed kit, or it is missing from `show` |
| Two HUDs fight | the main HUDs are exclusive: a scene `ui.hud` names the one that draws |
| Keys appear on screen | the HUD never shows keys; use `ui.prompts` in a tutorial and Options > Controls |
| Markers are missing on the mini-map | the entity has no `map_marker` component and none of the `markerTags` |
| The loading bar never appears | `loadingBar` is `false`, or `asset.preload` is not installed |