@brass-lantern/mcp 0.0.1-stage → 2.3.1

package/dist/docs/pages/reference/cartridges.md

@@ -0,0 +1,47 @@
+# 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 |
+|---|---|
+| `<prefix>:save:<id>` | A native world’s save, with up to 500 lines of history. Or the cartridge’s `saveKey`. |
+| `<save key>:named:<name>` | A native world’s named SAVE. |
+| `<prefix>:theme` | The player’s THEME, BLOOM and EFFECTS choices. |
+| `<prefix>:cartridge` | The last cartridge inserted. EJECT clears it, so a reload after EJECT shows the menu. |
+| `<prefix>:z:<id>:transcript` | A story’s screen, up to 500 lines, so a reload can redraw it. |
+| `<prefix>:z:auto:<signature>` | A story’s autosave, written every turn and cleared when it ends. |
+| `<prefix>:z:file:save:<gameid>:<name>` | A named SAVE in a story. |
+
+Stories loaded with LOAD are in IndexedDB, in a database named `<prefix>: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 `<prefix>:analytics-consent` and, only after consent, an anonymous Google Analytics client ID at `<prefix>:ga-cid` (and the session ID, `<prefix>:ga-sid`, in sessionStorage).

package/dist/docs/pages/reference/commands.md

@@ -0,0 +1,79 @@
+# 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 <someone> <item>` 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.

package/dist/docs/pages/reference/conditions-and-events.md

@@ -0,0 +1,129 @@
+# 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:NAME<op>N` | a numeric variable compared with `=`, `<`, `>`, `<=` or `>=` (unset is 0) |
+| `carrying<op>N` | 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`, `number<op>N` | 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 |
+| `heaviest<op>N` | the weight of the heaviest thing the player holds directly, counting what’s inside it (Zork’s narrow passage: `heaviest<=4`) |
+| `score<op>N` | 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.<id>.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.