rpg-event-generator 3.1.1 → 4.0.1

package/README.md

@@ -3,336 +3,86 @@
 [![npm version](https://badge.fury.io/js/rpg-event-generator.svg)](https://badge.fury.io/js/rpg-event-generator)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A powerful procedural content generation system for dynamic, context aware narratives and interactive experiences. Perfect for games, simulations, and creative applications.
-
-## ☕ Support
-
-If RPG Event Generator has been helpful to your project, consider buying me a coffee!
-
-<a href="https://www.buymeacoffee.com/Decept1kon" target="_blank">
-  <img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;">
-</a>
-
-## ✨ Features
-
-- **🧠 Intelligent Generation** - Context aware events that adapt to user state
-- **🎯 Advanced Templates** - Conditional templates, composition, inheritance, mixins
-- **🌍 World Building** - Automated world generation with factions and history
-- **⚡ Performance** - Template caching, parallel generation, batched processing
-- **🔌 Pluggable AI** - Optional AI/ML integration with multiple providers
-- **💾 Database Support** - Scalable storage with pluggable adapters
-- **🎮 Game Engine Export** - Unity C#, Godot GDScript, Unreal Engine C++
-- **🌐 Multi Language** - Generate content in different languages
-- **⏰ Time Systems** - Seasonal changes and temporal progression
-- **🤝 Relationship Networks** - Dynamic character relationships
-- **🎲 Markov Chains** - Natural sounding narratives
-
-## 📦 Installation
+Offline procedural RPG events with context flavoured text and a built in content library. No API key required.
 
 ```bash
 npm install rpg-event-generator
 ```
 
-### Requirements
-- Node.js 16+
-- TypeScript 4.5+ (for development)
+Requires Node.js 16+.
 
-## 🚀 Quick Start
-
-### Basic Usage
+## Quick start
 
 ```javascript
-const { RPGEventGenerator, generateRPGEvent } = require('rpg-event-generator');
+const { generateRPGEvent } = require('rpg-event-generator');
 
-// Simple event generation
 const event = generateRPGEvent({
-  age: 25,
-  gold: 500,
-  influence: 15,
-  career: 'merchant'
-});
-
-console.log(event.title);        // "Golden Opportunity"
-console.log(event.description);  // Procedurally generated narrative
-console.log(event.choices);      // Array of meaningful choices
-```
-
-### With Custom Configuration
-
-```javascript
-const generator = new RPGEventGenerator({
-  theme: 'fantasy'
-});
-
-// Generate context aware event
-const event = generator.generateEvent({
-  level: 15,
-  gold: 2500,
-  class: 'wizard'
+  level: 10,
+  location: 'forest',
+  weather: 'rainy',
+  class: 'fighter'
 });
 
-console.log(event.title);
-console.log(event.description);
-console.log(event.choices);
+console.log(event.title);        // e.g. "Heroic Quest"
+console.log(event.description);  // context prefixes: location, weather, time, class, race
+console.log(event.choices);      // [{ text, effect }, ...]
+console.log(event.type);         // e.g. "COMBAT"
 ```
 
-## 🎨 Advanced Usage
+Or with a configured instance:
 
-### World Building
 ```javascript
-// Generate complete game world
-const world = await generator.generateWorld();
-console.log(`World: ${world.regions.length} regions, ${world.factions.length} factions`);
-
-// Simulate history
-await generator.simulateWorldYears(50);
-const history = generator.getHistoricalEvents();
-```
+const { RPGEventGenerator } = require('rpg-event-generator');
 
-### Custom Templates
-```javascript
-// Register conditional template
-generator.registerTemplate('merchant', {
-  title: "Merchant Encounter",
-  conditional_choices: [{
-    condition: { player_gold: { gt: 1000 } },
-    choice: { text: "Buy rare artifact", effect: { gold: -500 } }
-  }]
-});
-```
-
-### AI Enhancement
-```javascript
-const aiGenerator = new RPGEventGenerator({
-  aiEnhancement: {
-    provider: 'openai',
-    apiKey: process.env.OPENAI_API_KEY
-  }
-});
-```
-
-## 🔧 Configuration
-
-```javascript
-const config = {
-  theme: 'fantasy',
-  enableAI: false,
-  enableDatabase: false,
-  enableCaching: true,
-  maxParallelGeneration: 4,
-
-  aiEnhancement: {
-    provider: 'openai',
-    apiKey: 'your-key'
-  }
-};
-```
-
-## 📚 API
-
-- `generateEvent(context)` - Generate single event
-- `generateEvents(context, count)` - Generate multiple events
-- `generateWorld()` - Create game world
-- `registerTemplate(id, template)` - Add custom template
-- `exportTemplates(format, path)` - Export to game engines
-
-Full API docs: [Documentation](https://ContextWeaver.github.io/context-weaver/)
-
-## 📄 License
-
-MIT License - see [LICENSE](LICENSE) file.
-
-## 🎯 Use Cases & Examples
-
-### Gaming Applications
-```javascript
-// RPG Character Interactions
 const generator = new RPGEventGenerator({ theme: 'fantasy' });
-const playerState = {
-  level: 15,
-  class: 'wizard',
-  gold: 2500,
-  reputation: 75
-};
-
-const event = generator.generateEvent(playerState);
-// Result: "The ancient tome pulses with magical energy..."
-```
-
-### Business Simulations
-```javascript
-// Customer Service Scenarios
-const businessGenerator = new RPGEventGenerator({
-  trainingData: [
-    'Customer reports billing discrepancy',
-    'Technical support ticket resolved',
-    'Product feedback received and processed'
-  ]
-});
-
-const scenario = businessGenerator.generateEvent({
-  department: 'support',
-  priority: 'high',
-  customerValue: 85
-});
-```
-
-### Educational Tools
-```javascript
-// Interactive Learning Scenarios
-const educationGenerator = new RPGEventGenerator({
-  theme: 'historical',
-  culture: 'educational'
-});
-
-const lesson = educationGenerator.generateEvent({
-  subject: 'history',
-  difficulty: 'intermediate',
-  learningObjectives: ['critical_thinking', 'decision_making']
-});
-```
-
-### Research & Data Simulation
-```javascript
-// User Behavior Modeling
-const researchGenerator = new RPGEventGenerator({
-  enableRelationships: true,
-  enableModifiers: true
-});
-
-const simulation = researchGenerator.generateEvent({
-  userType: 'research_subject',
-  conditions: ['experimental', 'controlled'],
-  variables: ['time_pressure', 'cognitive_load']
-});
+const event = generator.generateEvent({ level: 15, class: 'wizard', location: 'tower' });
 ```
 
-## 🆕 Latest Features (v3.1.0)
-
-### Database Integration
-Store and retrieve templates from databases for large-scale applications:
+## Custom content
 
 ```javascript
-const generator = new RPGEventGenerator({ enableDatabase: true });
-
-await generator.storeTemplateInDatabase(customTemplate);
-const retrieved = await generator.getTemplateFromDatabase('template_id');
-const searchResults = await generator.searchTemplatesInDatabase({ type: 'combat' });
+generator.addTrainingData({
+  titles: { COMBAT: ['Epic Duel'] },
+  descriptions: { COMBAT: ['Two warriors circle each other...'] },
+  choices: { COMBAT: ['Fight', 'Flee', 'Negotiate'] }
+}, 'my_theme');
 ```
 
-### World Building System
-Generate entire game worlds with factions, regions, and historical events:
+Use structured objects (`titles`, `descriptions`, `choices`). Raw string arrays are ignored in v4.
 
-```javascript
-const world = await generator.generateWorld();
-await generator.simulateWorldYears(50); // Advance world history
-const factionPower = generator.getFactionPowerRanking();
-```
+## Feature tiers
 
-### Advanced Template Features
-Create complex, conditional templates with inheritance and composition:
+**Start with Tier 1.** Everything else is optional.
 
-```javascript
-// Conditional templates
-const conditionalTemplate = {
-  id: 'level_based_event',
-  conditions: [{ type: 'stat_requirement', field: 'level', operator: 'gte', value: 10 }],
-  conditional_choices: [{
-    condition: { type: 'has_item', item: 'magic_sword' },
-    choice: { text: 'Use magic sword', effect: { damage: 50 } }
-  }]
-};
+| Tier | What | Use when |
+|------|------|----------|
+| **1 — Core** | `generateRPGEvent()` / `generateEvent()`, built-in library, `addTrainingData()` | Game jams, first ship |
+| **2 — Orchestrator** | Templates, rules, environmental modifiers, optional AI | Custom event logic |
+| **3 — Toolkit** | World sim, DB adapters, engine export scripts | Lore JSON, tooling experiments |
 
-// Template composition
-const composedTemplate = {
-  id: 'weather_merchant',
-  composition: [{
-    template_id: 'merchant_base',
-    merge_strategy: 'append_narrative'
-  }, {
-    template_id: 'weather_effects',
-    conditions: [{ type: 'random_chance', probability: 0.6 }]
-  }]
-};
-```
+Tier 3 (`generateWorld(seed)` or `{ seed, continentCount }`) produces seeded lore JSON — regions, factions, history. Use `getWorldLore(location)` for a one-line hook into player events. Not a live sim backbone.
 
-### Performance Optimizations
-Handle large-scale generation with advanced caching and parallel processing:
+## Documentation
 
-```javascript
-const generator = new RPGEventGenerator({
-  enableTemplateCaching: true,
-  enableEventCaching: true
-});
+Full guides ship with the repo — no wiki required.
 
-// Generate events in parallel
-const events = await generator.generateEventsParallel(100, context, 4); // 4 threads
-// Generate in batches for memory efficiency
-const batchedEvents = generator.generateEventsBatched(1000, context, 50); // 50 events per batch
-```
-
-## 🎮 Demo
-
-Run the included demo to explore all features:
-
-```bash
-# Using npm script (recommended)
-npm run demo
-
-# Direct script call
-node demo.js
-```
-
-This will demonstrate event generation, chains, time progression, customization, and more.
-
-## 📚 Documentation & Resources
-
-### 📖 Documentation
-- **Wiki Available**: Comprehensive guides, tutorials, and examples available on the [GitHub Wiki](https://github.com/ContextWeaver/context-weaver/wiki)
-- **API Documentation**: Complete TypeDoc reference available on [GitHub Pages](https://contextweaver.github.io/context-weaver/)
-
-### 🛠️ Development & Testing
-- Run `npm run demo` to see all 30+ features in action
-- Run `npm run docs` to regenerate API documentation
-- Run `npm test` to execute the comprehensive test suite
-- Check the `demo.js` file for interactive examples
-- Check the `test/` directory for usage examples
-
-### 📂 Key Directories
-- `src/` - Modular TypeScript source code
-- `docs/` - Complete documentation and guides
-- `templates/` - Built-in event templates
-- `test/` - Comprehensive test suite
-- `scripts/` - Build and export scripts
-
-## 🤝 Contributing
-
-We welcome contributions! Please feel free to submit issues, feature requests, and pull requests.
-
-### Development Setup
-
-```bash
-# Clone the repository
-git clone https://github.com/ContextWeaver/context-weaver.git
-cd context-weaver
-
-# Install dependencies
-npm install
-
-# Run tests
-npm test
-
-# Run demo
-npm run demo
-
-# Build for distribution
-npm run build
-```
+| Guide | Topic |
+|-------|--------|
+| [Getting Started](https://contextweaver.github.io/context-weaver/documents/getting-started.html) | Install, quick start, context fields |
+| [Examples](https://contextweaver.github.io/context-weaver/documents/examples.html) | Copy-paste snippets by tier |
+| [Custom Content](https://contextweaver.github.io/context-weaver/documents/custom-content.html) | `addTrainingData()` |
+| [Feature Tiers](https://contextweaver.github.io/context-weaver/documents/feature-tiers.html) | What to use when |
+| [World Building](https://contextweaver.github.io/context-weaver/documents/world-building.html) | Seeded world lore |
+| [Templates & Rules](https://contextweaver.github.io/context-weaver/documents/templates-and-rules.html) | Tier 2 orchestrator |
+| [Configuration](https://contextweaver.github.io/context-weaver/documents/configuration.html) | Generator options |
+| [Advanced Tooling](https://contextweaver.github.io/context-weaver/documents/advanced-tooling.html) | DB, export, AI |
 
-## 📄 License
+Build locally: `npm run docs` → open `docs/index.html`
 
-MIT License - see [LICENSE](LICENSE) file for details.
+- **API reference:** [contextweaver.github.io/context-weaver](https://contextweaver.github.io/context-weaver/)
+- **Migration (v3 → v4):** [MIGRATION.md](MIGRATION.md)
+- **Smoke test (local):** `npm run build && npm run demo` — short CLI check, not a feature tour
 
----
+## License
 
-**Generate infinite possibilities with RPG Event Generator!** 🎲✨
+MIT — see [LICENSE](LICENSE).