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 with traits:

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

export function createVillage(world: WorldModel) {
  // Create rooms as entities with traits
  const square = world.createEntity('village-square', EntityType.ROOM);
  square.add(new IdentityTrait({
    name: 'Village Square',
    description: 'A bustling square with a fountain at its center.',
  }));
  square.add(new RoomTrait());

  const tavern = world.createEntity('tavern', EntityType.ROOM);
  tavern.add(new IdentityTrait({
    name: 'The Rusty Mug',
    description: 'A warm tavern smelling of ale and roasted meat.',
  }));
  tavern.add(new RoomTrait());

  // Connect rooms via RoomTrait exits
  const squareTrait = square.get(RoomTrait);
  if (squareTrait) {
    squareTrait.exits[Direction.EAST] = { destination: tavern.id };
  }
  const tavernTrait = tavern.get(RoomTrait);
  if (tavernTrait) {
    tavernTrait.exits[Direction.WEST] = { destination: square.id };
  }

  // Objects in this region
  const coin = world.createEntity('coin', EntityType.OBJECT);
  coin.add(new IdentityTrait({
    name: 'silver coin',
    description: 'A tarnished silver coin.',
  }));
  world.moveEntity(coin.id, square.id);

  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.