1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
|
## 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
```
### 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 {182 bold}mysterious vase{/} with a rose in it."
```
Tag spec format: `{<0-255> [bold] [dim] [underline]}text{/}`
Gradients: `{g:196,82}gradient text{/}`. Multi-stop: `{g:45,39,59}three stops{/}`.
### 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
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
```
### 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 cutscenes 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 cutscenes.** 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;
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."
```
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.
### 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.
---
|
