From 84d74ca4351a97148ad8339676f9df7946bc21fb Mon Sep 17 00:00:00 2001
From: historia <[not public]>
Date: Thu, 25 Jun 2026 20:33:47 -0400
Subject: feat: trigger system for scripted events added.

---
 building_guide/rooms.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

(limited to 'building_guide/rooms.md')

diff --git a/building_guide/rooms.md b/building_guide/rooms.md
index 7028393..5a414a3 100644
--- a/building_guide/rooms.md
+++ b/building_guide/rooms.md
@@ -208,5 +208,27 @@ mobs:
 - Hazards stack with mobs: an aggressive mob in a hazardous room hits you while the room
   hazard also rolls against you.
 
+### Room triggers — scripted events when flags change
+
+A room can carry a `triggers:` block. Each trigger watches a player or world flag
+and fires a sequence of timed steps when that flag's value changes. See `triggers.md`
+for the full reference.
+
+```yaml
+triggers:
+  - on_player_flag: 1001_look_sign
+    steps:
+      - delay: 5
+        message: "The cabin shakes as the small craft touches down"
+      - delay: 5
+        message: "The pistons hiss as the rear staircase opens"
+      - set_player_flags:
+          1001_touchdown: true
+```
+
+Room triggers are scoped to the room — broadcasts go to that room, mobs spawn there,
+and the trigger only fires when the flag-setting player is in that room. For
+server-wide events, use global triggers in `data/triggers/` instead.
+
 ---
 
-- 
cgit v1.2.3