Installation

Prerequisites

• Node.js 18 or later
• npm or pnpm (recommended)
• A code editor (VS Code recommended for TypeScript support)

Create a New Project

The fastest way to get started is with the CLI:

npx @sharpee/sharpee init my-adventure
cd my-adventure
npm install

This scaffolds a complete story project with a starting room, build scripts, and TypeScript configuration.

For non-interactive setup (CI or scripting):

npx @sharpee/sharpee init my-adventure -y

Add to an Existing Project

If you already have a TypeScript project:

npm install @sharpee/sharpee

Or with pnpm:

pnpm add @sharpee/sharpee

What You Get

@sharpee/sharpee is the umbrella package. One install gives you:

You import everything from @sharpee/sharpee — no need to install individual packages.

Project Structure

A Sharpee story is organized by regions. Each region is a single TypeScript file containing everything in that area — rooms, objects, and connections:

my-adventure/
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts              # Story entry point
│   ├── regions/
│   │   ├── village.ts        # Rooms, objects, connections for the village
│   │   ├── forest.ts         # Everything in the forest area
│   │   └── dungeon.ts        # Underground rooms and items
│   ├── npcs/                 # NPC definitions (optional)
│   │   └── merchant.ts
│   └── actions/              # Story-specific actions (optional)
│       └── pray.ts
└── tests/
    └── transcripts/          # Test transcripts
        └── walkthrough.transcript

Each region file exports a setup function that creates entities using the entity helpers API:

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

export function createVillage(world: WorldModel) {
  const { room, object } = world.helpers();

  const square = room('Village Square')
    .description('A bustling square with a fountain at its center.')
    .build();

  const tavern = room('The Rusty Mug')
    .description('A warm tavern smelling of ale and roasted meat.')
    .build();

  world.connectRooms(square.id, tavern.id, Direction.EAST);

  object('silver coin')
    .description('A tarnished silver coin.')
    .in(square)
    .build();

  return { square, tavern };
}

TypeScript Configuration

The scaffolded project includes a working tsconfig.json. If setting up manually:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "commonjs",
    "moduleResolution": "node",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "./dist",
    "declaration": true
  },
  "include": ["src/**/*"]
}

Building

Once you’ve written your story, build it with the CLI:

npx @sharpee/sharpee build

This creates two outputs:

• dist/<story>.sharpee — Bundle for the Zifmia desktop runner
• dist/web/ — Static browser client you can deploy anywhere

To add browser support to your project (required for the browser output):

npx @sharpee/sharpee init-browser

Next Steps

Continue to the Quick Start guide to build your first playable story.