Preface

Sharpee is a parser-based interactive-fiction authoring system. You write a story in TypeScript; Sharpee gives you a world model, a parser, a library of standard actions, and a presentation layer, and turns your code into a playable game you ship to the web. The same story also runs as a plain text stream in a terminal. That form is how you will test your game as you build it, and it is the form a blind player’s screen reader or text-to-speech tooling ingests directly.

This book teaches you to author with Sharpee by building one story, Family Zoo, from a single room to a complete, shippable game. It grows the zoo one concept at a time, and every version of the code in these pages is real, compiled, and transcript-tested.

0.1 Two perspectives, one example

Interactive-fiction systems often keep two layers distinct: the language you write a story in, and the language the system itself is built from. Inform 7, for instance, lets authors write in readable natural-language syntax and drops to Inform 6 for lower-level work, a deliberate split that makes the authoring surface welcoming, with a deeper layer waiting when you need it.

Sharpee makes a different tradeoff: the story you write and the library you call are the same TypeScript. The cost is that there’s no gentle natural-language surface to start from; you’re writing code from line one. The benefit is that there’s no second language to learn when you want to see underneath. So this book carries both perspectives over a single running example, and you can move between them whenever you’re ready:

• The author’s perspective is the main narrative: building the zoo with Sharpee’s traits, actions, and messages as a ready-made vocabulary.
• The programmer’s perspective is a skippable deeper layer, the public API of the @sharpee/* library: the classes, methods, and types your author code is actually calling.

You can read the narrative straight through and ship a game without ever opening the deeper layer. Or you can follow both and come away understanding the library behind every line. The next chapter explains how to choose.

Introduction

Although this is a technical manual, it’s very personal to me. Interactive Fiction quite literally altered my life and DNA. I was in high school playing baseball and getting mostly average grades in the classes I liked and one day I accidentally stumbled into a room where two students were hovered over paper terminals: one playing Crowther and Woods’ Adventure (ADVENT), the other playing the MIT mainframe version of Zork (though the program was named DUNGEON).

I never returned to the baseball team or any other sport during the remaining two years of high school. Lightning had struck harder than the spider that transformed Peter Parker into Spider-Man.

Since that day I have off and on been very passionate about playing IF games and eventually even more passionate about building my own authoring system. That day also redirected my life towards a 40+ year career as a software engineer and architect from Milwaukee to Chicago.

Over the years I tried to dig into compilers and virtual machines, but that level of programming seemed to slip through my synapses, and I was never able to build anything useful. Add to that, my experience in the business world deepened my understanding of programming design patterns and architecture philosophy.

Then about three years ago ChatGPT arrived and later Claude. Generative AI allowed me to explore the concepts my previous capabilities had struggled to visualize. It didn’t do the work for me. It augmented what I already knew about software and about Interactive Fiction and created an environment where I could direct my ideas into that bucket list item, a new parser-based interactive fiction platform called Sharpee.

Sharpee owes its implementation to everyone that stands out in the Interactive Fiction community. From Crowther and Woods’, to the Infocom Implementors, to Graham Nelson, Andrew Plotkin, Emily Short, Mike Roberts, Kent Tessman, Jon Ingold, Tara McGrew, and so many more. I would not possess the domain knowledge without the entire community from Usenet to ifMud to intfiction.org.

With the IF domain knowledge and my software engineering experience I have been able to leverage Anthropic’s Claude to help design and create a working Interactive Fiction system in Typescript. This book is the first complete technical guide to building parser-based interactive fiction using Sharpee.

– David Cornelson

How to Read This Book

0.2 What kind of reader are you?

Sharpee has no natural-language authoring layer; you write TypeScript from Chapter 1. If that’s new to you, the primer there gets you going. Use this table to find your starting point:

Whichever you are, the two tracks below are how the book serves you.

0.3 Two tracks

This book has one spine and two depths. Pick the track that fits why you’re reading.

• Author’s Track: read the chapter bodies straight through. This is everything you need to build and ship the Family Zoo. Skip every “Under the Hood” box; you lose nothing required to finish the game.
• Programmer’s Track: read the chapter bodies and every “Under the Hood” box. The boxes form a guided tour of the public @sharpee/* library API behind the author’s code.

You can switch tracks at any time, and you can change your mind chapter to chapter. The narrative never depends on the boxes.

We use “track” for reading order. “Path” in this book always means an API or import path, never a way of reading.

0.4 The “Under the Hood” box

Whenever the author code uses a piece of the Sharpee library, an Under the Hood box shows the public surface of what was used: the class, its constructor, the relevant methods and types. It shows signatures only: never the implementation, never internal platform code, never anything you don’t get from the installed npm package. Here is the legend, and a live example:

class ContainerTrait implements ITrait {
  constructor(data?: Partial<ContainerTrait>);
  capacity?: {
    maxWeight?: number;
    maxVolume?: number;
    maxItems?: number;
  };
  isTransparent: boolean;
  enterable: boolean;
}

If you’re on the Author’s Track, that box was safe to skip; the chapter body already told you the player can carry things. If you’re on the Programmer’s Track, you just saw the exact class behind it.

0.5 How the zoo grows

Every chapter advances the same story. The code arrives as chapter-named cumulative snapshots: ch02-first-room.ts is a single room, ch04-navigation.ts adds more rooms, and so on through the complete game. Each chapter’s code matches a real, compiled snapshot in the book’s companion repository, under tutorials/familyzoo/v2.0.0/src/; browse it on GitHub at https://github.com/ChicagoDave/sharpee/tree/main/tutorials/familyzoo/v2.0.0/src. You don’t need to clone anything to read along; anything you read here, you can run. The one exception is Chapter 28, a read-along tour of the finished multi-file project: its code lives in the companion repository and is meant to be browsed there, not typed in.

0.6 Conventions

• Commands you type into the game are shown in a transcript block, prefixed >.

• TypeScript you write appears in fenced code blocks.

• Under the Hood boxes are the only place library signatures appear; author code in the body is always code you write.

• Chapters that add something playable end with a Try it (commands to type) and a Test it (the same ground as a transcript test for your suite; Chapter 2 introduces the mechanic, Chapter 29 completes it). Four more conventions do so much work in the chapters ahead that they have names. The chapters cite them by name, so when a listing leaves you unsure where its code goes (or whether it goes in at all), the name is your pointer back to this page.

• The import rule. The zoo grows in one file until late in the book, so imports accumulate. When a chapter shows an import, add only the names your file doesn’t already import; TypeScript rejects the same identifier imported twice.

• The placement rule. Unless a chapter says otherwise, new world-building code goes at the end of initializeWorld (before the player is placed), and new registrations go at the end of onEngineReady.

• The replacement rule. When a listing replaces an earlier one (an exits table, a scene), delete the old version rather than keeping both.

• The illustrative rule. Some listings show a shape without joining the zoo. You type a listing in only when the surrounding prose says to (“add this”, “type it in”, “create the file”, “goes in initializeWorld”). A listing framed as a supposition (“suppose”, “for example”, “to change how it looks”) or whose body is only comments is a shape to recognize, and the chapter says “nothing to type” wherever one could pass for real code.

1 Installing Sharpee: The CLI and Your First Project

Before you can build the Family Zoo, you need a working toolchain: Node.js, an editor, and the sharpee command. This chapter gets you from an empty folder to a built story in a handful of commands, and along the way explains the foundation the whole platform stands on.

1.1 Why Node and TypeScript?

Most interactive-fiction systems give you a purpose-built authoring language: Inform’s natural-language syntax, TADS’s bespoke object language. Sharpee takes a different path: a story is plain TypeScript that runs on Node.js, the same mainstream toolchain used across the web- and server-software world.

That’s a real trade-off. The cost is that you write actual code from the start; there’s no gentler English-like surface to ease in on. The payoff is everything that comes with a mainstream ecosystem:

• Real editors. Visual Studio Code (or any TypeScript-aware editor) gives you autocomplete, inline documentation, and will flag as you type.
• A type checker. TypeScript catches whole classes of mistakes, such as a misspelled property or the wrong kind of value, at compile time instead of mid-playthrough.
• The npm ecosystem. Installing Sharpee, or any other library, is one command, and the platform itself is just a package your story depends on.
• Ordinary tooling. Version control, testing, formatting: the things millions of developers already use work on a Sharpee story unchanged.

In short, the “platform” isn’t a separate application you launch. It’s a library you import. The rest of this chapter installs that ecosystem and the Sharpee command that drives it.

1.2 Working in a terminal

Every Sharpee command in this book is typed into a terminal, a text window where you enter commands and read their output. If you’ve never opened one, here’s where to find it:

• macOS: open Terminal (Applications → Utilities, or press ⌘-Space and type “Terminal”).
• Windows: open Windows Terminal or PowerShell from the Start menu.
• Linux: open your terminal emulator (often Ctrl-Alt-T).

You’ll see a prompt waiting for input. Type a command, press Enter to run it, and its output appears on the lines below. Throughout the book, a shaded block like this is one or more commands to type at that prompt:

node --version

Two you’ll lean on constantly: cd <folder> moves you into a folder (so cd my-game steps into the project you just made), and running a command with no arguments, plain sharpee, prints its help.

1.3 Installing Node and npm

Node.js is the runtime that executes your story; npm is its package manager, and it installs with Node, so you don’t fetch it separately. If you’ve done any modern JavaScript work you likely have both already; if not, install them once:

1. Go to nodejs.org and download the LTS (“Long-Term Support”) build for your operating system.
2. Run the installer and accept the defaults. (If you expect to juggle several Node versions, a version manager like nvm or fnm is a fine alternative, but the installer is the simplest start.)
3. Open a terminal and confirm both tools are on your path:

node --version    # want v18.0.0 or newer
npm --version

If each prints a version number, you’re set. npm is how you’ll install Sharpee next, and any other library a story ever needs.

1.4 Installing the CLI

Everything you do to a story, scaffold it, compile it, bundle it, goes through one command, sharpee. It ships in the @sharpee/devkit package; install it once, globally:

npm install -g @sharpee/devkit

Now sharpee is on your path. The platform itself (@sharpee/sharpee: the world model, parser, standard library, and presentation layer) is not installed globally; each story pulls it in as an ordinary dependency, so different stories can pin different platform versions.

1.5 Creating a story project

sharpee init scaffolds a new project. On its own it walks you through a short wizard (story title, package ID, author, description), each question defaulting to a sensible value (the directory name, your username, and so on). Pass -y to accept every default and scaffold in one shot, which is what we’ll do here:

sharpee init my-zoo -y
cd my-zoo
npm install

(Drop the -y if you’d rather answer the prompts yourself; the my-zoo argument just supplies the default for the first question.) init writes a small, complete starting point; npm install pulls down the platform it pins. After that you have:

my-zoo/
  src/
    index.ts        # a single starter file that hosts your story
  package.json      # pinned to the platform version devkit shipped with
  tsconfig.json     # TypeScript config, set up for Sharpee
  .gitignore        # ignores node_modules/, dist/, logs

src/index.ts is where the story lives. Right now it’s a starter stub; in the next chapter you’ll replace it with the first room of the zoo. The platform arrives prebuilt in node_modules, so there is no platform to compile; only your story.

1.6 Building the story

sharpee build

build compiles src/ and produces two artifacts you care about in dist/ (alongside TypeScript’s .d.ts declaration files):

• dist/index.js: your compiled story.
• dist/<id>.sharpee: a single zipped story bundle, the unit you hand to a client or share for distribution.

Whenever you change the story, sharpee build again. (If a build ever looks stale, delete dist/ and rebuild from a clean slate; build already checks that each step emits output, so a stale dist/ rarely survives a rebuild on its own.)

1.7 Playing it

A story bundle isn’t much fun to read as a .sharpee file; you want to play it. The simplest way is a self-contained web client. Add one to your project, then build:

sharpee init-browser   # adds the browser entry and its support files
sharpee build          # now also emits a web client → dist/web/

init-browser creates src/browser-entry.ts (the wiring file you’ll meet in Volume VII), a build-stamped src/version.ts, a browser/<package-name>.css stylesheet for your style overrides, and adds the browser runtime dependencies to package.json. If its output suggests running npm install, do so. One general note while you’re here: the CLI’s on-screen “next steps” hints can drift slightly between releases; when a hint and this book disagree, follow the book, whose flow every chapter builds on.

dist/web/ is a complete, static web page. Serve it with any static file server and open it in a browser:

npx serve dist/web

That’s the loop you’ll use throughout the book: edit src/, sharpee build, refresh the page, play.

Every snippet, online. As you work through the book, the full set of code snippets is browsable chapter by chapter, each step alongside the complete runnable file it builds up to, at sharpee.net/book-snippets.

1.8 The CLI at a glance

You’ve met most of these already; here’s the full set you’ll reach for as an author:

Run sharpee with no arguments any time to see this help summarized, and sharpee list to see which stories are registered.

1.9 A TypeScript primer

The chapters ahead are full of TypeScript, but they lean on only a handful of its features. If the snippets below read clearly, you have everything you need. The book introduces the rest in context, and your editor fills the gaps.

TypeScript is JavaScript with types. A type annotation, the : string part below, tells the compiler what kind of value something holds, so it can flag a mistake before you run anything:

const title: string = 'Willowbrook Family Zoo';
let turns: number = 0;

const declares a value that won’t be reassigned; let, one that will. You’ll rarely write the annotations by hand, since TypeScript infers most of them, but you’ll read them constantly.

Objects are bundles of named values, written { key: value }. In a type, a ? marks a property as optional:

const options = { isOpen: false, capacity: 10 };
// e.g. `capacity?: number` means capacity may be left out

Classes are templates you make instances of with new. Most of Sharpee’s building blocks, traits especially, are classes:

const light = new IdentityTrait({ name: 'flashlight' });

An interface is a contract. A class that implements an interface promises to provide everything the interface requires. Every Sharpee story is a class that implements the Story interface:

class MyStory implements Story { /* … */ }

Imports bring in code from other packages; exports hand yours out:

import { IdentityTrait } from '@sharpee/world-model';
export const story = new MyStory();

Functions can be written compactly as arrow functions, common in the short callbacks you’ll pass to the platform:

items.some(item => item.name === 'feed');

That’s the working vocabulary. Don’t try to memorize it. You’ll absorb it by building the zoo, one chapter at a time.

1.10 Key takeaway

Sharpee stories are TypeScript on Node, so the toolchain is the mainstream one: install Node (which brings npm), then the CLI with npm install -g @sharpee/devkit. Scaffold a project with sharpee init, write your story in src/index.ts, compile and bundle it with sharpee build, and play it by adding a web client (sharpee init-browser) and serving dist/web/. The Sharpee platform has everything you need to create an interactive fiction story.

2 Your First Room: Entities, Traits, and the World

You’re standing at the entrance to the Willowbrook Family Zoo. There’s a welcome sign and a ticket booth. You can look around and examine things, but there’s nowhere to go yet.

That’s it: one room, two things to look at. This is the simplest possible Sharpee story, and it’s where the Family Zoo begins. By the end of this chapter you’ll have a game you can play.

2.1 The Story interface

Every Sharpee story is a TypeScript class that implements the Story interface. The engine calls your class’s methods during startup to build the world. Three things every story must provide:

1. config: metadata such as the story’s title, author, version, and ID. The engine shows this as a banner when the game starts.
2. The createPlayer(world) method creates the player character. The engine calls this first. You create an entity, attach traits, and return it.
3. The initializeWorld(world) method builds the world, including: rooms, objects, connections. The engine calls this after createPlayer.

There are optional methods too (extendParser, extendLanguage, onEngineReady, and others), but a basic story needs none of them.

interface Story {
  config: StoryConfig;
  initializeWorld(world: WorldModel): void;
  createPlayer(world: WorldModel): IFEntity;
  // optional:
  getCustomActions?(): any[];
  getCustomVocabulary?(): CustomVocabulary;
  extendParser?(parser: Parser): void;
  isComplete?(): boolean;
}

2.2 Entities and traits

Everything in a Sharpee game is an entity: rooms, objects, characters, doors, even the player. An entity by itself is just an empty shell with an ID. You make it useful by attaching traits: components that answer “what is this thing?” and “what can it do?”

You create entities with world.createEntity(name, type). The type is a hint to the engine: EntityType.ROOM, EntityType.ITEM, EntityType.ACTOR, EntityType.SCENERY, and so on.

In this version we construct four traits, and import a fifth for later:

• IdentityTrait: a name, description, and aliases. Almost every entity has one. The description is what examine shows; the aliases are the alternative words the parser will accept. (Curly braces in a description are ordinary text; Chapter 5 introduces the one opt-in exception.)
• ActorTrait: marks an entity as a character. isPlayer: true tells the engine this is the player.
• ContainerTrait: lets an entity hold other entities. The player needs it to carry an inventory.
• RoomTrait: marks an entity as a room, with exits and a darkness flag.
• SceneryTrait: marks an entity as fixed, so the player can examine it but not take it. This chapter’s scenery gets its fixedness from EntityType.SCENERY alone, so the trait isn’t constructed here; it sits in the import block because Chapter 5 puts it to work.

2.3 The shape of the file

Before the methods, the top of the file: the imports, the config, and the class that holds everything. Every symbol the story uses comes from one of two packages: @sharpee/engine (the Story contract and StoryConfig) and @sharpee/world-model (the world, entity types, and traits).

import { Story, StoryConfig } from '@sharpee/engine';
import {
  WorldModel,
  IFEntity,
  EntityType,
} from '@sharpee/world-model';
import {
  IdentityTrait,
  ActorTrait,
  ContainerTrait,
  RoomTrait,
  SceneryTrait,
} from '@sharpee/world-model';

const config: StoryConfig = {
  id: 'familyzoo',
  title: 'Family Zoo',
  author: 'Sharpee Tutorial',
  version: '0.1.0',
  description:
    'A small family zoo: Learn Sharpee one concept at ' +
    'a time.',
};

class FamilyZooStory implements Story {
  config = config;

  // createPlayer(world)     - fills in next
  // initializeWorld(world)  - and after that
}

The two methods below are members of this FamilyZooStory class; they go where the comments are. We’ll write each one, then assemble the whole file at the end.

The scaffolded src/index.ts isn’t written exactly like the file we build here, but both are valid. The stub imports Story and StoryConfig from @sharpee/sharpee (a convenience barrel that re-exports the engine, world model, and parser as one package), where the book imports them from @sharpee/engine directly; the two names refer to the same types. The stub also defines the story as a plain object literal (export const story: Story = { config, createPlayer, … }) rather than a class. An object literal and a class instance satisfy the Story interface identically. We use the class form throughout the book because it gives the two methods a natural home and reads well as the story grows. Either style works; pick one and stay consistent.

2.4 Creating the player

The engine calls createPlayer first. Inside the class, you build the player like any other entity: create it, add traits, return it.

createPlayer(world: WorldModel): IFEntity {
  const player = world.createEntity('yourself', EntityType.ACTOR);

  player.add(new IdentityTrait({
    name: 'yourself',
    description: 'Just an ordinary visitor to the zoo.',
    aliases: ['self', 'myself', 'me'],
    properName: true,
    article: '',
  }));

  player.add(new ActorTrait({ isPlayer: true }));

  player.add(new ContainerTrait({
    capacity: { maxItems: 10 },
  }));

  return player;
}

The ContainerTrait is what makes take and inventory work. Without it, the player has nowhere to put anything.

class ContainerTrait implements ITrait {
  constructor(data?: Partial<ContainerTrait>);
  capacity?: {
    maxWeight?: number;
    maxVolume?: number;
    maxItems?: number;
  };
  isTransparent: boolean;
  enterable: boolean;
}

2.5 Building the world

initializeWorld runs after the player exists. Create a room, give it a RoomTrait and an IdentityTrait, then add some scenery.

initializeWorld(world: WorldModel): void {
  const entrance = world
    .createEntity('Zoo Entrance', EntityType.ROOM);

  entrance.add(new RoomTrait({ exits: {}, isDark: false }));
  entrance.add(new IdentityTrait({
    name: 'Zoo Entrance',
    description:
      'You stand before the gates of the Willowbrook Family ' +
      'Zoo. A cheerful welcome sign arches over the entrance, ' +
      'and a small ticket booth sits to one side.',
    aliases: ['entrance', 'gates', 'gate'],
    article: 'the',
  }));

  const sign = world
    .createEntity('welcome sign', EntityType.SCENERY);
  sign.add(new IdentityTrait({
    name: 'welcome sign',
    description:
      'A brightly painted wooden sign welcomes you to ' +
      'the zoo.',
    aliases: ['sign', 'wooden sign'],
    article: 'a',
  }));

  const booth = world
    .createEntity('ticket booth', EntityType.SCENERY);
  booth.add(new IdentityTrait({
    name: 'ticket booth',
    description:
      'A small wooden booth with a sliding glass window. A ' +
      'sign in the window reads "Self-Guided Tours / No ' +
      'Ticket Needed Today!"',
    aliases: ['booth', 'ticket booth', 'window'],
    article: 'a',
  }));

  world.moveEntity(sign.id, entrance.id);
  world.moveEntity(booth.id, entrance.id);

  const player = world.getPlayer();
  if (player) world.moveEntity(player.id, entrance.id);
}

The ticket booth is built exactly like the sign: an entity and an IdentityTrait for its name and description. Both are typed EntityType.SCENERY, so they stay put, and both are placed in the entrance; now examine booth in the “Try it” list has something to find.

2.6 Placing things

Creating an entity doesn’t put it anywhere. You place it with world.moveEntity(entityId, locationId), which puts the entity inside the location, whether that’s an object in a room, an item in a container, or the player in a room. Forget this step and the entity exists in the database but is invisible: the player can never reach it.

The player is no exception. world.moveEntity(player.id, entrance.id) is what sets the starting location.

2.7 Exposing the story

The two methods live inside the FamilyZooStory class from “The shape of the file.” The last piece is the bottom of the file: the engine loads your story from the module’s exports, so provide both a named story and a default. It then works however the module is loaded.

export const story: Story = new FamilyZooStory();
export default story;

The : Story annotation matters: it types story as the full Story interface, including the optional hooks like extendParser and extendLanguage you’ll add in later chapters. The browser client that sharpee init-browser generated in Chapter 1 checks for those hooks (if (story.extendParser) …), and under TypeScript’s strict mode that check only compiles if the type knows the hooks might exist. Without the annotation, story is typed as just FamilyZooStory, which doesn’t have them yet, and the browser build fails. Annotate the export and every chapter builds.

That’s the whole file: imports, config, the class with createPlayer and initializeWorld, and these exports.

2.8 Try it

> look                  See the room description
> examine sign          Read the welcome sign
> examine booth         Look at the ticket booth
> take sign             Can't, it's scenery ("fixed in place")
> inventory             Check what you're carrying (nothing yet)

2.9 Prove it: your first transcript test

Playing through the “Try it” list confirms the room works today. A transcript test confirms it still works after every change you’ll ever make, and you have twenty-nine chapters of changes ahead of you. A transcript is a plain-text file that reads like a play session: a small header, then each > line is a command and each [OK: …] line is an assertion checked against that command’s output.

Create a tests/transcripts/ folder in your project and save this as tests/transcripts/first-room.transcript:

title: First room
story: familyzoo
description: The entrance, the sign, and the booth respond

---

> look
[OK: contains "Zoo Entrance"]
[OK: contains "welcome sign"]

> examine sign
[OK: contains "brightly painted"]

> examine booth
[OK: contains "Self-Guided Tours"]

> take sign
[OK: contains "fixed in place"]

> inventory
[OK: matches /./]

The header’s three lines name the test; --- ends it. [OK: contains "…"] passes when the command’s output contains the text (matching is case-insensitive). Now run everything:

npx sharpee build --test

A word on the spelling: npx sharpee reaches the same CLI you installed in Chapter 1 (npx runs a project-local copy when one exists and falls back to the global install), so plain sharpee build --test works identically. The book writes the npx form for test runs so the command still works if you ever install the devkit locally instead of globally.

The build compiles the story, then replays every transcript it finds against a fresh copy of the game. The output below is trimmed to the part that matters; the real run also prints the build steps, absolute file paths, and a closing totals block:

Running: tests/transcripts/first-room.transcript
  "First room"

  > look                                             PASS
  > examine sign                                     PASS
  > examine booth                                    PASS
  > take sign                                        PASS
  > inventory                                        PASS

  5 passed

✓ All tests passed!

That’s the whole discipline. From here on, every chapter that adds something playable ends with a Test it block: one more file for this folder, a green suite before you move on. By the last page you’ll have a suite that plays the entire zoo, and the moment a future change breaks an earlier chapter’s behavior, a red line will point at exactly what stopped working. (Transcripts can also assert on events and world state, and chain into full walkthroughs; Chapter 29 covers all of that.)

2.10 Key takeaway

A Sharpee story is a class with a config, a player creator, and a world initializer. The world is made of entities with traits. Place everything explicitly, or it won’t exist.

3 The Play Loop: How a Turn Works

In the last chapter you built a room and played it: you typed a command, pressed Enter, and read a response. This chapter opens the hood on that exchange: what the engine does in the moment between the player’s keystroke and the next prompt. You won’t write any new code here. Understanding the loop is what makes everything after it make sense.

3.1 The loop

A running Sharpee story is a simple cycle, repeated until the player quits:

1. Show the player where they are and a prompt.
2. Wait for a typed command.
3. Run the turn: interpret the command and apply its effects.
4. Show the result.
5. Go back to step 2.

This is the play loop, and the engine provides it. You never write it; you supply the world it operates on. A “turn” is one trip through step 3, and that step has more going on inside it than it looks.

3.2 Anatomy of a turn

When the player types examine sign and presses Enter, the engine takes that line through a short pipeline. Each stage hands its result to the next.

3.2.1 Parse

The parser turns the raw text into a structured command: a verb and its noun phrases. examine sign becomes “the examining action, applied to something the player called sign.” At this point “sign” is just words; no particular object is attached yet.

3.2.2 Resolve scope

Next the engine matches those words to actual entities, and only the ones the player can currently perceive. This is scope: the welcome sign in the room resolves; an object locked in another room does not. Scope is also what lets the player call things by their aliases, the aliases you put on an IdentityTrait back in Chapter 2. If nothing matches, the turn ends right here with a “you can’t see any such thing” message.

3.2.3 Run the action: validate, execute, report

With a verb and a resolved object in hand, the matching action runs. Every action, the standard ones and any you write later, moves through the same phases:

• validate: can this happen? Is the sign here, and is it something you can examine? If not, the action is blocked and reports why.
• execute: change the world, if anything changes. (Examining changes nothing; taking moves an item into your hands.)
• report: record what happened.

Volume III, Making It Interactive, takes these phases apart in detail. For now, the shape (check, change, report) is all you need.

3.2.4 Events become text

Here’s the part that surprises newcomers: actions never print anything. Instead, the report phase emits events (small records of what happened), and each one carries a message id, not a finished sentence:

context.event('if.event.taken', {
  messageId: 'if.action.taking.taken',
  params: { item: 'brass key' },
});

(That snippet is illustrative; the zoo has no brass key. It just shows the shape of an event: a type, a message id, and parameters.)

If you come from web or app development, set one expectation aside: these are records first, not notifications racing off to listeners. They’re what the action reports, collected as the turn runs. (The world can react to them; Chapter 13 registers handlers with world.registerEventHandler. But rendering never depends on anyone listening.)

At the end of the turn the engine’s prose pipeline consumes the reported events: it looks each message id up in the language layer, fills in the message template’s placeholders, and renders the actual words the player reads.

Why the indirection? Because it keeps every player-facing word in one place. The same event can be rendered in another language, restyled in different prose, or suppressed entirely. When a room is dark, a “you see…” event is filtered out before it ever becomes text (that’s Light & Dark, later in Volume II). Volume V, Words, is devoted to that language layer.

3.2.5 Everyone else takes a turn

A turn isn’t only the player’s. Once the player’s action resolves, the rest of the world gets to move: NPCs act, and timed events (countdowns and background processes) tick forward. The zookeeper’s patrol and the parrot’s squawk in Volume VI happen here. Then the engine shows the turn’s result and returns to the prompt.

3.3 One turn, start to finish

Put it together with a single command in the one-room zoo from Chapter 2:

> examine sign

• Parse: the examining action, applied to “sign.”
• Scope: “sign” resolves to the welcome sign in the room.
• Action: examining validates (the sign is here and in scope), executes (nothing to change), and reports an event carrying the sign’s description.
• Text: the engine renders that event into the sign’s description, and it prints.
• Other actors: nothing else lives in this tiny world yet, so the turn ends.
• The prompt returns, and the loop comes back around.

Every command you type follows that same path, whether it’s look, take key, or a custom verb you invent ten chapters from now.

3.4 Key takeaway

A turn is a short pipeline: parse the text, resolve the words to objects in scope, run the matching action (validate → execute → report), turn the resulting events into text, then let NPCs and timed events move. The engine drives this loop; your job is to supply the world it runs on. Carry one idea forward above the rest: actions emit events, not text. The words are produced later, by the language layer, and that single separation is what makes a Sharpee story translatable, restylable, and able to stay quiet in the dark.

4 Rooms & Navigation: Exits Wired in Pairs

One room is a demo, not a game. In this chapter the zoo grows to four locations: the Zoo Entrance, a Main Path, a Petting Zoo, and an Aviary. The player can walk between them with compass directions: north, south, east, west.

Everything from the first chapter is still here. We’re adding rooms and the connections between them.

4.1 Exits live on the room

Rooms are connected through exits on the RoomTrait. Each exit maps a compass direction to a destination, which is just the ID of another room. The fragments in this section and the next are shapes to read, not code to type (the illustrative rule): entranceRoom stands for the entrance’s RoomTrait, which the .get() section below shows you how to fetch, and the complete listing at the end of the chapter wires every exit inline without that intermediate variable.

entranceRoom.exits = {
  [Direction.SOUTH]: { destination: mainPath.id },
};

Read that as: “when the player types south in the entrance, move them to the main path.” The Direction enum gives you all the standard IF directions: NORTH, SOUTH, EAST, WEST, UP, DOWN, the four diagonals, and IN / OUT. The parser already understands the short forms (n, se, and so on), so you never spell those out yourself.

4.2 Two rules that trip up everyone

Exits are one-way. This is the single most common beginner mistake. If the entrance has a south exit to the main path, the player can walk south, but they cannot walk back unless the main path also has a north exit to the entrance. Always wire exits in pairs:

entranceRoom.exits = {
  // entrance → path
  [Direction.SOUTH]: { destination: mainPath.id },
};
mainPathRoom.exits = {
  // path → entrance (the way back)
  [Direction.NORTH]: { destination: entrance.id },
};

Forget the return exit and the player gets stranded.

Create first, connect second. An exit needs its destination’s ID, and you can’t reference a room that doesn’t exist yet. So build every room with empty exits first, then wire the exits once they all exist.

4.3 Getting a trait back with .get()

In the first chapter we only ever added traits. To wire exits we need to read a trait back off an entity, which is what .get() does:

const entranceRoom = entrance.get(RoomTrait)!;
entranceRoom.exits = { /* ... */ };

The ! is a non-null assertion: “I know this room has a RoomTrait.” If you aren’t certain an entity has the trait, check instead of asserting:

const roomTrait = entrance.get(RoomTrait);
if (roomTrait) {
  roomTrait.exits = { /* ... */ };
}

4.4 First visits get their own prose

A room can carry two descriptions. The description on its IdentityTrait is the standing text: it prints every time the player looks or walks back in. The RoomTrait can also hold an initialDescription, and when it does, that text prints instead on the player’s first visit only. The distinction matters because arrival prose reads perfectly once and oddly ever after: “You step inside a soaring mesh dome” is exactly right the first time the player walks into the Aviary, and slightly wrong every time after, when they are already standing in it.

So the Aviary gets the pair. The arrival moment keeps its drama in initialDescription, and the standing description settles into plain present tense:

const aviary = world.createEntity('Aviary', EntityType.ROOM);
aviary.add(new RoomTrait({
  exits: {},
  isDark: false,
  initialDescription:
    'You step inside a soaring mesh dome. Brilliantly ' +
    'colored parrots chatter from rope perches, and a toucan ' +
    'eyes you curiously from a branch overhead. The exit ' +
    'back to the main path is to the east.',
}));
aviary.add(new IdentityTrait({
  name: 'Aviary',
  description:
    'Inside the soaring mesh dome, brilliantly colored ' +
    'parrots chatter from rope perches, and a toucan eyes ' +
    'you curiously from a branch overhead. The exit back to ' +
    'the main path is to the east.',
  aliases: ['aviary', 'bird house', 'dome'],
  article: 'the',
}));

Most rooms don’t need the pair; write one only where the arrival genuinely reads differently from the stay. (For a localized story there is a message-ID variant, initialDescriptionId; Chapter 18 covers the language layer.)

4.5 Putting it together

This chapter adds one new import, Direction, to the world-model line from Chapter 2:

import {
  WorldModel, IFEntity, EntityType, Direction,
} from '@sharpee/world-model';

Here is the complete initializeWorld for this version. It replaces the single-room one from Chapter 2: four rooms with full descriptions, the exits wired in both directions, the scenery for every room (your Chapter 2 welcome sign and ticket booth, plus three new objects for the new rooms), and the player placed at the entrance.

initializeWorld(world: WorldModel): void {
  // Step 1: create every room first, with empty exits.
  const entrance = world.createEntity(
    'Zoo Entrance',
    EntityType.ROOM,
  );
  entrance.add(new RoomTrait({ exits: {}, isDark: false }));
  entrance.add(new IdentityTrait({
    name: 'Zoo Entrance',
    description:
      'You stand before the gates of the Willowbrook Family ' +
      'Zoo. A cheerful welcome sign arches over the entrance, ' +
      'and a small ticket booth sits to one side. The main ' +
      'path leads south into the zoo grounds.',
    aliases: ['entrance', 'gates', 'gate'],
    article: 'the',
  }));

  const mainPath = world.createEntity(
    'Main Path',
    EntityType.ROOM,
  );
  mainPath.add(new RoomTrait({ exits: {}, isDark: false }));
  mainPath.add(new IdentityTrait({
    name: 'Main Path',
    description:
      'A wide gravel path winds through the heart of the zoo. ' +
      'Colorful direction signs point every which way. To the ' +
      'east, a white picket fence surrounds the petting zoo. ' +
      'To the west, a tall mesh enclosure rises above the ' +
      'treetops, the aviary. The entrance gates are back to ' +
      'the north.',
    aliases: ['path', 'main path', 'gravel path'],
    article: 'the',
  }));

  const pettingZoo = world.createEntity(
    'Petting Zoo',
    EntityType.ROOM,
  );
  pettingZoo.add(new RoomTrait({ exits: {}, isDark: false }));
  pettingZoo.add(new IdentityTrait({
    name: 'Petting Zoo',
    description:
      'A cheerful open-air enclosure filled with friendly ' +
      'animals. Pygmy goats trot around nibbling at visitors\' ' +
      'shoelaces, while a pair of fluffy rabbits hop near a ' +
      'hay bale. The main path is back to the west.',
    aliases: ['petting zoo', 'petting area', 'pen'],
    article: 'the',
  }));

  const aviary = world.createEntity('Aviary', EntityType.ROOM);
  aviary.add(new RoomTrait({
    exits: {},
    isDark: false,
    initialDescription:
      'You step inside a soaring mesh dome. Brilliantly ' +
      'colored parrots chatter from rope perches, and a toucan ' +
      'eyes you curiously from a branch overhead. The exit ' +
      'back to the main path is to the east.',
  }));
  aviary.add(new IdentityTrait({
    name: 'Aviary',
    description:
      'Inside the soaring mesh dome, brilliantly colored ' +
      'parrots chatter from rope perches, and a toucan eyes ' +
      'you curiously from a branch overhead. The exit back to ' +
      'the main path is to the east.',
    aliases: ['aviary', 'bird house', 'dome'],
    article: 'the',
  }));

  // Step 2: wire exits now that every room exists.
  entrance.get(RoomTrait)!.exits = {
    [Direction.SOUTH]: { destination: mainPath.id },
  };
  mainPath.get(RoomTrait)!.exits = {
    [Direction.NORTH]: { destination: entrance.id },
    [Direction.EAST]:  { destination: pettingZoo.id },
    [Direction.WEST]:  { destination: aviary.id },
  };
  pettingZoo.get(RoomTrait)!.exits = {
    [Direction.WEST]: { destination: mainPath.id },
  };
  aviary.get(RoomTrait)!.exits = {
    [Direction.EAST]: { destination: mainPath.id },
  };

  // Step 3: scenery. The welcome sign and ticket booth from
  // Chapter 2 stay in the entrance. The three new rooms get
  // scenery of their own. Each is the same pattern you already
  // know: an entity, an IdentityTrait, and a moveEntity to place
  // it. The EntityType.SCENERY type makes each one fixed.
  const sign = world.createEntity(
    'welcome sign',
    EntityType.SCENERY,
  );
  sign.add(new IdentityTrait({
    name: 'welcome sign',
    description:
      'A brightly painted wooden sign welcomes you to the zoo.',
    aliases: ['sign', 'welcome sign', 'wooden sign'],
    article: 'a',
  }));
  world.moveEntity(sign.id, entrance.id);

  const booth = world.createEntity(
    'ticket booth',
    EntityType.SCENERY,
  );
  booth.add(new IdentityTrait({
    name: 'ticket booth',
    description:
      'A small wooden booth with a sliding glass window ' +
      'reading "Self-Guided Tours / No Ticket Needed Today!"',
    aliases: ['booth', 'ticket booth', 'window'],
    article: 'a',
  }));
  world.moveEntity(booth.id, entrance.id);

  const directionSigns = world.createEntity(
    'direction signs',
    EntityType.SCENERY,
  );
  directionSigns.add(new IdentityTrait({
    name: 'direction signs',
    description:
      'A cluster of brightly colored arrow signs nailed to a ' +
      'wooden post. They point to: PETTING ZOO (east), AVIARY ' +
      '(west), REPTILE HOUSE (south -> coming soon!), and EXIT ' +
      '(north).',
    aliases: ['signs', 'direction signs', 'arrow signs', 'post'],
    article: 'some',
    grammaticalNumber: 'plural',
  }));
  world.moveEntity(directionSigns.id, mainPath.id);

  const goats = world.createEntity(
    'pygmy goats',
    EntityType.SCENERY,
  );
  goats.add(new IdentityTrait({
    name: 'pygmy goats',
    description:
      'Three pygmy goats with stubby legs and rectangular ' +
      'pupils, clearly hoping you have food.',
    aliases: ['goats', 'pygmy goats', 'goat'],
    article: 'some',
    grammaticalNumber: 'plural',
  }));
  world.moveEntity(goats.id, pettingZoo.id);

  const toucan = world.createEntity('toucan', EntityType.SCENERY);
  toucan.add(new IdentityTrait({
    name: 'toucan',
    description:
      'A Toco toucan with an enormous orange-and-black bill. ' +
      'It regards you with one intelligent eye.',
    aliases: ['toucan', 'bird', 'toco toucan'],
    article: 'a',
  }));
  world.moveEntity(toucan.id, aviary.id);

  // Step 4: place the player at the entrance, as in Chapter 2.
  const player = world.getPlayer();
  if (player) world.moveEntity(player.id, entrance.id);
}

The method is complete; nothing is abbreviated with an “as before” comment. The direction signs on the Main Path are what examine signs in the “Try it” list below reads.

4.6 The going action is free

You don’t write any movement code. Sharpee’s standard library includes a going action that, when the player types a direction, looks up the current room’s exits, finds the matching one, moves the player to the destination, and prints the new room’s description. Wiring the exits is the whole job.

4.7 The map

            Zoo Entrance
                 |  (south / north)
              Main Path
            /            \
   (west) Aviary      Petting Zoo (east)

4.8 Try it

> south                 Walk to the Main Path
> examine signs         Read the direction signs
> east                  Walk to the Petting Zoo
> west                  Back to the Main Path
> west                  Walk to the Aviary
> east                  Back to the Main Path
> north                 Back to the Zoo Entrance

One line can carry several commands: south. east, west; west, or east then north all work, and each statement runs as its own full turn. If a statement fails, the rest of the line is dropped; the parser won’t march on after a wrong turn.

4.9 Test it

A forgotten return exit is the classic map bug, and nothing catches it faster than replaying the round trip. Save this as tests/transcripts/navigation.transcript and run npx sharpee build --test; your first-room test runs right alongside it:

title: Navigation
story: familyzoo
description: Four rooms wired in pairs

---

> south
[OK: contains "Main Path"]

> examine signs
[OK: contains "PETTING ZOO"]

> east
[OK: contains "Petting Zoo"]

> west
[OK: contains "Main Path"]

> west
[OK: contains "Aviary"]

> east
[OK: contains "Main Path"]

> north
[OK: contains "Zoo Entrance"]

4.10 Key takeaway

Rooms are connected by exits on RoomTrait, each mapping a Direction to a destination room ID. Create every room before connecting them, and always wire exits in both directions, otherwise the player will get stuck.

5 Scenery & Portable Objects: Everything Is Portable by Default

A world you can only walk through is a stage set. In this chapter the zoo gains two kinds of things: scenery you can examine but never carry off (fences, benches, animals) and portable items the player can take, pocket, and drop (a zoo map, a souvenir penny, a bag of feed). Together they’re the difference between a room description and a place you can rummage through.

The surprising part is how little code each one takes. One of them takes no new trait at all.

5.1 Everything is portable by default

Here is Sharpee’s central rule about objects, and it catches everyone the first time: an entity is takeable unless you say otherwise. Create something with an IdentityTrait and nothing else, and the player can pick it up, carry it between rooms, and drop it wherever they like. There is no PortableTrait, because portability isn’t a feature you add. It’s the starting state.

So a souvenir penny needs only its identity and a home. Like every world-building block from here on, it goes at the end of initializeWorld, before the player is placed (the placement rule from How to Read This Book):

const penny = world.createEntity(
  'souvenir penny',
  EntityType.ITEM,
);
penny.add(new IdentityTrait({
  name: 'souvenir penny',
  description:
    'A flattened copper penny stamped with a smiling elephant.',
  aliases: ['penny', 'coin', 'souvenir'],
}));
world.moveEntity(penny.id, mainPath.id);

That’s a complete, takeable object. EntityType.ITEM is the type label for a generic portable thing; the IdentityTrait gives it a name, description, and aliases. No trait is needed to make it carryable; that’s the default.

5.2 EntityType.SCENERY makes a thing fixed

Most of the things in a room are not meant to be carried. You don’t want the player stuffing a park bench into a backpack or wandering off with the iron fence. Create a fixed thing as EntityType.SCENERY and it comes with a SceneryTrait already attached. That trait does exactly one thing: it blocks the taking action.

const fence = world.createEntity(
  'iron fence',
  EntityType.SCENERY,
);
fence.add(new IdentityTrait({
  name: 'iron fence',
  description:
    'A tall wrought-iron fence with animal silhouettes.',
  aliases: ['fence', 'iron fence', 'railing'],
}));
world.moveEntity(fence.id, entrance.id);

Now take fence gives the player “The iron fence is fixed in place.” But examine fence still works: scenery blocks taking, not looking. The entity keeps its IdentityTrait, so its description is always readable.

The mistake everyone makes once: a fixed thing that isn’t typed EntityType.SCENERY. The scenery type pins it for you, but a container, a supporter, or an animal you made an ACTOR is portable by default. If the player can pocket your feed dispenser, it has no SceneryTrait and you need to add one by hand.

5.3 When you still add SceneryTrait by hand

Typing a thing EntityType.SCENERY is the usual way to fix it, and it is enough on its own. You reach for an explicit SceneryTrait in only two cases:

• A fixed thing of another type. A feed dispenser is a CONTAINER and a park bench is a SUPPORTER; those types don’t arrive fixed, so you add a SceneryTrait to pin them in place.
• A custom refusal. A plain SceneryTrait gives the standard “fixed in place” line; construct it with your own message to say something specific.

A rule of thumb: if you’d find it strange for the player to put a thing in their pocket, make it EntityType.SCENERY.

5.4 Aliases make objects findable

Whether takeable or fixed, every object should answer to more than its exact name. If a room mentions “a wrought-iron fence,” the player might type examine fence, examine railing, or examine wrought-iron fence, and all of them should land:

aliases: ['fence', 'iron fence', 'wrought-iron fence', 'railing'],

The other easy miss: thin aliases. A player who can see a thing in the description but can’t refer to it the way they’d naturally say it will assume it isn’t really there. Be generous: every noun in your prose is a word the player may type.

5.5 What you get for free

Because portability is built in, so are the verbs that go with it. The standard library handles the whole inventory vocabulary without a line of code from you:

When the player carries an item and walks to a new room, the item travels with them. Carried things live with the player’s default ability to ‘contain’ items, so they go wherever the player goes. Loose portable objects left on the floor are listed after the room description:

Main Path
A wide gravel path winds through the heart of the zoo...

You can see a souvenir penny here.

Scenery is not listed this way; it’s expected to be named in the room’s description prose, where it belongs.

5.6 How taking actually decides

The whole portable-vs-fixed distinction comes down to one check. When the player types take map:

1. The parser finds the entity named “map” in the current room.
2. The taking action asks: does this entity have SceneryTrait?
   • If yes → blocked: “The zoo map is fixed in place.”
   • If no → it proceeds.
3. The action moves the entity into the player: world.moveEntity(map.id, player.id).
4. The player sees “Taken.”

That’s the entire rule. Portable or not is simply: does it have SceneryTrait? Creating a thing as EntityType.SCENERY is just the quickest way to give it one.

5.7 Putting it together

Fill each room with scenery for atmosphere, then scatter a few takeable items. Scenery is typed EntityType.SCENERY, which fixes it in place; items get nothing extra. (The iron fence below is the same one from the EntityType.SCENERY section above, shown again so this listing reads whole; add it once. The souvenir penny you created earlier in the chapter is not re-shown; it stays where you typed it.)

// Scenery: the SCENERY type fixes it in place, examinable,
// mentioned in room prose.
const fence = world.createEntity(
  'iron fence',
  EntityType.SCENERY,
);
fence.add(new IdentityTrait({
  name: 'iron fence',
  description:
    'A tall wrought-iron fence with animal silhouettes.',
  aliases: ['fence', 'iron fence', 'railing'],
}));
world.moveEntity(fence.id, entrance.id);

// More scenery: a pair of rabbits in the Petting Zoo, beside the
// goats.
const rabbits = world.createEntity('rabbits', EntityType.SCENERY);
rabbits.add(new IdentityTrait({
  name: 'rabbits',
  description:
    'A pair of Holland Lop rabbits with floppy ears and ' +
    'twitching noses, one pure white and the other brown and ' +
    'cream.',
  aliases: ['rabbits', 'rabbit', 'bunnies', 'bunny'],
  article: 'some',
  grammaticalNumber: 'plural',
}));
world.moveEntity(rabbits.id, pettingZoo.id);

// A takeable item: no SceneryTrait, so it's portable by default.
const zooMap = world.createEntity('zoo map', EntityType.ITEM);
zooMap.add(new IdentityTrait({
  name: 'zoo map',
  description:
    'A colorful folding map of the zoo, a heart drawn around ' +
    'the petting zoo in crayon.',
  aliases: ['map', 'zoo map', 'folding map'],
}));
world.moveEntity(zooMap.id, entrance.id);

// A second takeable item, in the Petting Zoo this time.
const animalFeed = world.createEntity(
  'bag of animal feed',
  EntityType.ITEM,
);
animalFeed.add(new IdentityTrait({
  name: 'bag of animal feed',
  description:
    'A small brown paper bag of dried corn and pellets. The ' +
    'label reads "ZOO SNACKS: Safe for goats, rabbits, and ' +
    'birds." It rustles invitingly.',
  aliases: [
    'feed', 'animal feed', 'bag of feed',
    'bag', 'corn', 'pellets',
  ],
}));
world.moveEntity(animalFeed.id, pettingZoo.id);

The souvenir penny from earlier in the chapter sits on the Main Path, and the pygmy goats you placed in the Petting Zoo back in Chapter 4 are scenery, so every object the “Try it” walkthrough touches is now in the world: the map and penny are portable, the feed waits in the Petting Zoo, and the goats stay put.

Plural-named scenery: the rabbits get grammaticalNumber: 'plural'. Sharpee’s messages agree in number with the entity, so this is what makes take rabbits report “The rabbits are fixed in place.” rather than “is”. Set it on anything with a plural name (pygmy goats, direction signs, flower beds) and the generated prose stays grammatical. (See Chapter 19 for how the message templates choose the verb.) The multi-file chapter’s object() builder (a fluent alternative you’ll meet in Chapter 28) spells this .plural().

5.8 Room-description snippets

Scenery lives in the room’s prose, and that rule pushes real work onto the prose: every fence, bench, and animal wants its clause, and every later change means re-editing one long string. Sharpee gives room descriptions one purpose-built tool for this. A snippet is a piece of text you write, spliced into the description at a marker you place. The splice is purely mechanical. There is no generated prose and no rewriting; every rendered character is something you wrote.

A marker is written {snippet:name} inside the description, and the room’s RoomTrait carries a matching snippet map giving each marker its text. Take the Petting Zoo. Chapter 4 wrote the rabbits directly into its description; carve that clause out as a snippet instead. In the Chapter 4 creation block, the description gains a marker where the clause used to be (the replacement rule):

  pettingZoo.add(new IdentityTrait({
    name: 'Petting Zoo',
    description:
      'A cheerful open-air enclosure filled with friendly ' +
      'animals. Pygmy goats trot around nibbling at ' +
      'visitors\' shoelaces{snippet:rabbits}. The main path ' +
      'is back to the west.',
    aliases: ['petting zoo', 'petting area', 'pen'],
    article: 'the',
  }));

Then, at the end of this chapter’s scenery code, after the rabbits exist, the room gets its snippet map. RoomTrait data is yours to set through .get(), the same way Chapter 4 wired exits:

pettingZoo.get(RoomTrait)!.snippets = {
  rabbits:
    ', while a pair of fluffy rabbits hop near a hay bale',
};

Rendered, the paragraph is exactly the one Chapter 4 shipped:

A cheerful open-air enclosure filled with friendly animals. Pygmy goats trot
around nibbling at visitors' shoelaces, while a pair of fluffy rabbits hop
near a hay bale. The main path is back to the west.

Two details to notice. The snippet carries its own leading comma and space: the splice inserts the text and nothing else, so whatever spacing and punctuation the sentence needs travels with the snippet. And the room only whispers the rabbits while the entity keeps its full identity: examine rabbits still gives the close-up from the rabbits’ own IdentityTrait, and nothing forces the spliced clause to name the entity the way the world model does. A quiet aside in the prose that rewards the player who examines it is exactly what this tool is for.

So far the snippet has only moved a clause. The payoff comes in three parts.

5.8.1 Lists vary the text

A snippet may be a list, and the platform picks one entry per render:

pettingZoo.get(RoomTrait)!.snippets = {
  rabbits: [
    ', while a pair of fluffy rabbits hop near a hay bale',
    ', while the rabbits doze in a heap of loose hay',
    '',
  ],
};

A list cycles by default: the first entry on the first render, the second on the next, wrapping when it runs out. The empty string is a legal entry that renders nothing, so with this map every third look leaves the rabbits unmentioned. Selection is seeded and deterministic, never wall-clock randomness, and each entry’s counter is saved with the game: transcripts replay identically (Chapter 29), and a saved game resumes its cycle where it left off (Chapter 30).

Cycling is one of five selectors, and the long form names one explicitly:

rabbits: {
  selector: 'random',
  texts: [ /* ... */ ],
},

cycling takes turns, stopping advances and then stays on the last entry, firstTime uses the first entry once and the second ever after, random picks with a seeded generator, and sticky picks once and repeats that pick forever. Chapter 19 shows the same selectors at work inside message templates.

5.8.2 mentions ties a snippet to its entity

The rabbits clause describes an entity that might not always be there. Name that entity in the entry and the snippet gates itself on the entity’s presence:

pettingZoo.get(RoomTrait)!.snippets = {
  rabbits: {
    texts: [
      ', while a pair of fluffy rabbits hop near a hay bale',
      ', while the rabbits doze in a heap of loose hay',
      '',
    ],
    mentions: rabbits.id,
  },
};

This final form, the texts list plus mentions, is the version the zoo keeps; the plain string and the bare list above were stepping stones on the way to it.

A snippet with mentions renders only while that entity is in the room, with no bookkeeping from you: if the rabbits are ever moved away or removed from play, their clause simply evaporates from the description, and it returns when they do. Presence is transitive containment, so rabbits inside a hutch inside the room still count as here. The field does a second job as coverage metadata: it records, mechanically, which scenery this prose accounts for.

5.8.3 The map is data your handlers can edit

The snippet map is plain data on the trait, so the event handlers of Chapter 13 may rewrite entries at runtime: swap in aftermath text after some event, or quiet a mention whose moment has passed. One convention keeps that safe: set an entry to the empty string rather than deleting it, so the load-time check described next stays meaningful.

5.8.4 The rules

Snippets are opt-in, room by room. A room with no snippet map is never scanned: braces in its description are ordinary prose, which is why nothing you wrote before this section changes meaning. Giving a room a map is what turns every {snippet:x} in its description into a marker. One invariant follows, so keep it in mind: the same description text renders differently depending on whether the room has a snippet map.

Mistakes fail loudly and early. A marker with no matching entry is an error the moment the story loads, naming the room and the marker. A map entry whose marker appears nowhere in the room’s text is a sharpee build warning (Chapter 31), since it is usually mid-edit drift. And if a handler leaves a marker unbound at runtime, the render splices nothing and logs a warning rather than crashing the turn.

Markers work in initialDescription too (the first-visit text from Chapter 4). Both texts share the room’s one snippet map, and a marker used in both draws from the same entry and the same counter: a first visit that renders the initial text advances the cycle, and the next look continues it in the standing description.

Two boundaries complete the picture. Snippets are not a general conditional text system: the map holds no functions, only text, and the one piece of world state it reads is the mentions presence gate. Anything more conditional belongs in an event handler editing the map. And for a localized story, any snippet text may be { messageId: '...' } instead of a literal string, resolving through the language layer of Chapter 18; single-language stories just write the text.

5.9 Try it

> look                  Notice the zoo map on the ground
> take map              Pick up the map
> inventory             See what you're carrying
> examine fence         You can look at scenery...
> take fence            ...but "The iron fence is fixed in place."
> south                 Walk to the Main Path (map comes with you)
> take penny            Pick up the souvenir penny
> drop map              Leave the map here
> look                  Map is now on the ground in Main Path
> east                  Go to the Petting Zoo
> take feed             Pick up the bag of animal feed
> take goats            Can't: they're scenery!

5.10 Test it

Portable-versus-fixed is exactly the kind of rule a later chapter can accidentally break. Add tests/transcripts/scenery-and-items.transcript:

title: Scenery and items
story: familyzoo
description: Portable by default; scenery fixed in place

---

> look
[OK: contains "zoo map"]

> take map
[OK: contains "Taken"]

> inventory
[OK: contains "zoo map"]

> examine fence
[OK: contains "wrought-iron"]

> take fence
[OK: contains "fixed in place"]

> south
[OK: contains "Main Path"]

> take penny
[OK: contains "Taken"]

> drop map
[OK: contains "Dropped"]

> look
[OK: contains "zoo map"]

> east
[OK: contains "Petting Zoo"]

> take feed
[OK: contains "Taken"]

> take goats
[OK: contains "fixed in place"]

The rabbits snippet deserves its own pin, because its whole point is behavior across repeated looks: the cycle advances, goes quiet on the empty entry, and wraps. Add tests/transcripts/room-snippets.transcript:

title: Room snippets
story: familyzoo
description: The rabbits snippet cycles, goes quiet, and wraps

---

> south
[OK: contains "Main Path"]

> east
[OK: contains "hop near a hay bale"]

> look
[OK: contains "doze in a heap"]

> look
[OK: not contains "rabbits"]

> look
[OK: contains "hop near a hay bale"]

The third look lands on the empty entry, so the description says nothing about rabbits at all, and the fourth wraps back to the first clause. That sequence is reliable enough to assert on because snippet selection is seeded, not random at the wall clock.

5.11 Key takeaway

Items are portable by default: EntityType.ITEM plus an IdentityTrait is a complete takeable object, no special trait required. SceneryTrait removes portability; it’s what makes fences, benches, and animals fixed in place while still examinable. Reach for scenery on anything the player shouldn’t pocket, and give every object generous aliases so it can be named the way a player would say it. And when the prose that mentions your scenery wants tuning or variety, room-description snippets splice author-written clauses at markers you place, deterministic, save-stable, and opt-in room by room.

6 Containers & Supporters: What Holds What

So far the zoo has things you walk past and things you carry. This chapter adds things that hold other things: a red backpack the player can store items inside, a feed dispenser bolted to a post at the petting zoo, and a park bench you can set objects on top of. Two new traits cover both cases, and the difference between them is the difference between in and on.

6.1 Two kinds of holders

Sharpee gives you two traits for entities that hold other entities:

• ContainerTrait: things go inside. Backpacks, boxes, drawers, dispensers.
• SupporterTrait: things go on top. Tables, shelves, benches, pedestals.

The parser sorts them out by preposition. “put X in Y” routes to the container; “put X on Y” routes to the supporter. You never write that logic; you just declare which kind of holder each object is.

> put map in backpack
You put the zoo map in the backpack.
> put penny on bench
You put the souvenir penny on the park bench.

6.2 ContainerTrait

A container holds entities inside it. You’ve already met this trait once: the player carries an inventory because the player entity itself has a ContainerTrait. In this chapter we put it on ordinary objects too. This block and the chapter’s other two (the dispenser and the bench) all follow the placement rule: end of initializeWorld, before the player is placed.

const backpack = world.createEntity(
  'backpack',
  EntityType.CONTAINER,
);
backpack.add(new IdentityTrait({
  name: 'backpack',
  description: 'A small red canvas backpack.',
  aliases: ['backpack', 'bag', 'pack'],
}));
backpack.add(new ContainerTrait({
  capacity: { maxItems: 5 },   // holds up to 5 things
}));
world.moveEntity(backpack.id, entrance.id);

Because we didn’t add SceneryTrait, this backpack is portable, and that’s where containers get interesting. (As always, the moveEntity is what puts it in the world; without it the backpack exists nowhere and take backpack finds nothing.)

6.2.1 Portable vs fixed containers

A container is fixed or portable on exactly the rule from the last chapter: SceneryTrait or not.

A portable container moves as a unit: the player takes the backpack and everything inside comes with it. A bag of five items counts as one item in the player’s own inventory. A fixed container, like the dispenser below, is for built-in storage the player can reach into but never walk off with:

const dispenser = world.createEntity(
  'feed dispenser',
  EntityType.CONTAINER,
);
dispenser.add(new IdentityTrait({
  name: 'feed dispenser',
  description:
    'A coin-operated feed dispenser mounted on a wooden post, ' +
    'its glass globe half full of pellets.',
  aliases: ['dispenser', 'feed dispenser', 'machine', 'globe'],
}));
dispenser.add(new ContainerTrait({ capacity: { maxItems: 3 } }));
// can't take the dispenser itself
dispenser.add(new SceneryTrait());
world.moveEntity(dispenser.id, pettingZoo.id);

A fixed container still needs its own IdentityTrait (the name and aliases are how the player refers to it, as in examine dispenser) and its moveEntity, which bolts it into the Petting Zoo.

6.3 SupporterTrait

A supporter is the surface counterpart: things rest on it rather than in it. SupporterTrait is the one new trait this chapter uses, so add it to the trait import you started in Chapter 2:

import {
  IdentityTrait,
  ActorTrait,
  ContainerTrait,
  RoomTrait,
  SceneryTrait,
  SupporterTrait,   // new this chapter
} from '@sharpee/world-model';

const parkBench = world.createEntity(
  'park bench',
  EntityType.SUPPORTER,
);
parkBench.add(new IdentityTrait({
  name: 'park bench',
  description:
    'A weathered wooden bench worn smooth by decades of ' +
    'visitors.',
  aliases: ['bench', 'park bench', 'seat'],
}));
parkBench.add(new SupporterTrait({ capacity: { maxItems: 3 } }));
// can't take the bench itself
parkBench.add(new SceneryTrait());
world.moveEntity(parkBench.id, mainPath.id);

The bench goes on the Main Path, so put penny on bench in the “Try it” walkthrough has a surface to use. The key behavioral difference from a container: supporters are always open, so whatever sits on a bench is visible without any special action. Containers, as the next chapter shows, can be opened and closed to hide their contents.

6.4 Capacity limits

Both traits accept the same capacity option:

capacity: { maxItems: 5 }

Try to put a sixth item in a five-item container and the player gets a “can’t fit” message. Capacity isn’t just bookkeeping. Limited space is the raw material of puzzles, forcing the player to choose what to carry and what to leave behind.

The mistake everyone makes once: leaving capacity off. A container or supporter with no capacity has no limit; it will swallow the entire zoo. If you want a bound, set maxItems explicitly.

6.5 Traits are composable

The real lesson of this chapter isn’t either trait on its own. It’s that an entity can wear several traits at once, and they stack cleanly:

• The park bench is a SupporterTrait (things go on it) and a SceneryTrait (you can’t take it).
• The feed dispenser is a ContainerTrait (things go in it) and a SceneryTrait (you can’t take it).

You’re not choosing one behavior per object. You’re assembling each object out of small, single-purpose traits until it does exactly what the world needs. Every chapter from here on is, underneath, more of this same move: combine traits to get new behavior.

6.6 Try it

> take backpack          Pick up the portable container
> take map               Pick up the zoo map
> put map in backpack    Store the map inside
> look in backpack       See what's in the backpack
> inventory              Backpack counts as one item; its contents ride along
> south                  Go to the Main Path
> take penny             Pick up the penny
> put penny on bench     Place it on the supporter
> look                   The penny is visible on the bench
> east                   Go to the Petting Zoo
> take dispenser         Can't: it's scenery
> examine dispenser      But you can look at it

6.7 Test it

Add tests/transcripts/containers.transcript, and note how the assertions pin the behavior (contents ride along, scenery refuses) rather than exact prose:

title: Containers and supporters
story: familyzoo
description: Backpack, dispenser, and bench hold things

---

> take backpack
[OK: contains "Taken"]

> take map
[OK: contains "Taken"]

> put map in backpack
[OK: contains "backpack"]
[OK: not contains "can't"]

> look in backpack
[OK: contains "map"]

> inventory
[OK: contains "backpack"]

> south
[OK: contains "Main Path"]

> take penny
[OK: contains "Taken"]

> put penny on bench
[OK: contains "bench"]
[OK: not contains "can't"]

> look
[OK: contains "penny"]

> east
[OK: contains "Petting Zoo"]

> take dispenser
[OK: contains "fixed in place"]

> examine dispenser
[OK: contains "coin-operated"]

6.8 Key takeaway

ContainerTrait holds things inside; SupporterTrait holds things on top; the parser routes “in” and “on” to the right one automatically. Either can be portable or fixed depending on whether it also has SceneryTrait, and a portable container carries its contents with it as a single inventory item. Set capacity to bound them, and remember that traits are composable, so you build each object by stacking the small traits it needs.

7 Openable Things, Locked Doors & Keys: Gating the Way Through

The containers in the last chapter gave up their contents freely. Real worlds make you work a little: a lunchbox you must open before you can reach the juice inside, a staff gate that stays shut until you find the right keycard. This chapter adds the closed state, first to containers and then to doors, and along the way wires up the zoo’s first real puzzle: find a key, unlock a gate, walk through.

It builds in two steps. OpenableTrait adds open and closed. LockableTrait adds locked and unlocked on top of it. Doors then connect rooms through that machinery.

7.1 OpenableTrait

OpenableTrait gives an entity an open/closed state and hooks up the built-in open and close actions. On its own it just tracks a boolean; its power comes from combining with other traits. The lunchbox in this section and the next two is a demonstration prop, not part of the zoo; nothing to type until the puzzle listing later in the chapter (the illustrative rule).

lunchbox.add(new OpenableTrait({
  isOpen: false,          // starts closed
  canClose: true,         // the player can close it again
  revealsContents: true,  // opening announces what's inside
}));

The three properties:

7.1.1 Openable + Container = a discoverable container

Put OpenableTrait and ContainerTrait on the same entity and the closed state starts to matter:

• Closed: contents are hidden. look in lunchbox reports it’s closed; put map in lunchbox is blocked.
• Open: contents are visible and every container operation works normally.

This is how you make the player discover things: they open something and find items they couldn’t see before.

7.1.2 Stocking a container that starts closed

Here’s a wrinkle you’ll hit during world setup. You want the lunchbox to start closed, but you also want a juice box inside it from the beginning. The engine enforces the same rules on you that it enforces on the player: you can’t moveEntity into a closed container. The fix is to open it, place the item, and close it back:

lunchbox.get(OpenableTrait)!.isOpen = true;   // temporarily open
// place the item inside
world.moveEntity(juice.id, lunchbox.id);
lunchbox.get(OpenableTrait)!.isOpen = false;   // close it again

The mistake everyone makes once: calling moveEntity into a container that’s closed at setup time and wondering why the item never appears. The engine plays by its own rules during initializeWorld(), so open the container, stock it, then close it.

7.2 LockableTrait

A lock is just a gate on opening. LockableTrait adds locked/unlocked state, and it’s almost always paired with OpenableTrait, because the entire point of a lock is to stop something from being opened.

staffGate.add(new LockableTrait({
  isLocked: true,      // starts locked
  keyId: keycard.id,   // THIS key unlocks THIS lock
}));

The critical property is keyId. It wires one specific key entity to one specific lock. When the player types unlock gate with keycard, the engine asks: does the player hold an entity whose id matches this lock’s keyId? If so, the unlock succeeds.

7.2.1 Keys are just items

A key needs no special trait. It’s an ordinary EntityType.ITEM with an IdentityTrait, nothing more. The only thing that makes it a key is that some lock’s keyId points at its id. Which means anything can be a key: a literal key, a keycard, a gemstone, a spoken word. The lock decides what opens it, not the key.

7.2.2 The unlock sequence

A locked door asks three separate actions of the player, in order:

1. Find the key: take keycard
2. Unlock the lock: unlock gate with keycard
3. Open the door: open gate

Only after all three can they pass. That sequence is a puzzle in miniature, and you get it for free just by combining the traits.

7.3 DoorTrait and the exit via property

A locked lunchbox is one thing; a locked door between rooms is what makes the zoo bigger. Two pieces connect a door to the map.

First, DoorTrait marks an entity as the connection between two rooms:

staffGate.add(new DoorTrait({
  room1: mainPath.id,      // one side
  room2: supplyRoom.id,    // the other side
  bidirectional: true,     // passable both ways
}));

Second, and this is the part that’s easy to forget, the rooms’ exits must route through the door using the via property:

mainPath.get(RoomTrait)!.exits = {
  [Direction.SOUTH]: {
    destination: supplyRoom.id,
    via: staffGate.id,          // must pass through this entity
  },
};

Now when the player types south, the going action checks the via entity before moving them:

• Is it closed? → “The staff gate is closed.”
• Is it locked? → “The staff gate is locked.”
• Is it open? → the player walks through.

The mistake everyone makes once: giving the gate every trait but forgetting via on the exit. Without via, the going action never consults the door; the exit is unconditional and the player strolls through a “locked” gate as if it weren’t there. The door’s state only matters because the exit points at it.

7.4 Wiring it all together

A working locked door is five traits on the door entity, plus a key, plus the via on the exit:

Plus a key (any portable item whose id you put in LockableTrait.keyId) and exits with via pointing at the door from both sides.

This chapter introduces three new traits, so add them to your world-model import:

import {
  OpenableTrait, LockableTrait, DoorTrait,
} from '@sharpee/world-model';

Here is the whole puzzle, in order: a new room behind the gate (with its shelves), the keycard the player finds, the gate itself as an EntityType.DOOR wearing all five traits, and the exits wired through it on both sides. The whole block goes at the end of initializeWorld (the placement rule), and where it replaces the Main Path exits from Chapter 4, delete the old assignment (the replacement rule).

// A new room, behind the gate.
const supplyRoom = world.createEntity(
  'Supply Room',
  EntityType.ROOM,
);
supplyRoom.add(new RoomTrait({ exits: {}, isDark: false }));
supplyRoom.add(new IdentityTrait({
  name: 'Supply Room',
  description:
    'A cluttered storage room behind the staff gate. Metal ' +
    'shelves line the walls, stacked with feed sacks, coiled ' +
    'hoses, and cleaning supplies.',
  aliases: ['supply room', 'storage room', 'store room'],
  article: 'the',
}));

// The metal shelves: scenery, so "examine shelves" has something
// to find.
const shelves = world.createEntity(
  'metal shelves',
  EntityType.SCENERY,
);
shelves.add(new IdentityTrait({
  name: 'metal shelves',
  description:
    'Industrial steel shelving stacked with feed sacks and ' +
    'supplies.',
  aliases: ['shelves', 'metal shelves', 'shelf', 'shelving'],
}));
world.moveEntity(shelves.id, supplyRoom.id);

// The key: an ordinary item, placed at the entrance for the
// player to find.
const keycard = world.createEntity(
  'staff keycard',
  EntityType.ITEM,
);
keycard.add(new IdentityTrait({
  name: 'staff keycard',
  description:
    'A white plastic keycard reading "WILLOWBROOK ZOO / STAFF ' +
    'ONLY," with a faded photo of a smiling zookeeper on the ' +
    'back.',
  aliases: [
    'keycard', 'key card', 'card', 'key', 'staff keycard',
  ],
  article: 'a',
}));
world.moveEntity(keycard.id, entrance.id);

// The gate: type DOOR, wearing all five traits, placed on the
// Main Path.
const staffGate = world.createEntity(
  'staff gate',
  EntityType.DOOR,
);
staffGate.add(new IdentityTrait({
  name: 'staff gate',
  description:
    'A sturdy metal gate marked STAFF ONLY, with a card reader ' +
    'beside it.',
  aliases: ['gate', 'staff gate', 'metal gate', 'staff door'],
  article: 'a',
}));
staffGate.add(new DoorTrait({
  room1: mainPath.id,
  room2: supplyRoom.id,
  bidirectional: true,
}));
staffGate.add(new OpenableTrait({ isOpen: false }));
staffGate.add(new LockableTrait({
  isLocked: true,
  keyId: keycard.id,
}));
staffGate.add(new SceneryTrait());
world.moveEntity(staffGate.id, mainPath.id);

// Wire the passage on BOTH sides, each routing through the gate
// with `via`. This replaces the Main Path exits from Chapter 4,
// adding the south passage.
mainPath.get(RoomTrait)!.exits = {
  [Direction.NORTH]: { destination: entrance.id },
  [Direction.EAST]:  { destination: pettingZoo.id },
  [Direction.WEST]:  { destination: aviary.id },
  [Direction.SOUTH]: {
    destination: supplyRoom.id,
    via: staffGate.id,
  },
};
supplyRoom.get(RoomTrait)!.exits = {
  [Direction.NORTH]: {
    destination: mainPath.id,
    via: staffGate.id,
  },
};

EntityType.DOOR is the label that says “this entity is a door”; the SceneryTrait is still what stops the player taking it. With the return exit on the Supply Room also routed via the gate, the player can walk back out the way they came.

7.5 Try it

> take keycard                Pick up the keycard
> south                       Go to the Main Path
> south                       "The staff gate is locked."
> unlock gate with keycard    Unlock it
> open gate                   Open it
> south                       Walk through to the Supply Room
> examine shelves             Look around the supply room
> north                       Back through the open gate

7.6 Test it

The gate is the zoo’s first real puzzle, which makes it the first test that guards a sequence: locked blocks, unlock-open-walk works. Add tests/transcripts/locked-gate.transcript:

title: The locked gate
story: familyzoo
description: Keycard unlocks the staff gate

---

> take keycard
[OK: contains "Taken"]

> south
[OK: contains "Main Path"]

> south
[OK: contains "locked"]

> unlock gate with keycard
[OK: not contains "can't"]

> open gate
[OK: not contains "can't"]

> south
[OK: contains "Supply Room"]

> examine shelves
[OK: contains "steel shelving"]

> north
[OK: contains "Main Path"]

7.7 Key takeaway

OpenableTrait adds open/closed state and the open/close actions; combined with ContainerTrait it hides contents until opened. LockableTrait adds a lock on top, with keyId wiring one key to one lock, and keys are just ordinary items. A door between rooms needs DoorTrait and a via on the exits pointing at it, or the going action will never check the door at all.

8 Light & Dark: What the Player Can See

South of the supply room lies a nocturnal animals exhibit, and it is pitch black. Walk in without a light and you can’t see a thing: no description, no animals, nothing to interact with but the way back out. The fix is sitting in the supply room: a flashlight. Switch it on, carry it in, and the darkness lifts to reveal sugar gliders, bush babies, and a barn owl.

Darkness is one of the oldest mechanics in interactive fiction, and it’s really two ideas working together: rooms that can be dark, and objects that can light them.

8.1 Dark rooms

Any room becomes dark by setting isDark: true on its RoomTrait. Here’s the one line that matters on the nocturnal exhibit (we build the whole room at the end of the chapter):

nocturnalExhibit.add(new RoomTrait({
  exits: {},
  isDark: true,     // this room is pitch black
}));

Enter a dark room with no light and the player sees a darkness message instead of the room description. They can’t examine, take, or touch anything; the only move available is to leave. The objects are still there; they’re just unreachable until there’s light.

8.2 LightSourceTrait

LightSourceTrait marks an entity as something that can illuminate a dark room:

flashlight.add(new LightSourceTrait({
  brightness: 8,    // how powerful, 1–10
  isLit: false,     // starts unlit
}));

When the player is carrying an entity whose isLit is true, dark rooms light up: the description appears normally and every object becomes accessible again.

8.3 SwitchableTrait

SwitchableTrait gives an entity an on/off state and the switch on / switch off actions:

flashlight.add(new SwitchableTrait({
  isOn: false,      // starts off
}));

On its own it just tracks on/off. Combined with LightSourceTrait, flipping the switch is what lights the device.

8.4 The flashlight pattern

A flashlight is three traits stacked, the composability lesson from earlier chapters applied again:

When the player switches it on:

1. SwitchableTrait.isOn becomes true.
2. LightSourceTrait.isLit becomes true; the engine links the two.
3. Any dark room the player carries it into is now lit.

This block starts life in the Supply Room, so it follows the placement rule (end of initializeWorld, where supplyRoom is already in scope):

const flashlight = world.createEntity(
  'flashlight',
  EntityType.ITEM,
);
flashlight.add(new IdentityTrait({
  name: 'flashlight',
  description:
    'A heavy rubberized flashlight with a bright halogen bulb.',
  aliases: ['flashlight', 'torch', 'light'],
}));
flashlight.add(new SwitchableTrait({ isOn: false }));
flashlight.add(new LightSourceTrait({
  brightness: 8,
  isLit: false,
}));
world.moveEntity(flashlight.id, supplyRoom.id);

The mistake everyone makes once: expecting SwitchableTrait alone to banish the dark. A switch with no LightSourceTrait just toggles on and off and lights nothing, and a LightSourceTrait with no switch is always lit. A controllable light needs both.

8.5 Other light-source patterns

The flashlight is the simplest case. The same trait covers others by changing which pieces you include:

Always-on light (a glowing gem, an enchanted sword): no switch, just lit:

gem.add(new LightSourceTrait({ isLit: true, brightness: 5 }));

Consumable light (a candle or torch that burns down):

candle.add(new LightSourceTrait({
  isLit: false,
  brightness: 3,
  fuelRemaining: 50,        // burns for 50 turns
  fuelConsumptionRate: 1,   // one fuel per turn
}));

Adjustable light (a lantern with a dimmer): set brightness high and let story code change it dynamically:

lantern.add(new LightSourceTrait({ brightness: 10 }));

8.6 Darkness as a gate

Objects inside a dark room exist the whole time; they’re simply inaccessible until there’s light. That makes darkness a natural gating mechanism: put something worth finding behind it, and the light source becomes the key that opens it. The flashlight here, a candle elsewhere, a magic spell in another game: same shape, different flavor.

8.7 Wiring it into the zoo

Two new traits arrive this chapter, so add them to your world-model import:

import {
  LightSourceTrait, SwitchableTrait,
} from '@sharpee/world-model';

The dark exhibit hangs off the Supply Room from Chapter 7. Build the room in full, connect it south of the supply room (with the way back north), and populate it with the animals the flashlight will reveal. The block follows the placement rule, and its new Supply Room exits table replaces Chapter 7’s, so delete the old one (the replacement rule):

const nocturnalExhibit = world.createEntity(
  'Nocturnal Animals Exhibit',
  EntityType.ROOM,
);
nocturnalExhibit.add(new RoomTrait({ exits: {}, isDark: true }));
nocturnalExhibit.add(new IdentityTrait({
  name: 'Nocturnal Animals Exhibit',
  description:
    'A hushed, cavern-like hall lit by faint blue moonlight ' +
    'panels. Sugar gliders leap between branches, wide-eyed ' +
    'bush babies cling to a rope, and an enormous barn owl ' +
    'perches motionless on a stump.',
  aliases: [
    'nocturnal exhibit', 'nocturnal animals',
    'dark exhibit', 'exhibit',
  ],
  article: 'the',
}));

// Connect it south of the Supply Room, with the way back north.
// This adds the south passage to the Supply Room exits from
// Chapter 7.
supplyRoom.get(RoomTrait)!.exits = {
  [Direction.NORTH]: {
    destination: mainPath.id,
    via: staffGate.id,
  },
  [Direction.SOUTH]: { destination: nocturnalExhibit.id },
};
nocturnalExhibit.get(RoomTrait)!.exits = {
  [Direction.NORTH]: { destination: supplyRoom.id },
};

// The animals: scenery, examinable only once the room is lit.
const sugarGliders = world.createEntity(
  'sugar gliders',
  EntityType.SCENERY,
);
sugarGliders.add(new IdentityTrait({
  name: 'sugar gliders',
  description:
    'A family of tiny sugar gliders with enormous dark eyes, ' +
    'gliding between branches.',
  aliases: ['sugar gliders', 'gliders', 'sugar glider'],
  article: 'some',
}));
world.moveEntity(sugarGliders.id, nocturnalExhibit.id);

const bushBabies = world.createEntity(
  'bush babies',
  EntityType.SCENERY,
);
bushBabies.add(new IdentityTrait({
  name: 'bush babies',
  description:
    'Two bush babies with impossibly large round eyes, ' +
    'clinging to a rope.',
  aliases: ['bush babies', 'bush baby', 'galagos'],
  article: 'some',
}));
world.moveEntity(bushBabies.id, nocturnalExhibit.id);

const barnOwl = world.createEntity(
  'barn owl',
  EntityType.SCENERY,
);
barnOwl.add(new IdentityTrait({
  name: 'barn owl',
  description:
    'An enormous barn owl with a heart-shaped white face, ' +
    'watching you without blinking.',
  aliases: ['barn owl', 'owl'],
  article: 'a',
}));
world.moveEntity(barnOwl.id, nocturnalExhibit.id);

The flashlight from earlier in the chapter sits in the Supply Room, ready to carry in, so examine owl and examine gliders in the walkthrough below both resolve once the light is on.

8.8 Try it

> take keycard                Get the key
> south                       Main Path
> unlock gate with keycard    Unlock the staff gate
> open gate                   Open it
> south                       Supply Room
> take flashlight             Grab the flashlight
> south                       Nocturnal Exhibit, dark!
> look                        "It is pitch dark…"
> north                       Retreat to the Supply Room
> switch on flashlight        Let there be light
> south                       Nocturnal Exhibit, now lit!
> examine owl                 Look at the barn owl
> examine gliders             Look at the sugar gliders
> switch off flashlight       Darkness returns
> look                        Dark again

8.9 Test it

Darkness is state, and state is what tests are best at. Add tests/transcripts/light-and-dark.transcript:

title: Light and dark
story: familyzoo
description: The flashlight lifts the darkness

---

> take keycard
[OK: contains "Taken"]

> south
[OK: contains "Main Path"]

> unlock gate with keycard
[OK: not contains "can't"]

> open gate
[OK: not contains "can't"]

> south
[OK: contains "Supply Room"]

> take flashlight
[OK: contains "Taken"]

> south
[OK: contains "dark"]

> look
[OK: contains "dark"]

> north
[OK: contains "Supply Room"]

> switch on flashlight
[OK: not contains "can't"]

> south
[OK: contains "Nocturnal Animals Exhibit"]
[OK: contains "moonlight"]

> examine owl
[OK: contains "heart-shaped"]

> examine gliders
[OK: contains "sugar gliders"]

> switch off flashlight
[OK: not contains "can't"]

> look
[OK: contains "dark"]

8.10 Key takeaway

isDark: true on a RoomTrait makes a room pitch black, locking out interaction until light arrives. LightSourceTrait lets an entity illuminate the dark, and SwitchableTrait adds the on/off control. A flashlight is just an item carrying both: switch it on, take it in, and the darkness lifts. Vary which traits you include for always-on, consumable, or adjustable lights.

9 The Map & Regions: Grouping Rooms

You’ve quietly been building a map since Chapter 4. Every RoomTrait you gave an exits table added another connection, and together the zoo’s six rooms (entrance, main path, petting zoo, aviary, and the supply room and nocturnal exhibit behind the staff gate) form a small but complete map. This chapter steps back to look at that map as a whole, and introduces regions: a way to treat a group of rooms as a single named place.

9.1 The map is the exits

There is no separate “map” object in Sharpee. The map is the set of exits you declared on each room: a graph of rooms joined by directions. A couple of habits keep that graph sane as it grows:

• Make exits reciprocal. If the main path leads east to the petting zoo, the petting zoo should lead west back. Sharpee won’t add the return exit for you, and a one-way passage the player can’t retrace is almost always a bug.
• Keep directions consistent. If north takes the player somewhere, south should bring them back. Players build a mental map from your compass; contradicting it is disorienting.
• Route doored connections through the door. The staff gate connection uses via so the door is actually checked (Chapter 7); the map and the barrier on it are the same link.

For six rooms you can hold the whole map in your head. For sixty, you’ll want a way to talk about areas rather than individual rooms. That’s what regions are for.

9.2 Regions: grouping rooms

A region is a named area that owns a set of rooms. The zoo divides naturally into two: the public area the visitor wanders freely (entrance, main path, petting zoo, aviary) and the staff area behind the gate (supply room, nocturnal exhibit). Regions let you name that division and act on it.

Type this pair into your project. The zoo is small enough that regions are optional here (nothing later depends on them), but wiring them in once shows the whole pattern, and the staff-area smell will pay off when the map grows. Create regions in initializeWorld(), before the rooms that belong to them:

world.createRegion('reg-public', {
  name: 'Public Zoo',
});

world.createRegion('reg-staff', {
  name: 'Staff Area',
  ambientSmell: 'disinfectant and animal feed',
});

By convention region IDs take a reg- prefix, to tell them apart from room IDs at a glance.

Then assign each room to its region. The assignRoom block needs every room already created, so it goes at the end of initializeWorld with the chapter’s other late additions (the placement rule):

world.assignRoom(entrance.id, 'reg-public');
world.assignRoom(mainPath.id, 'reg-public');
world.assignRoom(pettingZoo.id, 'reg-public');
world.assignRoom(aviary.id, 'reg-public');

world.assignRoom(supplyRoom.id, 'reg-staff');
world.assignRoom(nocturnalExhibit.id, 'reg-staff');

9.3 Region-wide properties

The reason to group rooms is that a region can carry properties its rooms inherit. A RegionOptions object accepts a few:

Setting defaultDark: true on, say, a cave region saves you marking every room isDark by hand: a property that belongs to the area lives on the area.

9.4 Crossing the boundary

The real power shows up when the player moves between regions. When a go command carries the player from a room in one region to a room in another, the engine emits two events automatically:

• if.event.region_exited, fired once for each region being left,
• if.event.region_entered, fired once for each region being entered.

You react to them exactly the way you’ll react to any event in Volume IV, by registering a handler. The sketch below is a preview of that volume, not part of the zoo (the illustrative rule); its body is only a comment, and nothing to type in this chapter:

world.registerEventHandler(
  'if.event.region_entered',
  (event, world) => {
    const data = event.data as { regionId?: string } | undefined;
    if (data?.regionId === 'reg-staff') {
      // The visitor just slipped into the staff area: flavor, a
      // warning, a scoring hook, whatever the moment calls for.
    }
  },
);

(event.data is typed unknown, so the cast is what lets the strict compiler accept the field access.)

This is the natural home for “as you enter the old town, the noise of the market swells”: atmosphere keyed to an area instead of bolted onto every room’s description.

9.5 Nesting and querying

Regions can nest. Give one a parentRegionId and a room in the child counts as being in the parent too:

world.createRegion('reg-underground', {
  name: 'The Underground',
  defaultDark: true,
});
world.createRegion('reg-mine', {
  name: 'Coal Mine',
  parentRegionId: 'reg-underground',
});
// a room in reg-mine answers true for reg-underground as well

And you can ask the world about membership at any time: world.isInRegion(roomId, 'reg-staff') gives a yes/no. If you add the optional @sharpee/queries package, its entity-query API lists every room in an area: world.rooms.inRegion('reg-staff', world).toArray(). The package installs world.rooms as a side effect, so it only exists after an import '@sharpee/queries'; line somewhere in your story; without that import, the plain WorldModel gives you isInRegion.

9.6 Key takeaway

The map is nothing more than the exits you declare on each room: keep them reciprocal and consistent and the graph stays trustworthy. When a map grows past what you can hold in your head, regions group rooms into named areas that can share properties (defaultDark, ambient sound and smell) and, best of all, fire if.event.region_entered / region_exited as the player crosses between them, the hook for area-wide atmosphere and events. A map the zoo’s size could have skipped regions entirely (we wired them in to learn the pattern), and they earn their keep when your world gets big enough to think about in neighborhoods.

10 The Standard Actions: The Four-Phase Model

So far the zoo has been a place to be: rooms to walk through, objects to examine, containers to open. Everything the player could do already worked: take, drop, open, go, examine. You never wrote a line of code to make it so. This volume is about how a world responds, and it starts with the machinery you’ve been leaning on all along: the standard action library, and the four-phase model every action in Sharpee obeys.

10.1 The verbs you got for free

Sharpee’s standard library (@sharpee/stdlib) ships a full vocabulary of interactive-fiction verbs. The moment you created a room and an object, the player could already act on them. The standard actions fall into three groups:

• World-changing actions alter the game state: take and drop, open and close, go, put and insert, lock and unlock, switch on/off, wear and remove, eat and drink, push, pull, give, enter and exit.
• Query actions only look: examine, look, read, search, inventory. They report what’s there without changing anything.
• Meta actions speak to the game rather than the world: save, restore, quit, wait, again, help, score.

You don’t register any of these; they come with the platform, wired to the traits you’ve already met. OpenableTrait is what makes open work on the lunchbox; SwitchableTrait is what makes switch on work on the flashlight. Add the trait, and the matching verb lights up. (The full catalog lives in Appendix B.)

10.2 One shape for every action

Every action, the standard ones above and the custom ones you’ll write in Volume IV, has the same four-part structure. Chapter 3 sketched it as “check, change, report”; here is the whole contract:

const someAction: Action = {
  id: 'if.action.taking',

  validate(context): ValidationResult { /* can this happen? */ },
  execute(context): void           { /* change the world */ },
  report(context): ISemanticEvent[] {
    /* record what happened */
  },
  blocked(context, result): ISemanticEvent[] {
    /* explain the refusal */
  },
};

The engine calls these in a fixed order, and each has exactly one job.

10.2.1 validate: can this happen?

validate is the gatekeeper. It checks preconditions and returns either { valid: true } or { valid: false, error: '...' }. Taking something checks that it’s here, that it’s not already in your hands, that it’s not scenery bolted to the floor. validate decides; it never changes anything.

10.2.2 execute: change the world

If validation passed, execute runs and performs the actual mutation, which moves the item into the player’s inventory, flipping isOpen to true. This is the only phase that changes game state, and it’s meant to be small. The real work usually lives in a behavior (more on those in Volume IV), with execute just coordinating it.

10.2.3 report: record what happened

report produces the events for the turn: the if.event.taken and if.event.opened records you met in Chapter 3, each carrying a message id rather than text. It generates events; it doesn’t mutate. Anything execute learned that report needs is handed forward through context.sharedData, never smuggled onto the context itself.

10.2.4 blocked: explain the refusal

If validate returns { valid: false }, the engine skips execute and report and calls blocked instead. Its job is to turn the validation error into an event the player can understand, such as “You can’t take that.” A refused action is still a complete, well-formed turn; it simply reports a different outcome.

10.3 Why the discipline matters

Splitting an action into four phases with strict rules (mutations only in execute, events only in report) is what makes the whole system predictable and extensible:

• Validation can be trusted. Because validate never changes anything, the engine can ask “would this work?” without side effects, which is how the parser can disambiguate and how a command can be checked before it commits.
• Every action reads the same way. Learn the shape once and you can read any action in the library, and write your own that slots in beside them.
• The world stays inspectable. State changes happen in one phase; the record of them happens in another. That clean seam is what lets event handlers (Chapter 13) react to what an action did, and what makes saved games and replays reliable.

You won’t write an action in this chapter, because the standard library already covers the zoo. But the four-phase model is the backbone of everything ahead: custom actions in Chapter 14 fill in all four phases by hand, capability dispatch in Chapter 15 delegates them per entity, and event handlers in Chapter 13 hang new consequences off the events report emits.

10.4 Key takeaway

The standard library gives you a complete set of IF verbs for free, each wired to the traits you add to entities, with no registration required. Behind every verb is the same four-phase contract: validate (can it happen?), execute (change the world), report (record what happened as events), and blocked (explain a refusal). Mutations live only in execute, events only in report, and data passes between them through context.sharedData. That single, uniform shape is what makes Sharpee actions predictable to read, safe to validate, and ready to extend.

11 Scope & Visibility: What the Player Can Reach

When the player types take key, two quiet questions get answered before anything happens: which key, and can the player refer to it at all? A key in the room is fair game; a key locked inside a closed box, or sitting in the next room, is not, even though both exist in the world. The system that draws that line is scope, and you’ve been relying on it since your very first room without touching it.

11.1 What scope is

Scope is the set of entities a command can refer to and act on right now. It’s computed fresh each turn from where the player is and what they can perceive: the room they’re in, the things in it, what they’re carrying, what’s inside open containers nearby. When the parser resolves the word “key,” it searches scope, not the whole world, which is why examine sign found the welcome sign in Chapter 2 but examine sign from a different room would not.

Think of scope as the answer to “what could the player plausibly mean?” Everything outside it is, as far as this command is concerned, invisible.

11.2 Degrees of access

Not everything in scope is equally available. Sharpee distinguishes a few degrees, because different verbs need different things:

• In the room: present in the player’s location.
• Visible: can be seen (subject to light; see below).
• Reachable: can be physically touched.
• Carried / worn: already in the player’s hands or on their body.
• Audible: can be heard even if not seen.

These overlap but aren’t identical, and the gap between them is where good puzzles live. You can see a fish through the glass of an aquarium but not reach it. You can hear the parrot squawking from the next room without it being visible. Most of the time the standard actions pick the right degree for you (examine wants visibility, take wants reach), so you rarely think about it. You reach for the distinction yourself only when you write a custom action whose verb needs a different degree.

11.3 Sight and darkness

Visibility isn’t free: it depends on light. In a dark room, such as the nocturnal exhibit from Light & Dark, the player can’t see, so visual scope collapses to almost nothing. The objects are still physically present, but a look or examine can’t reach them; the engine’s perception layer steps in and replaces “you see…” output with the darkness message instead. Bring a lit flashlight and visibility (and the room’s contents) snap back.

This is why darkness works as a gate: it doesn’t remove objects, it removes the player’s perception of them. Sight is the sense most puzzles gate on, but the same rule covers the others: a sound the player can’t hear is out of scope too.

11.4 Permissive parser, strict action

The parser is deliberately permissive, and this is worth understanding even though you rarely configure it: when it resolves a noun, it accepts anything the player could plausibly be touching, and leaves the harder judgment to the action. The action’s validate phase then applies the strict rule: does this verb actually require sight? reach?

The payoff is commands like attacking, pushing, or grabbing in the dark: the parser still resolves “the lever” by touch, and the action decides whether doing it blind is allowed. If the parser demanded full visibility up front, every in-the-dark interaction would fail with “you can’t see any such thing” before the action ever got a say. (When you write your own grammar in Volume V, you can set a pattern’s scope explicitly; until then, the standard verbs already strike this balance.)

Inside an action, the checks are simple helpers, context.canSee(entity) and context.canReach(entity), so a custom action can be as strict or as lenient as its verb demands.

11.5 Key takeaway

Scope is the per-turn set of things a command can refer to, computed from the player’s location and senses. The parser searches it, not the whole world, which is how take key finds the right key and ignores the one locked away. Within scope, verbs care about different degrees of access: visible, reachable, carried, audible. Visibility depends on light, so darkness shrinks sight-based scope without deleting the objects. And because the parser resolves permissively while each action validates strictly, the player can still act in the dark when the verb allows it.

12 Readable Objects & Switchable Devices: Things That Carry State

A zoo is full of things to read. Brass plaques by the enclosures, a glossy brochure at the entrance, a yellow warning sign outside the nocturnal exhibit. Each sign says something the player wants to take in, separate from what it looks like. And tucked on a shelf in the supply room is a battered radio that clicks on and off but sheds no light at all. This chapter covers two small, self-contained traits that round out an ordinary world: ReadableTrait for things with words, and SwitchableTrait for devices with an on/off state.

ReadableTrait is new this chapter; SwitchableTrait you met in Light & Dark and your file already imports it. Add only the new name to your world-model import (TypeScript rejects importing the same identifier twice, so don’t paste a second SwitchableTrait):

import { ReadableTrait } from '@sharpee/world-model';

The snippets below go in initializeWorld, at the end as usual (the placement rule). entrance, pettingZoo, and supplyRoom are the same room entities from earlier chapters, all in scope there.

12.1 ReadableTrait: what an object says

ReadableTrait gives an entity text that the read action displays:

plaque.add(new ReadableTrait({
  text:
    'PYGMY GOATS: These Nigerian Dwarf goats are gentle, ' +
    'curious, and always hungry.',
}));

read and examine are different verbs that pull from different traits, ReadableTrait.text versus IdentityTrait.description:

A brass plaque looks like “a brass plaque mounted on a wooden post.” It says “PYGMY GOATS: These Nigerian Dwarf goats are gentle, curious, and always hungry.” Two different strings, two different verbs.

The test for whether something wants a ReadableTrait: would a real person say “I want to read this”? A sign, a book, a letter, a label: yes. A rock, a fence, a tree: no; those just need a description.

12.2 Readable scenery: the info plaque

Plaques are scenery you can read but can’t take. Each includes IdentityTrait, ReadableTrait, and SceneryTrait.

const pettingPlaque = world
  .createEntity('info plaque', EntityType.SCENERY);
pettingPlaque.add(new IdentityTrait({
  name: 'info plaque',
  description:
    'A brass plaque mounted on a wooden post near the petting ' +
    'zoo gate. It has text etched into the metal.',
  aliases: ['plaque', 'info plaque', 'brass plaque'],
  properName: false,
  article: 'an',
}));
pettingPlaque.add(new ReadableTrait({
  text:
    'PYGMY GOATS: These Nigerian Dwarf goats are gentle, ' +
    'curious, and always hungry. They can eat up to 3% of ' +
    'their body weight daily. Please use only zoo-approved ' +
    'feed from the dispensers.\n\nHOLLAND LOP RABBITS: Known ' +
    'for their floppy ears and calm temperament. Our pair, ' +
    'Biscuit and Marmalade, were born right here at ' +
    'Willowbrook in 2023.',
}));
world.moveEntity(pettingPlaque.id, pettingZoo.id);

Note the \n\n between the two animals. Readable text is shown as-is, so line breaks are yours to place.

The mistake everyone makes once: writing one long unbroken paragraph and wondering why it reads like a wall. Use \n (or \n\n) to break readable text into lines and stanzas the way a real sign or page would.

12.3 Readable items: the brochure

ReadableTrait works on portable things too. Leave off SceneryTrait and the player can pick the object up and read it anywhere:

const brochure = world
  .createEntity('zoo brochure', EntityType.ITEM);
brochure.add(new IdentityTrait({
  name: 'zoo brochure',
  description:
    'A glossy tri-fold brochure with "WILLOWBROOK FAMILY ' +
    'ZOO" on the cover in cheerful yellow letters.',
  aliases: ['brochure', 'zoo brochure', 'pamphlet', 'leaflet'],
  properName: false,
  article: 'a',
}));
brochure.add(new ReadableTrait({
  text:
    'WILLOWBROOK FAMILY ZOO: Your Guide\n\n' +
    'EXHIBITS:\n' +
    '  Petting Zoo ............ East from Main Path\n' +
    '  Aviary ................. West from Main Path\n' +
    '  Nocturnal Animals ...... Staff Area (ask a keeper!)\n\n' +
    '"Where every visit is a wild adventure!"',
}));
world.moveEntity(brochure.id, entrance.id);

Readable scenery (plaques, warning signs) and readable items (brochures, letters, books) are the same trait; the only difference is whether the thing is fixed in place.

12.4 SwitchableTrait: a device with on/off state

Back in Light & Dark the flashlight combined SwitchableTrait with LightSourceTrait. But SwitchableTrait stands perfectly well on its own, for any device with an on/off state that isn’t a light. The supply-room radio is exactly that:

const radio = world.createEntity('radio', EntityType.ITEM);
radio.add(new IdentityTrait({
  name: 'radio',
  description:
    'A battered portable radio held together with duct ' +
    'tape. A faded sticker on the side reads "ZOO FM | All ' +
    'Animals, All The Time."',
  aliases: ['radio', 'portable radio'],
  properName: false,
  article: 'a',
}));
radio.add(new SwitchableTrait({ isOn: false }));   // starts off
// bolted to the shelf
radio.add(new SceneryTrait());
world.moveEntity(radio.id, supplyRoom.id);

The player can switch on radio, switch off radio, turn on radio, or turn off radio; the stdlib handles all four phrasings and reports the toggle. The radio has no LightSourceTrait, so switching it on changes its state but illuminates nothing. The SceneryTrait means it can’t be carried off.

The mistake everyone makes once: expecting a bare SwitchableTrait to do something dramatic. On its own it just tracks isOn. Combine it with LightSourceTrait for a controllable light, or react to its state with an event handler (the next volume of the book) when you want flipping the switch to do something.

12.5 Switchable vs. openable

SwitchableTrait and OpenableTrait look like twins (both hold a boolean, both have paired verbs), but they model different kinds of object, and the parser keeps their verbs apart:

You’d never “switch on” a door or “open” a radio. Pick the trait whose verbs match how a person would actually talk about the object.

12.6 Try it

> take brochure              Pick up the zoo brochure
> take keycard               Grab the staff keycard; it's here at the entrance
> read brochure              Read the guide, different from examine!
> examine brochure           See the physical brochure
> south                      Main Path
> east                       Petting Zoo
> read plaque                Read about the goats and rabbits
> examine plaque             See the brass plaque itself
> west                       Back to Main Path
> unlock gate with keycard   Open the staff area
> open gate                  Open the staff gate
> south                      Supply Room
> examine radio              See the battered radio
> switch on radio            Click, it's on
> switch off radio           Click, off again
> take radio                 Can't, it's scenery

12.7 Test it

Add tests/transcripts/readables.transcript; it pins the read-versus-examine distinction on both the plaque and the brochure:

title: Readables and switchables
story: familyzoo
description: Plaque, brochure, and radio carry state

---

> take brochure
[OK: contains "Taken"]

> take keycard
[OK: contains "Taken"]

> read brochure
[OK: contains "Your Guide"]

> examine brochure
[OK: contains "glossy"]

> south
[OK: contains "Main Path"]

> east
[OK: contains "Petting Zoo"]

> read plaque
[OK: contains "PYGMY GOATS"]

> examine plaque
[OK: contains "brass plaque"]

> west
[OK: contains "Main Path"]

> unlock gate with keycard
[OK: not contains "can't"]

> open gate
[OK: not contains "can't"]

> south
[OK: contains "Supply Room"]

> examine radio
[OK: contains "duct tape"]

> switch on radio
[OK: not contains "can't"]

> switch off radio
[OK: not contains "can't"]

> take radio
[OK: contains "fixed in place"]

12.8 Key takeaway

ReadableTrait separates what an object says (read) from what it looks like (examine); type fixed plaques and signs EntityType.SCENERY and leave portable brochures and books as plain items, and use \n to shape the text. SwitchableTrait gives any device an on/off toggle through the switch/turn verbs, alone for a plain device like the radio, or paired with another trait when the switch should drive something. It’s the sibling of OpenableTrait: same shape, different verbs, different kind of object.

13 Event Handlers: Reacting to What Happens

So far every object in the zoo has been something: scenery, a container, a readable sign. This chapter is where the world starts to react. Drop the bag of feed in the petting zoo and the goats rush over to devour it. Feed a souvenir penny into the press in the gift shop and it comes out flattened and embossed. Neither of those is a new verb. The player is using ordinary drop and put in. The reaction comes from an event handler listening for those actions and adding something on top.

This is the workhorse pattern for puzzles and special effects: let the standard actions do their job, then hook the events they emit.

13.1 Every action emits an event

When a standard action succeeds, it announces what happened by emitting an event. You react by registering a handler for that event type:

…and many more. The list grows with the stdlib, but the shape is always the same: an action happens, an event fires, your handler gets a look.

13.2 Two kinds of handler

There are two ways to listen, and which you choose depends on whether you want the player to see anything.

Silent handlers mutate world state and produce no text. Register them with world.registerEventHandler():

world.registerEventHandler('if.event.dropped', (event, world) => {
  // Set a flag, move an item, change state; but no visible text
  world.setStateValue('item-was-dropped', true);
});

Chain handlers return an event that turns into visible text. Register them with world.chainEvent(). The handler returns either an event (which gets dispatched and rendered) or null to stay quiet:

world.chainEvent(
  'if.event.dropped',
  (event, w) => {
    const data = event.data as Record<string, any>;
    // not our item, ignore
    if (data.itemId !== feedId) return null;
    return {
      id: `goats-react-${Date.now()}`,
      type: 'zoo.event.goats_react',
      timestamp: Date.now(),
      entities: {},
      data: { text: 'The goats rush over and devour the feed!' },
    };
  },
  { key: 'zoo.chain.goats-eat-feed' },
);

Use registerEventHandler() for bookkeeping the player never sees; use chainEvent() when something visible should happen.

The mistake everyone makes once: reaching for type: 'game.message' in a chain handler. The event processor treats a game.message returned from a handler as an override of the original action’s text, so instead of adding your reaction it replaces the “You drop the feed.” line. Use a custom event type like zoo.event.goats_react with a text field instead; the renderer displays any event that carries text, and the original action message survives.

13.3 Reading the event data

Each event carries a data object describing what happened. The fields depend on the event type:

// if.event.dropped
{ item: string, itemId: EntityId, toLocation: EntityId }

// if.event.put_in
{ itemId: EntityId, targetId: EntityId, preposition: 'in' }

Note item is the item’s name and itemId is its entity ID. Compare against itemId. Names aren’t unique; IDs are.

13.4 Setting up: the gift shop, the press, and remembering IDs

The reactions in this chapter need three things the world doesn’t have yet: a Gift Shop room, the souvenir press to put the penny in, and a way for a handler to refer to specific entities long after initializeWorld has run. The story remembers the IDs it cares about in two class fields, and the handler signatures pull in a few new types:

import { GameEngine } from '@sharpee/engine';
import { ISemanticEvent } from '@sharpee/core';
import { IWorldModel } from '@sharpee/world-model';

class FamilyZooStory implements Story {
  config = config;

  private roomIds: { giftShop: string; pettingZoo: string } =
    { giftShop: '', pettingZoo: '' };
  private entityIds: {
    animalFeed: string;
    penny: string;
    souvenirPress: string;
  } = { animalFeed: '', penny: '', souvenirPress: '' };

  // createPlayer / initializeWorld / onEngineReady …
}

In initializeWorld, at the end as usual (the placement rule), add the Gift Shop west of the Aviary and the press inside it, then record the IDs the handlers will match against (the penny and animalFeed entities were created back in Chapter 5). The Aviary exits assignment below replaces Chapter 4’s, so delete the old one (the replacement rule):

const giftShop = world.createEntity('Gift Shop', EntityType.ROOM);
giftShop.add(new RoomTrait({ exits: {}, isDark: false }));
giftShop.add(new IdentityTrait({
  name: 'Gift Shop',
  description:
    'A small zoo gift shop crammed with stuffed animals and ' +
    'postcards. A large souvenir penny press stands near the ' +
    'door. The aviary is back to the east.',
  aliases: ['gift shop', 'shop', 'store'],
  article: 'the',
}));
// Connect it west of the Aviary (and back east). This replaces
// the Aviary exits from Chapter 4, adding the west passage.
aviary.get(RoomTrait)!.exits = {
  [Direction.EAST]: { destination: mainPath.id },
  [Direction.WEST]: { destination: giftShop.id },
};
giftShop.get(RoomTrait)!.exits = {
  [Direction.EAST]: { destination: aviary.id },
};

const souvenirPress = world.createEntity(
  'souvenir press',
  EntityType.CONTAINER,
);
souvenirPress.add(new IdentityTrait({
  name: 'souvenir press',
  description:
    'A heavy cast-iron machine with a crank handle and a slot ' +
    'that accepts pennies. A sign reads: "INSERT PENNY, TURN ' +
    'HANDLE, KEEP FOREVER!"',
  aliases: ['press', 'souvenir press', 'penny press', 'machine'],
  article: 'a',
}));
souvenirPress.add(new ContainerTrait({
  capacity: { maxItems: 1 },
}));
souvenirPress.add(new SceneryTrait());
world.moveEntity(souvenirPress.id, giftShop.id);

// Remember the IDs the event handlers will match against.
this.roomIds.giftShop = giftShop.id;
this.roomIds.pettingZoo = pettingZoo.id;
this.entityIds.animalFeed = animalFeed.id;
this.entityIds.penny = penny.id;
this.entityIds.souvenirPress = souvenirPress.id;

The handlers themselves are registered in onEngineReady, which the engine calls once the world is fully built. The two reaction sections that follow both live inside it:

onEngineReady(engine: GameEngine): void {
  const world = engine.getWorld();
  // the chainEvent registrations below go here
}

13.5 Reaction pattern: the goats eat the feed

Putting it together: when the player drops the feed in the petting zoo, the goats react, but only once:

const feedId = this.entityIds.animalFeed;
const pettingZooId = this.roomIds.pettingZoo;

world.chainEvent(
  'if.event.dropped',
  (
    event: ISemanticEvent,
    w: IWorldModel,
  ): ISemanticEvent | null => {
    const data = event.data as Record<string, any>;

    // Is it the feed, dropped in the petting zoo?
    if (data.itemId !== feedId ||
        data.toLocation !== pettingZooId) {
      return null;
    }

    // Only react once
    if (w.getStateValue('goats-fed')) return null;
    w.setStateValue('goats-fed', true);

    return {
      id: `zoo-goats-eat-${Date.now()}`,
      type: 'zoo.event.goats_react',
      timestamp: Date.now(),
      entities: {},
      data: {
        text:
          'The pygmy goats spot the bag of feed and rush over! ' +
          'They crowd around, bleating excitedly, and devour ' +
          'the corn and pellets in seconds. The smallest goat ' +
          'looks up at you with big grateful eyes.',
      },
    };
  },
  { key: 'zoo.chain.goats-eat-feed' },
);

The getStateValue/setStateValue flag is the guard that keeps the goats from re-staging their feast every time the feed touches the ground.

Handlers can retune room prose, too. The snippet map from Chapter 5 is plain data on the room’s RoomTrait, and a handler may rewrite its entries at runtime. The goats handler above could leave a trace of the feast in the Petting Zoo’s own description (a shape to read, not code to type):

const zoo = w.getEntity(pettingZooId);
const roomTrait = zoo?.get(RoomTrait);
if (roomTrait?.snippets) {
  roomTrait.snippets.rabbits =
    ', while the rabbits nose through the scattered pellets';
}

This is the intended home for room prose that changes with the story: aftermath text after an explosion, a mention that goes quiet after hours. One convention keeps it safe: to silence an entry, set it to the empty string '' rather than deleting it, so the load-time unbound-marker check from Chapter 5 stays meaningful.

13.6 Transformation pattern: put A in, get B out

A classic puzzle shape: the player puts one item into a machine and a different item comes out. The souvenir press swallows a plain penny and produces a pressed one:

const pennyId = this.entityIds.penny;
const pressId = this.entityIds.souvenirPress;

world.chainEvent(
  'if.event.put_in',
  (
    event: ISemanticEvent,
    w: IWorldModel,
  ): ISemanticEvent | null => {
    const data = event.data as Record<string, any>;
    if (data.itemId !== pennyId ||
        data.targetId !== pressId) return null;

    // 1. Destroy the input
    w.removeEntity(pennyId);

    // 2. Create the output
    const pressedPenny = w.createEntity(
      'pressed penny',
      EntityType.ITEM,
    );
    pressedPenny.add(new IdentityTrait({
      name: 'pressed penny',
      description:
        'A flattened oval of copper with an embossed toucan.',
      aliases: ['pressed penny', 'pressed coin', 'souvenir'],
      properName: false,
      article: 'a',
    }));

    // 3. Hand it to the player
    const player = w.getPlayer();
    if (player) w.moveEntity(pressedPenny.id, player.id);

    // 4. Tell them what happened
    return {
      id: `zoo-press-penny-${Date.now()}`,
      type: 'zoo.event.penny_pressed',
      timestamp: Date.now(),
      entities: {},
      data: {
        text:
          'CLUNK! CRUNCH! WHIRRR! The souvenir press swallows ' +
          'the penny and spits out a beautiful pressed penny ' +
          'with an embossed toucan design. You pocket it ' +
          'proudly.',
      },
    };
  },
  { key: 'zoo.chain.penny-press' },
);

Remove the old entity, create the new one, move it to the player, return the text. That four-step shape covers a surprising number of machines, ovens, forges, and vending slots.

The { key: '...' } option gives each handler a unique identifier, which the engine needs to manage handlers across saves and reloads.

13.7 Try it

> south                     Main Path
> east                      Petting Zoo
> take feed                 Pick up the bag of animal feed
> drop feed                 The goats rush over!
> west                      Back to Main Path
> take penny                Grab the souvenir penny
> west                      Aviary
> west                      Gift Shop
> examine press             See the souvenir press
> put penny in press        CLUNK! CRUNCH! WHIRRR!
> inventory                 You're holding a pressed penny

13.8 Test it

Both reactions, the goats’ feast and the penny press, now have observable outcomes worth guarding. Add tests/transcripts/event-handlers.transcript:

title: Event handlers
story: familyzoo
description: Goats devour dropped feed; the press transforms the penny

---

> south
[OK: contains "Main Path"]

> east
[OK: contains "Petting Zoo"]

> take feed
[OK: contains "Taken"]

> drop feed
[OK: contains "devour"]

> west
[OK: contains "Main Path"]

> take penny
[OK: contains "Taken"]

> west
[OK: contains "Aviary"]

> west
[OK: contains "Gift Shop"]

> examine press
[OK: contains "INSERT PENNY"]

> put penny in press
[OK: contains "CLUNK"]

> inventory
[OK: contains "pressed penny"]

13.9 Key takeaway

Event handlers let standard actions do the work while you react to what they emit. world.registerEventHandler() runs silently for state bookkeeping; world.chainEvent() returns an event with a text field to show the player something. Match on itemId/targetId (not names), guard one-time reactions with a state flag, and never return game.message from a chain handler. Use a custom event type so your reaction adds to the action’s text instead of replacing it.

14 Custom Actions: Teaching the Parser New Verbs

Event handlers let you react to verbs the stdlib already knows. But sometimes the verb itself doesn’t exist yet. There’s no feed action in the standard library, no photograph. When you need a brand-new verb, you write a custom action, and wiring one up means touching every layer of Sharpee at once: the action logic, the grammar that recognizes the words, and the language that holds the text. This chapter feeds the goats and snaps photos to show all three.

Wiring an action touches several packages, so this chapter’s imports span a few. The block below is the complete set the chapter’s code relies on; your file already imports several of these (ISemanticEvent since Chapter 13, the world-model names since Chapter 2), so add only the ones you’re missing (TypeScript rejects importing the same identifier twice):

import {
  Action, ActionContext, ValidationResult,
} from '@sharpee/stdlib';
import type { Parser } from '@sharpee/parser-en-us';
import type { LanguageProvider } from '@sharpee/lang-en-us';
import { ISemanticEvent } from '@sharpee/core';
import {
  IdentityTrait, IFEntity, EntityType,
} from '@sharpee/world-model';

The action objects below are top-level consts. The three registration methods (getCustomActions, extendParser, extendLanguage) are members of your FamilyZooStory class, alongside initializeWorld.

14.1 The four-phase action

Every action, standard or custom, implements the same four-phase pattern you met in The Standard Actions. A custom action is just an Action object with those four methods. The skeleton below is a schematic of that shape (the illustrative rule): hasRequiredItem is a stand-in that exists nowhere, so typed literally it would not compile. There is nothing to type until the real feedAction in the next section:

const feedAction: Action = {
  id: 'zoo.action.feeding',
  group: 'interaction',

  // Phase 1: can the action proceed?
  validate(context: ActionContext): ValidationResult {
    if (!hasRequiredItem) {
      return { valid: false, error: 'no_feed' };
    }
    return { valid: true };
  },

  // Phase 2: mutate the world (only runs if valid)
  execute(context: ActionContext): void {
    context.world.setStateValue('item-used', true);
  },

  // Phase 3: success events (text output)
  report(context: ActionContext): ISemanticEvent[] {
    return [context.event('zoo.event.fed', {
      messageId: 'fed_goats',
    })];
  },

  // Phase 4: failure events (runs instead of
  // execute/report if invalid)
  blocked(
    context: ActionContext,
    result: ValidationResult,
  ): ISemanticEvent[] {
    return [context.event('zoo.event.feeding_blocked', {
      messageId: result.error,
    })];
  },
};

The engine runs them in order: validate() first; if it returns { valid: false } it jumps straight to blocked(); otherwise it calls execute() then report(). Validation checks, world mutation, success text, and failure text each live in their own phase, never tangled together.

14.2 A complete custom action: feeding

Here’s the feed action in full. It confirms the player is carrying feed, that the target is a feedable animal, and that the animal hasn’t already eaten:

const FEED_ACTION_ID = 'zoo.action.feeding';

const FeedMessages = {
  NO_FEED: 'zoo.feeding.no_feed',
  NOT_AN_ANIMAL: 'zoo.feeding.not_animal',
  ALREADY_FED: 'zoo.feeding.already_fed',
  FED_GOATS: 'zoo.feeding.fed_goats',
  FED_RABBITS: 'zoo.feeding.fed_rabbits',
  FED_GENERIC: 'zoo.feeding.fed_generic',
} as const;

const feedAction: Action = {
  id: FEED_ACTION_ID,
  group: 'interaction',

  validate(context: ActionContext): ValidationResult {
    const target = context.command.directObject?.entity;

    // Player must be carrying the feed
    const inventory = context.world
      .getContents(context.player.id);
    const hasFeed = inventory.some(item =>
      item.get(IdentityTrait)?.aliases?.includes('feed'));
    if (!hasFeed) {
      return { valid: false, error: FeedMessages.NO_FEED };
    }

    // There must be a target, and it must be feedable
    if (!target) {
      return { valid: false, error: FeedMessages.NOT_AN_ANIMAL };
    }
    const name =
      target.get(IdentityTrait)?.name?.toLowerCase() || '';
    const feedable = ['pygmy goats', 'rabbits']
      .some(a => name.includes(a));
    if (!feedable) {
      return { valid: false, error: FeedMessages.NOT_AN_ANIMAL };
    }

    // Not already fed
    if (context.world.getStateValue(`fed-${target.id}`)) {
      return { valid: false, error: FeedMessages.ALREADY_FED };
    }

    // Hand the target to the later phases
    context.sharedData.feedTarget = target;
    return { valid: true };
  },

  execute(context: ActionContext): void {
    const target = context.sharedData.feedTarget as IFEntity;
    if (target) {
      context.world.setStateValue(`fed-${target.id}`, true);
    }
  },

  report(context: ActionContext): ISemanticEvent[] {
    const target = context.sharedData.feedTarget as IFEntity;
    const name =
      target?.get(IdentityTrait)?.name?.toLowerCase() || '';

    let messageId: string = FeedMessages.FED_GENERIC;
    if (name.includes('goats')) {
      messageId = FeedMessages.FED_GOATS;
    } else if (name.includes('rabbits')) {
      messageId = FeedMessages.FED_RABBITS;
    }

    return [context.event('zoo.event.fed', {
      messageId,
      params: {
        animal: target?.get(IdentityTrait)?.name || 'animal',
      },
    })];
  },

  blocked(
    context: ActionContext,
    result: ValidationResult,
  ): ISemanticEvent[] {
    return [context.event('zoo.event.feeding_blocked', {
      messageId: result.error || FeedMessages.NOT_AN_ANIMAL,
    })];
  },
};