feat: trigger system for scripted events added.

1 files changed, 22 insertions, 0 deletions

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