Différences

Ci-dessous, les différences entre deux révisions de la page.

--- en:yaml:variables [2026/08/30 22:28] – maj 4.14 : dialogues, videos hebergees, mise en page, doc EN completee cyrilfiesta
+++ en:yaml:variables [2026/10/20 22:12] (Version actuelle) – Mod?les sur_place, port?e des encadr?s et objets 4.17 cyrilfiesta
@@ Ligne 3: / Ligne 3: @@
 ====== Variables (YAML) ======
-===== Numeric Variables =====
+===== Declaring variables =====
+Numeric variables belong in ''vars:'':
 <code yaml>
 vars:
   score: 0
   hp:
     value: 10
@@ Ligne 14: / Ligne 15: @@
 </code>
-The description is shown when the player examines the variable or when it is attached to a permanent option.
+Text variables belong in ''text_vars:'':
-===== Text Variables =====
 <code yaml>
@@ Ligne 25: / Ligne 24: @@
 </code>
-Use text variables in text with ''t_hero_name_t''.
+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.
-To wait for a free-form answer, add ''reply: true'' to a text or numeric variable. The player can then type the answer directly without using the ''reply'' command. Room names, aliases and known actions still take priority.
+===== 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:
-  guess:
+  score: 0
-    value: 0
+  best_score_p: 0
-    reply: true
+  world_record_o: 0
 text_vars:
-  hero_name:
+  last_ending_p: "none"
-    value: "Adventurer"
+  shared_message_o: "Welcome"
-    reply: true
 </code>
-A numeric answer is stored without displaying the technical variable-change message. Use an event to provide the feedback intended for the player.
+''online_vars:'' remains supported for older scenarios, but it is now legacy syntax. New ''_o'' variables should be declared in ''vars:'' or ''text_vars:''.
-===== Online Variables =====
+===== 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>
-online_vars:
+vars:
-  record_o:
+  high_score_o:
     value: 0
-    description: "Best score"
+    description: "Shared high score"
 </code>
-The name must end with ''_o''. Use it like any numeric variable: ''v_record_o_v''.
+''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.
-The variable ''nb_parties_o'' exists automatically and is incremented when a game starts.
+===== Variables in init: =====
-===== Room init: =====
+''init:'' can declare a variable when entering a room:
 <code yaml>
@@ Ligne 62: / Ligne 81: @@
   - var: die
     value: "%=1:6"
-    description: "Die roll result"
+    description: "Die roll"
   - text_var: state
     value: "resting"
-    description: "Current state"
 </code>
-===== Value Modifiers =====
+A relative operation on an unknown name starts from 0. Giving the variable an explicit initial value first is usually clearer.
-^ Syntax ^ Effect ^
+===== Free-form answers =====
-| ''0'' | Set to 0. |
-| ''"+1"'' | Add 1. |
-| ''"-3"'' | Subtract 3. |
-| ''"%=1:6"'' | Random from 1 to 6. |
-| ''"%+1:3"'' | Add random from 1 to 3. |
-| ''"%=v_min_v:v_max_v"'' | Random using variables as bounds. |
-===== In Text =====
+In a room's ''init:'', ''reply: true'' lets the player enter a value:
-  * ''v_name_v'' displays a numeric variable.
+<code yaml>
-  * ''t_name_t'' displays a text variable.
+init:
-  * ''v_turn_v|pad2'' displays the value padded to 2 digits.
+  - text_var: hero_name
+    value: "Adventurer"
+    reply: true
+</code>
-===== System variables =====
+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'' random draw |
+| ''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 names stay in French, even in an English scenario: the engine reads them itself.
+The system names above also work in English scenarios. For a declared ''turn'' variable, ''v_turn_v|pad2'' displays 7 as 07.
-===== Display formatting =====
+===== A common trap =====
-A numeric variable can be padded with ''|padN'':
+Event text is prepared before the action from that same event. To announce a new record, display the source variable:
 <code yaml>
-text: "Turn: v_turn_v|pad2"   # shows "Turn: 07" when turn = 7
+events:
+  - if: "v_score_v > v_record_o_v"
+    do: "record_o.=.v_score_v"
+    text: "New record: v_score_v"
 </code>
-===== A common trap with online variables =====
+===== Paths and spaced effects (4.17) =====
-⚠ The text of an event is evaluated **before** the action of that same event.
+[[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''.
-To display the **new** value of a record, show the source variable, not the destination:
+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>
-events:
+do:
-  - if: "v_score_v > v_record_o_v"
+  - hero.health + 10
-    do: "record_o.=.v_score_v"
+  - score + %1:6
-    # Shows v_score_v (the source), not v_record_o_v (not updated yet)
+  - score + %2:70,5:30
-    text: "New record: v_score_v (previous: v_record_o_v)"
 </code>
-**Find us on the [[https://discord.gg/Z63DtVV|Make&Play Discord]]**
+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.