1 files changed, 97 insertions, 0 deletions
diff --git a/building_guide/doors.md b/building_guide/doors.md
new file mode 100644
index 0000000..1e9fb7a
--- /dev/null
+++ b/building_guide/doors.md
@@ -0,0 +1,97 @@
+## Global vs Player State: Door Examples
+
+### Example A: Door with a button in another room (GLOBAL)
+
+A button in room 3 opens a door in room 7. Anyone can press it. Once pressed, the door is open for everyone.
+
+**Button object** (`data/objects/door_button.yaml`):
+```yaml
+id: door_button
+name: stone button
+hidden: true
+use_interactions:
+  - condition:
+      flag: secret_door_open
+      not: true
+    message: "You press the stone button. You hear grinding stone in the distance."
+    action:
+      set_flags:
+        secret_door_open: true
+```
+
+**Room 3** — contains the button:
+```yaml
+id: 3
+name: "Button Chamber"
+description: "A small stone chamber. A button protrudes from the east wall."
+exits:
+  south: 1
+objects:
+  - id: door_button
+```
+
+**Room 7** — contains the door:
+```yaml
+id: 7
+name: "Hidden Passage"
+description: "A dusty corridor. A heavy stone door blocks the way north."
+exits:
+  south: 2
+  north:
+    room: 8
+    condition:
+      flag: secret_door_open                           # checks WORLD flag
+      value: true
+    blocked_message: "A heavy stone door blocks the way."
+objects:
+  - id: stone_door
+    hidden: true
+```
+
+### Example B: Key-locked door (PLAYER-LOCAL)
+
+A locked door that only opens for a player carrying the key. Each player must find their own key.
+
+**Key item** (`data/items/rusty_key.yaml`):
+```yaml
+id: rusty_key
+name: rusty key
+description: "An old iron key, still functional."
+value: 0
+stackable: false
+```
+
+**Room 5** — locked door:
+```yaml
+id: 5
+name: "Locked Storage"
+description: "A small storage room. The way east is blocked by a locked iron door."
+exits:
+  west: 2
+  east:
+    room: 6
+    condition:
+      has_item: rusty_key                               # checks PLAYER inventory
+    blocked_message: "The iron door is locked. You need a key."
+objects:
+  - id: iron_door
+    hidden: true
+```
+
+**Room 6** — the other side (no key needed to exit):
+```yaml
+id: 6
+name: "Storage Closet"
+description: "Shelves of dusty crates."
+exits:
+  west: 5                                               # exit back — no condition
+spawns:
+  - item_id: uncut_ruby
+    quantity: 1
+    respawn_ticks: 500
+```
+
+Key difference: the button door uses `flag` (shared state — one player presses, everyone benefits), the key door uses `has_item` (per-player inventory check — each player needs their own key).
+
+---
+