` that loads `src/main.ts`. Copy `two-rooms.ts` into `src/`, then replace everything in `src/main.ts` with:
```ts
import { mountGame } from '@brass-lantern/vue';
import '@brass-lantern/vue/style.css';
import './style.css';
import { twoRooms } from './two-rooms.ts';
mountGame('#app', {
cartridges: [{ kind: 'world', id: 'two-rooms', title: 'TWO ROOMS', world: twoRooms }],
storagePrefix: 'two-rooms',
});
```
and everything in `src/style.css` with:
```css
html, body, #app { height: 100%; margin: 0; overflow: hidden; }
```
```bash
npm run dev
```
Open the address it prints and the game boots. What the options mean:
- **`cartridges`** are the games on offer. A cartridge with `kind: 'world'` is a world like this one; `id` names it (in its saves, for one), and `title` is what the menu shows. With one cartridge there’s no menu: the terminal boots straight into it.
- **`storagePrefix`** names everything the game keeps in the browser (saves, the player’s theme), so two games on one site don’t share saves.
- **The game fills `#app`**, which is why `style.css` gives it the whole window.
Vite tells TypeScript what a `.css` import is (the template’s `vite/client` types), and it accepts the `.ts` ending on `./two-rooms.ts`, as Node does. Outside Vite, [Using the library](https://mrballistic.github.io/brass-lantern/guide/using-the-library#put-a-game-on-a-page) says what to declare for the stylesheet, and covers themes and the rest of the options.
Players won’t type exactly the commands above. “Look under the mat” or “use the key on the door” aren’t commands the engine can act on by itself, so with the [intent server](https://mrballistic.github.io/brass-lantern/guide/intent-server) running they can be mapped onto EXAMINE MAT and UNLOCK DOOR WITH KEY. Without it (as with `createGame`, which never uses it) the player gets a nudge to rephrase.
## Where next
- Give the game a person to talk to, hints and a score: [Snack Attack](https://mrballistic.github.io/brass-lantern/guide/your-first-world) shows all three.
- Make the hall dark until you find a lamp: [darkness](https://mrballistic.github.io/brass-lantern/guide/building-worlds/recipes#darkness-and-death).
- Every field, with its default: the [world schema](https://mrballistic.github.io/brass-lantern/reference/world-schema).
---
Source: https://mrballistic.github.io/brass-lantern/guide/your-first-world
# The demo game: Snack Attack
A world is one TypeScript object: rooms, items, people, the lines they say, and the rules that join them. If you haven’t written one yet, start with [a two-room game](https://mrballistic.github.io/brass-lantern/guide/building-worlds/two-rooms); this page goes further, and builds **Snack Attack**, the tutorial world (`tutorial` in `@brass-lantern/engine/worlds`, [source on GitHub](https://github.com/mrballistic/brass-lantern/blob/main/packages/engine/src/worlds/tutorial.ts)), piece by piece. A test plays that exact file to the end, so everything here matches what the engine does.
The story: it’s 12:01, your pretzels are stuck in the break room vending machine, and you need your badge, a heavy object, and maybe some advice from Gary in Accounts.
## The shape
```ts
import type { World } from '@brass-lantern/engine';
export const tutorial: World = {
startRoom: 'cubicle',
rooms: { /* … */ },
items: { /* … */ },
npcs: { /* … */ },
dialogue: { /* … */ },
events: { intro: [ /* … */ ] },
flagLabels: { /* … */ },
// optional: hints, scoring, ranks, idle, quit, confused, ambient, finale
};
```
Every room, item and person has an **ID**, its key (`desk_drawer`, `gary`). IDs are snake_case and never shown to players. The engine’s state is small: where you are, where every item is, a set of **flags** (named booleans like `drawer_open`), a few numbers, which events have fired, and how many moves you’ve made. Everything a world does comes down to reading and setting those.
## Rooms
```ts
rooms: {
cubicle: {
name: 'Your Cubicle',
description: 'Gray carpet on the walls, gray carpet on the floor. Your desk has one drawer. It is closed.',
exits: { north: 'hallway', hallway: 'hallway', out: 'hallway' },
listExits: ['hallway'],
items: ['desk_drawer', 'stapler'],
npcs: [],
onEnter: [],
},
break_room: {
name: 'The Break Room',
description: 'A vending machine hums in the corner. Your lunch, a single bag of pretzels, hangs from its spiral, not quite falling.',
exits: { south: 'hallway', hallway: 'hallway', out: 'hallway' },
listExits: ['hallway'],
items: ['vending_machine'],
npcs: [],
onEnter: [{ if: '!flag:saw_pretzels', then: 'see_pretzels' }],
requires: 'has:badge',
denial: 'The break room door has a badge reader. You do not have a badge on you.',
},
}
```
- **`exits`** maps what the player can type to where it leads. Give each destination a few labels (a direction, a place name, `out`). The parser is forgiving about phrasing (“go to the hallway”, “hall”, “n”), but only matches labels you provide.
- **`listExits`** is what the player sees. The engine adds the direction that goes to the same place: `Exits: hallway (north).`
- **`requires`** is a [condition](https://mrballistic.github.io/brass-lantern/reference/conditions-and-events#conditions) for entering, and **`denial`** is the reply when it fails. A good denial hints at what’s missing.
- **`onEnter`** fires an event when you arrive, if its condition holds. **An `onEnter` event fires at most once per game.**
## Items
```ts
items: {
desk_drawer: {
name: 'desk drawer',
aliases: ['drawer', 'desk'],
description: 'A metal drawer that sticks.',
portable: false,
refusal: 'It is attached to the desk, which is attached to your career.',
tags: [],
onUse: [
{ if: '!flag:drawer_open', then: 'open_drawer' },
{ say: ['The drawer is already open. It holds nothing else of value.'] },
],
},
badge: { name: 'badge', aliases: ['id', 'card'], description: 'Your employee badge. The photo is from a better year.', portable: true, tags: [] },
stapler: { name: 'stapler', description: 'Heavy. Reliable. Faintly menacing.', portable: true, tags: ['weapon'] },
}
```
`name` is what players see; `aliases` are other words they might use. Every word of three or more letters a player types has to be in one of them (or the ID), so “metal drawer” finds nothing here until `metal drawer` is an alias; see [How names are matched](https://mrballistic.github.io/brass-lantern/guide/building-worlds/#how-names-are-matched). `portable: false` items stay put, and `refusal` is what trying to take one says.
The badge isn’t in any room: opening the drawer hands it over. **`onUse`** is a list of rules, and the first one whose conditions hold wins. Each rule can fire an event (`then`), print lines (`say`), require another item nearby (`with`), or test a condition (`if`). End with a plain `say` as the fallback. PUSH, PULL and PRESS mean USE, and OPEN falls back to use rules on anything that isn’t a container, so “open drawer” works.
Items also have `onTake`, `onWear` and `onSmash` hooks, and `instead`/`after` rules for any verb; see the [schema](https://mrballistic.github.io/brass-lantern/reference/world-schema#item).
## People
```ts
npcs: {
gary: {
name: 'Gary',
description: 'Gary from Accounts. He has opinions about the water cooler.',
onGive: { mug: 'gary_mug' },
refuse: { badge: '“That’s your badge, man. Keep your badge.”' },
refuseGift: '“I don’t want that.”',
},
},
dialogue: {
gary: {
default: '“Has anyone seen my mug?” Gary asks nobody in particular.',
'flag:gary_happy': '“Thanks for the mug. Hey, if that machine eats your money, just hit it. Hard. With something heavy.”',
},
},
```
GIVE MUG TO GARY takes the mug and fires `gary_mug`. With only one person in the room, GIVE MUG is enough. **`refuse`** declines a specific item and lets the player keep it. Gary is a proper name, so he has `article: ''`: the engine’s own lines about him (FOLLOW GARY, an order he can’t carry out) say “Gary”, not “the Gary”.
**Dialogue** maps conditions to lines; TALK TO uses the **last** entry whose condition holds, so list them from least to most advanced. Here, Gary’s advice only appears once he’s happy, which turns him into a hint.
## Events and flags
Events are named lists of lines. Most are prose. Lines in square brackets are shown to the player *and* change the game:
```ts
events: {
intro: [
'═══════════════════════════════',
' SNACK ATTACK',
'═══════════════════════════════',
'✨ IT IS 12:01. YOU ARE HUNGRY.',
],
open_drawer: [
'You yank the drawer open. Inside, under a decade of sticky notes: your badge.',
'[Added to inventory: badge]',
'[Flag set: Drawer open]',
],
gary_mug: [
'💼 Gary takes the mug and looks at it like a long-lost child.',
'💼 “You’re a good one,” he says, and lowers his voice. “That machine? Hit it.”',
'[Flag set: Gary is happy]',
],
},
flagLabels: {
'drawer open': 'drawer_open',
'gary is happy': 'gary_happy',
},
```
`[Flag set: Gary is happy]` sets whichever flag `flagLabels['gary is happy']` names. `[Added to inventory: badge]` and `[Badge consumed]` match items by their display **name**. `intro` plays when a new game starts. Line prefixes also choose the styling and typewriter speed: `💼` lines are scripted moments, `“` lines are narration. The full list is in [conditions and events](https://mrballistic.github.io/brass-lantern/reference/conditions-and-events#how-lines-are-styled).
## The ending
Snack Attack wins with the **finale**: smash a particular item, in a particular room, while holding a particular other item. (The other way to end a game is the `end` effect; see [Endings](https://mrballistic.github.io/brass-lantern/reference/world-schema#endings) and the [two-room game](https://mrballistic.github.io/brass-lantern/guide/building-worlds/two-rooms).)
```ts
finale: {
room: 'break_room',
item: 'vending_machine',
with: 'stapler',
event: 'free_lunch',
epilogue: [
{ if: 'flag:gary_happy', then: 'ending_with_gary' },
{ if: '!flag:gary_happy', then: 'ending_alone' },
],
footer: 'footer',
bareHanded: 'hurt_hand',
bareHandedAgain: 'Your hand still hurts. The machine is winning.',
wrongRoom: 'Not here. Save it for the machine.',
},
```
SMASH MACHINE WITH STAPLER plays `free_lunch`, then every epilogue event whose condition holds, then the score, then `footer`, and the game ends. The epilogue is where choices pay off: help Gary and you share the pretzels.
## The extras
```ts
hints: [
{ if: '!has:badge', text: 'The break room needs a badge. Check your desk.' },
{ if: '!flag:gary_happy', text: 'Gary lost his mug. Gary knows things.' },
{ if: '!flag:lunch_freed', text: 'The machine has your pretzels. Bring something heavy.' },
],
scoring: [
{ flag: 'drawer_open', points: 10 },
{ flag: 'gary_happy', points: 20 },
{ flag: 'lunch_freed', points: 20 },
],
ranks: [{ min: 0, title: 'Intern' }, { min: 50, title: 'Lunch Liberator' }],
confused: ['The office hums, uncomprehending. (Type HELP.)'],
ambient: [
{
if: 'in:break_room & !flag:lunch_freed',
every: 2,
lines: ['The vending machine hums, smug.', 'The pretzels sway, just out of reach.'],
},
],
```
- **HINT** shows the first hint whose condition holds, so order them along the critical path.
- **SCORE** sums points for flags that are set, and names the highest rank reached.
- **`confused`** replies rotate for input nothing could understand.
- **`ambient`** lines interrupt every few turns while their condition holds. They’re good for a ringing phone, a ticking clock, or a smug vending machine.
## Play it
Pass your world to `mountGame` as one of its `cartridges` (`{ kind: 'world', id: 'snack-attack', title: 'SNACK ATTACK', world: tutorial }`; see [Using the library](https://mrballistic.github.io/brass-lantern/guide/using-the-library#put-a-game-on-a-page)). Snack Attack itself ships with the engine: `import { tutorial } from '@brass-lantern/engine/worlds'`. The winning transcript for Snack Attack:
```
> open drawer
> take stapler
> north
> take mug and give mug to gary
> talk to gary
> north
> smash machine with stapler
```
Next: [test your world](https://mrballistic.github.io/brass-lantern/guide/testing), so it stays winnable as it grows.
---
Source: https://mrballistic.github.io/brass-lantern/guide/building-worlds/recipes
# Recipes
Each recipe is a small, complete world about one idea, in [`packages/engine/src/worlds/examples/`](https://github.com/mrballistic/brass-lantern/tree/main/packages/engine/src/worlds/examples). Every transcript on this page is what [a test](https://github.com/mrballistic/brass-lantern/blob/main/packages/engine/tests/worlds/examples/pages.test.ts) gets by typing its commands into that world.
**How a recipe fits into a world.** A recipe is a whole world file, built like the [two-room game](https://mrballistic.github.io/brass-lantern/guide/building-worlds/two-rooms): one `World` object with rooms, items, characters and events. The code blocks under each heading show the part of the file the recipe is about; the rest (the rooms around it, the events it names, its `seed`) is in **The whole world**, folded under the notes. To put an idea in your own game, copy the parts it shows into your world’s object, along with anything they name.
**To play a recipe**, you don’t need to copy anything: every one ships with the engine under the name its file exports. Set up a project as in [Play it](https://mrballistic.github.io/brass-lantern/guide/building-worlds/two-rooms#play-it) and type each `> ` line of a transcript, without the `> `:
```ts
import { createGame } from '@brass-lantern/engine';
import { containers } from '@brass-lantern/engine/worlds';
const game = createGame(containers);
for (const command of ['take key', 'open jar', 'take key from jar']) {
console.log(`> ${command}`);
console.log(game.send(command).lines.join('\n'));
}
```
Each transcript starts from a new game (a fresh `createGame`), just after its opening lines (`game.opening`). Where randomness matters, the world’s `seed` fixes it, so the same commands give the same replies every time.
**Rules** appear in every recipe. They hang off a verb (`instead: { examine: [ … ] }`), as a list:
- **`instead`** rules replace what the verb does; **`after`** rules run once it has worked.
- **A rule’s keys:** `if` is a [condition](https://mrballistic.github.io/brass-lantern/reference/conditions-and-events#conditions) that has to hold; `with` names the second object it applies to (`unlock tin with key`); `then` names an event to run; `say` prints lines instead.
- **The first rule that fits wins.** The list is tried in order, so put the specific rules before a catch-all `{ say: [ … ] }`. The thing’s own rules are asked before the room’s.
[Rules](https://mrballistic.github.io/brass-lantern/reference/world-schema#rules) has the whole shape, and [Events and effects](https://mrballistic.github.io/brass-lantern/reference/conditions-and-events#events-and-effects) lists the steps an event can take.
## Containers and keys
A shelf with a glass jar on it, a key in the jar, and a locked tin the key opens.
```ts
items: {
// A surface: what's on it is always in view and in reach.
shelf: { name: 'shelf', description: 'A sagging pine shelf.', portable: false, tags: [], scenery: true, surface: true, contains: ['jar'] },
// Transparent: you can see the key through the glass, but not take it until it's open.
jar: {
name: 'glass jar',
aliases: ['jar'],
description: 'A jar with a screw-top lid.',
portable: true,
tags: [],
container: { openable: true, transparent: true },
contains: ['key'],
},
key: { name: 'tin key', aliases: ['key'], description: 'A tiny key.', portable: true, tags: [] },
// Locked, opened by the key, with room for two things.
tin: {
name: 'cookie tin',
aliases: ['tin'],
description: 'A dented tin with a keyhole.',
portable: false,
refusal: 'It’s wedged in tight.',
tags: [],
container: { openable: true, locked: true, key: 'key', capacity: 2, opened: 'The lid pops off with a sigh of cinnamon.' },
contains: ['cookie'],
},
cookie: { name: 'cookie', description: 'Snickerdoodle.', portable: true, tags: [] },
},
```
- **A `surface`** (the shelf) shows what’s on it, and you can reach it.
- **A `container`** holds things. `openable` gives it a lid; `locked` and `key` lock it; `capacity` limits how many things fit directly inside; `opened` replaces the default “Opened.”.
- **`transparent`** lets the player see inside while it’s closed, but not reach in: TAKE KEY says which container is in the way.
- **`contains`** says what starts inside or on it.
**The whole world: containers.ts**
```ts
import type { World } from '@brass-lantern/engine';
/** Recipe: containers, surfaces and keys. See docs/guide/building-worlds/recipes.md. */
export const containers: World = {
startRoom: 'pantry',
rooms: {
pantry: {
name: 'Pantry',
description: 'Narrow shelves, a smell of cinnamon.',
exits: {},
items: ['shelf', 'tin'],
npcs: [],
onEnter: [],
},
},
items: {
// A surface: what's on it is always in view and in reach.
shelf: { name: 'shelf', description: 'A sagging pine shelf.', portable: false, tags: [], scenery: true, surface: true, contains: ['jar'] },
// Transparent: you can see the key through the glass, but not take it until it's open.
jar: {
name: 'glass jar',
aliases: ['jar'],
description: 'A jar with a screw-top lid.',
portable: true,
tags: [],
container: { openable: true, transparent: true },
contains: ['key'],
},
key: { name: 'tin key', aliases: ['key'], description: 'A tiny key.', portable: true, tags: [] },
// Locked, opened by the key, with room for two things.
tin: {
name: 'cookie tin',
aliases: ['tin'],
description: 'A dented tin with a keyhole.',
portable: false,
refusal: 'It’s wedged in tight.',
tags: [],
container: { openable: true, locked: true, key: 'key', capacity: 2, opened: 'The lid pops off with a sigh of cinnamon.' },
contains: ['cookie'],
},
cookie: { name: 'cookie', description: 'Snickerdoodle.', portable: true, tags: [] },
},
npcs: {},
dialogue: {},
events: {},
flagLabels: {},
};
```
```
> take key
The glass jar is closed.
> open jar
Opened.
> take key from jar
Taken: tin key.
> unlock tin with key
Unlocked.
> open tin
The lid pops off with a sigh of cinnamon.
> take cookie
Taken: cookie.
> put key in tin
Done.
```
Doors between rooms are the same block on an item with `door: true`; the [two-room game](https://mrballistic.github.io/brass-lantern/guide/building-worlds/two-rooms) has one.
## Darkness and death
A shed with a lamp, and a dark cellar below it.
```ts
cellar: {
name: 'Cellar',
description: 'Damp stone walls. Steps lead up.',
dark: true,
exits: { up: 'shed' },
items: ['jam'],
npcs: [],
onEnter: [],
},
```
```ts
lamp: { name: 'oil lamp', aliases: ['lamp'], description: 'A brass oil lamp.', portable: true, tags: [], switchable: true, light: true },
```
```ts
darkness: {
look: 'It is pitch black. Something breathes nearby.',
// A direction with no exit, in the dark: Zork's grue, minus the 20% you live.
blunder: [{ die: 'You stumble into something with far too many teeth.' }],
},
death: {
message: [' **** You have died ****'],
lives: 1,
respawn: 'shed',
resurrection: ['You wake on the shed floor with a headache and a new respect for the dark.'],
final: ['That was your last chance. The cellar keeps you.'],
},
```
- **`dark: true`** makes a room need light. A **`light`** item gives it while it’s on (it has to be **`switchable`** to turn on), whether it’s carried, on the floor, or inside something open.
- **In the dark** the player can only find what they’re carrying. Anything else gets `tooDark` (“It’s too dark to see.”), and no time passes.
- **`blunder`** runs when the player tries a direction with no exit in the dark. Zork’s grue is a [`chance`](https://mrballistic.github.io/brass-lantern/reference/conditions-and-events#events-and-effects) of death; this one always bites.
- **`death`** says what dying does. With `lives: 1` the player gets one resurrection in `respawn`; the next death plays `final` and ends the game. Without a `death` block, dying ends the game at once.
**The whole world: darkness.ts**
```ts
import type { World } from '@brass-lantern/engine';
/** Recipe: dark rooms, a lamp, and a death that isn't the end. See docs/guide/building-worlds/recipes.md. */
export const darkness: World = {
startRoom: 'shed',
rooms: {
shed: {
name: 'Shed',
description: 'A garden shed. A hatch in the floor leads down.',
exits: { down: 'cellar' },
items: ['lamp'],
npcs: [],
onEnter: [],
},
cellar: {
name: 'Cellar',
description: 'Damp stone walls. Steps lead up.',
dark: true,
exits: { up: 'shed' },
items: ['jam'],
npcs: [],
onEnter: [],
},
},
items: {
lamp: { name: 'oil lamp', aliases: ['lamp'], description: 'A brass oil lamp.', portable: true, tags: [], switchable: true, light: true },
jam: { name: 'jar of jam', aliases: ['jam', 'jar'], description: 'Damson, 1987.', portable: true, tags: [] },
},
darkness: {
look: 'It is pitch black. Something breathes nearby.',
// A direction with no exit, in the dark: Zork's grue, minus the 20% you live.
blunder: [{ die: 'You stumble into something with far too many teeth.' }],
},
death: {
message: [' **** You have died ****'],
lives: 1,
respawn: 'shed',
resurrection: ['You wake on the shed floor with a headache and a new respect for the dark.'],
final: ['That was your last chance. The cellar keeps you.'],
},
npcs: {},
dialogue: {},
events: {},
flagLabels: {},
};
```
```
> down
📍 Darkness
It is pitch black. Something breathes nearby.
> take jam
It’s too dark to see.
> east
You stumble into something with far too many teeth.
**** You have died ****
You wake on the shed floor with a headache and a new respect for the dark.
📍 Shed
A garden shed. A hatch in the floor leads down.
You can see: oil lamp.
Exits: down.
> take lamp
Taken: oil lamp.
> turn on lamp
The oil lamp is now on.
> down
📍 Cellar
Damp stone walls. Steps lead up.
You can see: jar of jam.
Exits: up.
```
A lamp that runs out is a variable and a few daemons: see [Time](https://mrballistic.github.io/brass-lantern/reference/world-schema#time).
## Timers
A kettle that boils three turns after you turn it on, a clock, and a dripping tap.
```ts
items: {
kettle: {
name: 'kettle',
description: 'A whistling kettle.',
portable: false,
tags: [],
switchable: true,
// Turning it on lights a three-turn fuse; turning it off puts it out.
after: { turn_on: [{ then: 'heat' }], turn_off: [{ then: 'cool' }] },
},
},
events: {
heat: [{ schedule: 'boil', in: 3 }],
cool: [{ cancel: 'boil' }],
boil: ['The kettle shrieks. Tea time.', { switch: 'kettle', on: false }, { set: 'boiled' }],
chime: ['The clock chimes the hour.'],
},
```
```ts
vars: { minutes: 0 },
daemons: [
// Every turn is a minute; on the fifth, the clock chimes.
{ if: 'var:minutes>=0', then: [{ add: 'minutes', by: 1 }] },
{ if: 'var:minutes=5', then: 'chime' },
],
ambient: [{ if: '!flag:boiled', every: 2, lines: ['The tap drips.', 'The tap drips again.'] }],
```
- **A fuse** is the `schedule` effect: run an event after so many turns. `cancel` stops it. Here **`after`** rules start and stop it: they run once TURN ON or TURN OFF has worked.
- **A daemon** runs after every turn while its `if` holds. Two daemons make a clock: one counts minutes in a **variable**, the other chimes when it reaches 5.
- **`ambient`** lines interrupt every few turns while their condition holds.
- **A turn** is a command the engine acted on. Misunderstood commands, questions, and VERBOSE or UNDO take no time.
**The whole world: timers.ts**
```ts
import type { World } from '@brass-lantern/engine';
/** Recipe: fuses, daemons and ambient lines. See docs/guide/building-worlds/recipes.md. */
export const timers: World = {
startRoom: 'kitchen',
rooms: {
kitchen: {
name: 'Kitchen',
description: 'A small kitchen with a kettle on the stove.',
exits: {},
items: ['kettle'],
npcs: [],
onEnter: [],
},
},
items: {
kettle: {
name: 'kettle',
description: 'A whistling kettle.',
portable: false,
tags: [],
switchable: true,
// Turning it on lights a three-turn fuse; turning it off puts it out.
after: { turn_on: [{ then: 'heat' }], turn_off: [{ then: 'cool' }] },
},
},
events: {
heat: [{ schedule: 'boil', in: 3 }],
cool: [{ cancel: 'boil' }],
boil: ['The kettle shrieks. Tea time.', { switch: 'kettle', on: false }, { set: 'boiled' }],
chime: ['The clock chimes the hour.'],
},
vars: { minutes: 0 },
daemons: [
// Every turn is a minute; on the fifth, the clock chimes.
{ if: 'var:minutes>=0', then: [{ add: 'minutes', by: 1 }] },
{ if: 'var:minutes=5', then: 'chime' },
],
ambient: [{ if: '!flag:boiled', every: 2, lines: ['The tap drips.', 'The tap drips again.'] }],
npcs: {},
dialogue: {},
flagLabels: {},
};
```
```
> turn on kettle
The kettle is now on.
> wait
Time passes.
The tap drips.
> wait
Time passes.
> wait
Time passes.
The kettle shrieks. Tea time.
> wait
Time passes.
The clock chimes the hour.
```
## Endings and verbs of your own
A garden with something buried in it, and a chapel. Digging and praying aren’t built in, so the world declares them.
```ts
verbs: {
dig: { words: ['dig', 'dig in'], target: 'optional', indirect: ['with'], reply: 'There’s nowhere to dig here.' },
pray: { words: ['pray'], target: 'none', reply: 'Your prayer goes unanswered here.' },
},
```
```ts
events: {
treasure: ['You dig. Your spade rings on a strongbox full of coins.', { score: 50 }, { end: 'rich' }],
blessing: ['A warm calm settles over you.', { score: 10 }, { end: 'peace' }],
},
scoring: [],
maxScore: 50,
endings: {
rich: { lines: ['✨ You are rich, and the garden is a mess.'], score: true, footer: ['Type RESTART to try another ending.'] },
peace: { lines: ['✨ You leave lighter than you came.'], score: true, footer: ['Type RESTART to try another ending.'] },
},
```
- **A world verb** does nothing by itself. Rules give it meaning: the flowerbed has an `instead.dig` rule, and so does the garden, for DIG with no object. The chapel has `instead.pray`. Anywhere else, the verb’s `reply` answers.
- **`end`** plays an ending: its lines, the score (with `score: true`), then the footer.
- **The score** here comes from the `score` effect, out of `maxScore`. Worlds can also award points for flags with [`scoring`](https://mrballistic.github.io/brass-lantern/reference/world-schema#world).
**The whole world: endings.ts**
```ts
import type { World } from '@brass-lantern/engine';
/** Recipe: verbs of your own, and more than one way to end. See docs/guide/building-worlds/recipes.md. */
export const endings: World = {
startRoom: 'garden',
rooms: {
garden: {
name: 'Garden',
description: 'An overgrown garden. A chapel stands to the east. Something glints in a flowerbed.',
exits: { east: 'chapel' },
items: ['spade', 'flowerbed'],
npcs: [],
onEnter: [],
// DIG with no target asks the room.
instead: { dig: [{ if: 'has:spade', then: 'treasure' }, { say: ['The soil is packed hard. You need a spade.'] }] },
},
chapel: {
name: 'Chapel',
description: 'Cool and quiet. The garden is west.',
exits: { west: 'garden' },
items: [],
npcs: [],
onEnter: [],
instead: { pray: [{ then: 'blessing' }] },
},
},
verbs: {
dig: { words: ['dig', 'dig in'], target: 'optional', indirect: ['with'], reply: 'There’s nowhere to dig here.' },
pray: { words: ['pray'], target: 'none', reply: 'Your prayer goes unanswered here.' },
},
items: {
spade: { name: 'spade', description: 'A rusty spade.', portable: true, tags: [] },
flowerbed: {
name: 'flowerbed',
aliases: ['bed', 'flowers', 'soil'],
description: 'Something glints in the soil.',
portable: false,
tags: [],
scenery: true,
instead: { dig: [{ if: 'has:spade', then: 'treasure' }] },
},
},
events: {
treasure: ['You dig. Your spade rings on a strongbox full of coins.', { score: 50 }, { end: 'rich' }],
blessing: ['A warm calm settles over you.', { score: 10 }, { end: 'peace' }],
},
scoring: [],
maxScore: 50,
endings: {
rich: { lines: ['✨ You are rich, and the garden is a mess.'], score: true, footer: ['Type RESTART to try another ending.'] },
peace: { lines: ['✨ You leave lighter than you came.'], score: true, footer: ['Type RESTART to try another ending.'] },
},
npcs: {},
dialogue: {},
flagLabels: {},
};
```
```
> dig
The soil is packed hard. You need a spade.
> take spade
Taken: spade.
> dig in flowerbed
You dig. Your spade rings on a strongbox full of coins.
✨ You are rich, and the garden is a mess.
[Score: 50 of 50, in 2 moves.]
Type RESTART to try another ending.
```
The other ending, from a new game:
```
> east
📍 Chapel
Cool and quiet. The garden is west.
Exits: west.
> pray
A warm calm settles over you.
✨ You leave lighter than you came.
[Score: 10 of 50, in 1 move.]
Type RESTART to try another ending.
```
## A guard to fight
An armory with a sword and an anvil too heavy to lift, and a guard who won’t let you through.
```ts
items: {
sword: { name: 'sword', description: 'Notched, but sharp.', portable: true, tags: [], weapon: true, size: 10 },
anvil: { name: 'anvil', description: 'Black iron, very heavy.', portable: true, tags: [], size: 60 },
club: { name: 'club', description: 'A knotted club.', portable: true, tags: [], weapon: true, size: 10 },
},
// Nothing heavier than 50 in all.
carry: { limit: 50 },
```
```ts
npcs: {
guard: {
name: 'guard',
description: 'A guard with a club blocks the arch.',
descriptions: [{ if: '!awake:guard', text: 'The guard lies senseless on the flagstones.' }],
holds: ['club'],
combat: {
strength: 2,
weapon: 'club',
firstStrike: 50,
// Without his club, he spends his turns looking for it.
onBusy: 'guard_gropes',
onDeath: 'guard_drops_club',
onUnconscious: 'guard_drops_club',
messages: {
missed: ['The guard’s club whistles past your head.'],
lightWound: ['The club catches your shoulder.'],
seriousWound: ['The club cracks against your ribs.'],
stagger: ['The guard shoves you back.'],
unconscious: ['The club comes down on your head.'],
killed: ['The guard’s club finds your temple.'],
loseWeapon: ['The guard knocks the {weapon} from your hand.'],
},
},
},
},
combat: {
strength: { min: 2, max: 2 },
// The engine's own lines say “their” and “themselves”; these make the guard “he”.
messages: { loseWeapon: ['The club flies out of the guard’s hand.'] },
texts: { defenseless: 'The guard can’t defend himself.' },
},
```
```ts
gate: {
name: 'Gatehouse',
description: 'A stone arch. Beyond it, daylight. The armory is south.',
exits: {
south: 'armory',
// The guard bars the way until he's dead or out cold.
north: { to: 'courtyard', denials: [{ if: 'awake:guard', text: 'The guard steps in front of you.' }] },
},
items: [],
npcs: ['guard'],
onEnter: [],
},
```
- **`carry`** turns on weight. Each item weighs its `size` (5 if unset) plus what’s inside it, and TAKE refuses what would go over `limit`.
- **`combat`** on a character makes it someone you can fight with a `weapon`. The engine runs the fight: your strength against theirs, a seeded roll, and Zork’s tables of results. The guard’s `messages` are its blows at you; `world.combat` holds yours (short defaults here).
- **The engine’s own fight lines say “they”** (“The guard drops their weapon.”), since it doesn’t know who a character is. The world’s own `combat` block (not the guard’s) replaces the two that would say it here, `messages.loseWeapon` and `texts.defenseless`, so the guard is “he” throughout.
- **`holds`** gives the guard his club. While he has it he fights back; knock it away and `onBusy` runs instead of a swing.
- **`awake:guard`** in the exit’s `denials` keeps the way shut until he’s dead or out cold.
- **`seed`** (here `seed: 1`, in the whole world below) fixes the world’s random generator, so this transcript plays the same way every time. Leave it out and every game differs.
- **DIAGNOSE** says how hurt you are; wounds heal with time.
**The whole world: guard.ts**
```ts
import type { World } from '@brass-lantern/engine';
/** Recipe: a guard to fight, and something too heavy to carry. See docs/guide/building-worlds/recipes.md. */
export const guard: World = {
startRoom: 'armory',
// A fixed seed, so the fight in the recipe's transcript plays the same way every time.
seed: 1,
rooms: {
armory: {
name: 'Armory',
description: 'Racks of rusted weapons. An anvil squats in the corner. A gate is north.',
exits: { north: 'gate' },
items: ['sword', 'anvil'],
npcs: [],
onEnter: [],
},
gate: {
name: 'Gatehouse',
description: 'A stone arch. Beyond it, daylight. The armory is south.',
exits: {
south: 'armory',
// The guard bars the way until he's dead or out cold.
north: { to: 'courtyard', denials: [{ if: 'awake:guard', text: 'The guard steps in front of you.' }] },
},
items: [],
npcs: ['guard'],
onEnter: [],
},
courtyard: {
name: 'Courtyard',
description: 'Sunlight, at last.',
exits: {},
items: [],
npcs: [],
onEnter: [{ if: 'in:courtyard', then: 'escape' }],
},
},
items: {
sword: { name: 'sword', description: 'Notched, but sharp.', portable: true, tags: [], weapon: true, size: 10 },
anvil: { name: 'anvil', description: 'Black iron, very heavy.', portable: true, tags: [], size: 60 },
club: { name: 'club', description: 'A knotted club.', portable: true, tags: [], weapon: true, size: 10 },
},
// Nothing heavier than 50 in all.
carry: { limit: 50 },
npcs: {
guard: {
name: 'guard',
description: 'A guard with a club blocks the arch.',
descriptions: [{ if: '!awake:guard', text: 'The guard lies senseless on the flagstones.' }],
holds: ['club'],
combat: {
strength: 2,
weapon: 'club',
firstStrike: 50,
// Without his club, he spends his turns looking for it.
onBusy: 'guard_gropes',
onDeath: 'guard_drops_club',
onUnconscious: 'guard_drops_club',
messages: {
missed: ['The guard’s club whistles past your head.'],
lightWound: ['The club catches your shoulder.'],
seriousWound: ['The club cracks against your ribs.'],
stagger: ['The guard shoves you back.'],
unconscious: ['The club comes down on your head.'],
killed: ['The guard’s club finds your temple.'],
loseWeapon: ['The guard knocks the {weapon} from your hand.'],
},
},
},
},
combat: {
strength: { min: 2, max: 2 },
// The engine's own lines say “their” and “themselves”; these make the guard “he”.
messages: { loseWeapon: ['The club flies out of the guard’s hand.'] },
texts: { defenseless: 'The guard can’t defend himself.' },
},
dialogue: { guard: { default: '“Move along.”' } },
flagLabels: {},
events: {
guard_drops_club: [{ move: 'club', to: 'here' }],
guard_gropes: ['The guard gropes for his club.'],
escape: ['✨ You walk out into the sun.', { end: 'free' }],
},
endings: { free: { lines: ['You’re free.'] } },
};
```
```
> take anvil
[That’s too heavy to carry with everything else.]
> take sword
Taken: sword.
> north
📍 Gatehouse
A stone arch. Beyond it, daylight. The armory is south.
Present: guard.
Exits: south, north.
> north
The guard steps in front of you.
The guard shoves you back.
> attack guard with sword
You’re still reeling from that last blow.
The guard’s club whistles past your head.
> attack guard with sword
You wound the guard.
The club catches your shoulder.
> attack guard with sword
The club flies out of the guard’s hand.
The guard gropes for his club.
> attack guard with sword
The guard can’t defend himself.
The guard is dead.
> diagnose
[You have a light wound, which will be cured after 28 moves.]
[You can be killed by one more light wound.]
> north
📍 Courtyard
Sunlight, at last.
✨ You walk out into the sun.
You’re free.
```
In [Infocom style](https://mrballistic.github.io/brass-lantern/reference/world-schema#style) (`style: 'infocom'` on the world) the same fight uses Zork’s words, and `kill guard` picks the one weapon you’re holding. The native Zork I that ships with the engine (`import { zork1 } from '@brass-lantern/engine/worlds'`) has a troll that is this recipe with Zork’s own numbers and messages.
## Scripts
A fortune teller who tells you one of three fortunes, then sticks to it.
```ts
verbs: { consult: { words: ['consult'], target: 'required' } },
events: { reading: [{ script: 'fortune' }] },
vars: { fortune: 0 },
scripts: {
// Picks one of three fortunes the first time, then sticks to it.
fortune: (ctx) => {
const told = ctx.state.vars?.fortune ?? 0;
const pick = told || ctx.roll(3);
const text = ['“A stranger will bring you soup.”', '“Beware of geese.”', '“You will find what you lost under the sofa.”'][pick - 1];
return told ? ['“I have told you already,” she sighs.', text] : [{ setVar: 'fortune', to: pick }, text];
},
},
```
- **A script** is a function in `scripts` that returns ordinary steps: lines and effects. Events call it with `{ script: 'name' }`. It gets one argument, `ctx`, the game as the script sees it; [Scripts](https://mrballistic.github.io/brass-lantern/reference/world-schema#scripts) lists what’s on it.
- **It reads the game, it doesn’t change it.** `ctx.state` is read-only; to change things, return effects (`setVar` here). That keeps the engine’s guarantees: a command it didn’t understand changes nothing, and saves replay exactly.
- **`ctx.roll(3)`** is 1 to 3 from the game’s seeded generator, never `Math.random()`. With this world’s `seed: 3` the fortune is the sofa one; another seed picks another.
- **A rule on a character** (`instead.consult` on Madame Zora) answers a world verb aimed at her.
**The whole world: fortune.ts**
```ts
import type { World } from '@brass-lantern/engine';
/** Recipe: a script, for what data alone can't say. See docs/guide/building-worlds/recipes.md. */
export const fortune: World = {
startRoom: 'tent',
seed: 3,
rooms: {
tent: {
name: 'Fortune Teller’s Tent',
description: 'Velvet, incense, and a crystal ball.',
exits: {},
items: [],
npcs: ['madame'],
onEnter: [],
},
},
items: {},
npcs: {
madame: {
name: 'Madame Zora',
article: '',
description: 'Madame Zora peers at you over the crystal ball.',
instead: { consult: [{ then: 'reading' }] },
},
},
verbs: { consult: { words: ['consult'], target: 'required' } },
events: { reading: [{ script: 'fortune' }] },
vars: { fortune: 0 },
scripts: {
// Picks one of three fortunes the first time, then sticks to it.
fortune: (ctx) => {
const told = ctx.state.vars?.fortune ?? 0;
const pick = told || ctx.roll(3);
const text = ['“A stranger will bring you soup.”', '“Beware of geese.”', '“You will find what you lost under the sofa.”'][pick - 1];
return told ? ['“I have told you already,” she sighs.', text] : [{ setVar: 'fortune', to: pick }, text];
},
},
dialogue: {},
flagLabels: {},
};
```
```
> consult madame
“You will find what you lost under the sofa.”
> consult madame
“I have told you already,” she sighs.
“You will find what you lost under the sofa.”
```
Reach for a script only when data can’t say it. Most behavior is rules, conditions and effects.
## Topics and orders
A librarian who answers questions, and won’t be bossed about.
```ts
npcs: {
librarian: {
name: 'librarian',
description: 'The librarian peers at you over her glasses.',
topics: {
books: '“Shelved by color. Don’t ask.”',
archive: [
{ if: 'has:brass_key', text: '“You have the key. Go on, then.”' },
{ text: 'lend_key' },
],
dragons: '“Second floor, between the cookbooks and the tax law.”',
// ASK LIBRARIAN ABOUT ME (or MYSELF).
me: '“You look like someone with an overdue book.”',
},
topicAliases: { archive: ['the archive', 'archives', 'old letters', 'key'], books: ['book', 'shelves'] },
noTopic: '“I couldn’t say, dear.”',
refuseOrder: '“Shh.”',
},
},
events: {
// A topic entry can name an event: asking about the archive lends you the key.
lend_key: ['“Oh, the archive.” She slides a brass key across the desk.', { move: 'brass_key', to: 'player' }],
found_it: ['✨ The letters are all here.', { end: 'found' }],
},
```
- **`topics`** answer ASK (or TELL) *librarian* ABOUT *something*. Each topic is a line, or a list of entries tried in order; the first whose `if` holds wins.
- **An entry can name an event**, which runs instead of printing. Asking about the archive lends you the key, once; after that the `has:brass_key` entry answers first.
- **`topicAliases`** are other words for a topic, matched the same way item names are, so “the archive”, “archives” and “key” all find `archive`.
- **A topic keyed `me`** answers ASK *librarian* ABOUT ME, and ABOUT MYSELF too.
- **`noTopic`** answers anything else. Without it, ASK falls back to what TALK TO would say.
- **`refuseOrder`** answers an order: “librarian, open the door” or “tell librarian to open the door”. Without it the reply is “librarian ignores you.” A rule on the character (`instead.order`) can answer a particular order instead; in a script it runs, `ctx.command.words.indirect` is what was ordered (“open the door”).
**The whole world: topics.ts**
```ts
import type { World } from '@brass-lantern/engine';
/** Recipe: topics and orders. See docs/guide/building-worlds/recipes.md. */
export const topics: World = {
startRoom: 'library',
rooms: {
library: {
name: 'Library',
description: 'Tall shelves, a reading lamp, and a locked door marked ARCHIVE.',
exits: { north: { to: 'archive', door: 'archive_door' } },
items: [],
npcs: ['librarian'],
onEnter: [],
scenery: ['archive_door'],
},
archive: {
name: 'Archive',
description: 'Boxes of old letters. You found it.',
exits: { south: { to: 'library', door: 'archive_door' } },
items: [],
npcs: [],
onEnter: [{ if: 'in:archive', then: 'found_it' }],
scenery: ['archive_door'],
},
},
items: {
archive_door: {
name: 'archive door',
aliases: ['door'],
description: 'A heavy door marked ARCHIVE.',
portable: false,
tags: [],
door: true,
container: { openable: true, locked: true, key: 'brass_key' },
},
brass_key: { name: 'brass key', aliases: ['key'], description: 'Small and brass.', portable: true, tags: [] },
},
npcs: {
librarian: {
name: 'librarian',
description: 'The librarian peers at you over her glasses.',
topics: {
books: '“Shelved by color. Don’t ask.”',
archive: [
{ if: 'has:brass_key', text: '“You have the key. Go on, then.”' },
{ text: 'lend_key' },
],
dragons: '“Second floor, between the cookbooks and the tax law.”',
// ASK LIBRARIAN ABOUT ME (or MYSELF).
me: '“You look like someone with an overdue book.”',
},
topicAliases: { archive: ['the archive', 'archives', 'old letters', 'key'], books: ['book', 'shelves'] },
noTopic: '“I couldn’t say, dear.”',
refuseOrder: '“Shh.”',
},
},
events: {
// A topic entry can name an event: asking about the archive lends you the key.
lend_key: ['“Oh, the archive.” She slides a brass key across the desk.', { move: 'brass_key', to: 'player' }],
found_it: ['✨ The letters are all here.', { end: 'found' }],
},
endings: { found: { lines: ['You found what you came for.'] } },
dialogue: { librarian: { default: '“Can I help you find something?”' } },
flagLabels: {},
};
```
```
> ask librarian about books
“Shelved by color. Don’t ask.”
> ask librarian about me
“You look like someone with an overdue book.”
> ask librarian about the weather
“I couldn’t say, dear.”
> librarian, open the door
“Shh.”
> ask librarian about the archive
“Oh, the archive.” She slides a brass key across the desk.
> ask librarian about the archive
“You have the key. Go on, then.”
```
A character with no `orders` or `obeys` only answers; see [Orders, numbers and a buggy](#orders-numbers-and-a-buggy) for one that carries them out.
## A wandering character
A cat who wanders three rooms and walks off with your sock.
```ts
// The cat's turn: a daemon that runs a script after every turn the engine acts on.
daemons: [{ if: 'alive:cat', then: [{ script: 'cat_turn' }] }],
scripts: {
cat_turn: (ctx) => {
const rooms = ['hall', 'kitchen', 'garden'];
const at = rooms.find((r) => ctx.npcIn('cat', r))!;
// Half the time it stays put.
if (ctx.roll(2) === 1) return [];
const next = rooms[(rooms.indexOf(at) + 1) % rooms.length];
const here = ctx.room();
const steps: EventStep[] = [{ moveNpc: 'cat', to: next }];
if (at === here) steps.push('The cat stalks off.');
if (next === here) steps.push('The cat pads in.');
// A sock on the floor where it arrives goes with it.
if (ctx.children(next).includes('sock')) {
steps.push({ move: 'sock', to: 'cat' });
if (next === here) steps.push('The cat bats the sock away somewhere. It’s gone.');
}
return steps;
},
},
```
- **A daemon** runs after every turn the engine acts on. This one’s `if` (`alive:cat`) keeps the cat moving for as long as it lives, and its step is a script.
- **The script decides; its steps act.** `ctx.npcIn` finds the cat, `ctx.roll` decides whether it moves, and `{ moveNpc }` moves it. Lines are printed only when the player can see the cat leave or arrive (`ctx.room()` is where the player is).
- **`ctx.children(room)`** lists what’s on the floor there. `{ move: 'sock', to: 'cat' }` puts the sock in the cat’s keeping; a character’s holdings aren’t listed in a room.
- The world’s **`seed`** (`seed: 4`) fixes the cat’s path, so the transcript below plays the same way every time: the cat stays in the kitchen for six turns, then comes to the hall and takes the sock, which starts on the hall floor. It keeps wandering after that (hall, kitchen, garden and round again), which is why it turns up in the kitchen behind you. `ctx` is described under [Scripts](https://mrballistic.github.io/brass-lantern/reference/world-schema#scripts).
**The whole world: wanderer.ts**
```ts
import type { EventStep, World } from '@brass-lantern/engine';
/** Recipe: a character who wanders and steals. See docs/guide/building-worlds/recipes.md. */
export const wanderer: World = {
startRoom: 'hall',
seed: 4,
rooms: {
hall: { name: 'Hall', description: 'A narrow hall. The kitchen is east, the garden south.', exits: { east: 'kitchen', south: 'garden' }, items: ['sock'], npcs: [], onEnter: [] },
kitchen: { name: 'Kitchen', description: 'A warm kitchen. The hall is west.', exits: { west: 'hall' }, items: [], npcs: ['cat'], onEnter: [] },
garden: { name: 'Garden', description: 'A small garden. The hall is north.', exits: { north: 'hall' }, items: [], npcs: [], onEnter: [] },
},
items: {
sock: { name: 'sock', description: 'A single woolly sock.', portable: true, tags: [] },
},
npcs: {
cat: { name: 'cat', description: 'A gray cat with opinions.', holds: [] },
},
// The cat's turn: a daemon that runs a script after every turn the engine acts on.
daemons: [{ if: 'alive:cat', then: [{ script: 'cat_turn' }] }],
scripts: {
cat_turn: (ctx) => {
const rooms = ['hall', 'kitchen', 'garden'];
const at = rooms.find((r) => ctx.npcIn('cat', r))!;
// Half the time it stays put.
if (ctx.roll(2) === 1) return [];
const next = rooms[(rooms.indexOf(at) + 1) % rooms.length];
const here = ctx.room();
const steps: EventStep[] = [{ moveNpc: 'cat', to: next }];
if (at === here) steps.push('The cat stalks off.');
if (next === here) steps.push('The cat pads in.');
// A sock on the floor where it arrives goes with it.
if (ctx.children(next).includes('sock')) {
steps.push({ move: 'sock', to: 'cat' });
if (next === here) steps.push('The cat bats the sock away somewhere. It’s gone.');
}
return steps;
},
},
events: {},
dialogue: {},
flagLabels: {},
};
```
```
> wait
Time passes.
> wait
Time passes.
> wait
Time passes.
> wait
Time passes.
> wait
Time passes.
> wait
Time passes.
The cat pads in.
The cat bats the sock away somewhere. It’s gone.
> look
📍 Hall
A narrow hall. The kitchen is east, the garden south.
Present: cat.
Exits: east, south.
> east
📍 Kitchen
A warm kitchen. The hall is west.
Exits: west.
The cat pads in.
```
Native Zork I’s thief is this recipe grown up: he moves through the rooms, steals what’s worth stealing, and stays out of sight (`hidden`) until he chooses to show himself.
## A room that listens
A cave that hears everything you say as an echo, until you say the magic word.
```ts
cave: {
name: 'Echoing Cave',
description: 'A vast cave. Every sound comes back to you, louder. The way out is out.',
descriptions: [{ if: 'flag:quiet', text: 'A vast cave, quiet now. The way out is out.' }],
exits: { out: 'ledge' },
items: [],
npcs: [],
onEnter: [],
// Until it's quiet, whatever you say is heard as noise.
capture: { if: '!flag:quiet', script: 'echo' },
},
```
```ts
scripts: {
echo: (ctx) => {
// Captures also see commands that arrive already parsed (AGAIN); this one only hears raw words.
if (ctx.line === undefined) return;
const words = ctx.line.toLowerCase().trim().split(/\s+/);
// Declining (returning nothing) lets the line be parsed as usual: OUT still works.
if (words[0] === 'out') return;
if (words[0] === 'echo') return [{ set: 'quiet' }, 'The cave falls silent.', { free: true }];
const last = words[words.length - 1];
return [`${last} ${last} ...`, { free: true }];
},
},
```
- **This world is in [Infocom style](https://mrballistic.github.io/brass-lantern/reference/world-schema#style)** (`style: 'infocom'`), like Zork: rooms show no exit line, and a room you’ve been in before shows just its name.
- **[`capture`](https://mrballistic.github.io/brass-lantern/reference/world-schema#capture)** sees each command before the parser does, while its `if` holds. The script reads the raw words from `ctx.line`.
- **Returning steps takes the command**, and drops the rest of the line. **Returning nothing declines**: the command is parsed as usual, so OUT still leaves.
- **A capture also sees commands that arrive already parsed** (AGAIN, the intent server’s reading), with `ctx.line` unset; this one only hears raw words, so it returns nothing then.
- **`{ free: true }`** makes the reply take no time. The transcript below counts three moves: IN, LOOK and OUT.
- Captured words never reach the intent server, and SAVE, UNDO and RESTART are handled before any capture, so a player can’t get stuck.
**The whole world: echo.ts**
```ts
import type { World } from '@brass-lantern/engine';
/** Recipe: a room that listens. See docs/guide/building-worlds/recipes.md. */
export const echo: World = {
startRoom: 'ledge',
style: 'infocom',
rooms: {
ledge: {
name: 'Ledge',
description: 'A narrow ledge outside a cave. The cave mouth is in.',
exits: { in: 'cave' },
items: [],
npcs: [],
onEnter: [],
},
cave: {
name: 'Echoing Cave',
description: 'A vast cave. Every sound comes back to you, louder. The way out is out.',
descriptions: [{ if: 'flag:quiet', text: 'A vast cave, quiet now. The way out is out.' }],
exits: { out: 'ledge' },
items: [],
npcs: [],
onEnter: [],
// Until it's quiet, whatever you say is heard as noise.
capture: { if: '!flag:quiet', script: 'echo' },
},
},
items: {},
npcs: {},
scripts: {
echo: (ctx) => {
// Captures also see commands that arrive already parsed (AGAIN); this one only hears raw words.
if (ctx.line === undefined) return;
const words = ctx.line.toLowerCase().trim().split(/\s+/);
// Declining (returning nothing) lets the line be parsed as usual: OUT still works.
if (words[0] === 'out') return;
if (words[0] === 'echo') return [{ set: 'quiet' }, 'The cave falls silent.', { free: true }];
const last = words[words.length - 1];
return [`${last} ${last} ...`, { free: true }];
},
},
events: {},
dialogue: {},
flagLabels: {},
};
```
```
> in
📍 Echoing Cave
A vast cave. Every sound comes back to you, louder. The way out is out.
> hello there
there there ...
> echo
The cave falls silent.
> look
📍 Echoing Cave
A vast cave, quiet now. The way out is out.
> out
📍 Ledge
```
Native Zork I’s Loud Room is this recipe with Zork’s rules: ECHO quiets it, and when the dam’s gates are open at high tide its end routine (`onEnd`) throws you out.
## A raft on a pond
A raft, a pond you can’t wade, and an island beyond it.
```ts
raft: {
name: 'raft',
description: 'A raft of lashed logs.',
portable: false,
tags: [],
vehicle: { travels: 'water' },
container: { open: true },
},
```
```ts
pond: {
name: 'Pond',
description: 'The middle of the pond. Lily pads drift by. An island lies to the east, the bank to the west.',
// Only something that floats goes here.
water: true,
exits: { west: 'bank', east: 'island' },
items: [],
npcs: [],
onEnter: [],
},
```
- **This world is in [Infocom style](https://mrballistic.github.io/brass-lantern/reference/world-schema#style)** too, so the vehicle lines are Zork’s: “Pond, in the raft”, “(raft)” when the parser fills in what you meant, and “(outside the raft)” on the room’s things.
- **`vehicle`** makes an item something to get into: BOARD it while it’s on the ground, DISEMBARK to get out.
- **`water`** marks a room only a water vehicle reaches. On foot it’s “You can’t go there without a vehicle.”; aboard, getting out there is refused.
- **The raft goes where you go**, and comes to rest on the island’s shore with you still aboard. Things you drop land in the raft, and the room’s things are “(outside the raft)”.
**The whole world: raft.ts**
```ts
import type { World } from '@brass-lantern/engine';
/** Recipe: a raft on a pond. See docs/guide/building-worlds/recipes.md. */
export const raft: World = {
startRoom: 'bank',
style: 'infocom',
rooms: {
bank: {
name: 'Pond Bank',
description: 'A muddy bank. A pond stretches east.',
exits: { east: 'pond' },
items: ['raft'],
npcs: [],
onEnter: [],
},
pond: {
name: 'Pond',
description: 'The middle of the pond. Lily pads drift by. An island lies to the east, the bank to the west.',
// Only something that floats goes here.
water: true,
exits: { west: 'bank', east: 'island' },
items: [],
npcs: [],
onEnter: [],
},
island: {
name: 'Island',
description: 'A tiny island with one tree. The pond is west.',
exits: { west: 'pond' },
items: ['pinecone'],
npcs: [],
onEnter: [],
},
},
items: {
raft: {
name: 'raft',
description: 'A raft of lashed logs.',
portable: false,
tags: [],
vehicle: { travels: 'water' },
container: { open: true },
},
pinecone: { name: 'pine cone', aliases: ['cone', 'pinecone'], description: 'A fine pine cone.', portable: true, tags: [] },
},
npcs: {},
events: {},
dialogue: {},
flagLabels: {},
};
```
```
> east
You can’t go there without a vehicle.
> board raft
You are now in the raft.
> east
📍 Pond, in the raft
The middle of the pond. Lily pads drift by. An island lies to the east, the bank to the west.
> disembark
(raft)
You realize that getting out here would be fatal.
> east
The raft comes to a rest on the shore.
📍 Island, in the raft
A tiny island with one tree. The pond is west.
There is a pine cone here. (outside the raft)
```
Native Zork I’s magic boat is this recipe with Zork’s rules on top: inflating it, the label, LAUNCH, punctures and the river’s current.
## Orders, numbers and a buggy
A workshop with a robot that does as it’s told, a dial you turn to a number, and a dune buggy for the sand beyond the yard.
```ts
npcs: {
robot: {
name: 'robot',
description: 'A squat robot on treads, with one clamp for an arm.',
// It does these built-in orders itself: “robot, go east”, “robot, take wrench”.
obeys: ['go', 'take'],
obeyReplies: { go: 'Whirr, click!', take: 'Click!' },
refuseOrder: 'The robot beeps, puzzled.',
// And these through rules, keyed by the verb: “robot, push the button”.
orders: {
push: [{ if: 'target:button', then: 'robot_pushes' }, { say: ['The robot has no use for that.'] }],
// “robot, go to the dunes”: in a go rule, `direction:` is where it was told to go, as typed.
go: [{ if: 'direction:dunes', say: ['The robot looks at its treads, then at the sand, and stays put.'] }],
},
},
},
```
- **`obeys`** lists the built-in orders the robot carries out itself: GO, TAKE, DROP and GIVE (“robot, give me the wrench”). `obeyReplies` is what it says; the default is “Okay.”
- **`orders`** is a table of rules per verb, for anything else (“robot, push the button”). Its rules read the order as the player wrote it: `target:button` is what it was told to push. “Push” is also the word the parser files under USE; the word typed is tried first, so `orders.push` answers it even when `orders.use` exists.
- **`direction:`** in an `orders.go` rule is the place the character was told to go, as typed: “robot, go to the dunes” is `direction:dunes`. A rule that answers stops the robot obeying; anything else (“robot, go east”) falls through to `obeys`.
- **An order ends the rest of the line**, and the objects of an order are looked up in *its* room, not the player’s.
```ts
dial: {
name: 'dial',
aliases: ['brass dial'],
// `{var:dial}` fills in from the game; it's 0 until the dial is set.
description: 'The brass dial points at {var:dial}.',
portable: false,
tags: [],
instead: {
turn: [
{ with: 'number', if: 'number:4', then: 'hatch_opens' },
{ with: 'number', then: 'dial_set' },
],
},
},
```
- **A number** is a second object: `turn dial to 4`. A rule says `with: 'number'` and tests `number:4`; `{ setVar: 'dial', from: 'number' }` keeps it and `{number}` prints it. `{var:dial}` fills in a description from the game, so EXAMINE shows where the dial points now.
```ts
dune: {
name: 'Dune',
description: 'Soft sand rolls away in every direction. The yard is west; a bigger dune lies east.',
// A terrain of the world's own: only something that travels on sand goes here.
terrain: 'sand',
exits: { west: 'yard', east: 'crest' },
items: [],
npcs: [],
onEnter: [],
},
crest: {
name: 'Crest',
description: 'The top of the biggest dune. You can see the whole desert, and it is all sand.',
terrain: 'sand',
exits: { west: 'dune' },
items: [],
npcs: [],
onEnter: [],
},
```
```ts
buggy: {
name: 'dune buggy',
aliases: ['buggy'],
description: 'A rattling dune buggy with fat tires.',
portable: false,
tags: [],
// It travels on land and on sand; its `leave` lines are said as it drives off with you.
vehicle: { travels: ['land', 'sand'], leave: ['The engine roars.', 'Sand sprays behind you.'] },
container: { open: true },
},
```
- **A terrain** is any name a room gives itself ([Vehicles](https://mrballistic.github.io/brass-lantern/reference/world-schema#vehicles) has the fields). On foot you can walk only where `onFoot` allows (default `['land']`), so the dunes need a vehicle that `travels` on `'sand'`. `leave` (and `arrive`, `landing`) are lines the vehicle says as it goes; with more than one, the seeded generator picks (this world’s `seed: 4` picks “Sand sprays behind you.” first).
**The whole world: workshop.ts**
```ts
import type { World } from '@brass-lantern/engine';
/** Recipe: orders, numbers and a buggy. See docs/guide/building-worlds/recipes.md. */
export const workshop: World = {
startRoom: 'workshop',
// Fixes the buggy's choice of line, so the recipe's transcript plays the same every time.
seed: 4,
rooms: {
workshop: {
name: 'Workshop',
description: 'Benches, a big brass dial on the wall and a red button. The yard is east.',
exits: { east: 'yard' },
items: ['dial', 'button', 'wrench'],
npcs: ['robot'],
onEnter: [],
},
yard: {
name: 'Yard',
description: 'A gravel yard. The workshop is west, and dunes begin to the east.',
exits: { west: 'workshop', east: 'dune' },
items: ['buggy'],
npcs: [],
onEnter: [],
},
dune: {
name: 'Dune',
description: 'Soft sand rolls away in every direction. The yard is west; a bigger dune lies east.',
// A terrain of the world's own: only something that travels on sand goes here.
terrain: 'sand',
exits: { west: 'yard', east: 'crest' },
items: [],
npcs: [],
onEnter: [],
},
crest: {
name: 'Crest',
description: 'The top of the biggest dune. You can see the whole desert, and it is all sand.',
terrain: 'sand',
exits: { west: 'dune' },
items: [],
npcs: [],
onEnter: [],
},
},
items: {
dial: {
name: 'dial',
aliases: ['brass dial'],
// `{var:dial}` fills in from the game; it's 0 until the dial is set.
description: 'The brass dial points at {var:dial}.',
portable: false,
tags: [],
instead: {
turn: [
{ with: 'number', if: 'number:4', then: 'hatch_opens' },
{ with: 'number', then: 'dial_set' },
],
},
},
button: { name: 'red button', aliases: ['button'], description: 'A red button. It begs to be pushed.', portable: false, tags: [] },
wrench: { name: 'wrench', description: 'A big, greasy wrench.', portable: true, tags: [] },
buggy: {
name: 'dune buggy',
aliases: ['buggy'],
description: 'A rattling dune buggy with fat tires.',
portable: false,
tags: [],
// It travels on land and on sand; its `leave` lines are said as it drives off with you.
vehicle: { travels: ['land', 'sand'], leave: ['The engine roars.', 'Sand sprays behind you.'] },
container: { open: true },
},
},
npcs: {
robot: {
name: 'robot',
description: 'A squat robot on treads, with one clamp for an arm.',
// It does these built-in orders itself: “robot, go east”, “robot, take wrench”.
obeys: ['go', 'take'],
obeyReplies: { go: 'Whirr, click!', take: 'Click!' },
refuseOrder: 'The robot beeps, puzzled.',
// And these through rules, keyed by the verb: “robot, push the button”.
orders: {
push: [{ if: 'target:button', then: 'robot_pushes' }, { say: ['The robot has no use for that.'] }],
// “robot, go to the dunes”: in a go rule, `direction:` is where it was told to go, as typed.
go: [{ if: 'direction:dunes', say: ['The robot looks at its treads, then at the sand, and stays put.'] }],
},
},
},
events: {
hatch_opens: ['The dial clicks to 4, and a hatch in the floor swings open. Inside is a tin of biscuits.', { setVar: 'dial', from: 'number' }, { end: 'biscuits' }],
dial_set: [{ setVar: 'dial', from: 'number' }, 'The dial clicks round to {number}. Nothing else happens.'],
robot_pushes: ['The robot extends its clamp and presses the button. Somewhere, a bell rings.'],
},
endings: { biscuits: { lines: ['A good day in the workshop.'] } },
dialogue: { robot: { default: 'The robot beeps.' } },
flagLabels: {},
};
```
```
> robot, go to the dunes
The robot looks at its treads, then at the sand, and stays put.
> robot, push the button
The robot extends its clamp and presses the button. Somewhere, a bell rings.
> robot, go east
Whirr, click!
> turn dial to 2
The dial clicks round to 2. Nothing else happens.
> examine dial
The brass dial points at 2.
> east
📍 Yard
A gravel yard. The workshop is west, and dunes begin to the east.
You can see: dune buggy.
Present: robot.
Exits: west, east.
> east
You can’t go there without a vehicle.
> board buggy
You are now in the dune buggy.
> east
Sand sprays behind you.
📍 Dune (in the dune buggy)
Soft sand rolls away in every direction. The yard is west; a bigger dune lies east.
Exits: west, east.
```
Turn the dial to 4 instead and the hatch opens, which ends the game.
---
Source: https://mrballistic.github.io/brass-lantern/guide/testing
# Testing a world
A world is data, and data rots quietly: an exit points at a renamed room, a flag label gets a typo, the ending becomes unreachable. Two kinds of test catch nearly all of it, and both run in plain Node with any test runner. The examples here use [Vitest](https://vitest.dev/).
## Play it
`createGame` from `@brass-lantern/engine` runs a world with no browser: feed it the lines a player would type, and read the replies. A test reads like a transcript:
```ts
import { describe, expect, it } from 'vitest';
import { createGame } from '@brass-lantern/engine';
import { tutorial } from '@brass-lantern/engine/worlds';
describe('Snack Attack', () => {
it('plays to the best ending', () => {
const game = createGame(tutorial, { seed: 1 });
const text = [
'open drawer',
'take stapler',
'north',
'take mug and give mug to gary',
'talk to gary',
'north',
'smash machine with stapler',
].flatMap((line) => game.send(line).lines).join('\n');
expect(game.state.gameOver).toBe(true);
expect(text).toContain('You share the pretzels');
expect(text).toContain('[Score: 50 of 50');
});
});
```
Swap `tutorial` for your own world (`import { myWorld } from './my-world'`). `seed` makes the game’s randomness repeatable, so a world with chance effects or fights plays the same way on every run.
Write at least two: the **shortest win**, and a run that **earns every point**. When either breaks, you’ve changed the critical path or the scoring, on purpose or not.
To pin every word, compare the whole transcript: `expect(text).toMatchInlineSnapshot()` fills itself in on the first `npx vitest -u`, and from then on any change to the text fails the test until you look at it.
`send` takes a whole line, as the player would type it: chained commands, pronouns, AGAIN, OOPS, UNDO and the answer to a question all work. When the game asks “Which door do you mean?”, the reply’s `awaiting` is true and the next `send` answers it. There’s no intent server in a test, so write commands the regex parser understands, and name things with words the world knows. Every word of three or more letters has to be in the thing’s name, an alias or its ID, so `take red ball` misses a thing called only “ball” (“You don’t see a “red ball” here.”). In brass style a close misspelling of a word in the name also matches. In the browser the intent server might rescue that; in a test it fails, which is how you find the alias players will need. Since 2.1.0 this is stricter than it was, so a test that passed on 2.0 can start failing here: add the alias (see [How names are matched](https://mrballistic.github.io/brass-lantern/guide/building-worlds/#how-names-are-matched)).
## Check the data
`auditWorld(world)` returns a list of problems, one string each, and an empty list when it finds none:
```ts
import { expect, it } from 'vitest';
import { auditWorld } from '@brass-lantern/engine';
import { myWorld } from './my-world';
it('has no broken references', () => {
expect(auditWorld(myWorld)).toEqual([]);
});
```
It finds the mistakes that fail silently in play:
- effects naming items, rooms, events or endings that don’t exist, and unknown effects;
- events named by rules, `onEnter`, `onTake`, `onWear`, `onSmash`, `onGive`, daemons and the finale that don’t exist;
- conditions of unknown kinds, or naming items and rooms that don’t exist (in rules, triggers, exits, `requires`, daemons, hints and scoring); `direction:` takes any lowercase word, since an `orders.go` rule sees the place as typed (`direction:basement`);
- exits to nowhere, doors that aren’t items, items listed in rooms or containers that don’t exist;
- a world verb word that a built-in verb already owns, and the reserved IDs `player` and `number`.
It doesn’t walk the map. A few more checks are worth writing for your own world. Every room reachable from the start:
```ts
it('every room is reachable from the start', () => {
const seen = new Set
();
const queue = [myWorld.startRoom];
while (queue.length) {
const id = queue.shift()!;
if (seen.has(id)) continue;
seen.add(id);
for (const exit of Object.values(myWorld.rooms[id]?.exits ?? {})) {
const to = typeof exit === 'string' ? exit : exit.to;
if (to) queue.push(to);
}
}
expect(Object.keys(myWorld.rooms).filter((id) => !seen.has(id))).toEqual([]);
});
```
More along the same lines: every `[Flag set: …]` label is in `flagLabels`; every flag in a `requires`, hint or scoring entry can actually be set by some event; every gated room has a `denial`; every `listExits` label is a real exit.
**Copy style** is easy to test too. If you use curly quotes, fail on straight ones:
```ts
it('uses smart punctuation', () => {
const strings: string[] = [];
const walk = (v: unknown): void => {
if (typeof v === 'string') strings.push(v);
else if (Array.isArray(v)) v.forEach(walk);
else if (v && typeof v === 'object') Object.values(v).forEach(walk);
};
walk(myWorld);
expect(strings.filter((s) => /["']/.test(s))).toEqual([]);
});
```
That walks every string in the world, IDs and conditions included, which is fine as long as those don’t use quotes either.
---
Source: https://mrballistic.github.io/brass-lantern/reference/world-schema
# World schema
Every field a world can use. The source of truth is [`packages/engine/src/types/world.ts`](https://github.com/mrballistic/brass-lantern/blob/main/packages/engine/src/types/world.ts), which has a comment on each one. “Condition” means a [condition string](https://mrballistic.github.io/brass-lantern/reference/conditions-and-events#conditions); “event” means a key in `events`.
## World
| Field | Type | |
|---|---|---|
| `startRoom` | room ID | Where a new game begins. |
| `onFoot?` | string[] | Terrains the player can walk into and get out of a vehicle in. Default `['land']`; a custom terrain is walkable only if listed. See [Vehicles](#vehicles). |
| `rooms` | `Record` | |
| `items` | `Record` | |
| `npcs` | `Record` | |
| `dialogue` | `Record` | What TALK TO says. |
| `events` | `Record` | Lines and [effects](https://mrballistic.github.io/brass-lantern/reference/conditions-and-events#events-and-effects). `intro` plays when a new game starts. |
| `flagLabels` | `Record` | Maps the lowercased label in `[Flag set: …]` lines to a flag ID. |
| `typoReplies?` | string[] | Lines said when a misspelled name is matched anyway (brass style only), once per thing, taken in turn. `{typed}` is the word as typed, `{name}` the thing’s name with its article in lowercase (“the guard”), so start a reply with `{typed}` or other text rather than `{name}`. Leave it out and corrections are silent. The engine records what it has teased in `GameState.typoMocked` (optional; saved with the game). Example: `“{typed}”? You mean {name}.` |
| `hints?` | `Hint[]` | HINT shows the first whose condition holds. |
| `scoring?` | `{ flag, points }[]` or `{ if, points }[]` | SCORE sums points for set flags, plus conditions that hold right now (a treasure in the case), plus the `score` variable. |
| `maxScore?` | number | The total SCORE reports. Default: the sum of `scoring`. |
| `ranks?` | `{ min, title }[]` | The highest `min` the score reaches is the rank. |
| `scoreLine?` | string | SCORE’s first line, replacing the style’s own. `{score}`, `{max}` and `{moves}` (“3 moves”) fill in: `'Your potential is {score} of a possible {max}, in {moves}.'` |
| `rankLine?` | string | SCORE’s rank line, replacing the style’s own. `{rank}` fills in: `'This score gives you the rank of {rank}.'` |
| `diagnose?` | `{ healthy?, wounded? }` | DIAGNOSE’s own lines for being unhurt and for being wounded, as fixed text. Unset, the engine’s wording stands. |
| `idle?` | string | Reply to WAIT or SIT where they don’t lead anywhere. Default: “Time passes.” |
| `quit?` | string | Reply to QUIT. |
| `confused?` | string[] | Replies for input nothing understood, rotated. |
| `ambient?` | `Ambient[]` | Timed interruptions. |
| `finale?` | `Finale` | The win condition. |
| `verbs?` | `Record` | Verbs this world adds. See [World verbs](#world-verbs). |
| `vars?` | `Record` | Starting values for numeric variables. |
| `seed?` | number | Seeds the random generator, for reproducible games. Default: the clock. |
| `daemons?` | `{ if, then }[]` | Run after every turn the engine acts on, while `if` holds. `then` is an event name or steps. See [Time](#time). |
| `darkness?` | object | Texts and behavior for dark rooms. See [Darkness](#darkness). |
| `death?` | object | What dying does. See [Death](#death). |
| `endings?` | `Record` | Named endings for the `end` effect. See [Endings](#endings). |
| `style?` | `'brass'` or `'infocom'` | Output conventions. See [Style](#style). Default `'brass'`. |
| `emptyInventory?` | string | INVENTORY with nothing carried. Default: “You are empty-handed.” |
| `smashRefusal?` | string | SMASH where nothing can be smashed, or at a person. |
| `title?` | string | The game’s full title, for VERSION and Infocom-style transcripts (“ZORK I: The Great Underground Empire”). |
| `credits?` | string[] | Lines VERSION prints after the title. |
| `carry?` | `Carry` | Carrying weight. Without it there’s no limit. See [Weight](#weight). |
| `combat?` | `CombatRules` | The player’s side of fights. See [Combat](#combat). |
| `scripts?` | `Record` | The code hatch: functions that return steps. See [Scripts](#scripts). |
| `capture?` | `Capture` | Takes input anywhere, after the room’s own capture. See [Capture](#capture). |
| `wait?` | `{ turns }` | WAIT runs the clock up to `turns` times, stopping after a turn where something happened (Zork: 3). Each counts as a move. |
| `statusLine?` | `'moves'` or `'score'` | The header in brass style: `MOVES: n` (the default) or `SCORE: n MOVES: n`. Infocom style always shows the room, score and moves. |
## Room
| Field | Type | |
|---|---|---|
| `name` | string | Shown as the room header. |
| `description` | string | |
| `firstDescription?` | string | Replaces `description` on the first visit only. |
| `dark?` | boolean | Needs a light source to see in. |
| `descriptions?` | `{ if, text }[]` | Descriptions that depend on the state of things (“a small window which is open”). The first whose condition holds replaces `description`. |
| `descriptionScript?` | script name | A [script](#scripts) whose `say` lines (joined with newlines) are the description, ahead of `firstDescription` and `descriptions`. It runs on every look, so it describes the game as it is now. Any step that isn’t a `say` is ignored (and the audit flags it), a script that says nothing falls back to the next description, and the engine restores the seed afterwards, so describing never changes the game. |
| `exits` | `Record` | What the player can type, and where it goes. Several labels per destination is normal. A label of `wait` or `sit` is taken by WAIT/SIT. See [Exit](#exit). |
| `listExits?` | label[] | What the exit line shows, in order; each gets the compass direction that leads the same way. Omit to list every label. |
| `items` | item ID[] | Items in the room at the start. |
| `npcs` | NPC ID[] | |
| `onEnter` | `{ if?, then, repeat? }[]` | Events fired on arrival when the condition holds: once per game, or every time with `repeat: true`. Leave out `if` and it always fires. |
| `requires?` | condition | Must hold to enter. |
| `denial?` | string | Shown when `requires` fails. |
| `scenery?` | item ID[] | Items present here without being in the room: a door shared by two rooms, a window, the sky. Examinable and usable, never listed or taken. |
| `instead?`, `after?` | `Record` | Rules for verbs used in this room. See [Rules](#rules). |
| `tags?` | string[] | Free-form labels for scripts to read (`maze`, `sacred`). The engine doesn’t. |
| `capture?` | `Capture` | Takes input here before it’s parsed. See [Capture](#capture). |
| `water?` | boolean or condition | Water (Zork’s NONLANDBIT): only a water vehicle goes here. A condition for a room that changes (a reservoir that drains: `'!flag:low_tide'`). See [Vehicles](#vehicles). |
| `air?` | boolean or condition | Air (Zork II’s balloon): shorthand for `terrain: 'air'`. Same shape as `water`. |
| `terrain?` | string | What kind of ground this is, for vehicles. Default `'land'` (or `'water'` / `'air'` where those shorthands hold); a set `terrain` wins over them. Any name works (`'sand'`). See [Vehicles](#vehicles). |
| `onEnd?` | `{ if, then }[]` | Run at the end of every command here, after the action and before the clock (Zork’s M-END). After WAIT’s turns when `wait` is set. |
### Exit
| Field | Type | |
|---|---|---|
| `to?` | room ID | Where it goes. Omit for an exit that only prints `denial` (“The door is boarded.”). |
| `if?` | condition | Must hold for this exit alone. |
| `denial?` | string | Shown when `if` fails, or always if there’s no `to`. Default: “You can’t go that way.” |
| `door?` | item ID | An item with `door: true` that must be open. A closed door says “The *name* is closed.” |
| `denials?` | `{ if, text }[]` | Refusals with their own reasons, checked first; the first whose `if` holds refuses with `text` (Zork’s chimney). |
| `then?` | event | Runs as the player goes through, before arriving (Zork’s exit routines). |
Message-only exits aren’t listed unless `listExits` names them.
## Item
| Field | Type | |
|---|---|---|
| `name` | string | Display name, and what event lines like `[Added to inventory: …]` match. Keep it unique. |
| `aliases?` | string[] | Other words players might use. Matched, never shown. Every word of three or more letters a player types must be in the name, an alias or the ID, so add the descriptive words players will reach for: `aliases: ['red ball']`. See [How names are matched](https://mrballistic.github.io/brass-lantern/guide/building-worlds/#how-names-are-matched). |
| `descriptionScript?` | script name | A script whose `say` lines are EXAMINE’s text, ahead of `description` (same rules as a room’s). See [Descriptions from state](#descriptions-from-state). |
| `description` | string | EXAMINE. Leave it empty (`''`) and EXAMINE does what Zork does for an object with no text: a container lists what’s in it or says “The *name* is empty.”; anything else is “There’s nothing special about the *name*.” |
| `portable` | boolean | Can it be taken? |
| `refusal?` | string | Reply to taking a non-portable item. |
| `tags` | string[] | Free-form; the engine doesn’t read them. |
| `onTake?` | event | Fires the first time it’s taken. |
| `onUse?` | `UseRule[]` | See below. |
| `onWear?` | event | Fires the first time it’s worn; WEAR again says “already wearing”. |
| `onSmash?` | event | Fires once, then the item is gone. |
| `contains?` | item ID[] | Items that start inside or on this one. |
| `container?` | `Container` | Makes it a container. See below. |
| `surface?` | boolean | Things can be put on it; what’s on it is always visible and reachable. |
| `scenery?` | boolean | Present but never listed (the house, the forest). |
| `door?` | boolean | A door between rooms; exits name it. Uses `container` for openable/open/locked/key. |
| `size?` | number | Its weight, in worlds with `carry` (Zork’s SIZE). Default 5. |
| `weapon?` | boolean | Something to fight with. |
| `vehicle?` | `{ travels, restsOn?, landing?, leave?, arrive?, lookScript? }` | Something the player can get into and travel in. See [Vehicles](#vehicles). |
| `onEnd?` | `{ if, then }[]` | A vehicle’s end routines: while the player is aboard they run instead of the room’s. |
| `burnable?` | boolean | BURN can set it alight (Zork’s BURNBIT). |
| `flaming?` | boolean | It can set things alight: always, or while it’s on if it switches (Zork’s FLAMEBIT). LIGHT or TURN ON on one that isn’t `switchable` says “It’s already lit.” It gives light only if it also has `light` and is on. |
| `treasure?` | number | What it’s worth (Zork’s TVALUE). The engine doesn’t read it; scripts and scoring can. |
| `text?` | string | What READ shows. Default: the description. |
| `initialDescription?` | string | Its own sentence in a room until first taken. |
| `roomDescription?` | string | Its own sentence in a room after that. Items with neither are gathered into “You can see: …”. |
| `roomDescriptionScript?` | script name | A world script whose `say` lines are its room sentence, ahead of both (Zork’s DESCFCN). It says everything itself: no “(outside the raft)” follows, and its contents aren’t listed. One that says nothing falls back to the others. |
| `climbRefusal?` | `{ if?, text }` | Infocom style: climbing it up or down where there’s no way that way says `text` (Zork’s tree: “There are no climbable trees here.”). |
| `switchable?` | boolean | TURN ON and TURN OFF work on it. |
| `light?` | boolean | Gives light while on: it lights a dark room it’s in, carried there, or inside something open or transparent there. |
| `home?` | room ID | Where it goes if the player dies carrying it. |
| `article?` | string | “a”, “an”, “some” or “” in listings. |
| `contentsHeading?` | string | The heading over its contents (“Your collection of treasures consists of:”). |
| `instead?`, `after?` | `Record` | See [Rules](#rules). |
### Container
| Field | Type | |
|---|---|---|
| `openable?` | boolean | Has a lid or door. Containers that aren’t openable are always open. |
| `open?` | boolean | Starts open. |
| `locked?` | boolean | Starts locked. |
| `key?` | item ID | Locks and unlocks it. |
| `transparent?` | boolean | You can see inside even when it’s closed. |
| `capacity?` | number | How many items fit directly inside. |
| `weight?` | number | The total weight it holds (Zork’s CAPACITY), in worlds with `carry`. |
| `opened?`, `closed?` | string | Lines for opening and closing it, instead of the defaults. |
You can see into a surface, an open container or a transparent one; you can reach into a surface or an open container. The parser only matches what you can see, and taking something you can see but can’t reach says which container is closed.
### UseRule
Rules are tried in order and the **first** whose conditions hold runs. For two-object commands, rules on both items are checked, so one rule covers “put the disk in the drive” and “use the drive with the disk”.
| Field | Type | |
|---|---|---|
| `if?` | condition | |
| `with?` | item ID | Another item that must be in the room or carried. If the player names a second object, it must be this one. `'number'` matches a command whose second object is a number typed by the player (TURN DIAL TO 4); test which with `number:`. |
| `then?` | event | |
| `say?` | string[] | Lines printed without changing anything. |
USE also covers PUSH, PULL, PRESS and ATTACH X TO Y. OPEN and PUT fall back to an item’s use rules when it isn’t a container (or isn’t in your hands), so OPEN DRAWER works on a drawer that has only a use rule. Using an item with `onWear` and no matching rule wears it. Verbs like SLEEP, UNPLUG or INSTALL are [world verbs](#world-verbs) now: declare them and give items `instead` rules.
## Rules
Items and rooms can carry rules for any verb, built-in or declared by the world:
```ts
instead: { move: [{ if: 'flag:rug_moved', say: ['It won’t budge again.'] }, { then: 'rug_moved' }] },
after: { take: [{ if: '!flag:took_egg', then: 'took_egg' }] },
```
- **`instead`** rules run in place of the verb’s default.
- **`after`** rules run after the default succeeds and changes something.
- **Lookup order:** the target item’s rules, then the indirect item’s, then the room’s. The first rule whose `if` holds (and whose `with` matches the other object, when given) wins.
- A rule is the same shape as a UseRule (above).
- **`as: 'target'` or `'indirect'`** limits a rule to its item’s role in the command (Zork’s PRSO and PRSI): a tube that refuses things put *into* it, not itself put somewhere.
- **`prep`** limits it to a preposition: `prep: 'in'` answers PUT … IN, not PUT … ON.
- **In Infocom style** the second object’s rules are asked before the first’s, as Zork’s PERFORM does (POUR WATER ON BELL asks the bell first).
- **`continue: true`** on an `instead` rule runs it and then lets the verb’s default go on as well (Zork’s “print, then RFALSE”): a line before the TAKE that still happens.
- **On a character**, rules answer verbs aimed at it, including `order` (see [NPC](#npc)).
- **The older hooks still work:** `onUse` is `instead.use`, and `onTake` is a one-shot `after.take`.
## World verbs
A world can add verbs without touching the engine or the intent server:
```ts
verbs: {
pray: { words: ['pray'], target: 'none', reply: 'If you pray enough, your prayers may be answered.' },
move: { words: ['move', 'shift'], target: 'required' },
drive: { words: ['drive', 'drive to'], target: 'optional', go: true },
},
```
| Field | Type | |
|---|---|---|
| `words` | string[] | Words and phrases that mean it. Phrases are matched before built-in verbs, single words after. |
| `target` | `'none'`, `'optional'`, `'required'` or `'text'` | `'text'` takes the rest of the line as typed words (SAY, ANSWER), read by `said:`. |
| `indirect?` | string[] | Prepositions that introduce a second object (`with`, `on`). |
| `reply?` | string | When no rule applies. Default: “Nothing happens.” `{target}` is replaced by the object’s name, `{a target}` by its name with an article. |
| `held?` | boolean | The object must be something you hold, or can see inside something you hold (Zork’s HELD): POUR WATER means the water in your bottle. |
| `go?` | boolean | Treat it as GO: through the target exit, or the exit labeled with the verb’s ID. `instead.go` rules (the vehicle’s, the room’s) answer it as they answer GO. |
| `afterBuiltIns?` | boolean | Its words may be built-in words: it reads only lines no built-in verb reads, after them (Zork III’s bare TURN DIAL, where the engine’s TURN wants TO or WITH). |
- A world verb does nothing by itself: give items or rooms `instead` rules for it.
- With no target, it looks for a rule on the room, then on anything in reach (SNOOZE finds the alarm clock).
- A word a built-in verb already uses (`take`, `open`, …) is ignored, unless the verb is `afterBuiltIns`; `auditWorld` reports any (“verb word … is a built-in”). Since 2.1.0 that includes `follow`: a world that declared its own FOLLOW should drop it, and its `orders.follow` rules keep working (see [Orders](#orders)).
- A `go: true` verb meets the same `instead.go` rules as GO, so a rule that refuses to leave refuses walking and driving alike:
```ts
verbs: { drive: { words: ['drive', 'drive to'], target: 'optional', go: true } },
rooms: {
garage: {
// …
instead: { go: [{ if: '!flag:gate_open', say: ['The gate is shut.'] }] },
},
},
```
```
> drive north
The gate is shut.
> north
The gate is shut.
```
## Style
- **`'brass'`** (the default) lists items as “You can see: …”, says “Taken: lamp.”, and shows an exit line.
- **`'infocom'`** follows Zork’s conventions:
- “There is a sword here.” and “Taken.”;
- no exit line;
- a room you’ve visited shows just its name and contents unless you LOOK (SUPERBRIEF shows only the name, in either style);
- lists newest first;
- SCORE says “Your score is 15 (total of 350 points), in 40 moves.”, and (like VERBOSE, BRIEF and SUPERBRIEF) runs no clock: no move, no timers, though the room’s end routine still runs;
- the header shows the room, score and moves, like Zork’s status line;
- questions, TAKE ALL and transcripts use Zork’s wording;
- bookkeeping lines like `[Flag set: …]` act without being shown;
- each thing’s contents are listed right after it;
- READ takes the thing first (“(Taken)”), EXAMINE of a thing with no description reads it, and opening a container whose one untouched thing has a first-seen sentence says “The coffin opens.” and that sentence;
- a door with no lines of its own “opens” and “is now closed”, and OPEN and CLOSE say “It is already open.” and “It is already closed.”;
- PUT … ON something that isn’t a surface says “There’s no good surface on the …”;
- a room’s `scenery` (Zork’s local globals) only answers to a word when nothing else in reach does;
- the second object’s rules come before the first’s;
- untouched things’ first-seen sentences are listed before everything else;
- EXAMINE of a closed box says “The box is closed.”
## Time
After every turn the engine acts on (never after a misunderstood command), these happen in order:
1. **The room’s end routines** (`onEnd`, Zork’s M-END).
2. **Fuses** count down, and those reaching zero run. A fuse is set by the `schedule` effect and removed by `cancel`; one set during a turn starts counting the next turn.
3. **Daemons** run, in order, each while its `if` holds.
4. **Ambient lines** print.
A lamp that burns down is a variable and a few daemons:
```ts
vars: { lamp_fuel: 185 },
daemons: [
{ if: 'on:lamp', then: [{ add: 'lamp_fuel', by: -1 }] },
{ if: 'on:lamp & var:lamp_fuel=85 & here:lamp', then: ['The lamp appears a bit dimmer.'] },
{ if: 'on:lamp & var:lamp_fuel<0', then: 'lamp_dies' },
],
```
With the world’s `wait` set, WAIT runs steps 1 to 3 up to that many times, stopping after one where something happened (a line printed or a fuse fired), and the room’s end routines run after them.
A **move** is one of these turns: MOVES in the header and SCORE count them. Commands that take no game time (VERBOSE, BRIEF, SUPERBRIEF, UNDO, SAVE, RESTORE, SCRIPT, VERSION, a question back to the player) don’t count, and nothing runs after them.
## Darkness
| Field | Type | |
|---|---|---|
| `look?` | string | LOOK and arriving in an unlit dark room. Default: “It is pitch black.” |
| `tooDark?` | string | Acting on something you can’t see. Default: “It’s too dark to see.” |
| `fall?` | string | When the room goes dark around you. Default: “It is now pitch black.” |
| `arrive?` | string | Said on arriving in an unlit room, before its darkness line (Zork’s “You have moved into a dark place.”). |
| `stumble?` | `{ chance, then, aboard? }` | Walking from an unlit dark room into another: `chance`% of `then` instead (Zork’s grue, 80), or `aboard` in a vehicle. |
| `litIf?` | condition | While it holds, every room is lit (Zork’s ALWAYS-LIT, for a spirit). Mustn’t use `lit:`. |
| `blunder?` | `EventStep[]` | Run when the player tries a direction with no exit in the dark. Zork’s grue: `[{ chance: 80, then: [{ die: '…' }], else: ['You can’t go that way.'] }]`. |
In an unlit dark room you can only find what you’re carrying. Trying to act on anything else gets `tooDark`: an understood refusal, so the intent server isn’t asked to re-guess. EXAMINE of a character who’s there gets it too (“It’s too dark to see.”); talking to a character, giving it things, ordering it and fighting it still work in the dark. Turning a light on or off says so (`fall`, or the room’s description).
Only an item with `light` that is on lights a room. A `flaming` thing with no switch (a torch, a lit match) answers LIGHT with “It’s already lit.”, and gives no light by itself. If it should also light the room, give it `light: true` and switch it on with a `{ switch: 'torch', on: true }` effect.
## Death
| Field | Type | |
|---|---|---|
| `message?` | `(string or { if, text })[]` | Printed after the cause; an entry with `if` only while it holds (Zork’s “Bad luck, huh?”). |
| `penalty?` | number | Added to the score. |
| `lives?` | number | Deaths survived before the final one. |
| `respawn?` | room ID | Where the player wakes. |
| `resurrection?` | string[] | |
| `scatter?` | room ID[] | Carried things are spread over these, at random (seeded). Things with a `home` go there instead; with no scatter rooms, they stay where the player fell. |
| `treasures?` | `'dark'` or `{ to }` | `'dark'`: treasures go to an unlit land room instead, walking the rooms in order at even odds each (Zork’s RANDOMIZE-OBJECTS). `{ to: 'case' }`: treasures without a `home` all go to that room, item or character (a trophy case), drawing no randomness. |
| `keepTimers?` | event[] | Timers a death leaves running, with their counts. Every other timer is cleared. |
| `final?` | string[] | The last death, which ends the game. |
| `then?` | event | Runs after a resurrection, to reset things (Zork’s trap door, unbarred). |
| `variants?` | `{ if, resurrection?, respawn?, then?, before? }[]` | The first whose `if` holds (decided as you die) replaces those fields; `before` runs ahead of the respawn. Zork sends you to Hades as a spirit once you’ve seen the Altar. |
| `instead?` | `{ if, lines }[]` | Checked first: the first that holds prints its lines (not the cause) and ends the game. Dying while already dead. |
The `die` effect uses it. Without a `death` block, dying prints the cause and ends the game. Pending fuses are canceled on death, except those in `keepTimers`.
## Endings
`endings: { victory: { lines: [...], score: true, footer: ['Type RESTART to play again.'] } }`. The `end` effect plays one: its lines, the score and rank if `score` is set, then the footer, and the game is over. The `finale` is an ending too, reached by smashing.
## NPC
| Field | Type | |
|---|---|---|
| `name` | string | |
| `article?` | string | Brass style: the article in the engine’s lines that start with the character’s name (“The robot can’t go that way.”, FOLLOW’s reply). Default `'the'`; `''` for a proper name, so Floyd isn’t “The Floyd”. Mid-sentence it’s lowercased: “You’d rather the robot came to you.” See [Orders](#orders). |
| `description` | string | EXAMINE. In an unlit dark room, EXAMINE of a character gets the [darkness](#darkness) reply. |
| `onGive?` | `Record- ` | GIVE hands the item over and fires the event. |
| `refuse?` | `Record
- ` | Declines that item; the player keeps it. |
| `refuseGift?` | string | Declines anything else. |
| `holds?` | item ID[] | What it carries at the start. Things a character holds can’t be seen or taken. |
| `descriptions?` | `{ if, text }[]` | Its line in the room and its EXAMINE reply, by state; the first whose condition holds wins. |
| `descriptionScript?` | script name | A script whose `say` lines are that description, ahead of `descriptions`. |
| `instead?`, `after?` | `Record` | Rules for verbs aimed at it: THROW X AT it, GIVE, TAKE, a world verb. |
| `combat?` | `Combatant` | Makes it someone you can fight. See [Combat](#combat). |
| `aliases?` | string[] | Other words for it (“robber”, “man”). Matched like an item’s: every word of three or more letters typed must be in the name, an alias or the ID. |
| `scenery?` | boolean | Present but not listed: the room’s own description mentions it (Zork’s cyclops). `{ npcState, scenery }` changes it in play. |
| `hidden?` | boolean | Starts hidden: in its room for scripts, but not seen, listed, matched or fought until revealed. |
| `topics?` | `Record` | ASK or TELL it ABOUT a topic. A list is tried in order; the first entry whose `if` holds answers. Text that names an event runs it. |
| `topicAliases?` | `Record` | Other words for a topic. A topic keyed or aliased `me` or `myself` answers ASK *X* ABOUT ME and ABOUT MYSELF (either word reaches it). |
| `noTopic?` | string | For a topic it has nothing on. Default: its TALK TO line. |
| `refuseOrder?` | string | Its answer to an order. Default: “*Name* ignores you.” |
| `orders?` | `Record` | Rules for orders, by the inner command’s verb. See [Orders](#orders). |
| `obeys?` | `('go' \| 'take' \| 'drop' \| 'give')[]` | Built-in orders it carries out itself when no order rule answers. |
| `obeyReplies?` | `Record` | Its acknowledgement when it obeys one of those. Default: “Okay.” |
| `follows?` | condition | While it holds, the character goes where the player goes. See [Followers](#followers). |
| `followLine?` | string | What it says on arriving after you. Unset: brass style prints “*Name* follows you.”; Infocom style prints nothing. |
| `heardFrom?` | room ID[] | Rooms from which the player can give it orders while it’s elsewhere (Zork III’s dungeon master on the parapet, ordered from the cell); its orders are carried out where it stands. |
Characters’ places and states live in the game state (`npcs`), starting from the rooms that list them. In brass style the room shows “Present: …”; in Infocom style each character prints its own line.
**Hidden characters.** A character that’s `hidden` (from the start, or by the `npcState` effect with `hidden: true`) is still in its room: `ctx.npcIn` and conditions like `with:` see it, but the player doesn’t, and it doesn’t fight. `{ npcState: 'thief', hidden: false }` reveals it. The `seen:` condition is true only when it’s in the player’s room and not hidden.
### Orders
“*name*, *command*”, “tell *name* to *command*” and a bare “tell *name*” are orders. What happens, in order:
1. **`instead.order`** rules on the character answer first, as for any verb. In one, `ctx.command.words.indirect` is the order as typed. A character with only `instead.order` (no `orders`, no `obeys`) answers, or says `refuseOrder`, and the rest of the line carries on.
2. Otherwise the order is read as a command of its own, with its objects resolved among what the character can reach in **its** room (ME or MYSELF is the player, YOURSELF the character itself; a number typed as an object counts). A word that names nothing there is a miss that changes nothing, so the intent server may still read it; one that matches several things asks which, taking no time. A character can’t refer to what the player carries.
3. **`orders`** rules are keyed by the inner command’s verb: `orders: { push: [...], take: [...] }`. They are the same shape as other [rules](#rules), and their conditions see the inner command (`target:`, `indirect:`, `number:`, `said:`, `direction:`). **The first word typed is tried first**, when it has a table (PUSH reads as USE, so “robot, push the button” runs `orders.push` even when `orders.use` exists); otherwise the parsed verb’s table (“robot, press the button” runs `orders.use`). A rule with `continue: true` runs and then lets step 4 go on.
4. If no rule answered and the verb is in `obeys`, the character performs it, saying `obeyReplies[verb]` (default “Okay.”):
- **`go`**: it walks that exit of its room. Nothing is printed but its reply: no leaving or arriving lines. No exit, or one that refuses, is a miss that says why (“The robot can’t go that way.”). In Infocom style it walks as the player does: no exit says “You can’t go that way.”, and an exit that refuses says its own refusal.
- **`take`** and **`drop`**: the thing moves to or from the character (weight limits apply only to the player). One it can’t take or drop is a miss that says why, by name: “The robot can’t take the dial.”, “The robot doesn’t have the sock.” In Infocom style a take it can’t do says the player’s own take line.
- **`give`**: “give me the key” moves it from the character to the player (the second object is the player).
5. Otherwise `refuseOrder`, or “*Name* ignores you.”
In brass style the why-lines in step 4 start with the character’s `article` (default “the”): “The robot can’t go that way.” Give a proper name `article: ''` and it reads “Floyd can’t go that way.”
**An order to a character with `orders` or `obeys` ends the rest of the line** (Zork clears the typed-ahead commands), unless it was a miss. That includes an obeying character’s refusal, which takes a turn like any understood command. A character with neither answers orders only through `instead.order` and `refuseOrder`.
**`heardFrom`** lists rooms from which the player can give a character orders while it’s somewhere else. Its orders are carried out where it stands (Zork III’s dungeon master, ordered from the cell while he stands on the parapet).
```ts
robot: {
name: 'robot',
obeys: ['go', 'take'],
obeyReplies: { go: 'Whirr, buzz, click!' },
orders: {
push: [{ if: 'target:red_button', then: 'lift_cage' }],
use: [{ say: ['The robot ignores that.'] }], // “robot, press the button”; “robot, push the button” runs orders.push
},
},
```
### FOLLOW
FOLLOW is a built-in verb. With no rule of the world’s:
- bare FOLLOW asks “What do you want to follow?”;
- FOLLOW *character* points the player at the order form: “You’d rather Floyd came to you. Try FLOYD, FOLLOW ME.” (with `article: ''`);
- FOLLOW *thing* says “You can’t follow that.”;
- FOLLOW *something not here* is a miss, so the intent server may read it.
An `instead.follow` rule on the character (or the room) answers FOLLOW *character* instead. **“*X*, FOLLOW ME”** is an order: it runs `orders.follow`, where ME is the player (`target:player`). The engine keeps no following state of its own, so a rule that agrees sets it with the `follow` effect, and the character then goes where the player goes ([Followers](#followers)):
```ts
floyd: {
name: 'Floyd',
article: '',
description: 'Floyd, a cheerful robot.',
orders: { follow: [{ if: 'target:player', then: 'floyd_tags_along' }] },
},
// events:
floyd_tags_along: ['“Floyd go too!” he squeaks.', { follow: 'floyd' }],
```
```
> follow floyd
You’d rather Floyd came to you. Try FLOYD, FOLLOW ME.
> floyd, follow me
“Floyd go too!” he squeaks.
> north
📍 Study
…
Floyd follows you.
```
A character with no `orders.follow` rule answers “floyd, follow me” as any other order it has no rule for (step 5 above).
### Followers
`follows` is a condition on the character; while it holds, after each move the **player** makes (GO, doors, ENTER, CLIMB; not a script’s `goTo` or a `moveVehicle`), the character moves into the player’s new room if it was in the room the player left, and is awake and not hidden. It’s checked after the move, so `in:ROOM` sees the new room. Its `followLine` prints as it arrives. The `follow` and `unfollow` effects set and clear the character’s `following` state (an optional field of its game state, not a flag), which `following:NPC` reads, for a switch rather than a condition. Characters who arrive take the engine’s placing order, so room listings keep it.
## Weight
```ts
carry: { limit: 100, self: 5, fumble: { over: 7, chance: 8 } },
```
| Field | Type | |
|---|---|---|
| `limit` | number | The total weight the player can carry when healthy. |
| `self?` | number | The player’s own weight, counted in (Zork’s ADVENTURER is 5). |
| `fumble?` | `{ over, chance }` | Carrying more than `over` things, each TAKE has `count × chance` percent to fumble. |
| `tooHeavy?`, `tooHeavyHurt?`, `fumbled?` | string | The refusals. |
An item weighs its `size` plus everything inside it. Wounds lower the limit and healing restores it.
## Combat
A character with `combat` can be fought: ATTACK *it* WITH *a weapon*. The engine owns the mechanics, ported from Zork I: strength against strength picks one of six blow tables, and a seeded roll picks the result (missed, staggered, wounded, knocked out, killed, disarmed). After every turn the engine acts on, characters in the room who are fighting swing back.
| `Combatant` field | Type | |
|---|---|---|
| `strength` | number | The troll: 2. |
| `weapon?` | item ID | What it fights with, while it holds it. |
| `fears?` | `{ item, by }` | The player’s weapon that weakens it (the troll fears the sword, by 1). |
| `wake?` | number | Percent added each turn to its chance of waking while out cold. Default 25. |
| `firstStrike?` | number | Percent chance each turn to start a fight while you’re in the room. |
| `messages?` | `Partial>` | Its blows at the player, one picked at random. `{weapon}` and `{defender}` are filled in. |
| `onDeath?`, `onUnconscious?`, `onWake?` | event | When it dies, is knocked out, comes round. |
| `onBusy?` | event | Instead of swinging when its weapon is on the floor (the troll recovers his axe). |
| `CombatRules` field | Type | |
|---|---|---|
| `messages?` | same | The player’s blows. |
| `strength?` | `{ min, max }` | The player’s strength, from `min` at no score to `max` at `maxScore` (Zork: 2 to 7). |
| `cureWait?` | number | Turns for one wound to heal (Zork: 30). |
| `texts?` | `Partial>` | Fixed lines: refusals, the death line, the fog. Defaults: Zork’s words in Infocom style, short ones in brass. |
**In Infocom style** ATTACK works the way Zork’s parser does: with one weapon in hand, `kill troll` picks it (“(with the sword)”); otherwise it asks what to attack with; a weapon you aren’t holding is refused without taking a turn. DIAGNOSE reports your wounds. A [recipe](https://mrballistic.github.io/brass-lantern/guide/building-worlds/recipes#a-guard-to-fight) shows a whole fight.
## Numbers, typed words and prepositions
**Numbers.** A number in an object slot is the player’s typed number (Zork’s INTNUM): `turn dial to 4`, `set year to 776`. It’s digits up to 1000, or H:MM as minutes (hours under 8 count as afternoon); a bigger number is just an unknown word. Both forms are built-in and go through rules as the verb `turn` with the second object `number`. With no rule, Infocom style says Zork’s “This has no effect.”; brass style misses, so the intent server may still read the input. A bare TURN X keeps its own meaning. The command keeps the digits as typed, so a number no rule wants misses with them (“take 5”: “You don’t see a “5” here.”); `number` is a reserved ID, like `player`. Digits that name a thing in sight or a character here (an item named “locker 12” or aliased `5`; whole words only, so “1” is not locker 12) are that thing, as Zork’s parser reads a word it knows before trying a number: `turn dial to 12` with locker 12 present is TURN DIAL WITH the locker, its rules fire, and `number:12` still holds. Only when nothing is called that are the digits `number`. TURN X WITH a thing, with no rule, says “This has no effect.” in every style.
```ts
dial: {
instead: { turn: [
{ with: 'number', if: 'number:4', then: 'door_opens' },
{ with: 'number', say: ['The dial clicks and nothing happens.'] },
] },
},
```
- **`number:N`** and `numberN` read it in conditions; **`{ setVar: 'year', from: 'number' }`** stores it; **`{number}`** in a line prints it, and `ctx.number` has it in a script.
- A rule with `with: 'number'` matches only a command whose second object is a number.
- An order can carry one (“robot, turn the dial to 4” runs `orders.turn` with `number:4`).
**Typed words.** A world verb with `target: 'text'` (SAY, INCANT, ANSWER) takes the rest of the line as typed words. They are never resolved to things, so naming nothing is no miss. Outer quotes are dropped and whitespace collapsed. **`said:WORDS`** matches them as lowercase whole words, with punctuation and quotes ignored (`said:a well` matches `answer “A well.”`), and `ctx.text` has them. The verb consumes the whole rest of the line, so it ends the line: `say "well". west` drops WEST, as in Zork. A quoted phrase isn’t split at its full stops or commas. Only double quotes (straight or curly) quote; a single quote is an apostrophe (`answer 'don't know'` keeps every word). This applies to every world: a quoted “. ” doesn’t end a command. Unlike Zork, where only a quoted phrase is typed words, **unquoted text counts too**: `answer well` solves a riddle that wants “a well”.
**Prepositions.** These forms go through the ordinary rules. With no rule, Infocom style gives Zork’s reply below; brass style misses with the same line (all but READ, which reads), so the intent server can still read the input. A rule answers in both styles.
| Form | Rule verb | Built-in reply |
|---|---|---|
| PUT/PUSH/SLIDE X UNDER Y | `put`, `prep: 'under'` | “You can’t do that.” |
| PUT X BEHIND Y | `put`, `prep: 'behind'` | “That hiding place is too obvious.” |
| THROW X OFF/OVER Y | `throw`, `prep: 'off'` or `'over'` | “You can’t throw anything off of that!” |
| READ X THROUGH/WITH Y | `read`, with the second object | reads X |
| PUSH X *direction*, PUSH X TO Y | `push`, `direction:DIR` / the second object | “You can’t push things to that.” |
**ME.** ME and MYSELF in an object slot name the player; so do SELF and YOURSELF, unless something in sight (or someone here) is named or aliased that. Rules match them with `target:player` or `indirect:player` (and `with: 'player'`). The engine adds no replies of its own for ME: a verb aimed at it with no rule misses with the word typed (“You don’t see a “me” here.”), so a world says what Zork says (“You can’t tie anything to yourself.”) in a rule. The reserved ID `player` is never matched against a thing’s or character’s name (a “record player” is safe from TAKE ME); typed, “player” is an ordinary word. In an order, ME is the speaker (“robot, give me the key”) and YOURSELF the character (“robot, push yourself”). ASK *X* ABOUT ME (or MYSELF) reaches a topic keyed or aliased `me` or `myself`, and nothing else: `topicAliases: { you: ['me'] }` answers both.
## Descriptions from state
- **Templates.** `{var:NAME}` (0 when unset) and `{number}` fill in from the game in any room, item or character description, a `descriptions` entry, an event line, and an item’s `initialDescription` and `roomDescription` wherever they list it (the room, a container’s contents, a surface, opening a container). A `{number}` with no number typed stays as written. Expanding reads the game and changes nothing.
```ts
tally: { name: 'tally board', description: 'Chalk marks.', portable: false, tags: [], roomDescription: 'A tally board on the wall reads {var:tally}.' },
```
With `tally` at 3, LOOK lists “A tally board on the wall reads 3.”
- **`descriptionScript`** on a room, item or character names a [script](#scripts) that builds the description from the game: its `say` lines, joined with newlines. It comes first, ahead of `descriptions`, `firstDescription` and `description`. It’s for descriptions a condition list can’t say: a grid of cells, a dial’s setting, a room that lists its own exits.
- **`roomDescriptionScript`** on an item is its sentence in a room listing, ahead of its other sentences; it says everything itself, so no “(outside the boat)” follows and its contents aren’t listed (Zork’s DESCFCN).
- **`vehicle.lookScript`** describes a vehicle from inside. See [Vehicles](#vehicles).
- A description script may use `ctx.roll`, but the engine puts the seed back afterwards, so looking never changes the game. A script that says nothing falls back to the next description. The audit runs each description script once on a new game and flags a step that isn’t a `say`, or a script name that doesn’t exist.
## Scripts
The code hatch, for behavior data can’t express (a thief’s mind, a sword that glows near monsters):
```ts
scripts: {
fortune: (ctx) => [ctx.roll(3) === 1 ? '“Beware of geese.”' : '“Soup is coming.”'],
},
events: { reading: [{ script: 'fortune' }] },
```
A script gets a read-only view of the game and returns ordinary steps, which the engine runs. `ctx` has:
- `state` (frozen in development and tests), `world`;
- `random()` and `roll(n)`, from the game’s seeded generator, so saves and UNDO replay exactly;
- `here(id)`, `carried(id)`, `holder(id)`, `room()`, `npc(id)`;
- `npcIn(id, room)` (hidden or not), `hidden(id)`;
- `aboard()`, the vehicle the player is in, `water(room?)` and `terrain(room?)` (the room’s terrain name);
- `rooms()` in the world’s order, `visited(room)`, `tags(room)`, `lit(room?)`;
- `children(place)`, what’s directly in a room, item or character, in listing order;
- `test(condition)`, whether a [condition](https://mrballistic.github.io/brass-lantern/reference/conditions-and-events#conditions) holds now, through the engine’s own parser (scripts never parse conditions themselves);
- `exits(room)`, the exits the player could take from that room now (`{ direction, to }[]`): no entry in its `denials` holds, its `if` holds and its door is open. It’s the same check the player’s moves and characters’ orders use, so a script never offers an exit GO would refuse;
- `resolve(words, scope?)`, words read as an item the way the parser would: `'here'` (within reach, the default), `'held'` or `'all'`; null if none matches;
- `number` and `text`, the number or the typed words in the command being run (TURN DIAL TO 4, SAY HELLO);
- `treasure(id)`, an item’s `treasure` value or 0;
- `playerStrength()`, the player’s fight strength now;
- `line`, the raw input, and `action`, the parsed command, when a [capture](#capture) runs the script; `parse(text)`, which reads a command with the world’s verbs as the parser would;
- `arg`, from `{ script, arg }`;
- `command`, the command being run with its objects resolved to IDs, when a rule ran the script. `command.words` keeps the words typed for objects that didn’t resolve.
Scripts run only where events run, so a command the engine didn’t understand still changes nothing. The world audit fails on a `script` effect naming no script. See the [scripts recipe](https://mrballistic.github.io/brass-lantern/guide/building-worlds/recipes#scripts).
## Vehicles
```ts
raft: { name: 'raft', vehicle: { travels: 'water' }, container: { open: true }, … },
pond: { name: 'Pond', water: true, … },
```
- **BOARD** (GET IN, CLIMB IN) gets in a vehicle that’s on the ground here; **DISEMBARK** (GET OUT, GET OFF, STAND) gets out, except where the room’s terrain isn’t one the player walks (water, air, sand unless `onFoot` lists it): “You realize that getting out here would be fatal.” While aboard, EXIT on its own is DISEMBARK too (Zork’s V-EXIT); otherwise it’s the direction out. In Infocom style, DISEMBARK with no object names the one vehicle in sight: “(raft)”.
- **Terrains:** every room has one: `terrain`, or `'water'` / `'air'` from those shorthands, else `'land'`. The world’s `onFoot` (default `['land']`) lists those the player walks on. A vehicle’s `travels` is a terrain name or list (`['land', 'sand']`); the old `'water'`, `'air'` and `'none'` still work (`'none'` is `[]`: it never moves). Its `restsOn` (default `['land']`, unless it travels on land) are the terrains it comes to rest on from one it travels, and it can’t cross from one to another.
- **Moving:** on foot, a room’s terrain must be in `onFoot`, else “You can’t go there without a vehicle.” Aboard, the destination’s terrain must be in `travels`, or in `restsOn` while you’re on a terrain in `travels`, else “You can’t go there in a raft.” (a vehicle won’t go overland). The vehicle goes wherever you go, scripted moves included, and you stay aboard.
- **Landing:** `landing` (the same forms as `leave`) is said as the vehicle comes onto a `restsOn` terrain from a traveled one you can’t walk on (`landing: 'The balloon lands.'`). Unset, a water vehicle says Zork’s “The raft comes to a rest on the shore.” and a blank line; others say nothing.
- **`leave` / `arrive`:** said as it leaves with you aboard (before the new room) and as it arrives (after), and by `{ moveVehicle }`. `leave` is worked out in the room being left (a script’s `ctx.room()` is the origin, and its draw comes before any grue draw), once the move is known to be allowed. `arrive` and `landing` are worked out in the new room. Each of the three is a string, a list (one line picked with the seeded generator; a plain string draws nothing), or `{ script: 'name' }` (that script’s `say` lines print; its other steps don’t run). A script’s draws from the generator are kept, unlike a description script, which restores the seed. The audit runs each script once and flags any step that isn’t a `say`. Example: a dune buggy over a sand maze is `vehicle: { travels: ['land', 'sand'], leave: ['The engine roars.', 'Sand sprays.'] }` with the maze rooms `terrain: 'sand'`.
- **Aboard:** DROP puts things in the vehicle, TAKE *vehicle* says “You’re inside of it!”, and the room’s things stay in reach. The vehicle’s rules are asked before the room’s (Zork’s M-BEG): an `instead.go` on it can refuse directions. Its `onEnd` runs in place of the room’s. GO goes through rules too, so a room can have `instead.go` rules.
- **Looking:** the header names the vehicle (“Pond, in the raft”); the vehicle isn’t listed, its contents are; in Infocom style the room’s things are “(outside the raft)”, as Zork’s PRINT-CONT does. A vehicle’s `lookScript` (`vehicle: { travels: 'air', lookScript: 'basketLook' }`) describes it from inside: its `say` lines follow the room’s description, and the name on a brief arrival, but not a room whose own `descriptionScript` described it in full (Zork’s vehicle M-LOOK, which a room’s M-LOOK cuts off).
- Dying takes you out of the vehicle, which stays where you died. Conditions `aboard`, `aboard:ITEM`, `water:here|ROOM` and `terrain:NAME[:here|ROOM]`; effects `{ board }` and `{ disembark }`; script helpers `ctx.aboard()`, `ctx.water(room?)` and `ctx.terrain(room?)`.
See the [raft recipe](https://mrballistic.github.io/brass-lantern/guide/building-worlds/recipes#a-raft-on-a-pond).
## Capture
```ts
capture: { if: '!flag:quiet', script: 'echo' },
```
A room’s capture, then the world’s, sees each command of a line before it’s parsed, while its `if` holds. The script reads `ctx.line` and returns steps to take it, or nothing to let it parse as usual. Add `{ free: true }` for a reply that takes no time.
It also sees commands that arrive already parsed (AGAIN, OOPS, an answer to a question, the intent server’s reading), with `ctx.line` unset and `ctx.action` holding the command, so a limit like a spirit’s can’t be slipped past. A capture that only cares about raw words returns nothing when `ctx.line` is unset.
- Taking a command ends the line: the rest is dropped, as Zork’s Loud Room drops it.
- It runs ahead of the intent server, so captured input is never sent to the LLM.
- SAVE, RESTORE, UNDO and the other store commands come first, so a capture can’t trap the player; it never runs once the game is over.
- A capture that declines changes nothing, even if it rolled the dice.
Zork uses it twice: the Loud Room, which hears everything as noise until you say ECHO, and a spirit’s limits (DEAD-FUNCTION) after death. See the [listening room recipe](https://mrballistic.github.io/brass-lantern/guide/building-worlds/recipes#a-room-that-listens).
## Dialogue
```ts
dialogue: {
gary: {
default: '“Has anyone seen my mug?”',
'flag:gary_happy': '“Thanks for the mug.”',
'flag:gary_happy & has:stapler': '“Careful with that stapler.”',
},
}
```
`default` plus any number of condition keys. TALK TO uses the **last** key whose condition holds, so order them from least to most specific.
## Ambient
| Field | Type | |
|---|---|---|
| `if` | condition | |
| `every` | number | Turns between interruptions. A turn is a command the engine acted on. |
| `lines` | string[] | Printed in rotation. |
## Finale
Smashing `item` in `room` while carrying `with` ends the game: `event`, then each matching `epilogue` event in order, then the score and rank, then `footer`.
| Field | Type | |
|---|---|---|
| `room` | room ID | |
| `item` | item ID | |
| `with` | item ID | The tool. |
| `event` | event | |
| `epilogue` | `{ if, then }[]` | Checked after `event` runs, so flags it sets count. |
| `footer` | event | |
| `bareHanded?` | event | One-shot, for smashing `item` without the tool. |
| `bareHandedAgain?` | string | Later bare-handed attempts. |
| `wrongRoom?` | string | Smashing it with the tool somewhere else. |
---
Source: https://mrballistic.github.io/brass-lantern/reference/conditions-and-events
# Conditions and events
## Conditions
Conditions are strings, used by `requires`, exits (`if`, `denials`), room `descriptions`, `onEnter`, rules (`instead`, `after`, `onUse`), dialogue keys, hints, scoring, daemons, the finale’s epilogue and ambient lines. One parser handles all of them. A missing or blank condition always holds, so a trigger (`onEnter` and the like) may leave out `if`.
| Condition | True when |
|---|---|
| `flag:NAME` | the flag is set |
| `has:ITEM` | the item is in the inventory |
| `held:ITEM` | the item is carried at any depth: directly, or inside something carried (Zork’s HELD?). `has:` means carried directly |
| `in:ROOM` | the player is in that room |
| `visited:ROOM` | the player has been there |
| `inside:ITEM:PLACE` | the item is directly in PLACE: a room, another item, or `player` |
| `open:ITEM` | the container or door is open |
| `locked:ITEM` | it’s locked |
| `on:ITEM` | it’s switched on |
| `here:ITEM` | the player can reach it (in the room, carried, or in something open) |
| `var:NAMEN` | a numeric variable compared with `=`, `<`, `>`, `<=` or `>=` (unset is 0) |
| `carryingN` | how many things the player holds directly |
| `target:ID`, `indirect:ID` | that slot of the command being run resolved to that ID (`player` for ME and MYSELF, and SELF or YOURSELF when nothing here is called that); false otherwise |
| `direction:DIR` | the direction typed in `PUSH X NORTH` (compass, `up`, `down`), or, in an `orders.go` rule, the place the character was told to go, as typed: “milton, go to the basement” is `direction:basement`. Any lowercase word passes the audit |
| `number:N`, `numberN` | the number typed in the command being run (`TURN DIAL TO 4`, `SET DIAL TO 776`); false when the command has none. A rule with `with: 'number'` matches that command |
| `said:WORDS` | the words typed after a text verb (`target: 'text'`, e.g. `ANSWER A WELL`), compared as lowercase whole words with punctuation and quotes ignored; false when the command has none |
| `heaviestN` | the weight of the heaviest thing the player holds directly, counting what’s inside it (Zork’s narrow passage: `heaviest<=4`) |
| `scoreN` | the score, as SCORE reports it (Zork wins at `score>=350`); a `scoring` entry can’t test it |
| `lit:here`, `lit:ROOM` | the room has light |
| `following:NPC` | the character is following the player (`{ follow }` set it; a character’s `follows` condition is separate) |
| `alive:NPC` | the character isn’t dead |
| `awake:NPC` | alive and conscious |
| `fighting:NPC` | in a fight with the player (and conscious) |
| `with:NPC` | in the player’s room (hidden or not) |
| `seen:NPC` | in the player’s room and not hidden |
| `aboard`, `aboard:ITEM` | the player is in a vehicle (that one) |
| `water:here`, `water:ROOM` | the room is water now |
| `terrain:NAME`, `terrain:NAME:ROOM` | the room (default: the player’s) is that terrain now: `land`, `water`, `air`, or one of the world’s own |
| `!…` | negates any of the above |
| `a & b` | every part holds: `in:break_room & !flag:lunch_freed` |
There’s no “or”. Write two rules, or two dialogue keys, instead. An unrecognized condition is false in play. `auditWorld` reports it, and a condition naming an item or room that doesn’t exist, in rules, triggers, exits, `requires`, daemons, hints and scoring (it doesn’t check dialogue keys, ambient lines or room descriptions).
## Events and effects
An event is a named list of steps, run in order. A string is printed. An object is an effect:
| Effect | Does |
|---|---|
| `{ say: 'text' }` | Prints, like a plain string. |
| `{ set: 'flag' }`, `{ clear: 'flag' }` | Turns a flag on or off. |
| `{ move: 'item', to: 'room' }` | Moves an item to a room, `'player'`, `'here'` (the player’s room), another item, a character, or `null` (offstage). |
| `{ moveNpc: 'npc', to: 'room' }` | Moves a character, or `null` (gone). |
| `{ follow: 'npc' }`, `{ unfollow: 'npc' }` | Sets or clears the character’s `following` state (`npcs..following` in the game state; no flag): the character then goes where the player goes (GO, doors, ENTER, CLIMB; not scripted moves), like a `follows` condition on the character. |
| `{ npcState: 'npc', fighting?, staggered?, strength?, hidden?, scenery? }` | Sets a character’s combat state, hides and reveals it, or (`scenery`) keeps it out of the room’s list and puts it back (Zork’s NDESCBIT in play). |
| `{ script: 'name', arg? }` | Runs one of the world’s [scripts](https://mrballistic.github.io/brass-lantern/reference/world-schema#scripts) and the steps it returns. |
| `{ hide: 'item' }`, `{ reveal: 'item' }` | Hides an item where it is (not seen, listed or taken), or shows it again. |
| `{ board: 'item' }`, `{ disembark: true }` | Puts the player in a vehicle that’s in the room, or takes them out. |
| `{ touch: 'item' }` | Marks an item handled (Zork’s TOUCHBIT): its first-seen sentence is over. |
| `{ unlist: 'item' }`, `{ relist: 'item' }` | Keeps an item where it is, seen and usable but out of the room’s list, or lists it again (the tied rope). |
| `{ open }`, `{ close }`, `{ lock }`, `{ unlock }` | Changes a container’s or door’s state. |
| `{ switch: 'item', on: true }` | Switches a light (or anything switchable). |
| `{ add: 'var', by: n }`, `{ setVar: 'var', to: n }` | Changes a numeric variable. |
| `{ setVar: 'var', from: 'number' }` | Sets it to the number typed in the command (0 if none). |
| `{ score: n }` | Adds to the score. |
| `{ go: 'room' }` | Moves the player there and describes it. With `quiet: true`, without describing it (Zork’s mirror). |
| `{ look: true }` | Describes the player’s room in full, as LOOK does. |
| `{ unvisit: 'room' }` | Forgets the player has been there, so the next arrival shows the full description (Zork clears TOUCHBIT when the dam drains). |
| `{ schedule: 'event', in: n }`, `{ cancel: 'event' }` | Runs an event after `n` turns, or stops it. |
| `{ chance: 80, then: [...], else: [...] }` | Picks a branch at random (from a seeded generator, so saves replay exactly). |
| `{ if: 'condition', then: [...], else: [...] }` | Picks a branch by a [condition](#conditions). `else` is optional. |
| `{ stopLine: true }`, `{ stopLine: 'text' }` | Drops the rest of the command line (Zork’s P-CONT). The text, if any, is said only if commands were left. |
| `{ moveVehicle: 'item', to: 'room' }` | Moves a vehicle to a room. If the player is aboard they arrive with it, as on any arrival; otherwise its `leave` and `arrive` lines are said when the player sees it go or come. It isn’t a move the player makes, so followers stay behind. |
| `{ free: true }` | The turn takes no time: no move, no timers or daemons (a capture’s echo). |
| `{ noDarkLine: true }` | A line already said the light went out, so the engine doesn’t add its own. |
| `{ run: 'event' }` | Runs another event here. |
| `{ die: 'cause' }` | Kills the player. See [Death](https://mrballistic.github.io/brass-lantern/reference/world-schema#death). Nothing after it runs. |
| `{ end: 'ending' }` | Plays an ending. See [Endings](https://mrballistic.github.io/brass-lantern/reference/world-schema#endings). Nothing after it runs. |
Effects print nothing unless they say so. An effect naming something that doesn’t exist does nothing in play, and `auditWorld` reports it. It also checks the events named by rules, `onEnter`, `onTake`, `onWear`, `onSmash`, `onGive`, daemons and the finale.
### Templates
`{var:NAME}` (the variable, 0 when unset) and `{number}` (the number typed in the command; left as written when there is none) fill in when a line is printed: event lines, descriptions, and an item’s `initialDescription` and `roomDescription` wherever the engine lists it (in the room, in a container or on a surface, or when opening a container shows it):
```ts
vars: { tally: 3 },
items: {
tally: { name: 'tally board', description: 'Chalk marks.', portable: false, tags: [], roomDescription: 'A tally board on the wall reads {var:tally}.' },
},
```
```
> look
📍 Hall
A hall. The study is north.
A tally board on the wall reads 3.
```
### Bracket lines (the older form)
Some lines are printed **and** change the game. They still work, and in an Infocom-style world they act without being shown:
| Line | Effect |
|---|---|
| `[Flag set: Gary is happy]` | Sets the flag `flagLabels['gary is happy']` names. An unmapped label does nothing, so test for it. |
| `[Added to inventory: badge]` | Gives the player the item whose `name` is “badge”. |
| `[Badge consumed]` | Removes the item whose `name` is “badge” from the inventory. |
Facts worth knowing:
- **Events from `onEnter`, `onTake`, `onWear`, `onSmash` and the finale’s `bareHanded` fire once per game.** Events from a use rule’s `then` and from `onGive` run every time the rule matches, so guard them with a `!flag:` condition if they should happen once.
- **Bracket lines only turn flags on.** To turn one off, use the `{ clear: 'flag' }` effect.
- **Item lines match display names**, not IDs. To upgrade an item, consume the old one and add the new: `[Lamp consumed]`, then `[Added to inventory: lit lamp]`.
- **`intro`** plays when a new game starts. A chapter break is just a line, such as `✨ CHAPTER 2: THE AFTERNOON`.
## How lines are styled
Every line the player sees is classified by how it starts, which sets its look and typewriter speed:
| Starts with | Style | Use it for |
|---|---|---|
| `📍` | room header | added by the engine; don’t start your own lines with it |
| `💼 🌀 👔 💕 💻 💾 🔨 💥 📎 ✨ 🪄 🤜 😖 😴 🐟 🌺 📬 📞` | scripted moment | events (18ms/char) |
| `═` or `“` | banner, narration | 12ms/char |
| `[` | system | flags, inventory, hints, score (instant) |
| anything else | prose | descriptions, replies (10ms/char) |
A line starting with an emoji that isn’t in the list renders as prose. The set is fixed in this version, so pick from the list for scripted moments.
**Copy style:** the built-in replies use curly quotes and apostrophes (“ ” ’). Your world will read best if it does too.
---
Source: https://mrballistic.github.io/brass-lantern/reference/commands
# Player commands
The built-in verbs are fixed; a world gives them things to act on, and can add verbs of its own. Anything the regex parser doesn’t recognize, or recognizes but can’t act on, can go to the [intent server](https://mrballistic.github.io/brass-lantern/guide/intent-server), which maps loose phrasing onto these.
| Command | Also | Notes |
|---|---|---|
| GO *place* | `n` `s` `e` `w` `ne` `nw` `se` `sw` `u` `d` `in` `out`, `walk/head/run/move to …`, a bare exit label | Matches the room’s exit labels. |
| ENTER [*place*] | `go into` | An exit by name, the way in, or the exit through a door you name. |
| CLIMB [*thing*] | `climb up`, `climb down` | Up, or the room’s `climb` exit. |
| LOOK | `l` | Describes the room again. |
| TAKE *item* | `get` `grab` `pick up` | |
| DROP *item* | `put down` `leave` | |
| TAKE ALL, DROP ALL, PUT ALL IN / ON *thing* | `everything`; `… but X and Y`, `… except X, Y` | One line per thing: “lamp: Taken.”. TAKE ALL takes what’s in reach and not inside something you carry (in Infocom style, what’s directly in the room, with a reason for anything that can’t be taken). |
| EXAMINE *thing* | `x` `inspect` `look at` | Items and people, and what’s inside or on an item. In the dark you can’t examine people either (“It’s too dark to see.”). |
| FOLLOW *person* | | Bare FOLLOW asks what to follow. With no rule of the world’s, a person (say, Floyd) gets “You’d rather Floyd came to you. Try FLOYD, FOLLOW ME.” and a thing “You can’t follow that.” To bring someone along, order them: *person*, FOLLOW ME. See [FOLLOW](https://mrballistic.github.io/brass-lantern/reference/world-schema#follow). |
| READ *thing* | | The item’s text. |
| OPEN / CLOSE *thing* | `shut` | Containers and doors. |
| LOCK / UNLOCK *thing* WITH *key* | | |
| PUT *item* IN / ON *thing* | `insert`, `place`, `set` | Into an open container with room, or onto a surface. UNDER and BEHIND are asked of the world’s rules (in Infocom style, otherwise “You can’t do that.” / “That hiding place is too obvious.”). |
| TAKE *item* FROM *thing* | `get … out of`, `remove … from` | |
| LOOK IN *thing* | `search` | What’s inside. |
| TURN ON / OFF *thing* | `switch on`, `light`; `extinguish`, `douse`, `blow out`, `put out` | Switchable items. LIGHT on something already burning with no switch (a torch) says “It’s already lit.” |
| BURN *thing* WITH *item* | `light … with`, `burn down`, `ignite`, `incinerate` | Something burnable, with something burning. The thing’s rules answer first (lighting candles with a match). |
| TURN *thing* WITH *tool* | `to`, `for`; SET *thing* TO *x* | A rule on the thing decides; otherwise “This has no effect.” TURN ON … WITH … is TURN ON. The second object can be a number: TURN DIAL TO 4, SET YEAR TO 776 (digits up to 1000, or H:MM); with no rule for it, that answers “This has no effect.” in Infocom style, and elsewhere the intent server gets a turn. Digits that name something here (locker 12) are that thing, not the number. |
| PLUG *thing* WITH *item* | | The same: a rule, or “This has no effect.” |
| BOARD *vehicle* | `get in`, `climb in`, `sit in` | Into a vehicle on the ground here. See [vehicles](https://mrballistic.github.io/brass-lantern/reference/world-schema#vehicles). |
| DISEMBARK [*vehicle*] | `get out`, `get off`, `stand` | Out again, if it’s safe. EXIT on its own does this while you’re aboard, and is a direction (out) otherwise. |
| USE *item* [ON *thing*] | `push` `pull` `press` `operate` `attach X to Y` | See [use rules](https://mrballistic.github.io/brass-lantern/reference/world-schema#userule). OPEN and PUT fall back to an item’s use rules when it isn’t a container. |
| GIVE *item* TO *person* | `hand` `offer` `return` | With one person present, GIVE *item* is enough. `GIVE
- ` works too (`GIVE LUMBERGH THE REPORT`). |
| TALK TO *person* | `speak/chat with`, `question` | With one person present, TALK is enough. |
| ASK *person* ABOUT *topic* | `tell … about …` | The person’s answer on that topic, if the world gives it [topics](https://mrballistic.github.io/brass-lantern/reference/world-schema#npc); otherwise what TALK TO says. ABOUT ME and ABOUT MYSELF reach a topic keyed or aliased `me` or `myself`. |
| *person*, *command* | `tell/order/ask … to …` | An order (a bare TELL *person* is one too). *person*, FOLLOW ME is one too, answered by the character’s `orders.follow` rules. A character the world lets obey carries out GO, TAKE, DROP and GIVE ME, or answers a rule (“robot, push the button”); others answer or ignore it. An order to such a character ends the rest of the line. |
| WEAR *item* | `put on` | A thing in sight but not held is taken first: (first taking the shirt). |
| SMASH *thing* [WITH *item*] | `break` `destroy` `wreck` `whack` `beat` | |
| ATTACK *someone* WITH *weapon* | `kill` `hit` `fight` `stab` | At a character who fights, combat; at anything else, SMASH (in a world without combat). In Infocom style, `kill troll` picks the one weapon you hold, or asks. |
| THROW *item* [AT *target*] | `toss` `hurl`; OFF, OVER | A rule on the target decides; otherwise it lands on the floor. OFF and OVER, with no rule: Zork’s refusal in Infocom style; elsewhere the intent server gets a turn. |
| PUSH *thing* *direction* | PUSH *thing* TO *x*; READ *thing* THROUGH *x* | Only a world’s rules answer these (otherwise “You can’t push things to that.” in Infocom style; elsewhere the intent server gets a turn); READ THROUGH reads it. |
| DIAGNOSE | | Your wounds, and how much more you could take. |
| WAIT / SIT | `z`, `sit down` `relax` | Takes a `wait` / `sit` exit if the room has one. |
| INVENTORY | `i` `inv` | |
| HINT | `hints` `clue` | |
| VERBOSE / BRIEF / SUPERBRIEF | | Full descriptions always, on first visits only, or never (LOOK still shows them). Takes no game time. |
| SCORE | | |
| AGAIN | `g` | Repeats the last command, meaning the same things. |
| OOPS *word* | | Replaces the word nobody understood in your last line, and tries it again: `examine lanturn`, then `oops lantern`. |
| UNDO | | Takes back the last move, up to 50 moves. Not kept across a reload, a RESTART or a RESTORE. Takes no game time. |
| QUIT | | Prints the world’s `quit` reply; the game carries on. |
| SAVE [*name*] | | Saves the game under a name (`save before the troll`). Without a name, asks for one. Names are lowercase letters, digits, spaces, `-` and `_`, up to 32. |
| RESTORE [*name*] | | Goes back to a named save. Without a name, lists them and asks which. |
| LOAD | | Goes back to the automatic save, which is kept after every move. |
| RESTART | | Wipes the automatic save and starts over. Named saves are kept. |
| SCRIPT / UNSCRIPT | | Starts a transcript, then downloads it as a text file. |
| VERSION | | The app’s version, then the world’s title and credits. |
| THEME [*name*] | | Lists the color themes, or switches to one (`crt-amber`, `crt-green`, `simple`, `simple-light`, `simple-dark`, plus any the game adds). Remembered in the browser. Takes no game time. Works at the cartridge menu and in story files too, like BLOOM and EFFECTS. |
| BLOOM ON / OFF | | Turns the phosphor glow on or off. |
| EFFECTS ON / OFF | | Turns every screen effect on or off. |
| COOKIES | `privacy` | Analytics settings, when analytics are configured. |
| EJECT | | Back to the cartridge menu (builds with more than one cartridge). |
| LOAD (at the menu) | `open`, or drop a file on the terminal | Play a Z-machine story file from your computer. In a native world, LOAD restores your save instead. |
| REMOVE *number* (at the menu) | `forget` | Take a story you loaded off the shelf. |
| PLAY | | Start a story file again after it ends. |
| CANCEL | | At a SAVE or RESTORE prompt, or a story file’s. |
| HELP | `?` | |
**World verbs:** a world can add its own (SNOOZE, PRAY, MOVE, Zork’s ULYSSES …); they’re listed in its HELP. See [World verbs](https://mrballistic.github.io/brass-lantern/reference/world-schema#world-verbs).
**Typed words:** a world’s SAY, ANSWER or INCANT (see [World verbs](https://mrballistic.github.io/brass-lantern/reference/world-schema#world-verbs)) takes the rest of the line, quoted or not: `answer “a well”`. A quoted phrase is never split at its full stops, commas or `and`, and the text verb ends the line: `say "well". west` says “well” and drops WEST, as in Zork.
**ME:** `me` and `myself` mean you where a thing is expected, and so do `self` and `yourself` unless something here is called that. In an order, “robot, give me the key” hands it to you, and “robot, push yourself” means the robot. A world decides what, if anything, happens; with nothing to say, the reply is the usual one for a word that names nothing here (“You don’t see a “me” here.”).
**Chaining:** `take key and wallet`, `north then look`, `west. take lamp.` Each piece runs separately (and gets its own intent-server retry if it misses). A name that contains “and” stays whole: in a world where “lost and found” is a thing’s name or one of its aliases, `take flair from lost and found and go north` is two commands, not three. Words that only appear in a description don’t count.
**Pronouns:** `it`, `them` and `that` mean the last thing you acted on, as in `take the mug then give it to gary`; `him` and `her` mean the last person.
**Names:** every word of three or more letters you type has to be in the thing’s name or one of its other words: `take red ball` doesn’t find a thing the world calls only “ball”. Shorter words are ignored, and a word can be shortened (`lant` for lantern). In brass style a close misspelling of a word in the name matches too (`lunberg` for Lumbergh). See [How names are matched](https://mrballistic.github.io/brass-lantern/guide/building-worlds/#how-names-are-matched).
**Questions:** when a word matches more than one thing, the game asks which (“Which do you mean: the wooden door or the trap door?”, or in Infocom style “Which door do you mean, the wooden door or the trap door?”), and when a verb is missing its object, what (“What do you want to take?”). Answer with just the missing words (`trap`, `the sword`), or type a new command to move on. Answer BOTH (or ALL, EACH) to act on each, for TAKE, DROP and PUT; other verbs answer “One at a time: …?”. Questions take no game time, and answers are never sent to the intent server.
**Keys:** Up and Down step through your last 100 commands, keeping whatever you’d started typing. Enter on an empty line, or any letter, finishes the text that’s typing out.
---
Source: https://mrballistic.github.io/brass-lantern/reference/cartridges
# Cartridges and storage
## Cartridges
Cartridges are what you pass in `GameOptions.cartridges` (see [Using the library](https://mrballistic.github.io/brass-lantern/guide/using-the-library#every-option)). The types, `Cartridge`, `WorldCartridge` and `ZCodeCartridge`, are exported from both `@brass-lantern/engine` and `@brass-lantern/vue`.
**A native world:**
| Field | Type | Notes |
|---|---|---|
| `kind` | `'world'` | |
| `id` | string | Unique; part of the save key. |
| `title` | string | The menu and the header. |
| `world` | `World` | See the [world schema](https://mrballistic.github.io/brass-lantern/reference/world-schema). |
| `saveKey?` | string | Overrides the save key, e.g. to keep loading saves written under an older key. |
**A Z-machine story file:**
| Field | Type | Notes |
|---|---|---|
| `kind` | `'zcode'` | |
| `id` | string | Unique; part of the transcript key. |
| `title` | string | The menu and the header. |
| `story` | string | The file’s URL, relative to `GameOptions.storyBaseUrl` (default `/`), e.g. `stories/zork1.z3`. |
| `format` | string | Shown in the menu, e.g. `Z-machine v3`. |
Stories a player loads with LOAD become cartridges too, with `local: true` and an id like `local-r119-880429-bf44` (release, serial number, checksum). You don’t write those.
With one cartridge, the terminal boots straight into it: no menu, no EJECT, no LOAD. With more, it opens on the menu, and a reload goes straight back to the last cartridge if it has a game in progress.
## Browser storage
Everything is in the player’s browser, under `storagePrefix`:
| Key | What |
|---|---|
| `:save:` | A native world’s save, with up to 500 lines of history. Or the cartridge’s `saveKey`. |
| `:named:` | A native world’s named SAVE. |
| `:theme` | The player’s THEME, BLOOM and EFFECTS choices. |
| `:cartridge` | The last cartridge inserted. EJECT clears it, so a reload after EJECT shows the menu. |
| `:z::transcript` | A story’s screen, up to 500 lines, so a reload can redraw it. |
| `:z:auto:` | A story’s autosave, written every turn and cleared when it ends. |
| `:z:file:save::` | A named SAVE in a story. |
Stories loaded with LOAD are in IndexedDB, in a database named `:stories`.
The library stores nothing else. Anything your app keeps (an analytics consent answer, say) is its own: the demo site, for example, keeps its consent answer at `:analytics-consent` and, only after consent, an anonymous Google Analytics client ID at `:ga-cid` (and the session ID, `:ga-sid`, in sessionStorage).