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

====== Choices and Buttons (YAML) ======

Choices define the exits available from a room - navigation, access conditions and buttons shown to the player.

===== Minimal syntax =====

The simplest form: a destination, nothing else.

<code yaml>
choices:
  - to: forest
  - to: village
</code>

The room ''forest'' is reachable by typing ''go forest''. No button is displayed.

===== Adding a button =====

''button:'' displays a clickable button below the room text.

<code yaml>
choices:
  - button: "⬆️ Go north"
    to: forest

  - button: "🏠 Back to village"
    to: village
</code>

===== Typed command =====

''command:'' defines a keyword the player can type (in addition to the button).

<code yaml>
choices:
  - command: north
    button: "⬆️ Go north"
    to: forest
</code>

The player can click the button **or** type ''north'' or ''go north''. Without ''command:'', use the destination id, for example ''go forest''.

With [[en:yaml:texte#listing_choices_in_the_text|choice lists in the text]], a choice without an alias uses its position in the list. An explicit numeric alias takes priority over a room number or an automatic button shortcut.

See [[en:yaml:alias|Aliases and commands]] for global shortcuts and action aliases.

===== Button inherited from the room =====

If the destination room has a ''button:'', choices pointing to it without their own ''button:'' inherit that label automatically.

<code yaml>
rooms:
  - id: laboratory
    button: "⚗️ Laboratory"
    text: "..."

  - id: corridor
    choices:
      - to: laboratory    # displays "⚗️ Laboratory" without repeating it here
</code>

===== to: previous =====

''to: previous'' returns to the room the player came from.

<code yaml>
choices:
  - command: back
    button: "↩️ Back"
    to: previous
</code>

===== Access condition (if:) =====

''text:'' describes the attempt, including when ''if:'' fails. ''text_ok:'' and ''text_ko:'' describe the result of that condition.

<code yaml>
choices:
  - command: enter
    button: Enter
    to: secret_room
    text: "You push the door."
    if: "key"
    text_ok: "The lock gives way."
    text_ko: "The door stays locked."
</code>

^ Situation ^ Texts shown ^ Effect and movement ^
| No ''if:'' | ''text'' | Yes |
| Condition passes | ''text'' and ''text_ok'' | Yes |
| Condition fails | ''text'' and ''text_ko'' | No |
| ''text_ok'' without ''if:'' | No OK text | Yes |
| Disabled button | None | No |

Texts follow their order in the YAML. In the editor, use the move buttons beside the text fields to change that order; a new choice starts with the Text field.

''effect:'' runs after checking ''if:'', before the texts and movement. Texts therefore read the values updated by the effect, even when ''effect:'' is written after them.

This rule applies to choices. An action uses ''text_ok:'' on success, including without a condition. An event uses ''text:'' when it runs; that text is not shown when its condition fails.

===== Conditional button (visible-if / disabled-if) =====

<code yaml>
choices:
  - command: expert
    button: "🏆 Expert mode"
    to: expert_room
    visible-if: "v_score_v > 50"    # button hidden if score <= 50

  - command: move
    button: "💀 Move on"
    to: next_room
    disabled-if: "v_hp_v <= 0"      # button visible but inactive if HP = 0
</code>

  * ''visible-if:'' - the button disappears if the condition is false
  * ''disabled-if:'' - the button stays visible but cannot be clicked

===== Click effect (effect:) =====

''effect:'' runs an action **before** moving to the destination.

<code yaml>
choices:
  - command: buy
    button: "🪙 Buy (-10 gold)"
    to: shop
    if: "v_gold_v >= 10"
    effect: "gold.-.10"
</code>

===== Clear HUD on click =====

<code yaml>
choices:
  - command: back
    button: "↩️ Back"
    to: home
    clear-hud:
      - all
</code>