**Language / Langue :** [[fr:yaml:hud|FR]] | **EN**

====== HUD - Panels (YAML) ======

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.

===== Positions =====

  * ''top'', ''bottom'', ''left'', ''right''
  * ''top-left'', ''top-right'', ''bottom-left'', ''bottom-right''

===== Base Syntax =====

<code yaml>
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"
</code>

===== Size =====

^ Key ^ Effect ^
| ''size: 30'' | 30% of the game area along the main axis: height for top/bottom, width for left/right and corners. |
| ''width: 25'' | Explicit width as a percentage. |
| ''height: 15'' | Explicit height as a percentage. |

''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.

===== Style =====

<code yaml>
hud:
  position: top-right
  size: 38
  background: "#1a1a2e"
  text-color: "#e0e0ff"
  text: "Styled HUD"
</code>

===== Conditional Text =====

<code yaml>
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"
</code>

===== Split =====

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

<code yaml>
hud:
  position: left
  width: 28
  text: |
    Current zone
    demo_split
    [[split]]
    HP: v_hp_v
    Score: v_score_v
</code>

===== Several panels at once =====

<code yaml>
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"
</code>


===== Clear HUD =====

<code yaml>
# On a room, choice or event:
clear-hud:
  - all
</code>

To clear only one corner:

<code yaml>
clear-hud:
  - top-right
</code>

===== Video inside a HUD =====

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

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

A hosted video works here too. See [[en:yaml:medias|Sounds, images and videos]].

===== Room scope (4.17) =====

**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:

<code yaml>
hud:
  position: top-left
  scope: room
  text: The map of this room.
</code>

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 [[en:yaml:modeles|inline models]] too; ''grille_2d'' requests it explicitly. French syntax: ''portee: salle''.

===== Percentage and alignment in a panel =====

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''.

<code yaml>
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
</code>