HUD
Usage guide of the HUD kits: hud.action, hud.open_world, hud.moba, hud.nameplates, hud.minimap and hud.tactical: what each shows, settings and defaults, scenes, modding, engines.
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 #
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.
{ "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 |