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

====== Variables (YAML) ======

===== Declaring variables =====

Numeric variables belong in ''vars:'':

<code yaml>
vars:
  score: 0
  hp:
    value: 10
    description: "Health points"
</code>

Text variables belong in ''text_vars:'':

<code yaml>
text_vars:
  hero_name:
    value: "Adventurer"
    description: "Hero name"
</code>

The description is shown when the player examines the variable or when it is attached to a permanent option. Use ''v_score_v'' for a numeric value inside text and ''t_hero_name_t'' for a text value.

===== Scope: regular, persistent or online =====

The suffix in the variable name determines its scope. All three kinds still belong in ''vars:'' or ''text_vars:''.

^ Name ^ Scope ^ Storage ^
| ''score'' | Current game | Removed with that game |
| ''record_p'' | Local persistent | Kept on this device between games |
| ''record_o'' | Online | Shared by players loading the same scenario source |

<code yaml>
id: my-scenario

vars:
  score: 0
  best_score_p: 0
  world_record_o: 0

text_vars:
  last_ending_p: "none"
  shared_message_o: "Welcome"
</code>

''online_vars:'' remains supported for older scenarios, but it is now legacy syntax. New ''_o'' variables should be declared in ''vars:'' or ''text_vars:''.

===== Persistent _p variables =====

A ''_p'' variable belongs to the scenario ''id:'', not to a game save. It survives a victory, defeat, give-up and new game. It is useful for records, collections, previously seen endings and counters shared by several playthroughs.

A root ''id:'' is required as soon as a scenario uses a ''_p'' variable. Keep it stable after publishing. Two translations with the same ID share their persistent variables.

An existing value is loaded when the scenario starts. The first fixed assignment in ''init:'' does not overwrite it; a relative operation such as ''+1'' is still applied to the stored value.

**Reset** clears the current scenario's ''_p'' variables and [[en:yaml:achievements|achievements]], then starts a new game.

===== Online _o variables =====

For a scenario source authorised by the server, an ''_o'' variable is shared between players. It belongs to the scenario URL or path, not to its ''id:''. Outside these sources, it stays local to the game.

<code yaml>
vars:
  high_score_o:
    value: 0
    description: "Shared high score"
</code>

''nb_parties_o'' is created automatically and increases whenever a game starts. In a standalone export, ''_o'' variables become local to that standalone and do not contact a shared server.

===== Variables in init: =====

''init:'' can declare a variable when entering a room:

<code yaml>
init:
  - var: die
    value: "%=1:6"
    description: "Die roll"
  - text_var: state
    value: "resting"
</code>

A relative operation on an unknown name starts from 0. Giving the variable an explicit initial value first is usually clearer.

===== Free-form answers =====

In a room's ''init:'', ''reply: true'' lets the player enter a value:

<code yaml>
init:
  - text_var: hero_name
    value: "Adventurer"
    reply: true
</code>

Room names, aliases and known actions still take priority. A numeric answer is stored without a technical message; use an event to show the feedback intended for the player.

===== Value modifiers =====

^ Syntax ^ Effect ^
| ''0'' | Set the value to 0 |
| ''"+1"'' | Add 1 |
| ''"-3"'' | Subtract 3 |
| ''"%=1:6"'' | Draw a number between 1 and 6 |
| ''"%+1:3"'' | Add a number drawn between 1 and 3 |
| ''"%=v_min_v:v_max_v"'' | Use variables as bounds |

===== System variables and display =====

^ Variable ^ Value ^
| ''v_resultat_v'' | Result of the last ''%=X:Y'' draw |
| ''v_valeur_v'' | Last code entered through ''go room code'' |
| ''v_reponse_v'' | Value entered with ''reply'' |
| ''v_timer_name_v'' | Seconds left on the ''timer_name'' timer |

The system names above also work in English scenarios. For a declared ''turn'' variable, ''v_turn_v|pad2'' displays 7 as 07.

===== A common trap =====

Event text is prepared before the action from that same event. To announce a new record, display the source variable:

<code yaml>
events:
  - if: "v_score_v > v_record_o_v"
    do: "record_o.=.v_score_v"
    text: "New record: v_score_v"
</code>

===== Paths and spaced effects (4.17) =====

[[en:yaml:listes-boucles|Lists and collections]] add paths such as ''hero.health'', ''bag[0]'' or ''party[v_position_v].health''. The markers remain ''v_..._v'' and ''t_..._t''.

In ''do:'', ''health + 10'' is equivalent to ''health.+.10''. Operators: ''<nowiki>= + - * / // ** %%</nowiki>'' and random ''%''. ''/'' rounds ties to even, ''//'' truncates towards zero and ''<nowiki>%%</nowiki>'' is modulo. Division by zero is an error.

<code yaml>
do:
  - hero.health + 10
  - score + %1:6
  - score + %2:70,5:30
</code>

The last example draws 2 with weight 70 or 5 with weight 30. ''result'' holds the drawn number before the operator is applied. Older forms remain accepted.

''init:'' also accepts ''var: hero.health'' or ''text_var: hero.name'', with ''modifiable: true'' or ''reply: true''. These input paths must cross collections only and target an existing simple property; list indices are excluded.

===== Describing structured data =====

Lists, collections, properties and elements can have descriptions separate from their values, in ''data_info:'' (French: ''infos_donnees:''). ''examine hero.health'' shows the value and its description. Roots can also be bound to tags to reset their whole contents. See [[en:yaml:listes-boucles|Structured data descriptions and tags]].

In the editor, online variables remain grouped with numbers or text according to their type. Declare an ''_o'' number in ''vars'' and an ''_o'' text variable in ''text_vars''. Historical ''vars_online'' declarations remain readable on import.