rpg-event-generator 1.0.0 → 1.1.1

package/README.md

@@ -2,32 +2,18 @@
 
 A powerful procedural event generation system for RPG games, capable of creating virtually infinite contextual events based on player state and game world.
 
-## ✨ Features
-
-- **Infinite Event Generation**: Creates unique, contextual events using custom Markov chains and procedural techniques
-- **Player-Aware**: Events adapt to player stats, career, relationships, life stage, reputation, and social standing
-- **14+ Dramatic Event Types**: From court scandals and noble duels to ancient curses and bandit kings
-- **Immersive Storytelling**: Each event features rich narratives with atmospheric descriptions and meaningful consequences
-- **Dynamic Effects**: Context-aware rewards and consequences that scale with character development and power level
-- **Career Integration**: Events specifically tailored to noble, merchant, warrior, and criminal careers
-- **Relationship Impact**: Events that affect and are affected by your social connections and personal history
-- **Seasonal & Location Themes**: Events adapt to time of year and geographical setting for added immersion
-- **Consequence Tracking**: Events can have long-term effects on character development and reputation
-- **Personality-Driven Choices**: Multiple meaningful choices that define your character's personality and path
-- **Quality Filtering**: Built-in filters ensure only interesting, non-generic events are generated
-- **Modular Design**: Easy to integrate into existing game systems
-- **Highly Configurable**: Customize training data, templates, and generation parameters
-
-## 🚀 Quick Start
+## 🚀 Installation
 
 ```bash
 npm install rpg-event-generator
 ```
 
+## ✨ Quick Start
+
 ```javascript
 import { RPGEventGenerator, generateRPGEvent } from 'rpg-event-generator';
 
-// Quick single event
+// Simple event generation
 const event = generateRPGEvent({
   age: 25,
   gold: 500,
@@ -35,65 +21,44 @@ const event = generateRPGEvent({
   career: 'merchant'
 });
 
-console.log(event.title); // "Golden Opportunity"
-console.log(event.description); // Procedurally generated description
-console.log(event.choices); // Array of choices with effects
+console.log(event.title);        // "Golden Opportunity"
+console.log(event.description);  // Procedurally generated narrative
+console.log(event.choices);      // Array of meaningful choices
+```
 
-// Advanced usage with custom generator
-const generator = new RPGEventGenerator({
-  stateSize: 2,
-  trainingData: ['Your custom story fragments...']
-});
+## 📋 Features
 
-// Generate multiple events
-const events = generator.generateEvents({
-  age: 30,
-  gold: 1000,
-  influence: 25,
-  career: 'knight',
-  skills: { combat: 60, diplomacy: 40 }
-}, 3);
-```
+- **🎲 Infinite Event Generation**: Custom Markov chains create unique, contextual events
+- **👤 Player-Aware**: Events adapt to stats, career, relationships, reputation, and social standing
+- **🎭 14+ Event Types**: Court scandals, noble duels, ancient curses, bandit kings, and more
+- **📖 Immersive Storytelling**: Rich narratives with atmospheric descriptions and meaningful consequences
+- **⚖️ Dynamic Difficulty Scaling**: Events automatically scale based on player power level
+- **🎨 Thematic Training Sets**: Fantasy, sci-fi, and historical themes with cultural variants
+- **⛓️ Event Chains**: Multi-part story sequences with escalating consequences
+- **⏰ Time-Based Events**: Seasonal changes and evolving long-term storylines
+- **🔧 Modular Event System**: Create and manage custom templates, training data, and chains
+- **💾 Game Integration**: Proper save/load state management for real games
+- **🧪 Comprehensive Testing**: 45+ automated tests ensuring reliability
 
-## 📖 Usage Examples
+## 📖 Usage Guide
 
 ### Basic Event Generation
 
 ```javascript
 const generator = new RPGEventGenerator();
-
-// Generate a random event
 const event = generator.generateEvent();
 
 console.log(event);
 // {
 //   id: "event_1704567890123_xyz789",
 //   title: "Perilous Bandit King's Challenge",
-//   description: "The infamous bandit king blocks your path, offering you a choice: join his band or face certain death. Your business interests are directly affected by this development. Choose wisely, for the wrong path leads to ruin.",
-//   narrative: "The infamous bandit king blocks your path, offering you a choice: join his band or face certain death.",
+//   description: "Generated narrative based on Markov chains...",
 //   choices: [
-//     {
-//       text: "Join the bandits",
-//       effect: { gold: 375, reputation: -23, combat_skill: 12 },
-//       consequence: "bandit"
-//     },
-//     {
-//       text: "Challenge him to single combat",
-//       effect: { reputation: 32, health: -18 },
-//       requirements: { combat_skill: 60 },
-//       consequence: "hero"
-//     },
-//     {
-//       text: "Bribe your way past",
-//       effect: { gold: -320, safe_passage: true },
-//       consequence: "diplomat"
-//     }
+//     { text: "Fight back", effect: { health: -20, reputation: 25 } },
+//     { text: "Pay tribute", effect: { gold: -200, safe_passage: true } }
 //   ],
 //   type: "BANDIT_KING",
-//   consequence: null,
-//   urgency: "normal",
-//   theme: "adventure",
-//   context: { /* player context used */ }
+//   difficulty: "normal"
 // }
 ```
 
@@ -106,121 +71,355 @@ const playerContext = {
   influence: 40,
   reputation: 25,
   career: 'noble',
-  skills: {
-    diplomacy: 70,
-    combat: 45,
-    intrigue: 30
-  },
+  skills: { diplomacy: 70, combat: 45, intrigue: 30 },
   relationships: [
-    { name: 'Lord Harrington', type: 'ally', relationship: 60 },
-    { name: 'Lady Beaumont', type: 'lover', relationship: 45 }
+    { name: 'Lord Harrington', type: 'ally', relationship: 60 }
   ],
   location: 'capital',
   season: 'winter'
 };
 
 const event = generator.generateEvent(playerContext);
-// Generates events like:
-// - Diplomatic missions (high diplomacy skill)
-// - Court intrigue opportunities (high influence)
-// - Social events involving relationships
-// - Winter-themed challenges
+// Generates events appropriate to noble career, high influence, winter season
 ```
 
 ### Custom Training Data
 
+Enhance text generation with your own story fragments:
+
 ```javascript
 const customTrainingData = [
   'In the shadowed alleys of the ancient city',
-  'The dragon\'s roar echoes through the mountains',
-  'Elven merchants display their enchanted wares',
-  'A dwarven smith forges weapons of legend',
-  'The tavern is filled with adventurers and mercenaries',
-  'Ancient runes glow with mystical power',
-  'The forest whispers secrets to those who listen'
+  'The dragon\'s roar echoes through the misty mountains',
+  'Elven merchants display their enchanted crystal wares',
+  'A dwarven smith forges weapons of legendary power',
+  'The tavern overflows with adventurers and mysterious strangers',
+  'Ancient runes glow with ethereal magical energy',
+  'The enchanted forest whispers secrets to those who listen carefully'
 ];
 
 const generator = new RPGEventGenerator({
   trainingData: customTrainingData
 });
+
+// Events will now incorporate your custom story elements
+const event = generator.generateEvent();
+// May generate: "In the shadowed alleys of the ancient city, a mysterious stranger approaches..."
 ```
 
-## 🔧 API Reference
+### Thematic Training Sets
+
+```javascript
+// Fantasy (default) - knights, magic, dragons
+const fantasyGen = new RPGEventGenerator({ theme: 'fantasy' });
+
+// Fantasy with Norse culture - vikings, runes, fjords
+const norseGen = new RPGEventGenerator({
+  theme: 'fantasy',
+  culture: 'norse'
+});
+const norseEvent = norseGen.generateEvent();
+// Generates: "The longships sail into the fjord under the northern lights..."
+
+// Sci-fi - corporations, AI, space exploration
+const sciFiGen = new RPGEventGenerator({ theme: 'sci-fi' });
+
+// Cyberpunk sci-fi - neon cities, megacorps, hackers
+const cyberpunkGen = new RPGEventGenerator({
+  theme: 'sci-fi',
+  culture: 'cyberpunk'
+});
+const cyberEvent = cyberpunkGen.generateEvent();
+// Generates: "Neon lights reflect off rain-slicked streets in the megacity sprawl..."
+
+// Historical - medieval politics, exploration, warfare
+const historicalGen = new RPGEventGenerator({ theme: 'historical' });
+
+// Victorian historical - industrial revolution, social reform
+const victorianGen = new RPGEventGenerator({
+  theme: 'historical',
+  culture: 'victorian'
+});
+const victorianEvent = victorianGen.generateEvent();
+// Generates: "Steam engines power the industrial revolution across soot-stained cities..."
+```
+
+### Event Chains
+
+```javascript
+// Start a multi-part storyline
+const generator = new RPGEventGenerator();
+const firstEvent = generator.startChain('BANDIT_RISING');
+
+console.log(firstEvent.title); // "Treacherous Bandit Ambush"
+console.log(firstEvent.chainId); // "chain_1704567890123_xyz789"
+
+// Advance chain based on player choice
+const nextEvent = generator.advanceChain(firstEvent.chainId, 'hero');
+console.log(nextEvent.title); // "Perilous Bandit King's Challenge"
+
+// Check active chains
+const activeChains = generator.getActiveChains();
+console.log(`Active chains: ${activeChains.length}`);
+
+// Available built-in chains:
+// - BANDIT_RISING: Highway robbery escalating to kingdom threat
+// - COURT_SCANDAL_CHAIN: Royal intrigue with multiple betrayals
+// - CURSE_OF_THE_ARTIFACT: Ancient curse with escalating effects
+// - MERCHANT_EMPIRE: Trade empire building with setbacks
+```
 
-### RPGEventGenerator Class
+### Time-Based Events
 
-#### Constructor Options
+```javascript
+// Advance game time and handle due events
+const dueEvents = generator.advanceGameDay();
+
+dueEvents.forEach(event => {
+  if (event.type === 'time_based_chain') {
+    const chainData = generator.timeSystem.timeBasedEvents.get(event.chainId);
+    const gameEvent = generator.generateChainEvent(chainData);
+    // Add to your game's event system
+  }
+});
+
+// Start evolving storylines
+generator.startTimeBasedChain('POLITICAL_UPRISING');
+// - Day 1: Whispers of dissent appear
+// - Day 7: Public protests erupt
+// - Day 14: Open rebellion begins
+// - Day 21: Revolutionary climax
+
+// Check current game time
+const currentTime = generator.getCurrentTime();
+console.log(`Day ${currentTime.day}, Season: ${currentTime.season}`);
+```
+
+### Modular Event System
+
+```javascript
+// Register custom event templates
+const customTemplate = {
+  title: 'Mystic Vision',
+  narrative: 'You experience a vivid prophetic dream showing future events.',
+  choices: [
+    {
+      text: 'Seek out the prophecy',
+      effect: { wisdom: 15, risk: 20 },
+      consequence: 'visionary'
+    },
+    {
+      text: 'Dismiss it as a dream',
+      effect: { stress: -10 },
+      consequence: 'skeptical'
+    }
+  ]
+};
+
+generator.registerEventTemplate('MYSTIC_VISION', customTemplate);
+
+// Add custom training data for better text generation
+generator.addCustomTrainingData([
+  'The ancient prophecy foretells of great change',
+  'Mystic visions reveal hidden truths to the worthy',
+  'Dreams of the future guide the destinies of heroes'
+], 'mystical');
+
+// Create custom event chains
+const visionChain = {
+  name: 'Prophetic Journey',
+  description: 'A chain of events triggered by mystic visions',
+  stages: [
+    { day: 1, template: 'MYSTIC_VISION' },
+    { day: 5, template: 'ANCIENT_RUINS' },
+    { day: 10, template: 'FINAL_PROPHECY' }
+  ]
+};
+
+generator.registerEventChain('PROPHECY_CHAIN', visionChain);
+
+// Export/import custom content for sharing
+const customContent = generator.exportCustomContent();
+console.log('Exported:', Object.keys(customContent.templates).length, 'templates');
+
+const newGenerator = new RPGEventGenerator();
+const importResult = newGenerator.importCustomContent(customContent);
+console.log('Imported:', importResult.templates.success, 'templates');
+```
+
+### Dynamic Difficulty Scaling
+
+Events automatically scale based on player power level:
+
+```javascript
+// Weak character (easy difficulty)
+const weakling = {
+  gold: 50,
+  influence: 10,
+  skills: { combat: 20 }
+};
+const easyEvent = generator.generateEvent(weakling);
+console.log(`Difficulty: ${easyEvent.difficulty}`); // "easy"
+// Effects scaled for beginners: higher rewards, lower penalties
+
+// Powerful character (hard difficulty)
+const hero = {
+  gold: 50000,
+  influence: 500,
+  skills: { combat: 100, diplomacy: 80 },
+  relationships: [{ name: 'King', type: 'ally', relationship: 80 }]
+};
+const hardEvent = generator.generateEvent(hero);
+console.log(`Difficulty: ${hardEvent.difficulty}`); // "hard"
+// Effects scaled for challenge: lower rewards, higher penalties
+
+// Legendary character (legendary difficulty)
+const godlike = {
+  gold: 200000,
+  influence: 1000,
+  skills: { combat: 200, diplomacy: 150 },
+  age: 120,
+  reputation: 95
+};
+const epicEvent = generator.generateEvent(godlike);
+console.log(`Difficulty: ${epicEvent.difficulty}`); // "legendary"
+// Effects scaled for epic gameplay: minimal rewards, maximum penalties
+```
+
+**Difficulty Tiers:**
+- **Easy** (Power 0-50): Generous rewards, forgiving penalties
+- **Normal** (Power 25-150): Standard scaling, balanced challenges
+- **Hard** (Power 100-300): Reduced rewards, harsher penalties
+- **Legendary** (Power 250+): Minimal rewards, extreme challenges
+
+## 🔧 API Reference
+
+### Constructor Options
 
 ```javascript
 const generator = new RPGEventGenerator({
-  stateSize: 2,        // Markov chain state size (default: 2)
-  trainingData: [...]  // Custom training data array (optional)
+  stateSize: 2,           // Markov chain state size (default: 2)
+  trainingData: [...],     // Custom training data array
+  theme: 'fantasy',        // 'fantasy', 'sci-fi', 'historical'
+  culture: 'norse'         // Cultural variant within theme
 });
 ```
 
-#### Methods
+### Core Methods
 
-- `generateEvent(playerContext)` - Generate a single event
+- `generateEvent(playerContext)` - Generate single event
 - `generateEvents(playerContext, count)` - Generate multiple events
-- `addTrainingData(data)` - Add more training data
-- `resetTrainingData(data)` - Reset with new training data
+- `generateTimeAwareEvent(playerContext)` - Generate season-aware event
+
+### Event Chain Methods
+
+- `startChain(chainId)` - Start choice-based event chain
+- `advanceChain(chainId, choice)` - Advance chain based on choice
+- `getActiveChains()` - Get all active chains
+
+### Time-Based Methods
+
+- `advanceGameDay()` - Advance time and return due events
+- `startTimeBasedChain(chainId)` - Start time-evolving chain
+- `getCurrentTime()` - Get current game time/season
+- `getActiveTimeChains()` - Get active time-based chains
+
+### Game State Methods
+
+- `getGameState()` - Export complete game state
+- `loadGameState(state)` - Import saved game state
+
+### Modular Methods
+
+- `registerEventTemplate(id, template)` - Add custom event template
+- `addCustomTrainingData(data, category)` - Add custom training data
+- `registerEventChain(id, chainConfig)` - Add custom event chain
+- `exportCustomContent()` - Export custom templates/chains/data
+- `importCustomContent(content)` - Import custom content
 
 ### Player Context Object
 
 ```javascript
 {
-  age: number,              // Player age
-  gold: number,             // Player wealth
-  influence: number,        // Political/social influence
-  reputation: number,       // Social reputation
-  career: string,           // Player's career/job
-  skills: {                 // Skill levels object
-    combat: number,
+  age: number,                    // Player age
+  gold: number,                   // Player wealth
+  influence: number,              // Political/social influence
+  reputation: number,             // Social reputation
+  career: string,                 // Player's career/job ('noble', 'merchant', 'warrior', etc.)
+  skills: {                       // Skill levels object
+    combat: number,               // 0-100 scale
     diplomacy: number,
-    // ... other skills
+    intrigue: number,
+    magic: number,
+    survival: number
   },
-  relationships: [{         // Array of relationships
-    name: string,
-    type: string,          // 'friend', 'lover', 'ally', etc.
-    relationship: number   // Relationship strength (0-100)
+  relationships: [{               // Array of NPC relationships
+    name: string,                 // NPC name
+    type: string,                 // 'friend', 'lover', 'ally', 'enemy', 'rival'
+    relationship: number          // Relationship strength (0-100)
   }],
-  location: string,         // Current location
-  season: string           // Current season
+  location: string,               // Current location ('capital', 'village', 'forest', etc.)
+  season: string                  // Current season ('spring', 'summer', 'autumn', 'winter')
 }
 ```
 
-### Event Object Structure
+### Complete Event Object Structure
 
 ```javascript
 {
-  id: string,              // Unique event identifier
-  title: string,           // Dynamic, context-aware title
-  description: string,     // Rich procedural description
-  narrative: string,       // Core story premise
-  choices: [{              // Array of meaningful choices
-    text: string,          // Choice text with contextual flavor
-    effect: {              // Effects scaled by context
-      gold?: number,        // Wealth changes
-      influence?: number,   // Social/political power
-      reputation?: number,  // Social standing
-      health?: number,      // Physical well-being
-      stress?: number,      // Mental strain
-      karma?: number,       // Moral standing
-      // ... many more effects
+  id: "event_1704567890123_xyz789",    // Unique event identifier
+  title: "Perilous Bandit King's Challenge", // Dynamic, context-aware title
+  description: "The infamous bandit king blocks your path, offering you a choice...", // Rich procedural description
+  narrative: "The infamous bandit king blocks your path, offering you a choice: join his band or face certain death.",
+  choices: [
+    {
+      text: "Join the bandits",
+      effect: { gold: 375, reputation: -23, combat_skill: 12 },
+      consequence: "bandit"
     },
-    consequence: string    // Long-term character effect
-  }],
-  type: string,           // Rich event category (COURT_SCANDAL, etc.)
-  consequence: string|null, // Applied consequence after choice
-  urgency: string,        // 'normal', 'high', 'critical'
-  theme: string,          // 'political', 'criminal', 'supernatural', etc.
-  context: object         // Full context used for generation
+    {
+      text: "Challenge him to single combat",
+      effect: { reputation: 32, health: -18 },
+      requirements: { combat_skill: 60 },
+      consequence: "hero"
+    },
+    {
+      text: "Bribe your way past",
+      effect: { gold: -320, safe_passage: true },
+      consequence: "diplomat"
+    }
+  ],
+  type: "BANDIT_KING",
+  consequence: null,
+  context: { /* Full context used for generation */ },
+  urgency: "normal",
+  theme: "adventure",
+  difficulty: "normal"
 }
 ```
 
-## 🎮 Integration Guide
+## 🎮 Game Integration
+
+### Real-Time Strategy Integration
+
+```javascript
+function onNewGameDay() {
+  const dueEvents = generator.advanceGameDay();
+
+  dueEvents.forEach(event => {
+    if (event.type === 'time_based_chain') {
+      const chainData = generator.timeSystem.timeBasedEvents.get(event.chainId);
+      const gameEvent = generator.generateChainEvent(chainData);
+      triggerInGameEvent(gameEvent);
+    } else if (event.type === 'seasonal_random') {
+      const seasonalEvent = generator.generateTimeAwareEvent(playerContext);
+      triggerInGameEvent(seasonalEvent);
+    }
+  });
+}
+```
 
-### React Native Game Integration
+### React Game Integration
 
 ```javascript
 import React, { useState, useEffect } from 'react';
@@ -243,13 +442,24 @@ function GameEventSystem({ playerStats }) {
     setCurrentEvent(null); // Clear event
   };
 
-  if (!currentEvent) return null;
+  if (!currentEvent) return <div>No active events</div>;
 
   return (
-    <EventDialog
-      event={currentEvent}
-      onChoice={handleChoice}
-    />
+    <div className="event-dialog">
+      <h2>{currentEvent.title}</h2>
+      <p>{currentEvent.description}</p>
+      <div className="choices">
+        {currentEvent.choices.map((choice, index) => (
+          <button
+            key={index}
+            onClick={() => handleChoice(index)}
+            className="choice-button"
+          >
+            {choice.text}
+          </button>
+        ))}
+      </div>
+    </div>
   );
 }
 ```
@@ -257,174 +467,155 @@ function GameEventSystem({ playerStats }) {
 ### Redux Integration
 
 ```javascript
-// Action creators
-export const generateEvent = (playerContext) => {
-  const generator = new RPGEventGenerator();
-  const event = generator.generateEvent(playerContext);
-
-  return {
-    type: 'GENERATE_EVENT',
-    payload: event
-  };
-};
+// Action Types
+export const GENERATE_EVENT = 'GENERATE_EVENT';
+export const RESOLVE_EVENT = 'RESOLVE_EVENT';
+export const ADVANCE_GAME_DAY = 'ADVANCE_GAME_DAY';
+
+// Action Creators
+export const generateEvent = (playerContext) => ({
+  type: GENERATE_EVENT,
+  payload: { playerContext }
+});
 
 export const resolveEvent = (eventId, choiceIndex) => ({
-  type: 'RESOLVE_EVENT',
+  type: RESOLVE_EVENT,
   payload: { eventId, choiceIndex }
 });
 
+export const advanceGameDay = () => ({
+  type: ADVANCE_GAME_DAY
+});
+
 // Reducer
-const eventReducer = (state = {}, action) => {
+const initialState = {
+  generator: new RPGEventGenerator(),
+  currentEvent: null,
+  gameTime: { day: 1, season: 'spring' }
+};
+
+const eventReducer = (state = initialState, action) => {
   switch (action.type) {
-    case 'GENERATE_EVENT':
-      return { ...state, currentEvent: action.payload };
-    case 'RESOLVE_EVENT':
-      return { ...state, currentEvent: null };
+    case GENERATE_EVENT:
+      const event = state.generator.generateEvent(action.payload.playerContext);
+      return { ...state, currentEvent: event };
+
+    case RESOLVE_EVENT:
+      // Apply choice effects to player state
+      const choice = state.currentEvent.choices[action.payload.choiceIndex];
+      const newPlayerState = applyChoiceEffects(choice.effect);
+      return {
+        ...state,
+        currentEvent: null,
+        playerState: newPlayerState
+      };
+
+    case ADVANCE_GAME_DAY:
+      const dueEvents = state.generator.advanceGameDay();
+      return {
+        ...state,
+        gameTime: state.generator.getCurrentTime(),
+        dueEvents: dueEvents
+      };
+
     default:
       return state;
   }
 };
 ```
 
-## 🧪 Testing
+### Save/Load System
 
-```bash
-npm test
-```
-
-The package includes comprehensive tests covering:
-- Event generation with various contexts
-- Effect resolution
-- Markov chain text generation
-- Template selection algorithms
-
-## 🎯 Event Types
-
-### Court & Political (Variable probability)
-- **Court Scandal**: Royal court intrigue with betrayal and scandal
-- **Noble Duel**: Honor challenges and duels of reputation
-- **Market Crash**: Economic disasters affecting trade and wealth
-- **Trade War**: Merchant rivalries and economic warfare
-
-### Criminal Underworld (Variable probability)
-- **Thieves' Guild**: Criminal organization recruitment and underworld dealings
-- **Blackmail Opportunity**: Leverage compromising information for gain
-- **Bandit King Challenge**: Highway robbery and outlaw confrontations
-
-### Supernatural & Mysterious (Variable probability)
-- **Ancient Curse**: Cursed artifacts and supernatural afflictions
-- **Ghostly Visitation**: Spirits seeking justice or redemption
-- **Lost Civilization**: Archaeological discoveries and ancient treasures
-
-### Personal & Dramatic (Variable probability)
-- **Forbidden Love**: Romance across social boundaries with scandal
-- **Family Secret**: Hidden lineage and ancestral revelations
-- **Desertion Temptation**: Military crises testing loyalty and courage
-- **Mercenary Contract**: Dangerous employment with high rewards
-
-### Adventure & Exploration (Variable probability)
-- **Bandit King**: Confrontations with notorious outlaws
-- **Lost Civilization**: Exploration of ancient ruins and artifacts
-
-Probabilities dynamically adjust based on player career, skills, reputation, wealth, and current life circumstances.
-
-## 🔄 How It Works
-
-### 1. Context Analysis
-The generator analyzes player stats to understand their current situation and capabilities.
-
-### 2. Template Selection
-Based on context, it selects an appropriate event template from 14+ rich narrative types (Court Scandal, Forbidden Love, Ancient Curse, etc.).
-
-### 3. Procedural Description
-Uses custom Markov chains trained on immersive RPG-themed text to generate unique, atmospheric descriptions.
-
-### 4. Dynamic Choices
-Creates contextually appropriate choices with effects that scale based on player stats, career, and relationships.
+```javascript
+// Save complete game state
+function saveGame(playerState) {
+  const gameState = {
+    player: playerState,
+    events: generator.getGameState(),
+    timestamp: Date.now()
+  };
 
-### 5. Effect Resolution
-Converts effect ranges into specific numbers and applies sophisticated context multipliers based on character background.
+  localStorage.setItem('rpgGameSave', JSON.stringify(gameState));
+  console.log('Game saved successfully');
+}
 
-## 🎨 Customization
+// Load complete game state
+function loadGame() {
+  try {
+    const savedGame = JSON.parse(localStorage.getItem('rpgGameSave'));
+    if (!savedGame) return false;
 
-### Custom Event Templates
+    // Restore generator state
+    generator.loadGameState(savedGame.events);
 
-```javascript
-const customTemplates = {
-  QUEST: {
-    title: 'Epic Quest',
-    choices: [
-      { text: 'Accept the quest', effect: { influence: [20, 40] } },
-      { text: 'Decline politely', effect: {} }
-    ]
-  }
-};
+    // Restore player state
+    return savedGame.player;
 
-// Extend the generator
-class CustomRPGEventGenerator extends RPGEventGenerator {
-  constructor(options) {
-    super(options);
-    this.templates = { ...this.templates, ...customTemplates };
+  } catch (error) {
+    console.error('Failed to load game:', error);
+    return false;
   }
 }
 ```
 
-### Custom Effect Types
+## 🧪 Testing
 
-```javascript
-// Add custom effects
-const event = generator.generateEvent(playerContext);
+```bash
+npm test
+```
 
-// Custom effect resolution
-function resolveCustomEffects(choice, playerContext) {
-  const effects = resolveEffect(choice.effect, playerContext);
+**Comprehensive test coverage (45+ tests):**
+- ✅ Core event generation and validation
+- ✅ Context adaptation and player responsiveness
+- ✅ Thematic systems and cultural variants
+- ✅ Event chains and multi-stage progression
+- ✅ Dynamic difficulty scaling
+- ✅ Time systems and seasonal mechanics
+- ✅ Modular features and custom content
+- ✅ Edge cases and error handling
+- ✅ Game state persistence and integration
 
-  // Add custom logic
-  if (effects.experience) {
-    // Handle experience gain
-  }
+## 🎯 Event Types
 
-  if (effects.relationshipChange) {
-    // Update relationship values
-  }
+### Court & Political
+- **Court Scandal**: Royal intrigue with betrayal and scandal
+- **Noble Duel**: Honour challenges and duels of reputation
+- **Market Crash**: Economic disasters affecting trade
+- **Trade War**: Merchant rivalries and economic warfare
 
-  return effects;
-}
-```
+### Criminal Underworld
+- **Thieves' Guild**: Criminal organisation recruitment
+- **Blackmail Opportunity**: Leverage compromising information
+- **Bandit King Challenge**: Highway robbery confrontations
 
-## 📊 Performance
+### Supernatural & Mysterious
+- **Ancient Curse**: Cursed artefacts and afflictions
+- **Ghostly Visitation**: Spirits seeking justice
+- **Lost Civilisation**: Archaeological discoveries
 
-- **Generation Speed**: ~10-50ms per event
-- **Memory Usage**: ~2-5MB for trained Markov generator
-- **Infinite Variety**: Can generate millions of unique events
-- **Scalable**: Works with any number of players/contexts
+### Personal & Dramatic
+- **Forbidden Love**: Romance across social boundaries
+- **Family Secret**: Hidden lineage revelations
+- **Desertion Temptation**: Military loyalty crises
+- **Mercenary Contract**: Dangerous employment opportunities
 
 ## 🤝 Contributing
 
 1. Fork the repository
-2. Create a feature branch
-3. Add tests for new functionality
-4. Ensure all tests pass
-5. Submit a pull request
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit changes (`git commit -m 'Add amazing feature'`)
+4. Push to branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
 
 ## 📄 License
 
-MIT License - see LICENSE file for details.
+MIT License - see [LICENSE](LICENSE) file for details.
 
 ## 🙏 Acknowledgments
 
-- Uses [Chance.js](https://chancejs.com/) for random number generation
+- [Chance.js](https://chancejs.com/) for random number generation
 - Custom Markov chain implementation for procedural text generation
 
-## 🔮 Future Enhancements
-
-- **Thematic Training Sets**: Fantasy, Sci-fi, Historical themes
-- **Multi-language Support**: Generate events in different languages
-- **Event Chains**: Multi-part event sequences
-- **Dynamic Difficulty**: Events scale with player power level
-- **Cultural Context**: Region-specific event generation
-- **Time-based Events**: Events that change over time
-
 ---
 
 **Generate infinite adventures with RPG Event Generator!** ⚔️📚✨