@cyoa/engine

A flexible and extensible engine for creating "Choose Your Own Adventure" (CYOA) style games. It's designed to be used in any JavaScript environment, from web browsers to Node.js servers.

Features

• Simple and flexible story format: Define your story in JSON or YAML.
• State management: The engine handles all game state, including stats, variables, and visited beats.
• Extensible: Add your own custom logic with plugins.
• Deterministic: Use a seed to create a deterministic random number generator for reproducible playthroughs.

Installation

You can install the engine using your favorite package manager:

npm install @cyoa/engine
# or
yarn add @cyoa/engine
# or
pnpm add @cyoa/engine

Usage

Here's a minimal example of how to use the engine:

import { Engine } from '@cyoa/engine';
import type { Story } from '@cyoa/engine';

// Define a simple story
const story: Story = {
  id: 'my-first-story',
  version: '1.0.0',
  start: 'intro',
  knots: {
    main: {
      beats: {
        intro: {
          text: 'You are in a dark room. There is a door to your left and a door to your right.',
          choices: [
            { text: 'Go left', target: 'left_door' },
            { text: 'Go right', target: 'right_door' },
          ],
        },
        left_door: {
          text: 'You found the exit!',
        },
        right_door: {
          text: 'You fell into a pit!',
        },
      },
    },
  },
};

// Create a new engine instance
const engine = new Engine({ story });

// Get the current beat
let currentBeat = engine.current();
console.log(currentBeat.text); // "You are in a dark room. There is a door to your left and a door to your right."

// Get the available choices
const choices = engine.choices();
console.log(choices.map(c => c.text)); // ["Go left", "Go right"]

// Make a choice
currentBeat = engine.step(0); // or engine.step('intro#0')
console.log(currentBeat.text); // "You found the exit!"

Core Concepts

Story

A story is a JavaScript object that defines the structure of your game. It contains:

• id: A unique identifier for your story.
• version: The version of your story.
• start: The ID of the beat where the story begins.
• knots: A collection of "knots," which are groups of related "beats."
• beats: The individual moments in your story. A beat can have text, choices, and actions that modify the game state.

GameState

The GameState object represents the current state of the game. It includes:

• beatId: The ID of the current beat.
• stats: A key-value store for numerical stats (e.g., health, mana).
• vars: A key-value store for any other data you want to track.
• visited: A record of how many times each beat has been visited.
• seed: The seed used to initialize the random number generator.

Engine

The Engine class is the heart of the package. It takes a story object and manages the game state as the player progresses through the story. It provides methods to:

• Get the current beat and available choices.
• Make a choice and transition to the next beat.
• Save and load the game state.
• And much more!