From e2d5b081f27141bb3dd89dbe595860b8a1345d55 Mon Sep 17 00:00:00 2001
From: historia <[not public]>
Date: Thu, 25 Jun 2026 21:23:34 -0400
Subject: feat: on_enter features ported over to triggers, cosmetic fixes with
 trigger messages

---
 building_guide/rooms.md | 30 +++++++++++++++++++++++++-----
 1 file changed, 25 insertions(+), 5 deletions(-)

(limited to 'building_guide')

diff --git a/building_guide/rooms.md b/building_guide/rooms.md
index 5a414a3..ebdf37d 100644
--- a/building_guide/rooms.md
+++ b/building_guide/rooms.md
@@ -127,7 +127,7 @@ objects:
   - id: iron_gate                                      # hidden object (see below)
 ```
 
-### On-enter scripts — messages and timed cutscenes when a player arrives
+### On-enter scripts — messages and timed sequences when a player arrives
 
 Each `on_enter` step shows a `message`, optionally gated by a `condition`. Steps
 whose condition fails are skipped.
@@ -144,9 +144,9 @@ on_enter:
       player_flag: talked_to_guard   # subsequent visits
 ```
 
-**Timed cutscenes.** A step may also carry a `delay` (ticks to wait before it
+**Timed sequences.** A step may also carry a `delay` (ticks to wait before it
 fires) and/or set flags (`set_flags` / `set_player_flags`). If any surviving step
-has a delay or sets a flag, the whole sequence runs as a scheduled cutscene;
+has a delay or sets a flag, the whole sequence runs as a scheduled enter sequence;
 plain message-only scripts still print instantly.
 
 ```yaml
@@ -163,11 +163,31 @@ on_enter:
     message: "The crowd forms a single-file line."
 ```
 
+**Step actions.** On-enter steps support all the same actions as trigger steps:
+`broadcast`, `broadcast_global`, `spawn_mob`, `despawn_mob`, `give_item`,
+`take_item`, `teleport`, and `heal`. See the [trigger step actions](triggers.md#step-actions)
+table for details.
+
+```yaml
+on_enter:
+  - condition: { player_flag: boss_summoned }
+    delay: 10
+    broadcast: "The ground trembles..."
+  - condition: { player_flag: boss_summoned }
+    delay: 20
+    broadcast: "A massive guardian emerges from the shadows!"
+    spawn_mob:
+      id: altar_guardian
+      owner_only: true
+      despawn_on_leave: true
+```
+
 Notes:
 - `delay` counts ticks before the step fires; `delay: 0` (or omitted) fires on the next tick.
 - Conditions are evaluated **once** on entry, so a flag a step sets won't cancel a later step in the same sequence.
-- Gate a cutscene on a flag the sequence itself sets (above, `lined_up`) so it doesn't replay on a return visit.
-- If a player disconnects mid-cutscene it resumes on reconnect, so they can't get stuck behind an exit the cutscene was meant to open. Plain `on_enter` messages never replay on login.
+- Gate a sequence on a flag the sequence itself sets (above, `lined_up`) so it doesn't replay on a return visit.
+- If a player disconnects mid-sequence it resumes on reconnect, so they can't get stuck behind an exit the sequence was meant to open. Plain `on_enter` messages never replay on login (except the first room for new characters).
+- Setting player flags from on_enter steps fires room triggers watching those flags — this is how room 1001's touchdown sequence works.
 
 ### Conditional room descriptions
 
-- 
cgit v1.2.3