**Language / Langue :** [[fr:yaml:syntaxe-base|FR]] | **EN**

====== YAML Syntax — Base ======

The YAML format is the modern JDR-Bot scenario format. It is easier to read, easier to edit, and more powerful than the legacy .txt format.

===== File Structure =====

<code yaml>
title: "My scenario"
description: "A short adventure made with JDR-Bot."
markdown: story
font: serif

vars:
  hp:
    value: 10
    description: "Health points"

rooms:
  - id: start
    text: |
      You wake up in a dark forest.
      A light glows in the distance.
    choices:
      - command: forward
        button: "Move toward the light"
        to: clearing
      - command: wait
        button: "Stay where you are"
        to: bad_end

  - id: clearing
    text: "You reach a moonlit clearing."
    events:
      - if: ~
        end: victory
        text: "You found the way out!"
</code>

===== Root Keys =====

^ Key ^ Description ^ Required ^
| ''title:'' | Scenario title. | yes |
| ''description:'' | Description shown in the scenario catalogue and standalone export. | no |
| ''markdown:'' | Global text rendering: ''none'', ''fix'', ''bold'', ''italic'', ''quote'', ''story'', or a code-block language. | no |
| ''size:'' | Default text size in pixels. | no |
| ''font:'' | Default font: ''serif'', ''monospace'', ''cursive'', ''Georgia'', etc. | no |
| ''background:'' | Default text-block background on web/desktop. | no |
| ''text-color:'' | Default text color on web/desktop. | no |
| ''vars:'' | Global numeric variables. | no |
| ''text_vars:'' | Global text variables. | no |
| ''online_vars:'' | Persistent variables shared across playthroughs. | no |
| ''options:'' | Permanent toolbar buttons. | no |
| ''global_aliases:'' | Reusable button labels. | no |
| ''tags:'' | Reusable behavior groups. | no |
| ''models:'' | Reusable room models. | no |
| ''global_events:'' | Events available in every room. | no |
| ''global_actions:'' | Custom actions available everywhere. | no |
| ''global_timers:'' | Timers that survive room changes. | no |
| ''global_events_order:'' | Global event order: ''before'' or ''after''. | no |
| ''rooms:'' | Scenario rooms. | yes |

===== Room Structure =====

<code yaml>
- id: room_id
  num: 3                # optional explicit number; must stay increasing in YAML order
  button: "Home"        # label inherited by choices pointing to this room
  text: "..."
  background: "#111827"
  text-color: "#f5f0d8"

  init:
    - var: die
      value: "%=1:6"

  objects:
    - name: key
      location: table
      description: "An old rusty key."
      pickup_text: "You take the key."

  events:
    - if: "v_hp_v <= 0"
      to: game_over
      text: "You collapse."

  choices:
    - command: go
      button: "Go there"
      to: destination
      if: ~

  actions:
    - verb: inspect
      target: chest
      if: ~
      text_ok: "An old locked chest."

  hud:
    position: top
    text: "HP: v_hp_v"
</code>

===== Room Numbers =====

By default, rooms are numbered in YAML order. ''num:'' can preserve historical room numbers, but explicit numbers must be strictly increasing in the exported document. In the editor, reordering rooms in the left list changes that export order.

===== Endings =====

<code yaml>
events:
  - if: ~
    end: victory
    text: "Winning ending."

  - if: ~
    end: defeat
    text: "Losing ending."
</code>

===== Important Rules =====

  * Room IDs must be unique.
  * Variables used in conditions should be declared in ''vars:'', ''text_vars:'', ''online_vars:'' or ''init:''.
  * ''~'' means always true.
  * Events run in order; the first event that redirects with ''to:'' stops the following ones.
  * Object conditions use ''key'' or ''-key'', not ''o_key_o''.

===== See Also =====

  * [[en:yaml:texte|Text and formatting]]
  * [[en:yaml:variables|Variables]]
  * [[en:yaml:evenements|Events]]
  * [[en:yaml:choix|Choices and buttons]]
  * [[en:yaml:objets|Objects]]