Getting Started

Inspired by Twine SugarCube, Sugarbox is a lightweight¹, headless, framework-agnostic library for building web-based 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
• Achievements and settings stored separately from save slots
• Headless by design (you bring the renderer and UI)

---

Installation

This library is uploaded to npm at https://www.npmjs.com/package/sugarbox

npm

npm install sugarbox

pnpm

pnpm install sugarbox

yarn

yarn install sugarbox

bun

bun install sugarbox

Sample usage

Notes on the current API:

• Engine initialization uses vars (not variables)
• Passage content lives on passage.data (not passage.passage)

import { SugarboxEngine } from "sugarbox";

const startPassage = {
  name: "Start",
  data: "You wake up in a quiet room.",
  tags: ["intro"],
};

const otherPassages = [
  { name: "Hallway", data: "A long corridor stretches ahead." },
];

const engine = await SugarboxEngine.init({
  name: "Test",
  vars: { playerName: "Dave", inventory: { gold: 123, gems: 12 } },
  startPassage,
  otherPassages,
  // Optionally: config, classes, achievements, settings, migrations
});

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

engine.navigateTo("Hallway");

Footnotes

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