rpg-event-generator 1.1.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,319 +71,43 @@ 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
 });
-```
-
-## 🔧 API Reference
-
-### RPGEventGenerator Class
-
-#### Constructor Options
-
-```javascript
-const generator = new RPGEventGenerator({
-  stateSize: 2,        // Markov chain state size (default: 2)
-  trainingData: [...]  // Custom training data array (optional)
-});
-```
 
-#### Methods
-
-- `generateEvent(playerContext)` - Generate a single event
-- `generateEvents(playerContext, count)` - Generate multiple events
-- `addTrainingData(data)` - Add more training data
-- `resetTrainingData(data)` - Reset with new training data
-
-### 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,
-    diplomacy: number,
-    // ... other skills
-  },
-  relationships: [{         // Array of relationships
-    name: string,
-    type: string,          // 'friend', 'lover', 'ally', etc.
-    relationship: number   // Relationship strength (0-100)
-  }],
-  location: string,         // Current location
-  season: string           // Current season
-}
-```
-
-### 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
-    },
-    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
-}
-```
-
-## 🎮 Integration Guide
-
-### React Native Game Integration
-
-```javascript
-import React, { useState, useEffect } from 'react';
-import { RPGEventGenerator } from 'rpg-event-generator';
-
-function GameEventSystem({ playerStats }) {
-  const [currentEvent, setCurrentEvent] = useState(null);
-  const [generator] = useState(() => new RPGEventGenerator());
-
-  useEffect(() => {
-    // Generate event when time advances
-    const event = generator.generateEvent(playerStats);
-    setCurrentEvent(event);
-  }, [playerStats, generator]);
-
-  const handleChoice = (choiceIndex) => {
-    const choice = currentEvent.choices[choiceIndex];
-    // Apply effects to player stats
-    applyEffects(choice.effect);
-    setCurrentEvent(null); // Clear event
-  };
-
-  if (!currentEvent) return null;
-
-  return (
-    <EventDialog
-      event={currentEvent}
-      onChoice={handleChoice}
-    />
-  );
-}
-```
-
-### Redux Integration
-
-```javascript
-// Action creators
-export const generateEvent = (playerContext) => {
-  const generator = new RPGEventGenerator();
-  const event = generator.generateEvent(playerContext);
-
-  return {
-    type: 'GENERATE_EVENT',
-    payload: event
-  };
-};
-
-export const resolveEvent = (eventId, choiceIndex) => ({
-  type: 'RESOLVE_EVENT',
-  payload: { eventId, choiceIndex }
-});
-
-// Reducer
-const eventReducer = (state = {}, action) => {
-  switch (action.type) {
-    case 'GENERATE_EVENT':
-      return { ...state, currentEvent: action.payload };
-    case 'RESOLVE_EVENT':
-      return { ...state, currentEvent: null };
-    default:
-      return state;
-  }
-};
-```
-
-## 🧪 Testing
-
-```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.
-
-### 5. Effect Resolution
-Converts effect ranges into specific numbers and applies sophisticated context multipliers based on character background.
-
-## 🎨 Customization
-
-### Custom Event Templates
-
-```javascript
-const customTemplates = {
-  QUEST: {
-    title: 'Epic Quest',
-    choices: [
-      { text: 'Accept the quest', effect: { influence: [20, 40] } },
-      { text: 'Decline politely', effect: {} }
-    ]
-  }
-};
-
-// Extend the generator
-class CustomRPGEventGenerator extends RPGEventGenerator {
-  constructor(options) {
-    super(options);
-    this.templates = { ...this.templates, ...customTemplates };
-  }
-}
-```
-
-### Custom Effect Types
-
-```javascript
-// Add custom effects
-const event = generator.generateEvent(playerContext);
-
-// Custom effect resolution
-function resolveCustomEffects(choice, playerContext) {
-  const effects = resolveEffect(choice.effect, playerContext);
-
-  // Add custom logic
-  if (effects.experience) {
-    // Handle experience gain
-  }
-
-  if (effects.relationshipChange) {
-    // Update relationship values
-  }
-
-  return effects;
-}
+// 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..."
 ```
 
-## 📊 Performance
-
-- **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
-
-## 🤝 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
-
-## 📄 License
-
-MIT License - see LICENSE file for details.
-
-## 🙏 Acknowledgments
-
-- Uses [Chance.js](https://chancejs.com/) for random number generation
-- Custom Markov chain implementation for procedural text generation
-
-## 🎨 Thematic Training Sets
-
-Choose from different genres and settings for your RPG events:
+### Thematic Training Sets
 
 ```javascript
 // Fantasy (default) - knights, magic, dragons
@@ -429,15 +118,19 @@ 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 lights, megacorps, hackers
+// 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' });
@@ -447,44 +140,82 @@ 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
-
-Create multi-part story sequences where events trigger follow-ups:
+### Event Chains
 
 ```javascript
+// Start a multi-part storyline
 const generator = new RPGEventGenerator();
-
-// Start a bandit rising chain
 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, 'bandit');
+const nextEvent = generator.advanceChain(firstEvent.chainId, 'hero');
 console.log(nextEvent.title); // "Perilous Bandit King's Challenge"
 
-// Available chains: BANDIT_RISING, COURT_SCANDAL_CHAIN, CURSE_OF_THE_ARTIFACT, MERCHANT_EMPIRE
+// 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
 ```
 
-Event chains create more engaging narratives with escalating consequences and multi-stage stories.
+### Time-Based Events
 
-## 🔧 Modular Event System
+```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
+  }
+});
 
-Create and manage custom event templates, training data, and chains:
+// 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
 
-```javascript
-const generator = new RPGEventGenerator();
+// 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 } },
-    { text: 'Dismiss it as a dream', effect: { stress: -10 } }
+    {
+      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
@@ -504,181 +235,386 @@ const visionChain = {
     { day: 10, template: 'FINAL_PROPHECY' }
   ]
 };
+
 generator.registerEventChain('PROPHECY_CHAIN', visionChain);
 
 // Export/import custom content for sharing
 const customContent = generator.exportCustomContent();
-// Share with other developers or save for backup
+console.log('Exported:', Object.keys(customContent.templates).length, 'templates');
 
-const anotherGenerator = new RPGEventGenerator();
-anotherGenerator.importCustomContent(customContent);
+const newGenerator = new RPGEventGenerator();
+const importResult = newGenerator.importCustomContent(customContent);
+console.log('Imported:', importResult.templates.success, 'templates');
 ```
 
-**Custom Content Management:**
-- **Templates**: `getCustomTemplates()`, `unregisterEventTemplate()`
-- **Training Data**: Organized by categories for easy management
-- **Event Chains**: `getCustomChains()`, `unregisterEventChain()`
-- **Export/Import**: Full backup and sharing capabilities
-
-## ⚖️ Dynamic Difficulty Scaling
+### Dynamic Difficulty Scaling
 
 Events automatically scale based on player power level:
 
 ```javascript
 // Weak character (easy difficulty)
-const weakling = { gold: 50, influence: 10 };
+const weakling = {
+  gold: 50,
+  influence: 10,
+  skills: { combat: 20 }
+};
 const easyEvent = generator.generateEvent(weakling);
-// Rewards: 50% higher, penalties: 30% lower
+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 } };
+const hero = {
+  gold: 50000,
+  influence: 500,
+  skills: { combat: 100, diplomacy: 80 },
+  relationships: [{ name: 'King', type: 'ally', relationship: 80 }]
+};
 const hardEvent = generator.generateEvent(hero);
-// Rewards: 20% lower, penalties: 30% higher
+console.log(`Difficulty: ${hardEvent.difficulty}`); // "hard"
+// Effects scaled for challenge: lower rewards, higher penalties
 
 // Legendary character (legendary difficulty)
-const god = { gold: 200000, influence: 1000, skills: { combat: 200 } };
-const epicEvent = generator.generateEvent(god);
-// Rewards: 40% lower, penalties: 60% higher
+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): Beginner-friendly events
-- **Normal** (Power 25-150): Balanced challenges
-- **Hard** (Power 100-300): Demanding encounters
-- **Legendary** (Power 250+): Epic, high-stakes events
+- **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
 
-## ⏰ Time-Based Events
+## 🔧 API Reference
 
-Events evolve over time with seasonal changes and long-term story arcs:
+### Constructor Options
 
 ```javascript
-const generator = new RPGEventGenerator();
+const generator = new RPGEventGenerator({
+  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
+});
+```
 
-// Advance game time
-const timeEvents = generator.advanceTime(30); // Advance 30 days
-console.log('Season:', generator.getCurrentTime().season); // May change
+### Core Methods
 
-// Start evolving storylines
-generator.startTimeBasedChain('POLITICAL_UPRISING');
-// - Day 1: Whispers of dissent
-// - Day 7: Public protests
-// - Day 14: Open rebellion
-// - Day 21: Revolutionary climax
+- `generateEvent(playerContext)` - Generate single event
+- `generateEvents(playerContext, count)` - Generate multiple events
+- `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
 
-// Generate time-aware events
-const seasonalEvent = generator.generateTimeAwareEvent(playerContext);
-// Events adapt to current season with appropriate themes
+### 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 ('noble', 'merchant', 'warrior', etc.)
+  skills: {                       // Skill levels object
+    combat: number,               // 0-100 scale
+    diplomacy: number,
+    intrigue: number,
+    magic: number,
+    survival: number
+  },
+  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 ('capital', 'village', 'forest', etc.)
+  season: string                  // Current season ('spring', 'summer', 'autumn', 'winter')
+}
 ```
 
-**Available Time-Based Chains:**
-- **`POLITICAL_UPRISING`**: Rebellion that builds over weeks
-- **`ECONOMIC_COLLAPSE`**: Market crisis with escalating consequences
-- **`MYSTICAL_AWAKENING`**: Supernatural events that intensify over time
+### Complete Event Object Structure
 
-**Seasonal Events:**
-- **Spring**: Romance, renewal, festivals
-- **Summer**: Tournaments, celebrations, activity
-- **Autumn**: Harvest, preparation, scarcity
-- **Winter**: Solstice rituals, survival challenges, warmth-seeking
+```javascript
+{
+  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"
+    },
+    {
+      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"
+}
+```
 
 ## 🎮 Game Integration
 
-For real game integration, use these methods instead of timers:
+### Real-Time Strategy Integration
 
 ```javascript
-const generator = new RPGEventGenerator();
-
-// Each game day, advance time and check for events
 function onNewGameDay() {
   const dueEvents = generator.advanceGameDay();
 
-  // Process each due event in your game
   dueEvents.forEach(event => {
     if (event.type === 'time_based_chain') {
-      // Generate the actual event for your game
       const chainData = generator.timeSystem.timeBasedEvents.get(event.chainId);
       const gameEvent = generator.generateChainEvent(chainData);
-      // Add gameEvent to your game's event system
       triggerInGameEvent(gameEvent);
     } else if (event.type === 'seasonal_random') {
-      // Generate a seasonal event
       const seasonalEvent = generator.generateTimeAwareEvent(playerContext);
       triggerInGameEvent(seasonalEvent);
     }
   });
 }
+```
 
-// Save/Load game state
-function saveGame() {
-  const gameState = generator.getGameState();
-  // Save gameState to your game's save file
-}
+### React Game Integration
 
-function loadGame(savedState) {
-  generator.loadGameState(savedState);
-  // Game is now restored with proper time/chain state
+```javascript
+import React, { useState, useEffect } from 'react';
+import { RPGEventGenerator } from 'rpg-event-generator';
+
+function GameEventSystem({ playerStats }) {
+  const [currentEvent, setCurrentEvent] = useState(null);
+  const [generator] = useState(() => new RPGEventGenerator());
+
+  useEffect(() => {
+    // Generate event when time advances
+    const event = generator.generateEvent(playerStats);
+    setCurrentEvent(event);
+  }, [playerStats, generator]);
+
+  const handleChoice = (choiceIndex) => {
+    const choice = currentEvent.choices[choiceIndex];
+    // Apply effects to player stats
+    applyEffects(choice.effect);
+    setCurrentEvent(null); // Clear event
+  };
+
+  if (!currentEvent) return <div>No active events</div>;
+
+  return (
+    <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>
+  );
 }
+```
+
+### Redux Integration
+
+```javascript
+// 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,
+  payload: { eventId, choiceIndex }
+});
+
+export const advanceGameDay = () => ({
+  type: ADVANCE_GAME_DAY
+});
 
-// Monitor active chains
-const activeChains = generator.getActiveTimeChains();
-// Shows all ongoing storylines with their progress
+// Reducer
+const initialState = {
+  generator: new RPGEventGenerator(),
+  currentEvent: null,
+  gameTime: { day: 1, season: 'spring' }
+};
+
+const eventReducer = (state = initialState, action) => {
+  switch (action.type) {
+    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;
+  }
+};
 ```
 
-**Key Benefits:**
-- **Persistent State**: Chains survive game saves/loads
-- **Event-Driven**: No timers, events trigger when you advance days
-- **Game-Controlled**: You control when time passes
-- **Multiple Events**: Handle multiple events per day
+### Save/Load System
 
-## 🗺️ Cultural Context
+```javascript
+// Save complete game state
+function saveGame(playerState) {
+  const gameState = {
+    player: playerState,
+    events: generator.getGameState(),
+    timestamp: Date.now()
+  };
 
-Add regional/cultural flavor within each theme:
+  localStorage.setItem('rpgGameSave', JSON.stringify(gameState));
+  console.log('Game saved successfully');
+}
 
-### Fantasy Cultures
-- **`norse`**: Vikings, runes, mead halls, thunder gods
-- **`arabian`**: Sultans, djinn, bazaars, flying carpets
-- **`celtic`**: Druids, fairy mounds, stone circles, clan warfare
-- **`asian`**: Imperial courts, samurai, dragon spirits, tea ceremonies
+// Load complete game state
+function loadGame() {
+  try {
+    const savedGame = JSON.parse(localStorage.getItem('rpgGameSave'));
+    if (!savedGame) return false;
 
-### Sci-Fi Cultures
-- **`cyberpunk`**: Neon cities, megacorps, neural implants, hackers
-- **`space_opera`**: Galactic empires, Jedi knights, hyperspace, alien ambassadors
-- **`post_apocalyptic`**: Wastelands, mutants, vault dwellers, irradiated ruins
+    // Restore generator state
+    generator.loadGameState(savedGame.events);
 
-### Historical Cultures
-- **`medieval`**: Knights, castles, feudal lords, alchemists
-- **`victorian`**: Industrial revolution, social reformers, steam power
-- **`ancient_roman`**: Gladiators, senators, aqueducts, barbarian hordes
+    // Restore player state
+    return savedGame.player;
 
-Cultural variants blend with base theme data for authentic regional flavor!
+  } catch (error) {
+    console.error('Failed to load game:', error);
+    return false;
+  }
+}
+```
 
 ## 🧪 Testing
 
-This package includes comprehensive test coverage with **45+ automated tests** ensuring reliability and quality:
-
 ```bash
 npm test
 ```
 
-**Test Coverage Includes:**
-- ✅ **Core Generation** - Event creation and validation
-- ✅ **Context Adaptation** - Player stat responsiveness
-- ✅ **Thematic Systems** - Theme and culture switching
-- ✅ **Event Chains** - Multi-stage story progression
-- ✅ **Difficulty Scaling** - Power-based event adjustment
-- ✅ **Time Systems** - Seasonal and temporal mechanics
-- ✅ **Modular Features** - Custom content registration
-- ✅ **Edge Cases** - Error handling and validation
-- ✅ **Integration** - Game state persistence
-
-All features are thoroughly tested with both unit and integration tests for maximum reliability.
-
-## 🔮 Future Enhancements
-- **Multi-language Support**: Generate events in different languages
-- **Event Dependencies**: Complex prerequisite systems
-- **Event Modifiers**: Weather, season, and environmental effects
-- **Character Relationships**: NPC interaction networks
-- **Event Editor**: Visual template creation interface
+**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
+
+## 🎯 Event Types
+
+### 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
+
+### Criminal Underworld
+- **Thieves' Guild**: Criminal organisation recruitment
+- **Blackmail Opportunity**: Leverage compromising information
+- **Bandit King Challenge**: Highway robbery confrontations
+
+### Supernatural & Mysterious
+- **Ancient Curse**: Cursed artefacts and afflictions
+- **Ghostly Visitation**: Spirits seeking justice
+- **Lost Civilisation**: Archaeological discoveries
+
+### 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 (`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](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- [Chance.js](https://chancejs.com/) for random number generation
+- Custom Markov chain implementation for procedural text generation
 
 ---
 

package/dist/index.js

@@ -2274,7 +2274,8 @@ class RPGEventGenerator {
       }
       return description;
     } catch (error) {
-      return template.narrative;
+      const templateType = this.mapTemplateToType(template.type || Object.keys(this.templates).find(key => this.templates[key] === template));
+      return this.getFallbackDescription(templateType);
     }
   }
 
@@ -2524,16 +2525,46 @@ class RPGEventGenerator {
     return this.chance.pickone(locations);
   }
 
+  /**
+   * Map template ID to fallback type
+   * @param {string} templateId - Template identifier
+   * @returns {string} Fallback type
+   * @private
+   */
+  mapTemplateToType(templateId) {
+    if (!templateId) return 'ENCOUNTER';
+    const typeMapping = {
+      'COURT_SCANDAL': 'ENCOUNTER',
+      'NOBLE_DUEL': 'CHALLENGE',
+      'FORBIDDEN_LOVE': 'ENCOUNTER',
+      'FAMILY_SECRET': 'MYSTERY',
+      'THIEVES_GUILD': 'CHALLENGE',
+      'BLACKMAIL_OPPORTUNITY': 'OPPORTUNITY',
+      'ANCIENT_CURSE': 'MYSTERY',
+      'GHOSTLY_VISITATION': 'MYSTERY',
+      'LOST_CIVILIZATION': 'MYSTERY',
+      'BANDIT_KING': 'CHALLENGE',
+      'MARKET_CRASH': 'CHALLENGE',
+      'TRADE_WAR': 'CHALLENGE',
+      'MERCENARY_CONTRACT': 'OPPORTUNITY',
+      'DESERTION_TEMPTATION': 'CHALLENGE'
+    };
+    return typeMapping[templateId] || 'ENCOUNTER';
+  }
+
   /**
    * Get fallback description if Markov generation fails
    * @private
    */
   getFallbackDescription(templateType) {
+    const professions = ['merchant', 'warrior', 'mage', 'noble', 'thief', 'priest', 'blacksmith', 'alchemist'];
+    const products = ['sword', 'potion', 'artifact', 'weapon', 'armor', 'tool', 'gem', 'scroll'];
+    const locations = ['village', 'town', 'city', 'castle', 'forest', 'mountain', 'ruins'];
     const fallbacks = {
-      ENCOUNTER: `A ${faker.person.jobTitle()} approaches you with an unusual proposition.`,
-      OPPORTUNITY: `A rare ${faker.commerce.product()} has become available at an exceptional price.`,
-      CHALLENGE: `A ${faker.person.jobTitle()} challenges your position in the community.`,
-      MYSTERY: `Strange occurrences have been reported near ${faker.location.city()}.`
+      ENCOUNTER: `A ${this.chance.pickone(professions)} approaches you with an unusual proposition.`,
+      OPPORTUNITY: `A rare ${this.chance.pickone(products)} has become available at an exceptional price.`,
+      CHALLENGE: `A ${this.chance.pickone(professions)} challenges your position in the community.`,
+      MYSTERY: `Strange occurrences have been reported near ${this.chance.pickone(locations)}.`
     };
     return fallbacks[templateType] || fallbacks.ENCOUNTER;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rpg-event-generator",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Procedural RPG event generation system for games",
   "main": "dist/index.js",
   "files": [