Sharpee

A parser-based Interactive Fiction authoring platform built in TypeScript.

Quick Start

The sharpee CLI ships in @sharpee/devkit — install it globally:

npm install -g @sharpee/devkit

Scaffold a project, then build and play:

sharpee init my-adventure
cd my-adventure
npm install
sharpee build
open dist/web/index.html

Command	What it does
sharpee init <name>	Create a new story project
sharpee init-browser	Add browser client to existing project
sharpee build	Build .sharpee bundle + browser client
sharpee build-browser	Build browser client only
sharpee ifid	Generate or validate an IFID

What's Included

@sharpee/sharpee is the umbrella package — it re-exports the story runtime baseline (ADR-178), the imports a story author needs. It deliberately does not re-export every symbol; for advanced use, import a sub-package directly. All 28 packages below are published individually on npm under the @sharpee scope.

Package	Description
@sharpee/sharpee	Umbrella package — re-exports the story runtime baseline (ADR-178)
@sharpee/core	Event system, types, utilities
@sharpee/engine	Game engine, turn cycle, command execution
@sharpee/event-processor	Applies semantic events to the world model
@sharpee/world-model	Entity system with traits and behaviors
@sharpee/if-domain	Core domain model and contracts
@sharpee/if-services	Runtime service interfaces (perception)
@sharpee/stdlib	51 standard IF actions (take, drop, open, lock, etc.)
@sharpee/lang-en-us	English language output
@sharpee/parser-en-us	English natural language parser
@sharpee/helpers	Fluent entity builders (world.helpers())
@sharpee/queries	LINQ-style fluent entity query API
@sharpee/character	NPC behavior chain: character model, conversation, goals, influence, propagation
@sharpee/plugins	Plugin contracts for engine turn-cycle extensibility
@sharpee/plugin-npc	NPC behaviors and autonomous turn processing
@sharpee/plugin-scheduler	Daemons and fuses (timed events)
@sharpee/plugin-state-machine	Declarative puzzle and narrative orchestration
@sharpee/media	Audio event types, AudioRegistry, and capability negotiation
@sharpee/text-blocks	Structured text output interfaces (ITextBlock, IDecoration)
@sharpee/channel-service	Universal channel-I/O wire producer (ADR-163)
@sharpee/platform-browser	Framework-free browser client infrastructure
@sharpee/ext-basic-combat	Generic skill-based combat extension
@sharpee/ext-testing	Debug and testing tools (/debug, /trace, $teleport)
@sharpee/bootstrap	Story loader — assembles a .sharpee story into a runnable game
@sharpee/devkit	The sharpee CLI — build/test/verify/scaffold orchestration (ADR-180)
@sharpee/story-runtime-baseline	Manifest of the canonical baseline packages a bundle may import (ADR-178)
@sharpee/ide-protocol	Wire types for the IDE project-introspection manifest (ADR-184)
@sharpee/transcript-tester	Transcript-based testing framework

Features

• Event-Driven Architecture — Immutable semantic events for all state changes
• Natural Language Parser — Complex player commands with slot constraints
• Rich World Model — Entities with traits, behaviors, and relationships
• 51 Standard Actions — take, drop, open, close, lock, unlock, wear, eat, drink, attack, and more
• Four-Phase Action Pattern — Consistent validate/execute/report/blocked flow
• Capability Dispatch — Entity-specific handling for generic verbs
• Entity Helpers — Fluent builder API for rooms, objects, containers, doors, actors
• NPC Behavior Chain — Character model with psychology, constraint-based conversation, goal pursuit, information propagation, and NPC-to-NPC influence
• Direction Vocabularies — Location-relative directions (compass, naval, minimal, or custom)
• Audio System — Typed audio events, AudioRegistry, procedural sound, atmosphere builder
• Daemons & Fuses — Timed events and background processes
• Perception System — Darkness, blindness, and sensory restrictions
• Language Layer Separation — All text output goes through localizable message IDs
• Channel-Based UI — Story→UI signals flow over channels (ADR-163); the same story runs in the CLI, a framework-free browser client, and the Zifmia multi-user server
• Full TypeScript — Strict typing throughout

Creating a Story

import { Story, StoryConfig } from '@sharpee/engine';
import { WorldModel, IFEntity, Direction } from '@sharpee/world-model';
import '@sharpee/helpers';

export const config: StoryConfig = {
  id: 'my-adventure',
  title: 'My Adventure',
  author: 'Your Name',
  version: '1.0.0',
};

export class MyStory implements Story {
  config = config;

  initializeWorld(world: WorldModel): void {
    const { room, object } = world.helpers();

    const start = room('Starting Room')
      .description('A simple room with a lamp on the floor.')
      .build();

    object('brass lamp')
      .description('A well-polished brass lamp.')
      .in(start)
      .build();

    const player = world.getPlayer();
    world.moveEntity(player!.id, start.id);
  }

  createPlayer(world: WorldModel): IFEntity {
    const { actor } = world.helpers();

    return actor('yourself')
      .description('As good-looking as ever.')
      .aliases('self', 'me')
      .properName()
      .inventory({ maxItems: 10 })
      .build();
  }
}

export const story = new MyStory();
export default story;

See the Getting Started guide for a complete walkthrough.

Entity Helpers

world.helpers() returns fluent builders for common entity types:

import '@sharpee/helpers';

const { room, object, container, actor, door } = world.helpers();

// Rooms
const cave = room('Dark Cave').description('A damp cave.').dark().build();

// Objects with custom traits
const note = object('crumpled note')
  .description('A crumpled piece of paper.')
  .addTrait(new ReadableTrait({ text: 'The code is 4-7-2.' }))
  .in(cave)
  .build();

// Containers
const chest = container('wooden chest')
  .openable({ isOpen: false })
  .lockable({ isLocked: true, keyId: key.id })
  .in(cave)
  .build();

// Items in closed containers (bypasses validation)
object('gold coin').skipValidation().in(chest).build();

// Doors between rooms
door('iron door')
  .between(cave, hallway, Direction.NORTH)
  .openable({ isOpen: false })
  .build();

Architecture

+-----------------------------------------------+
|              Your Story                       |
+--------------------+--------------------------+
| stdlib (actions)   | lang-en-us (messages)    |
| plugins (npc,      | parser-en-us (grammar)   |
|  scheduler, state) |                          |
+--------------------+--------------------------+
| engine | world-model | helpers | channels     |
+-----------------------------------------------+
| if-domain | if-services | event-processor     |
+-----------------------------------------------+
| core (events, types) | media (audio types)   |
+-----------------------------------------------+

Rendering is the engine's prose pipeline producing ITextBlock[], carried to the UI by channels (ADR-163/174) — there is no separate text service.

Key Principles

1. Actions emit semantic events, not text — The language layer converts message IDs to prose
2. Behaviors own mutations — Actions coordinate, behaviors perform state changes
3. Traits compose entity capabilities — Add container, lockable, wearable, etc.
4. Parser scope is permissive — Actions decide if visibility is truly required

Zifmia Multi-User Server

Zifmia is the multi-user server (ADR-177) for hosting .sharpee story bundles — each player gets their own session over a shared story, with per-room saves. It ships as a self-contained Docker container and is built with sharpee build --zifmia.

Standard Actions

Movement: going, entering, exiting, climbing Manipulation: taking, dropping, putting, inserting, removing, giving, throwing Containers/Doors: opening, closing, locking, unlocking Examination: looking, examining, searching, reading Interaction: talking, showing, attacking Devices: switching on/off, pushing, pulling, raising, lowering Wearables: wearing, taking off Consumables: eating, drinking Senses: touching, smelling, listening Meta: inventory, score, help, save, restore, restart, quit, undo, again, wait, about, version, sleep

Repository Development

git clone https://github.com/ChicagoDave/sharpee.git
cd sharpee
pnpm install

# Build everything (devkit; ADR-180)
./sharpee build dungeo

# Run tests
pnpm test

# Run specific package tests
pnpm --filter '@sharpee/stdlib' test

# Run story transcript tests
node dist/cli/sharpee.js --test stories/dungeo/tests/transcripts/*.transcript

Example Stories

Story	Location	Description
dungeo	stories/dungeo	Mainframe Zork implementation (~191 rooms, 650 points + 100 endgame)
familyzoo	tutorials/familyzoo	The book's Family Zoo — chapter-by-chapter tutorial snapshots, built against the published npm packages
entropy	stories/entropy	Original sci-fi story with audio system (in progress)

Roadmap

Sharpee is actively developed. These are the open Architecture Decision Records representing planned future work.

Recently Implemented

• NPC Behavior Chain (ADR-141, 142, 144, 145, 146) — Character psychology, conversation, goal pursuit, information propagation, NPC influence
• Direction Vocabularies (ADR-143) — Location-relative directions (compass, naval, minimal, custom)
• Audio System (ADR-138) — SFX, music, ambient, procedural audio, AudioRegistry
• Entity Helpers (ADR-140) — Fluent builder API for story setup
• Action Interceptors (ADR-118) — Story-level hooks on standard actions

Accepted (Implementation Planned)

• Screen Reader Accessibility (ADR-100) — ARIA support for the Zifmia client
• Speech Accessibility (ADR-139) — TTS/STT for blind and motor-impaired players
• Equivalent Objects (ADR-147) — Identical object groups, numeric commands, trade/sell/barter

Proposed

Area	ADR	Description
Story Paradigms	ADR-083	Spirit PC — Non-physical player character support
Story Paradigms	ADR-102	Dialogue Extension — NPC conversation systems (ASK/TELL, menus)
Story Paradigms	ADR-103	Choice-Based Stories — CYOA-style with parser hybrid
World Model	ADR-020	Clothing and Pockets — Container hierarchy for wearable items
Clients	ADR-098	Terminal Client — CLI-based game client
Clients	ADR-099	GLK Client — Standard IF interpreter protocol
Clients	ADR-122	Rich Media and Story Styling — Embedded media in output
Zifmia	ADR-125	Panel and Windowing System — Multi-panel desktop client
Zifmia	ADR-128	Walkthrough Panel — In-client walkthrough display
Zifmia	ADR-130	Story Installers — Split runner from author packaging tool
Author Tools	ADR-115	Map Export CLI — Export story maps from code
Author Tools	ADR-116	Prompt-to-Playable — AI-assisted story development
Author Tools	ADR-131	Automated World Explorer — Regression test generator
Engine	ADR-127	Location-Scoped Interceptors — Room-tied action interceptors

See the full ADR index for the complete set of architecture decisions.

License

MIT License — Copyright 2025-2026 David Cornelson

Links

• Website
• npm Package
• Documentation
• Downloads (Zifmia)
• Issue Tracker