Getting Started

Inspired by Twine SugarCube, Choicekit is a lightweight¹, headless, framework-agnostic library for building interactive fiction.

---

Features

• Passages and navigation
• State with snapshot-based history
• Saving and loading with versioning, optional compression, and migrations
• Deterministic pseudorandom number generation (PRNG)
• Custom class serialization for richer game objects
• Headless by design (you bring the renderer and UI)

---

Installation

Install from npm package choicekit.

npm

npm install choicekit

pnpm

pnpm add choicekit

yarn

yarn add choicekit

bun

bun add choicekit

Sample usage

Notes on the current API:

• Prefer ChoicekitEngineBuilder for ergonomic type-safe setup
• Passage content lives on passage.data

import { ChoicekitEngineBuilder } from "choicekit";

const engine = await new ChoicekitEngineBuilder()
  .withName("test-story")
  .withPassages(
    { name: "Start", data: "You wake up in a quiet room.", tags: ["intro"] },
    { name: "Hallway", data: "A long corridor stretches ahead." },
  )
  .withVars({ playerName: "Dave", inventory: { gold: 123, gems: 12 } })
  .build();

engine.setVars((state) => {
  state.playerName = "Sheep";
  state.inventory.gems = 21;
});

engine.navigateTo("Hallway");

Footnotes

1. Less than 8KB after minification and gzip compression ↩