This is a framework for creating and playing through non-linear interactive stories. Everything runs client-side in your browser -- files never leave your computer.
If you like this, consider supporting further development!
This project is a pnpm monorepo with three packages:
packages/shared/-- Shared TypeScript types, utilities, and action systempackages/editor/-- Web-based story creation tool (React Flow graph editor)packages/viewer/-- Web-based story player (Markdown rendering, save/load progress)stories/-- Example stories and story collectionscripts/-- Build scripts for bundle generation
- React 19 + TypeScript -- Modern UI framework with type safety
- React Flow (
@xyflow/react) -- Graph editor (replaces Cytoscape.js) - Vite -- Fast build tool with HMR
- pnpm workspaces -- Monorepo dependency management
- Vitest + Playwright -- Comprehensive testing suite
- Node.js >= 18.0.0
- pnpm >= 9.0.0
# Install dependencies
pnpm install# Run viewer in dev mode (http://localhost:5174)
pnpm --filter viewer dev
# Run editor in dev mode (http://localhost:5173)
pnpm --filter editor dev
# Run all packages in dev mode
pnpm dev# Run unit tests
pnpm test
# Run E2E tests
pnpm test:e2e
# Type check
pnpm typecheck
# Full verification (typecheck + test + test:e2e)
pnpm verify# Build all packages
pnpm build
# Download launcher binaries (tVeb web server for bundle launcher)
pnpm download:launcher-binaries
# Build viewer bundle for ZIP export (includes viewer + launcher)
pnpm build:viewer-for-bundleNote: The editor's bundle generation feature requires the viewer bundle to be built first. Run pnpm download:launcher-binaries and pnpm build:viewer-for-bundle before generating playable adventure bundles. The generated bundles include a minimal self-contained web server, making them directly launchable on Windows and Linux without any additional software.
Stories are JSON files. See the example story for the format and the stories README for a list of available stories.
A story consists of:
- Sections -- Story content linked via choices in the
.nextarray. Sections without choices are terminal. - State -- Current game state including variables (for consistent naming, conditional logic, etc.)
- Media -- Images/videos per section, either linked or embedded as data URIs.
Choices may have a description (displayed as a clickable option) or be empty (acting as a simple "next" button for pagination).
The editor can export stories as standalone ZIP bundles that include:
- Pre-built viewer application
- Story JSON and media files
- Self-contained web server binaries (Windows + Linux)
- Launch scripts for easy startup
- README with usage instructions
All launcher files are placed at the top level of the bundle for easy access.
Users can run bundles by:
- Linux/macOS: Double-click
run_story_adventure.shor run from terminal - Windows: Double-click
run_story_adventure.bator use PowerShell script
The launcher automatically starts the web server and opens the story in the default browser. No installation or configuration required.
Web Server: Bundles use tVeb (Tiniest Veb Server), a minimal (~1.5 MB) open-source static file server.
This project uses the following open source components:
- React -- UI framework
- React Flow -- Graph editor (replaces Cytoscape.js)
- Bootstrap 5 -- UI components
- marked -- Markdown rendering in the viewer
- DOMPurify -- HTML sanitization in the viewer
- JSZip -- Bundle export (zipping)
- file-saver -- Large file downloads from browser memory
- Vite -- Build tool
- Vitest -- Test runner
- Playwright -- E2E testing
See the respective project pages for licenses and meta-dependencies.
Copyright 2024-2025 Sebastian Schmittner
All code published in this repository is free software: it can be redistributed and/or modified under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. See LICENSE for details.
For included open source dependencies, different licenses may apply. See the respective project pages listed above.
