Sharpee Sharpee

Quick Start

Create Your Project

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

The scaffolded project gives you a single starting room. Let’s expand it into a two-region story.

Build a Region

Create src/regions/house.ts with a few connected rooms and objects. The entity helpers API lets you build rooms and objects with a fluent builder:

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


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


  // Rooms
  const foyer = room('Foyer')
    .description('A grand entrance hall with marble floors. A doorway leads north to the library.')
    .build();


  const library = room('Library')
    .description('Dusty bookshelves line every wall. A reading desk sits beneath a window.')
    .build();


  // Connect rooms
  world.connectRooms(foyer.id, library.id, Direction.NORTH);


  // Objects
  const book = object('dusty book')
    .description('An ancient tome with faded gold lettering.')
    .in(library)
    .build();


  const key = object('brass key')
    .description('A small brass key with an ornate handle.')
    .in(foyer)
    .build();


  return { foyer, library };
}

Each builder handles entity creation, IdentityTrait, and RoomTrait automatically. The .in() method accepts an entity directly for compile-time safety.

Wire It Into Your Story

Update src/index.ts to use the region:

import { Story, StoryConfig } from '@sharpee/engine';
import { WorldModel, IFEntity } from '@sharpee/world-model';
import '@sharpee/helpers';
import { createHouse } from './regions/house';


export const config: StoryConfig = {
  id: 'my-adventure',
  title: 'My Adventure',
  author: 'Your Name',
  version: '1.0.0',
  description: 'A short adventure in a mysterious house.',
};


export class MyAdventure implements Story {
  config = config;


  initializeWorld(world: WorldModel): void {
    const house = createHouse(world);


    // Place the player in the foyer
    const player = world.getPlayer();
    if (player) {
      world.moveEntity(player.id, house.foyer.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 MyAdventure();
export default story;

Containers and Locked Doors

The helpers support containers, doors, and placing items in closed containers during setup:

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


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


  const foyer = room('Foyer')
    .description('A grand entrance hall. A locked door leads east.')
    .build();


  const study = room('Study')
    .description('A private study with a mahogany desk.')
    .build();


  // Locked door between rooms
  const key = object('brass key')
    .description('A small brass key.')
    .in(foyer)
    .build();


  door('oak door')
    .description('A heavy oak door with a brass lock.')
    .between(foyer, study, Direction.EAST)
    .openable({ isOpen: false })
    .lockable({ isLocked: true, keyId: key.id })
    .build();


  // Closed chest with a gem inside
  const chest = container('wooden chest')
    .description('A sturdy wooden chest with iron bands.')
    .openable({ isOpen: false })
    .in(study)
    .build();


  // .skipValidation() bypasses the "container is closed" rule
  object('sparkling gem')
    .description('A gem that catches the light.')
    .skipValidation()
    .in(chest)
    .build();


  return { foyer, study };
}

Custom Traits

For traits the builders don’t have explicit methods for, use .addTrait():

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


const note = object('crumpled note')
  .description('A crumpled piece of paper.')
  .addTrait(new ReadableTrait({
    text: 'The combination is 4-7-2.'
  }))
  .in(study)
  .build();

Build Your Story

Build the .sharpee bundle and browser client:

Terminal window
npx @sharpee/sharpee build

This produces:

  • dist/my-adventure.sharpee — Story bundle for the Zifmia desktop runner
  • dist/web/ — Browser client you can host anywhere

To play, open dist/web/index.html in your browser — no server needed.

Try these commands in the game:

  • look — describe the current room
  • north or n — move north
  • examine book — look at something
  • take key — pick up an item
  • inventory — see what you’re carrying
  • unlock door with key — unlock a locked door
  • open chest — open a container

Next Steps