path: root/building_guide/rooms.md

## Rooms

**The filename is the ID.** A room's numeric filename is its ID (`1.yaml` → room `1`); the
loader derives it from the filename. Do not put an `id:` field in the file — it is ignored.
Exits and other rooms reference a room by that number. (A nested `- id:` under `objects:` or
`mobs:` is a *reference* to an object/mob by its filename, and is still required.)

Minimal room:
```yaml
name: "Town Square"
description: "Cobblestone paths lead in all directions. A fountain gurgles peacefully."
exits:
  north: 2
  west: 7
  east: 3
```

### Map color — default symbol color on the map

A room may set a default `color` that tints its node on the map and the links connecting it to
neighbouring nodes. A player's per-room `symbol` color (set via the `symbol` command) overrides it.

```yaml
color: "5E"
```

### Inline Color Tags

Room descriptions support inline color tags using `{spec}text{/}` syntax. Untagged text uses the `room_desc` color.

```yaml
description: "On the table lies a {B6 bold}mysterious vase{/} with a rose in it."
```

Tag spec format: `{<00-FF> [bold] [dim] [underline]}text{/}`

Gradients: `{g:C4,52}gradient text{/}`. Multi-stop: `{g:2D,27,3B}three stops{/}`.

### Exits — simple vs conditional

Simple exit — always passable:
```yaml
exits:
  north: 2
  ne: 3                           # ne/nw/se/sw also work
  southeast: 4
```

Conditional exit — blocked until a world flag is set:
```yaml
exits:
  north:
    room: 11
    condition:
      flag: gate_open
    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
    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
        - player_flag: paid_toll
    blocked_message: "The bridge is out, and the toll collector blocks the path."
```

Exit that sets flags when used — `set_flags` / `set_player_flags` are applied
only when the player actually moves through the exit (not when it's blocked):
```yaml
exits:
  north:
    room: 21
    condition:
      player_flag: lined_up
    set_player_flags:
      boarded_shuttle: true        # marks "left this area" on the way out
```

### Hidden exits

Hidden exits are invisible in `look` and `verbs` output until the player
discovers them by traversing them once. Even hidden, the exit is still
traversable — just not listed. Once a player moves through a hidden exit, it
becomes "discovered" for that character and appears in listing with a
`(HIDDEN)` tag. On the map, hidden exits (and rooms only reachable via them)
do not appear until the character discovers them. Gods in `god` mode see all
hidden exits regardless of discovery.

```yaml
exits:
  down:
    room: 1002
    hidden: true
```

### Always-blocked exits

Always-blocked exits are blocked to players but always visible. They appear in
`look`/`verbs`/`exits` tagged `(blocked)` (same as a conditionally-blocked exit),
refuse movement with the standard "The way <dir> is blocked." message, and
render on the map as blocked `X` connectors. Gods in `god` mode can traverse
them (and see no `(blocked)` tag). Primarily used for agility course
room-to-room links so the map can lay the course out visually.

```yaml
exits:
  north:
    room: 99999221
    always_blocked: true
```

`always_blocked` is absolute: when set, a `condition:` on the same exit is not
evaluated (the exit is blocked unconditionally). Don't combine the two — if you
need a conditionally-gated exit, use `condition:` alone.

Hidden and always_blocked can be combined: the exit is invisible until
discovered (or seen by a god), and then shows as blocked.

### Map grid & one-way exits

All exits (north/south/east/west/ne/nw/se/sw) must form a consistent 3D grid: from
any starting room, walking horizontal directions should never land two different
rooms on the same 3D coordinate, and a given room must always resolve to the same
spot. Up/down move on the z-axis within this same grid (different floors share the
same x/y coordinate space).

Startup validation enforces this, starting from `startup_validation.root_rooms`
(see config.yaml). It reports an **overlap** (two rooms on one grid cell) or a
**twist** (one room on two cells) as an ERROR so you can fix the wiring.

Exits don't have to be reciprocal. A one-way link (e.g. room 2001 has `east: 2006`
but 2006 has no `west` back) renders on the map as a directional arrow
(`← ↑ → ↓`, or `< ^ > v` in ASCII, with `↗↖↘↙` for diagonal) instead of a
two-way bar. If a link is open in one direction but blocked (failing condition) in
the other, the open direction's arrow is shown; only a link with no traversable
direction shows the blocked `X`. Blocked up/down exits also show the blocked `X`.

### Item Spawns — ground items that respawn

```yaml
item_spawns:
  - id: bronze_pickaxe
    quantity: 1
    respawn_ticks: 30     # reappears 30 ticks (18 seconds) after being picked up
  - 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 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.

```yaml
on_enter:
  - message: "The guard barks: \"State your business!\""
    condition:
      player_flag: talked_to_guard
      not: true                  # only the first visit

  - message: "The guard nods. \"Back again?\""
    condition:
      player_flag: talked_to_guard   # subsequent visits
```

**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 enter sequence;
plain message-only scripts still print instantly.

```yaml
on_enter:
  - condition: { player_flag: boarded, not: true }
    delay: 5
    message: "Some of the crowd look you up and down."
  - condition: { player_flag: boarded, not: true }
    delay: 5
    message: "The pilot calls out: \"Tickets, please! Nice and orderly!\""
    set_player_flags:
      lined_up: true             # opens an exit, flips a description, etc.
  - condition: { player_flag: boarded, not: true }
    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 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

A room's `description` can be a plain string or a list of conditional variants.
Entries are checked top-to-bottom; the first whose condition passes wins. An
entry with no condition always matches — put it last as the fallback.

```yaml
description:
  - condition:
      player_flag: boarded
      not: true
    text: "A concrete pad swarming with a couple dozen anxious passengers."
  - text: "A large, empty concrete pad in the middle of the ocean."
```

### Hazardous rooms — environmental danger

A room can reference a shared hazard by ID. The hazard rolls an attack against
everyone in the room every few ticks using the combat formulas (see `hazards.md`).

```yaml
name: "Exposed Solar Array"
hazard: solar_radiation        # ID of a data/hazards/<id>.yaml definition
exits:
  south: 99999180
objects:
  - id: rock_outcrop           # a safespot object shields players from the hazard
mobs:
  - solar_panel_frame          # a task worksite (see mobs.md > Task Mobs)
```

- Players are warned with a `[Y/n]` prompt before walking from a **safe** room into a
  **hazardous** one (unless they disable the `danger_warning` option). Moving between
  two hazardous rooms does not re-prompt.
- A safespot object (an overhang, alcove, rock outcrop, …) shields a hidden player from
  **all** hazard damage — but performing a melee attack/work step forces you out of cover.
- 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.

---