HUD panels (hud:) display persistent information on the player screen: HP, score, mini-map, countdown, and so on.

HUD panels are visible on web and desktop. On Discord and terminal they are ignored; essential information should also appear in narrative text.

• top, bottom, left, right
• top-left, top-right, bottom-left, bottom-right

rooms:
  - id: fight_room
    hud:
      position: top-right
      text: |
        HP: v_hp_v / v_hpmax_v
        Score: v_score_v
    events:
      - if: ~
        do: "hp.-.3"
        button: "Lose 3 HP"
        text: "Ouch!"
        hud:
          position: top-right
          text: "HP: v_hp_v / v_hpmax_v"

width: and height: are independent; either can be used alone. Defaults depend on the position.

On mobile, side panels become top/bottom panels, so their size controls the height.

hud:
  position: top-right
  size: 38
  background: "#1a1a2e"
  text-color: "#e0e0ff"
  text: "Styled HUD"

vars: {hp: 10, hpmax: 10}
hud:
  position: top-right
  text:
    - if: "v_hp_v <= 0"
      text: "DEAD"
    - if: "v_hp_v <= 3"
      text: "CRITICAL! HP: v_hp_v"
    - text: "HP: v_hp_v / v_hpmax_v"

[[split]] divides the panel into two zones.

hud:
  position: left
  width: 28
  text: |
    Current zone
    demo_split
    [[split]]
    HP: v_hp_v
    Score: v_score_v

hud:
  - position: top-left
    text: "❤️ v_hp_v HP"
  - position: top-right
    text: "⭐ v_score_v pts"
  - position: bottom-right
    text: "📍 Area: v_area_v"

# On a room, choice or event:
clear-hud:
  - all

To clear only one corner:

clear-hud:
  - top-right

The video syntax can be used inside the text of a panel:

hud:
  position: top
  text:
    - "((loop;muted:https://example.com/video.mp4))"

A hosted video works here too. See Sounds, images and videos.

Panels remain persistent by default, until explicitly replaced or cleared. Add scope: room to clear a panel when leaving the room where it was placed:

hud:
  position: top-left
  scope: room
  text: The map of this room.

This works on rooms, actions, choices and events, including global interactions: ownership is assigned to the room where the panel is actually placed. An action without movement, a refresh or navigation to the same room does not clear it. Moving, using the phone's Back button or ending the game removes it. Other persistent panels remain visible.

A panel declared on the room is placed again on each entry. An interaction-created panel waits for that interaction to run again. Replaced panels are not automatically restored. Saves preserve scope and room ownership; older panels without scope retain their persistent behaviour.

In the editor, tick Clear when leaving the room on the panel. The box is unchecked by default. Scope is optional in inline models too; grille_2d requests it explicitly. French syntax: portee: salle.

Alongside [[split]], [[split:40]] gives 40% to the previous zone. The split follows the panel axis. Blocks such as [[align:center]]text[[/align]] also accept left / right, gauche / centre / droite, or a text variable t_cote_t.

title: 'Wiki 4.17: HUD'
vars:
  pv: 10
rooms:
- id: atelier
  text: A chest.
  hud:
    position: top
    text: |
      [[align:center]]Map.[[/align]]
      [[split:40]]
      HP: v_pv_v
  choices:
  - command: rester
    button: Stay
    to: atelier