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

====== Events (YAML) ======

Events are action blocks run automatically or called through an interaction, such as a button, shortcut or ''trigger_event:id''. A button waits for a click. Without a button, ''manual: true'' or a shortcut makes the event manual. Merely referencing its ID in ''trigger_event:'' never makes it manual: otherwise it is still evaluated on entry and after commands.

===== Base Syntax =====

<code yaml>
events:
  - if: "condition"
    do: "action"
    text: "Displayed message"
</code>

  * ''if:'' - trigger condition. ''~'' or missing means always true.
  * ''do:'' - action or list of actions.
  * ''text:'' - optional displayed text.

===== Actions Available in do: =====

^ Syntax ^ Effect ^
| ''score.+.10'' | Add 10 to ''score''. |
| ''hp.-.3'' | Subtract 3 from ''hp''. |
| ''score.=.0'' | Set ''score'' to 0. |
| ''score.=.v_other_v'' | Copy another variable. |
| ''score.=.%1:6'' | Random value from 1 to 6. |
| ''score.=.%1:70,5:20,10:10'' | Weighted draw: 1 has weight 70, 5 and 10 have weights 20 and 10. |
| ''object&&inventory&&Description'' | Add an object. |
| ''-object&&inventory&&null'' | Remove an object. |
| ''event_global:id:ON'' | Enable a global event. |
| ''event_global:id:OFF'' | Disable a global event. |
| ''event_global:id:SWITCH'' | Toggle a global event. |
| ''timer_global:id:ON'' | Start a global timer. |
| ''timer_global:id:OFF'' | Stop a global timer. |
| ''trigger_event:id'' | Call an enabled local or global event by its id. |

Several actions in one event:

<code yaml>
do:
  - "hp.+.5"
  - "score.+.10"
  - "event_global:visit_bonus:ON"
</code>

===== Endings =====

<code yaml>
events:
  - if: "v_hp_v <= 0"
    end: defeat
    text: "You died."
  - if: "v_score_v >= 100"
    end: victory
    text: "Congratulations!"
</code>

''do:'' can be combined with ''end:''; its effects run before the game ends.

===== Redirection =====

<code yaml>
events:
  - if: "v_hp_v <= 0"
    to: death_room
    text: "You pass out..."
</code>

An event with ''to:'' stops following events.

===== Event Button =====

<code yaml>
events:
  - if: ~
    button: "Eat an apple (+3 HP)"
    do: "hp.+.3"
    text: "You eat the apple. HP: v_hp_v"
</code>

===== Limit Uses =====

<code yaml>
events:
  - if: ~
    button: "Pick up a coin"
    do: "score.+.10"
    max: 3
    text:
      - if: "_max_atteint_"
        text: "No coins remain."
      - text: "+10 score."
</code>


===== Conditional buttons (visible-si / grise-si) =====

<code yaml>
events:
  - if: ~
    button: "⚔️ Attack"
    visible-if: "v_hp_v > 0"   # hidden when HP reach 0
    do: "score.+.5"
    text: "You attack!"

  - if: ~
    button: "🏃 Flee"
    disabled-if: "v_hp_v <= 0" # visible but inactive when HP reach 0
    to: accueil
</code>

''visible-if:'' hides the button when the condition is false. ''disabled-if:'' keeps the button visible but inactive when the condition is true.

On Discord, buttons are frozen inside the message that was sent. Clicking 🔄 (refresh) forces a redisplay with up to date buttons.

===== Conditional text on an event =====

The ''text:'' field accepts a list of conditional blocks:

<code yaml>
text:
  - if: "_max_atteint_"
    text: "No charge left!"
  - if: "v_score_v > 50"
    text: "🏆 Wealthy adventurer: score v_score_v!"
  - text: "Action done."   # fallback, always shown
</code>

===== Sequential behaviour =====

Important: events run in order. Each one sees the values **already changed** by the previous ones. An event carrying ''to:'' or ''end:'' **stops** the ones after it.

===== Timer started by an event =====

<code yaml>
events:
  - if: ~
    timer: hourglass
    duration: "30"
    to: expiration_room
    text: "The hourglass is running!"
</code>

''v_hourglass_v'' holds the remaining seconds. A local timer is cancelled when the player leaves the room.

===== Manual command inside do: (v4.9) =====

The ''command:'' action inside ''do:'' runs a text command of the bot, from an event, a choice or an action:

<code yaml>
do:
  - command: "take key"
  - command: "inspect chest"
  - command: "go laboratory"
</code>

It works with the standard commands: ''go'', ''back'', ''take'', ''throw'', ''inspect'', ''inventory'', ''refresh'', ''reply'', ''edit'', ''vars''. Their French names are accepted too (''avancer'', ''reculer'', ''prendre'', ''jeter'', ''examiner'', ''inventaire'', ''rafraichir'', ''repondre'', ''modifier'', ''variables'').

Useful to chain a series of actions automatically, or to simulate an interaction from an event.


===== Inline Events =====

A local event can be triggered by a tooltip or clickable element, and a ''source:'' + ''target:'' pair defines a drag&drop event.

  * [[en:yaml:tooltips|Interactive tooltips]]: ''%%{{label:?text:!id}}%%'' or ''%%{{label:!id}}%%''.
  * [[en:yaml:clickable-elements|Clickable elements]]: ''%%{{label:@id}}%%''.
  * [[en:yaml:drag-drop|Drag & drop]]: ''source:'' + ''target:'' on the event.

Local events can be controlled with ''event:id:ON'', ''event:id:OFF'' and ''event:id:SWITCH''.

===== Manual event without a button =====

^ Key ^ Effect ^
| ''manual: true'' | Prevents automatic execution, without adding a button. |

A choice can call this event explicitly. Its conditions, state and usage limits still apply.

<code yaml>
title: 'Wiki 4.17: manual'
rooms:
- id: depart
  text: Start.
  events:
  - id: alerte
    manual: true
    text: Called only by the choice.
  choices:
  - command: appeler
    button: Call
    to: depart
    effect: trigger_event:alerte
</code>

The alert text is absent on entry. The "Call" choice triggers it. Removing ''manual: true'' also makes it automatic; ''trigger_event:'' does not change that rule. French: ''manuel: true'' and ''declencher_event:alerte''.