## Global vs Player State: Door Examples

> **Filenames are IDs.** Object and room YAML below carry no `id:` field — the filename is the ID (e.g. `door_button.yaml` → `door_button`). A nested `- id:` under a room's `objects:` list is a *reference* and stays.

### 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
name: stone button
hidden: true
on_use:
  - condition:
      global_flag: secret_door_open
      not: true
    message: "You press the stone button. You hear grinding stone in the distance."
    action:
      set_global_flags:
        secret_door_open: true
```

**Room 3** — contains the button:
```yaml
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
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
name: rusty key
description: "An old iron key, still functional."
value: 0
stackable: false
```

**Room 5** — locked door:
```yaml
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
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 `global_flag` (shared state — one player presses, everyone benefits), the key door uses `has_item` (per-player inventory check — each player needs their own key).

---