JDR-Bot

Outils pour utilisateurs

Outils du site

Piste :
en:yaml:variables

Différences

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

Lien vers cette vue comparative

Les deux révisions précédentesRévision précédente
en:yaml:variables [2026/08/31 20:56] – Wiki : fins de pages homogènes, liens Discord retirés cyrilfiestaen:yaml:variables [2026/09/26 03:42] (Version actuelle) – documentation 4.15 : succès, variables persistantes et exports cyrilfiesta
Ligne 3: Ligne 3:
 ====== Variables (YAML) ====== ====== Variables (YAML) ======
  
-===== Numeric Variables =====+===== Declaring variables ===== 
 + 
 +Numeric variables belong in ''vars:'':
  
 <code yaml> <code yaml>
 vars: vars:
   score: 0   score: 0
- 
   hp:   hp:
     value: 10     value: 10
Ligne 14: Ligne 15:
 </code> </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> <code yaml>
Ligne 25: Ligne 24:
 </code> </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> <code yaml>
 +id: my-scenario
 +
 vars: vars:
-  guess: +  score: 0 
-    value: 0 +  best_score_p: 0 
-    reply: true+  world_record_o: 0
  
 text_vars: text_vars:
-  hero_name: +  last_ending_p: "none" 
-    value: "Adventurer" +  shared_message_o: "Welcome"
-    reply: true+
 </code> </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 ===== 
 + 
 +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:''.
  
 <code yaml> <code yaml>
-online_vars: +vars: 
-  record_o:+  high_score_o:
     value: 0     value: 0
-    description: "Best score"+    description: "Shared high score"
 </code> </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> <code yaml>
Ligne 62: Ligne 81:
   - var: die   - var: die
     value: "%=1:6"     value: "%=1:6"
-    description: "Die roll result"+    description: "Die roll"
   - text_var: state   - text_var: state
     value: "resting"     value: "resting"
-    description: "Current state" 
 </code> </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 =====+Add ''reply: true'' to a variable declared in the room to wait for free-form input:
  
-  * ''v_name_v'' displays a numeric variable. +<code yaml> 
-  * ''t_name_t'' displays a text variable. +text_vars: 
-  * ''v_turn_v|pad2'' displays the value padded to 2 digits.+  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 =====+===== System variables and display =====
  
 ^ Variable ^ Value ^ ^ 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_valeur_v'' | Last code entered through ''go room code'' |
 | ''v_reponse_v'' | Value entered with ''reply'' | | ''v_reponse_v'' | Value entered with ''reply'' |
 | ''v_timer_name_v'' | Seconds left on the ''timer_name'' timer | | ''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. +These system names stay in French. ''v_turn_v|pad2'' pads a number with zeroes: 7 becomes 07.
- +
-===== Display formatting ===== +
- +
-A numeric variable can be padded with ''|padN'': +
- +
-<code yaml> +
-text: "Turn: v_turn_v|pad2"   # shows "Turn: 07" when turn = 7 +
-</code>+
  
-===== A common trap with online variables =====+===== A common trap =====
  
-⚠ The text of an event is evaluated **before** the action of that same event. +Event text is prepared before the action from that same event. To announce a new record, display the source variable:
-To display the **new** value of a record, show the source variable, not the destination:+
  
 <code yaml> <code yaml>
Ligne 111: Ligne 129:
   - if: "v_score_v > v_record_o_v"   - if: "v_score_v > v_record_o_v"
     do: "record_o.=.v_score_v"     do: "record_o.=.v_score_v"
-    # Shows v_score_v (the source), not v_record_o_v (not updated yet) +    text: "New record: v_score_v"
-    text: "New record: v_score_v (previous: v_record_o_v)"+
 </code> </code>
  
en/yaml/variables.txt · Dernière modification : de cyrilfiesta