rpg-event-generator 1.0.0 → 1.1.0

package/README.md

@@ -416,14 +416,269 @@ MIT License - see LICENSE file for details.
 - Uses [Chance.js](https://chancejs.com/) for random number generation
 - Custom Markov chain implementation for procedural text generation
 
-## 🔮 Future Enhancements
+## 🎨 Thematic Training Sets
+
+Choose from different genres and settings for your RPG events:
+
+```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'
+});
+
+// Sci-fi - corporations, AI, space exploration
+const sciFiGen = new RPGEventGenerator({ theme: 'sci-fi' });
+
+// Cyberpunk sci-fi - neon lights, megacorps, hackers
+const cyberpunkGen = new RPGEventGenerator({
+  theme: 'sci-fi',
+  culture: 'cyberpunk'
+});
+
+// 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'
+});
+```
+
+## ⛓️ Event Chains
+
+Create multi-part story sequences where events trigger follow-ups:
+
+```javascript
+const generator = new RPGEventGenerator();
+
+// Start a bandit rising chain
+const firstEvent = generator.startChain('BANDIT_RISING');
+console.log(firstEvent.title); // "Treacherous Bandit Ambush"
+
+// Advance chain based on player choice
+const nextEvent = generator.advanceChain(firstEvent.chainId, 'bandit');
+console.log(nextEvent.title); // "Perilous Bandit King's Challenge"
+
+// Available chains: BANDIT_RISING, COURT_SCANDAL_CHAIN, CURSE_OF_THE_ARTIFACT, MERCHANT_EMPIRE
+```
+
+Event chains create more engaging narratives with escalating consequences and multi-stage stories.
+
+## 🔧 Modular Event System
+
+Create and manage custom event templates, training data, and chains:
+
+```javascript
+const generator = new RPGEventGenerator();
+
+// 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 } }
+  ]
+};
+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();
+// Share with other developers or save for backup
+
+const anotherGenerator = new RPGEventGenerator();
+anotherGenerator.importCustomContent(customContent);
+```
+
+**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
+
+Events automatically scale based on player power level:
+
+```javascript
+// Weak character (easy difficulty)
+const weakling = { gold: 50, influence: 10 };
+const easyEvent = generator.generateEvent(weakling);
+// Rewards: 50% higher, penalties: 30% lower
+
+// Powerful character (hard difficulty)
+const hero = { gold: 50000, influence: 500, skills: { combat: 100 } };
+const hardEvent = generator.generateEvent(hero);
+// Rewards: 20% lower, penalties: 30% higher
+
+// Legendary character (legendary difficulty)
+const god = { gold: 200000, influence: 1000, skills: { combat: 200 } };
+const epicEvent = generator.generateEvent(god);
+// Rewards: 40% lower, penalties: 60% higher
+```
+
+**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
 
-- **Thematic Training Sets**: Fantasy, Sci-fi, Historical themes
+## ⏰ Time-Based Events
+
+Events evolve over time with seasonal changes and long-term story arcs:
+
+```javascript
+const generator = new RPGEventGenerator();
+
+// Advance game time
+const timeEvents = generator.advanceTime(30); // Advance 30 days
+console.log('Season:', generator.getCurrentTime().season); // May change
+
+// Start evolving storylines
+generator.startTimeBasedChain('POLITICAL_UPRISING');
+// - Day 1: Whispers of dissent
+// - Day 7: Public protests
+// - Day 14: Open rebellion
+// - Day 21: Revolutionary climax
+
+// Generate time-aware events
+const seasonalEvent = generator.generateTimeAwareEvent(playerContext);
+// Events adapt to current season with appropriate themes
+```
+
+**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
+
+**Seasonal Events:**
+- **Spring**: Romance, renewal, festivals
+- **Summer**: Tournaments, celebrations, activity
+- **Autumn**: Harvest, preparation, scarcity
+- **Winter**: Solstice rituals, survival challenges, warmth-seeking
+
+## 🎮 Game Integration
+
+For real game integration, use these methods instead of timers:
+
+```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
+}
+
+function loadGame(savedState) {
+  generator.loadGameState(savedState);
+  // Game is now restored with proper time/chain state
+}
+
+// Monitor active chains
+const activeChains = generator.getActiveTimeChains();
+// Shows all ongoing storylines with their progress
+```
+
+**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
+
+## 🗺️ Cultural Context
+
+Add regional/cultural flavor within each theme:
+
+### 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
+
+### 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
+
+### Historical Cultures
+- **`medieval`**: Knights, castles, feudal lords, alchemists
+- **`victorian`**: Industrial revolution, social reformers, steam power
+- **`ancient_roman`**: Gladiators, senators, aqueducts, barbarian hordes
+
+Cultural variants blend with base theme data for authentic regional flavor!
+
+## 🧪 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 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
+- **Event Dependencies**: Complex prerequisite systems
+- **Event Modifiers**: Weather, season, and environmental effects
+- **Character Relationships**: NPC interaction networks
+- **Event Editor**: Visual template creation interface
 
 ---