@sharpee/sharpee

A modern TypeScript interactive fiction engine for creating text adventures and parser-based games.

Installation

Add the runtime library to a project that embeds the engine:

npm install @sharpee/sharpee

To scaffold and build a story from the command line, install the devkit globally — it provides the sharpee CLI:

npm install -g @sharpee/devkit
# then
sharpee init my-story
sharpee build

Features

• Event-Driven Architecture - Immutable events for all state changes
• Rich World Model - Entities with traits, behaviors, and relationships
• Natural Language Parser - Understands complex player commands
• Extensible - Add custom actions, behaviors, and game mechanics
• Type-Safe - Full TypeScript with strict typing

Quick Start

import {
  GameEngine,
  EnglishParser,
  EnglishLanguageProvider
} from '@sharpee/sharpee';
// WorldModel is re-exported type-only; constructing a world imports the sub-package
import { WorldModel } from '@sharpee/world-model';

// Set up language + parser
const language = new EnglishLanguageProvider();
const parser = new EnglishParser(language);

// Build the engine (world and player typically come from your story setup)
const world = new WorldModel();
const engine = new GameEngine({ world, player, parser, language });

// Register the story, then start
engine.setStory(story);
engine.start();

// Process player commands
const result = await engine.executeTurn('look');

Rendering is no longer a separate text service (ADR-174). The engine's prose pipeline produces ITextBlock[] that are carried to the UI by channels (ADR-163); use renderToString to flatten blocks for a plain-text host.

What's Included

This umbrella package re-exports the story runtime baseline — the imports a story author needs (ADR-178). It deliberately does not re-export every symbol from every sub-package; for advanced use, import the specific sub-package directly (e.g. @sharpee/world-model, @sharpee/stdlib).

| Export | Description | |--------|-------------| | GameEngine | Main game runtime | | WorldModel, IFEntity, TraitType | Entity and world management (types) | | EnglishParser | Natural language command parser | | EnglishLanguageProvider | English language provider | | renderToString, renderStatusLine | Flatten prose blocks for a text host | | ITextBlock, IDecoration | Prose-pipeline output types (ADR-096) | | QueryManager | Player input queries (yes/no, menus) |

Standard Actions

The engine includes 57 standard IF actions out of the box:

• Movement: go, enter, exit
• Manipulation: take, drop, put, insert, remove
• Interaction: open, close, lock, unlock, push, pull
• Observation: look, examine, search, read
• Communication: talk, give, show
• Meta: save, restore, quit, inventory, score

Documentation

• GitHub Repository
• Author's Tutorial — build a complete story, eight chapters
• Chord Language Guide
• Stdlib Reference
• API Reference
• Architecture Decisions

Example Stories

See the stories directory for complete examples:

• Cloak of Darkness - The classic IF benchmark
• Dungeo - Full implementation of Mainframe Zork (~190 rooms)

Requirements

• Node.js 18+
• TypeScript 5.3+ (for development)

License

MIT