1 files changed, 122 insertions, 0 deletions
diff --git a/worldbuilding_guide/rooms.md b/worldbuilding_guide/rooms.md
new file mode 100644
index 0000000..95e1972
--- /dev/null
+++ b/worldbuilding_guide/rooms.md
@@ -0,0 +1,122 @@
+## Rooms
+
+Minimal room:
+```yaml
+id: 1
+name: "Town Square"
+description: "Cobblestone paths lead in all directions. A fountain gurgles peacefully."
+exits:
+  north: 2
+  west: 7
+  east: 3
+```
+
+### Exits — simple vs conditional
+
+Simple exit — always passable:
+```yaml
+exits:
+  north: 2
+```
+
+Conditional exit — blocked until a world flag is set:
+```yaml
+exits:
+  north:
+    room: 11
+    condition:
+      flag: gate_open
+      value: true
+    blocked_message: "A heavy iron gate blocks the way north."
+```
+
+Conditional exit — blocked unless the PLAYER has a flag (key, permission, quest state):
+```yaml
+exits:
+  east:
+    room: 12
+    condition:
+      player_flag: has_vault_key
+      value: true
+    blocked_message: "The vault door is locked. You need a key."
+```
+
+Conditional exit with compound condition — requires both a world flag AND a player flag:
+```yaml
+exits:
+  north:
+    room: 20
+    condition:
+      all_of:
+        - flag: bridge_repaired
+          value: true
+        - player_flag: paid_toll
+          value: true
+    blocked_message: "The bridge is out, and the toll collector blocks the path."
+```
+
+### Spawns — ground items that respawn
+
+```yaml
+spawns:
+  - item_id: bronze_pickaxe
+    quantity: 1
+    respawn_ticks: 30     # reappears 30 ticks (18 seconds) after being picked up
+  - item_id: copper_ore
+    quantity: 3
+    respawn_ticks: 50
+```
+
+### Mobs — NPCs placed in the room
+
+Simple string (no wandering):
+```yaml
+mobs:
+  - "newbie_trainer"
+  - "man"
+```
+
+With wander config per-instance:
+```yaml
+mobs:
+  - id: man
+    wander_interval: 10      # attempts to wander every 10 ticks
+  - id: man
+    wander_interval: 15
+    wander_rooms: [1, 4, 5]  # optional — only exit to these rooms
+```
+
+Mob wander config lives in the room YAML, not in the mob definition. This keeps mobs generic
+so the same `man` can wander differently depending on where it's placed. Mobs wander through
+legal (unconditioned) room exits. If no legal exits exist, the mob stays still. Mobs with
+no `wander_interval` never wander.
+
+### Objects — interactive fixtures
+
+```yaml
+objects:
+  - id: copper_rock                                    # simple placement
+  - id: copper_rock                                    # second instance
+  - id: fishing_spot
+    wander_rooms: [7, 8, 9]                            # teleports between these rooms
+    wander_interval: 12                                # every 12 ticks
+  - id: iron_gate                                      # hidden object (see below)
+```
+
+### On-enter scripts — messages when a player arrives
+
+```yaml
+on_enter:
+  - message: "The guard barks: \"State your business!\""
+    condition:
+      player_flag: talked_to_guard
+      not: true                                        # only first visit
+
+  - message: "The guard nods. \"Back again?\""
+    condition:
+      player_flag: talked_to_guard
+      value: true                                      # subsequent visits
+```
+
+---
+