@whisker/core-ts

Core TypeScript runtime for Whisker interactive fiction engine.

Overview

This package contains the core models, types, and utilities for the Whisker story engine. It is framework-agnostic and can be used in any JavaScript/TypeScript environment.

Installation

npm install @whisker/core-ts
# or
pnpm add @whisker/core-ts

What's Included

Models

• Story - The main story container with passages, variables, and metadata
• Passage - Individual story passages/nodes with content and choices
• Choice - Player choices that navigate between passages
• Variable - Story variables with types (string, number, boolean)
• LuaFunction - Custom Lua functions for scripting
• ScriptBlock - Script blocks for passage logic
• Playthrough - Player session tracking
• ChangeLog - Story change history
• Comment - Comments and annotations
• Collaborator - Collaborator information

Validation

• StoryValidator - Main story validation with pluggable validators

  • Dead Links Validator - Find broken passage links
  • Empty Passages Validator - Find passages with no content
  • Missing Start Passage Validator - Ensure start passage exists
  • Undefined Variables Validator - Find undefined variable references
  • Unreachable Passages Validator - Find unreachable passages
  • Unused Variables Validator - Find unused variables
  • Validate Assets Validator - Validate asset references
  • Validate IFID Validator - Validate Interactive Fiction ID
  • Validate Passage Metadata Validator - Validate passage metadata
  • Validate Scripts Validator - Validate Lua scripts
  • Validate Stylesheets Validator - Validate CSS stylesheets

• AutoFixer - Automatically fix validation issues

• QualityAnalyzer - Analyze story quality and provide recommendations

• createDefaultValidator() - Create validator with all default validators

Utilities

• whiskerCoreAdapter - Format conversion between editor and runtime formats

  • toWhiskerCoreFormat() - Convert to Whisker Core format (v1.0, v2.0)
  • toWhiskerFormatV21() - Convert to Whisker Format v2.1 with editorData
  • fromWhiskerCoreFormat() - Import from Whisker Core format
  • importWhiskerFile() - Auto-detect format and import
  • generateIfid() - Generate Interactive Fiction ID (UUID v4)

• idGenerator - Unique ID generation

  • generateId() - Generate timestamp-based unique IDs

Types

Complete TypeScript type definitions for all models and data structures.

Usage

import { Story, Passage, Variable } from '@whisker/core-ts';
import { toWhiskerCoreFormat, generateIfid } from '@whisker/core-ts';

// Create a new story
const story = new Story({
  metadata: {
    title: 'My Story',
    author: 'Author Name',
    version: '1.0.0',
    ifid: generateIfid()
  },
  startPassage: 'start'
});

// Add a passage
const passage = story.createPassage({
  title: 'start',
  content: 'Welcome to the story!'
});

// Add a variable
const variable = story.createVariable({
  name: 'playerName',
  type: 'string',
  initial: ''
});

// Export to Whisker Core format
const exported = toWhiskerCoreFormat(story.serialize(), {
  formatVersion: '2.0'
});

Format Support

• Whisker Format v1.0 - Basic story format
• Whisker Format v2.0 - Typed variables format
• Whisker Format v2.1 - EditorData namespace support

Testing

The package includes comprehensive test coverage (340+ tests).

pnpm test

Building

pnpm build

License

MIT