Variables (YAML)

Declaring variables

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.

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

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

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

Online _o variables

An _o variable is stored on the server and shared by players loading the same source. It belongs to the scenario URL or path, not to its id:.

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.

Variables in init:

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.

Free-form answers

Add reply: true to a variable declared in the room to wait for free-form input:

text_vars:
  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.

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

These system names stay in French. v_turn_v|pad2 pads a number with zeroes: 7 becomes 07.

A common trap

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"