rpg-event-generator 1.3.0 → 2.0.1

package/README.md

@@ -1,7 +1,16 @@
-# RPG Event Generator
+# RPG Event Generator v2.0.1
 
 A powerful procedural event generation system for RPG games, capable of creating virtually infinite contextual events based on player state and game world.
 
+## ✨ What's New in v2.0.1
+
+- 🎨 **Theme Creator**: Build custom themes with your own training data
+- 🧠 **Rule Engine**: Create conditional rules that modify event generation
+- 🎲 **Pure Markov Mode**: Generate events purely from custom text (no templates)
+- 🌐 **Cross-Platform Export**: Unity C#, Godot GDScript, TypeScript support
+- 📚 **Template Library**: 429 professionally crafted event templates included across 7 genres (fantasy, sci-fi, horror, historical, modern, cyberpunk, space-opera)
+- 🏗️ **Creative Tools**: Visual tools for event customization
+
 > **Note:** This package was originally created for a personal RPG project and shared publicly because it might be useful for other game developers. The repository is private, so bug reports and maintenance issues cannot be submitted directly. Check npm regularly for updates, new features, or breaking changes.
 
 ## Installation
@@ -30,9 +39,13 @@ console.log(event.choices);      // Array of meaningful choices
 
 ## Demo
 
-Run the included `demo.js` file to see the RPG Event Generator in action:
+Run the included demo to see the RPG Event Generator in action:
 
 ```bash
+# Using npm script (recommended)
+npm run demo
+
+# Direct script call
 node demo.js
 ```
 
@@ -68,6 +81,175 @@ Since this is a personal project with a private repository:
 - **NPC Relationships**: Dynamic character relationship networks and social consequences
 - **Event Templates Library** (v1.3.0): Pre-built genre-specific event collections for fantasy, sci-fi, horror, and historical themes, with support for custom template creation
 
+### Revolutionary Features (v2.0.1) 🎉
+
+- **🎨 Theme Creator**: Design custom game worlds with your own training data and atmospheric text
+- **🧠 Rule Engine**: Create sophisticated conditional rules that dynamically modify events based on player state, location, stats, and more
+- **🎲 Pure Markov Mode**: Generate completely custom events using only your provided text - no templates required
+- **💰 Event Economy**: User-generated content marketplace with theme sharing, rule packs, and quality metrics
+- **📚 Template Library**: Generate hundreds of events across 7 genres using included CLI export tools
+- **🌐 Cross-Platform Export**: Export events in JSON and TypeScript formats (Unity/Godot integration guides available)
+- **⚙️ Creative Tools**: Visual interfaces for theme building, rule creation, and advanced customization
+
+### Planned Engine Integrations (Future Release)
+
+- **🎮 Unity Plugin**: Package Manager compatible integration (planned)
+- **🎯 Godot Addon**: Asset Library compatible addon (planned)
+- **🔗 Game Engine Guides**: Integration patterns and API examples available now
+
+## Event Economy System 💰
+
+The Event Economy enables **user-generated content sharing** and marketplace functionality for custom themes, rules, and content packs.
+
+### Key Features
+
+- **🎨 Theme Marketplace**: Save, share, and import custom themes with training data
+- **🧠 Rule Pack Sharing**: Exchange collections of custom rules between users
+- **📦 Content Packs**: Bundle themes and rules into complete game configurations
+- **⭐ Quality Metrics**: Automatic quality scoring for shared content
+- **📤 Export/Import**: Easy sharing via JSON files
+
+### Basic Usage
+
+```javascript
+const EventEconomy = require('./scripts/event-economy');
+
+// Initialize the system
+const economy = new EventEconomy('./my-user-content');
+
+// Save a custom theme
+const themeData = {
+  author: 'YourName',
+  description: 'Cyberpunk western theme',
+  tags: ['cyberpunk', 'western', 'scifi'],
+  theme: 'cyberpunk',
+  culture: 'western',
+  trainingData: [
+    'neon signs flicker in the dusty saloon',
+    'robotic sheriffs patrol the asteroid streets',
+    'cyborg outlaws ride mechanical horses'
+  ],
+  enableRuleEngine: true,
+  customRules: [] // your custom rules here
+};
+
+const filepath = economy.saveTheme('CyberWestern', themeData);
+console.log(`Theme saved to: ${filepath}); // ./my-user-content/themes/cyberwestern.json
+
+// List available themes
+const themes = economy.listThemes();
+console.log('Available themes:', themes);
+
+// Load and use a theme
+const loadedTheme = economy.loadTheme('CyberWestern');
+// Use with generator...
+```
+
+### CLI Tools
+
+The Event Economy includes command-line tools for content management:
+
+```bash
+# Using npm scripts (recommended)
+npm run economy:list
+npm run economy:stats
+
+# Using direct script calls
+node scripts/event-economy.js list-themes
+node scripts/event-economy.js stats
+
+# Save a theme (API integration needed)
+node scripts/event-economy.js save-theme "MyTheme"
+```
+
+For global installation, you can also use:
+```bash
+npx rpg-events list-themes
+npx rpg-export unity fantasy
+```
+
+### Content Pack Creation
+
+```javascript
+// Create a complete content pack
+const packData = {
+  author: 'ContentCreator',
+  description: 'Complete cyberpunk western adventure pack',
+  theme: themeData, // include your theme
+  rulePacks: ['combat-rules', 'dialogue-rules'] // reference rule packs
+};
+
+const packPath = economy.createContentPack('CyberWesternAdventure', packData);
+```
+
+### File Formats
+
+#### Theme Files (`themes/*.json`)
+```json
+{
+  "name": "CyberWestern",
+  "version": "1.0.0",
+  "author": "YourName",
+  "description": "Cyberpunk western theme",
+  "tags": ["cyberpunk", "western"],
+  "settings": {
+    "theme": "cyberpunk",
+    "culture": "western",
+    "enableRuleEngine": true,
+    "pureMarkovMode": false
+  },
+  "trainingData": ["sentence 1", "sentence 2"],
+  "customRules": [],
+  "statistics": {
+    "trainingSentences": 2,
+    "estimatedQuality": 85
+  }
+}
+```
+
+#### Rule Pack Files (`rules/*.json`)
+```json
+{
+  "name": "CombatRules",
+  "rules": [
+    {
+      "name": "weak_enemy_bonus",
+      "conditions": [
+        {"type": "stat_less_than", "stat": "level", "value": 5}
+      ],
+      "effects": [
+        {"type": "modify_difficulty", "value": -1}
+      ]
+    }
+  ]
+}
+```
+
+### Quality Metrics
+
+Themes are automatically scored on:
+- **Training Data Quality**: Sentence variety and length
+- **Rule Complexity**: Advanced rule usage
+- **Completeness**: All required fields present
+- **Metadata**: Author info, tags, descriptions
+
+### Integration with Generator
+
+```javascript
+// Load theme and apply to generator
+const theme = economy.loadTheme('CyberWestern');
+const generator = new RPGEventGenerator({
+  theme: theme.settings.theme,
+  culture: theme.settings.culture,
+  trainingData: theme.trainingData,
+  customRules: theme.customRules,
+  enableRuleEngine: theme.settings.enableRuleEngine
+});
+
+// Generate events with custom theme
+const event = generator.generateEvent();
+```
+
 ## Usage Guide
 
 ### Basic Event Generation
@@ -315,12 +497,12 @@ const event = generator.generateEnhancedEvent({
 
 ### Event Templates Library (v1.3.0)
 
-Load pre-built event collections for different game genres:
+Use the included library of 429 professionally crafted event templates across 7 genres:
 
 ```javascript
 const generator = new RPGEventGenerator({
   enableTemplates: true,
-  templateLibrary: 'fantasy'  // Auto-load fantasy templates
+  templateLibrary: 'fantasy'  // Load fantasy templates
 });
 
 // Generate from specific template
@@ -332,9 +514,16 @@ const fantasyEvent = generator.generateFromGenre('fantasy');
 
 // Discover available templates
 const availableTemplates = generator.getAvailableTemplates();
-console.log(Object.keys(availableTemplates)); // ['fantasy']
+console.log(Object.keys(availableTemplates)); // ['fantasy', 'sci-fi', etc.]
+```
 
-// Available genres: 'fantasy', 'sci-fi', 'horror', 'historical'
+You can also export templates to other formats using CLI tools:
+
+```bash
+# Export templates for different engines
+npm run export:unity fantasy        # Unity C# ScriptableObjects
+npm run export:godot cyberpunk      # Godot GDScript Resources
+npm run export:typescript space-opera # TypeScript interfaces
 ```
 
 Each template includes:
@@ -343,6 +532,8 @@ Each template includes:
 - **Difficulty scaling** and context requirements
 - **Professional quality** event design
 
+**Available genres**: 'fantasy', 'sci-fi', 'horror', 'historical', 'modern', 'cyberpunk', 'space-opera'
+
 #### Custom Template Creation
 Add your own templates to the library system:
 
@@ -579,7 +770,310 @@ const generator = new RPGEventGenerator({
   urgency: "normal",
   theme: "adventure",
   difficulty: "normal"
+
+}
+```
+
+## 🎨 v2.0.0 Theme Creator
+
+Create completely custom game worlds with your own atmospheric text and storytelling style.
+
+### Custom Theme Creation
+
+```javascript
+const generator = new RPGEventGenerator({
+  trainingData: [
+    'Space cowboys patrol asteroid fields on mechanical horses',
+    'Neon-lit cantinas echo with the hum of quantum pianos',
+    'Laser revolvers fire streams of pure starlight',
+    'Alien saloons serve drinks that change your memories',
+    'Robotic sheriffs maintain order in floating colonies'
+  ],
+  theme: 'sci-fi',
+  culture: 'western'
+});
+
+// Events will incorporate your custom atmosphere
+const event = generator.generateEvent({
+  career: 'gunslinger',
+  location: 'asteroid-town'
+});
+```
+
+### Pure Markov Mode
+
+Generate events using only your custom training data - completely bypassing templates.
+
+```javascript
+const pureGenerator = new RPGEventGenerator({
+  trainingData: [
+    'Crystal caves echo with ancient magic',
+    'Shadowy figures move through fog-shrouded forests',
+    'Forgotten ruins hide treasures and traps',
+    'Mysterious merchants offer enchanted artifacts',
+    'Wandering bards sing tales of lost kingdoms'
+  ],
+  pureMarkovMode: true,  // No templates used
+  enableTemplates: false
+});
+
+// Generates events purely from your text
+const event = pureGenerator.generateEvent();
+// Type: "MARKOV_GENERATED"
+// Title: "Crystal caves echo with ancient magic."
+// Description: Generated purely from your atmospheric training sentences
+```
+
+## 🧠 v2.0.0 Rule Engine
+
+Create intelligent, conditional rules that modify events based on player state and game context.
+
+### Basic Rule Creation
+
+```javascript
+const generator = new RPGEventGenerator({
+  enableRuleEngine: true
+});
+
+// Add a wealthy player bonus
+generator.addCustomRule('wealthy_bonus', {
+  conditions: [
+    { type: 'stat_greater_than', params: { stat: 'gold', value: 1000 } }
+  ],
+  effects: {
+    addTags: ['wealthy_player'],
+    modifyChoices: {
+      multiply: { gold: 1.3 },  // 30% more gold rewards
+      add: { reputation: 5 }    // Bonus reputation
+    }
+  }
+});
+
+// Events for wealthy players get enhanced
+const wealthyEvent = generator.generateEvent({ gold: 2000 });
+console.log(wealthyEvent.tags); // Includes 'wealthy_player'
+```
+
+### Advanced Rule Conditions
+
+```javascript
+// Complex conditional logic
+generator.addCustomRule('noble_intrigue', {
+  conditions: [
+    { type: 'and', params: {
+      conditions: [
+        { type: 'career_is', params: { career: 'noble' } },
+        { type: 'location_is', params: { location: 'castle' } },
+        { type: 'stat_greater_than', params: { stat: 'influence', value: 50 } }
+      ]
+    }}
+  ],
+  effects: {
+    modifyTitle: { append: ' (Royal Privilege)' },
+    setDifficulty: 'hard',
+    addTags: ['noble_bonus', 'court_influence']
+  }
+});
+
+// Available condition types:
+// - stat_greater_than, stat_less_than, stat_between
+// - location_is, season_is, career_is, time_greater_than
+// - has_item, relationship_status
+// - random_chance
+// - and, or, not (for combining conditions)
+```
+
+### Rule Management
+
+```javascript
+// Validate rules before adding
+const rule = { /* your rule */ };
+const validation = generator.validateCustomRule(rule);
+if (validation.valid) {
+  generator.addCustomRule('my_rule', rule);
+} else {
+  console.log('Rule errors:', validation.errors);
 }
+
+// Manage rules
+console.log(generator.getCustomRules());  // View all rules
+generator.removeCustomRule('my_rule');    // Remove specific rule
+generator.clearCustomRules();             // Remove all rules
+```
+
+## 🌐 v2.0.0 Cross-Platform Export
+
+Export your events directly to game engines.
+
+### Unity Integration
+
+```javascript
+// Programmatic export
+const exporter = require('./scripts/export-templates.js');
+exporter.exportTemplates('unity', 'fantasy');
+
+// Creates: templates/unity/fantasy/event_1.cs
+// Result: Event1.cs - Unity ScriptableObject
+```
+
+```bash
+# Using npm scripts
+npm run export:unity fantasy
+
+# Direct script call
+node scripts/export-templates.js unity fantasy
+```
+
+### Godot Integration
+
+```javascript
+// Export for Godot
+const exporter = require('./scripts/export-templates.js');
+exporter.exportTemplates('godot', 'cyberpunk');
+
+// Creates: templates/godot/cyberpunk/event_1.gd
+// Result: Event1.gd - Godot Resource script
+```
+
+```bash
+# Using npm scripts
+npm run export:godot cyberpunk
+
+# Direct script call
+node scripts/export-templates.js godot cyberpunk
+```
+
+### TypeScript Support
+
+```javascript
+// Export as TypeScript interfaces
+const exporter = require('./scripts/export-templates.js');
+exporter.exportTemplates('typescript', 'space-opera');
+
+// Creates: templates/typescript/space-opera/event_1.ts
+// Result: Strongly-typed event definitions
+```
+
+```bash
+# Using npm scripts
+npm run export:typescript space-opera
+
+# Direct script call
+node scripts/export-templates.js typescript space-opera
+```
+
+## 📊 v2.0.0 Enhanced Template Library
+
+Generate 400+ professionally crafted events across 7 genres:
+
+- **Fantasy**: Knights, dragons, magic, medieval politics
+- **Sci-Fi**: Space exploration, technology, alien encounters
+- **Horror**: Supernatural terror, psychological horror
+- **Historical**: Medieval courts, exploration, diplomacy
+- **Modern**: Contemporary settings, urban adventures
+- **Cyberpunk**: Neon cities, hackers, megacorporations
+- **Space Opera**: Galactic empires, starships, cosmic conflicts
+
+### Template Integration
+
+```javascript
+// Load genre-specific templates
+const fantasyGen = new RPGEventGenerator({
+  enableTemplates: true,
+  templateLibrary: 'fantasy'
+});
+
+// Generate from specific genre
+const fantasyEvent = fantasyGen.generateFromGenre('fantasy');
+const horrorEvent = fantasyGen.generateFromTemplate('haunted_mansion');
+
+// Available templates
+console.log(fantasyGen.getAvailableTemplates());
+// { fantasy: [...], sci-fi: [...], horror: [...], etc. }
+```
+
+## 🎯 v2.0.0 API Reference
+
+### Constructor Options (v2.0.0 additions)
+
+```javascript
+const generator = new RPGEventGenerator({
+  // v1.x options still supported
+  theme: 'fantasy',
+  culture: 'norse',
+  trainingData: [...],
+  enableModifiers: true,
+
+  // v2.0.0 new options
+  enableRuleEngine: true,     // Enable custom rules system
+  customRules: {},           // Pre-load custom rules
+  pureMarkovMode: false,     // Generate purely from training data
+  templateLibrary: null,     // Load specific template genre
+  chance: new Chance()        // Custom Chance.js instance (optional)
+});
+```
+
+### New Methods (v2.0.0)
+
+```javascript
+// Rule Engine
+generator.addCustomRule(name, ruleDefinition);
+generator.removeCustomRule(name);
+generator.getCustomRules();
+generator.clearCustomRules();
+generator.validateCustomRule(rule);
+
+// Template System
+generator.generateFromTemplate(templateId);
+generator.generateFromGenre(genre);
+generator.getAvailableTemplates();
+
+// Export System (via export-templates.js)
+exporter.exportTemplates('unity', 'fantasy');
+exporter.exportTemplates('godot', 'cyberpunk');
+exporter.exportTemplates('typescript', 'space-opera');
+```
+
+## 🔄 v2.0.0 Migration Guide
+
+### From v1.x to v2.0.0
+
+**✅ Fully Backward Compatible**
+- All existing code continues to work unchanged
+- v1.x features remain fully functional
+- No breaking changes to existing API
+
+**🚀 New Features are Opt-in**
+```javascript
+// v1.x code - still works perfectly
+const generator = new RPGEventGenerator();
+
+// v2.0.0 enhancements - opt-in only
+const enhancedGenerator = new RPGEventGenerator({
+  enableRuleEngine: true,     // New feature
+  pureMarkovMode: false,      // New feature
+  templateLibrary: 'fantasy'  // Enhanced feature
+});
+```
+
+**📈 Performance Improvements**
+- Optimized rule evaluation
+- Efficient template loading
+- Better memory management for large template libraries
+
+**🎲 Custom Randomness Control**
+```javascript
+// For games that need deterministic randomness or custom seeding
+const customChance = new Chance('your-seed-here');
+const generator = new RPGEventGenerator({
+  chance: customChance  // Optional: pass your own Chance instance
+});
+
+// For testing with predictable results
+const testChance = new Chance(12345);  // Always same results
+const testGenerator = new RPGEventGenerator({
+  chance: testChance
+});
 ```
 
 ## 🎮 Game Integration
@@ -748,7 +1242,7 @@ function loadGame() {
 npm test
 ```
 
-**Comprehensive test coverage (45+ tests):**
+**Comprehensive test coverage (70+ tests):**
 - ✅ Core event generation and validation
 - ✅ Context adaptation and player responsiveness
 - ✅ Thematic systems and cultural variants
@@ -758,6 +1252,12 @@ npm test
 - ✅ Modular features and custom content
 - ✅ Edge cases and error handling
 - ✅ Game state persistence and integration
+- ✅ **Event Economy system (25+ tests)**
+  - Theme saving/loading/export/import
+  - Rule pack management
+  - Content pack creation
+  - Quality metrics and statistics
+  - File I/O operations and validation
 
 ## 🎯 Event Types