Narrative Event Scheduler

A sophisticated narrative event scheduling system built with TypeScript. This system manages story events using reactive state management, conditional availability (with Quis-style conditions), and story grammar for narrative structure.

🏗️ Architecture

The system consists of several key components:

Core Components

• ReactiveStateManager: Manages application state with reactive updates and change notifications
• NarrativeEvent: Represents individual story events with conditions, priorities, and execution logic
• ConditionEvaluator: Evaluates event conditions against current state (with simplified Quis-style logic)
• NarrativeEventScheduler: Main scheduler that manages event selection and execution
• StoryGrammarIntegration: Integrates story grammar rules for narrative structure

Key Features

• ✅ Reactive State Management: State changes automatically trigger updates
• ✅ Conditional Event Availability: Events only execute when their conditions are met
• ✅ Multiple Selection Strategies: Priority-based, random, weighted random, least executed
• ✅ Grammar-based Narrative Structure: Uses story grammar for structured storytelling
• ✅ Tick-based Execution: Discrete time steps for event scheduling
• ✅ Extensible Event System: Custom execution logic and state changes

🚀 Setup

Install dependencies:

npm install

📖 Usage

Build Commands

• Build for production: npm run build
• Build for development with watch mode: npm run dev

Code Quality

• Lint TypeScript files: npm run lint
• Auto-fix linting issues: npm run lint:fix

Running the Example

The project includes a complete example adventure story that demonstrates all features:

npm run build && node dist/index.js

This runs an interactive adventure where:

• Hero starts in a village
• Can explore forest, meet villagers, rest at inn
• Encounters wolves, finds treasure
• State affects event availability
• Story concludes when victory conditions are met

🎯 Example Usage

import { 
  NarrativeEventScheduler, 
  NarrativeEvent, 
  SelectionStrategies 
} from './dist/index.js';

// Create events
const events = [
  new NarrativeEvent({
    id: 'start',
    name: 'Begin Adventure',
    conditions: ['!hasStarted'],
    priority: 10,
    stateChanges: { hasStarted: true, location: 'forest' }
  })
];

// Create scheduler
const scheduler = new NarrativeEventScheduler({
  events,
  initialState: { hasStarted: false },
  selectionStrategy: SelectionStrategies.highestPriority
});

// Run narrative
const result = await scheduler.tick();
console.log(`Executed ${result.eventsExecuted} events`);

🎮 Condition System

Events use a simplified condition syntax:

// Boolean checks
'hasStarted'           // Check if variable is truthy
'!hasStarted'          // Negation

// Comparisons  
'health > 50'          // Greater than
'gold >= 100'          // Greater than or equal
'level < 5'            // Less than
'name == "hero"'       // Equality

📊 Event Selection Strategies

• Priority-based: Select highest priority event
• Random: Random selection from available events
• Weighted Random: Random selection weighted by priority
• Least Executed: Balanced storytelling by execution count
• Grammar-based: Uses story grammar rules for structured narrative

🎭 Story Grammar

Define narrative structure with grammar rules:

const grammarRules = [
  GrammarRuleBuilder.create('exploration')
    .withEvents(['explore_forest', 'find_treasure'])
    .withCondition('location == "forest"')
    .withWeight(8)
    .build()
];

🔧 Development Workflow

1. Write TypeScript code in the src/ directory
2. Use npm run dev for development with automatic rebuilding
3. Use npm run lint to check code quality
4. Use npm run build to create a production build
5. Test with node dist/index.js

📋 Dependencies

• Runtime: quis, story-grammar
• Development: TypeScript, ESLint, Webpack, ts-loader

✨ Features Implemented

• ✅ Reactive state management with change notifications
• ✅ Event system with conditions and custom execution logic
• ✅ Multiple event selection strategies
• ✅ Simplified Quis-style condition evaluation
• ✅ Story grammar integration for narrative structure
• ✅ Complete working example with adventure story
• ✅ TypeScript with strict type checking
• ✅ ESLint configuration
• ✅ Webpack bundling
• ✅ Comprehensive documentation

The system provides a solid foundation for narrative-driven applications, interactive storytelling, and procedural content generation.