Variables (YAML)

Numeric variables belong in vars::

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

Text variables belong in text_vars::

text_vars:
  hero_name:
    value: "Adventurer"
    description: "Hero name"

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.

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

id: my-scenario

vars:
  score: 0
  best_score_p: 0
  world_record_o: 0

text_vars:
  last_ending_p: "none"
  shared_message_o: "Welcome"

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

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 achievements, then starts a new game.

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.

vars:
  high_score_o:
    value: 0
    description: "Shared high score"

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.

init: can declare a variable when entering a room:

init:
  - var: die
    value: "%=1:6"
    description: "Die roll"
  - text_var: state
    value: "resting"

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

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

init:
  - text_var: hero_name
    value: "Adventurer"
    reply: true

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.

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

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

events:
  - if: "v_score_v > v_record_o_v"
    do: "record_o.=.v_score_v"
    text: "New record: v_score_v"

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: = + - * / // ** %% and random %. / rounds ties to even, truncates towards zero and %% 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 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.