RPG Event Generator


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!

✨ Features

- 🧠 Intelligent Generation - Context aware events that adapt to user state with location, weather, time, class, and race integration
- 📚 Massive Content Library - 1,870+ unique narrative elements (850+ titles, 510+ descriptions, 510+ choices) across 17 event types
- 🎯 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
- 🎨 Thematic Consistency - Perfect alignment between titles, descriptions, and choices
- ♾️ Infinite Variety - 98%+ unique descriptions across 1000+ events
- 🎲 Optional Markov Mode - Traditional Markov chain generation available via pureMarkovMode option

📦 Installation

``bash
npm install rpg-event-generator
`

$3

- Node.js 16+
- TypeScript 4.5+ (for development)

🚀 Quick Start

$3

`javascript
const { RPGEventGenerator, generateRPGEvent } = require('rpg-event-generator');

// Simple event generation with context
const event = generateRPGEvent({
age: 25,
gold: 500,
influence: 15,
career: 'merchant',
location: 'market',
weather: 'sunny',
class: 'trader'
});

console.log(event.title); // "Golden Opportunity"
console.log(event.description); // "In the market, beneath clear blue skies, a shrewd merchant..."
console.log(event.choices); // Array of contextually relevant choices
console.log(event.type); // "ECONOMIC"
console.log(event.tags); // ["economic", "moderate"]
`

$3

`javascript
const generator = new RPGEventGenerator({
theme: 'fantasy'
});

// Generate context aware event with rich contextual details
const event = generator.generateEvent({
level: 15,
gold: 2500,
class: 'wizard',
race: 'elf',
location: 'tower',
weather: 'storm',
timeOfDay: 'night'
});

console.log(event.title); // "Arcane Ritual Chamber"
console.log(event.description); // "Deep in the night, within the shadows of the tower, arcane runes float..."
console.log(event.choices); // Perfectly matched magical choices
console.log(event.type); // "MAGIC" or "SPELLCASTING"
`

$3

`javascript
// Add custom content for any theme
generator.addTrainingData({
titles: {
COMBAT: ['⚔️ Epic Duel', '🗡️ Warrior Showdown']
},
descriptions: {
COMBAT: ['Two legendary warriors circle each other in a duel that will determine the fate of kingdoms.']
},
choices: {
COMBAT: ['⚔️ Engage in honorable combat', '🛡️ Take defensive position', '💨 Attempt strategic retreat']
}
}, 'custom_theme');

// Custom content is automatically used when generating events
const event = generator.generateEvent({ class: 'fighter' });
// Will use custom content from 'custom_theme' if available
`

🎨 Advanced Usage

$3

`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();
`

$3

`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 } }
}]
});
`

$3

`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

$3

- generateEvent(context) - Generate single context-aware event with 1,870+ possible narrative combinations
- generateEvents(context, count) - Generate multiple unique events
- addTrainingData(data, theme) - Add custom titles, descriptions, and choices (supports multi-theme)

$3

- generateWorld() - Create game world
- registerTemplate(id, template) - Add custom template
- exportTemplates(format, path) - Export to game engines

$3

17 Event Types: ADVENTURE, COMBAT, ECONOMIC, EXPLORATION, GUILD, MAGIC, MYSTERY, POLITICAL, QUEST, SOCIAL, SPELLCASTING, SUPERNATURAL, TECHNOLOGICAL, UNDERWORLD, FIGHTER, CLERIC, ROGUE, MAGE, NECROMANCER

Each type includes 50+ titles, 30+ descriptions, and 30+ specific choices for infinite variety.

Full API docs: Documentation

📄 License

MIT License - see LICENSE file.

🎯 Use Cases & Examples

$3

`javascript
// RPG Character Interactions with Rich Context
const generator = new RPGEventGenerator({ theme: 'fantasy' });
const playerState = {
level: 15,
class: 'wizard',
race: 'elf',
gold: 2500,
reputation: 75,
location: 'ancient library',
weather: 'foggy',
timeOfDay: 'midnight'
};

const event = generator.generateEvent(playerState);
// Result: "At the stroke of midnight, deep within the ancient library, arcane runes float in the air..."
// With perfectly matched choices like "Channel arcane energies", "Consult mystical visions", etc.
`

$3

`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
});
`

$3

`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']
});
`

$3

`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']
});
`

🆕 Latest Features (v4.0.0)

$3

The core event generation system has been completely rebuilt to provide truly infinite event variety:

- 1,870+ Unique Narrative Elements: Expanded from 8 titles/5 descriptions/4 choices to 50+ titles/30+ descriptions/30+ choices per event type
- Perfect Thematic Matching: Choices now perfectly align with event descriptions (e.g., scouting descriptions get military choices)
- Enhanced Context Integration: Dynamic contextual phrases based on location (70% rate), weather (60% rate), time of day (50% rate), and class/race (40% rate)
- Proven Variety: 100% unique titles, 98% unique descriptions in 50-event batches
- Multi-Theme Support: Custom content from any theme is automatically discovered and used
- Simplified Architecture: Replaced Markov chain generation with direct content mapping for more reliable, coherent output (Markov chains still available via pureMarkovMode option)

$3

`javascript
// Before: Generic, repetitive
Title: "Dangerous Encounter"
Description: "A situation presents itself."
Choices: ["Fight bravely", "Use strategy"]

// After: Rich, contextual, unique
Title: "Scouts' Vital Intelligence"
Description: "Beneath the stormy downpour, scouts range ahead of main forces, mapping terrain and reporting enemy positions with deadly accuracy."
Choices: ["Report findings", "Set up ambush", "Gather more intelligence", "Return to base"]
`

Previous Features (v3.1.0)

$3

Store and retrieve templates from databases for large-scale applications:

`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' });
`

$3

Generate entire game worlds with factions, regions, and historical events:

`javascript
const world = await generator.generateWorld();
await generator.simulateWorldYears(50); // Advance world history
const factionPower = generator.getFactionPowerRanking();
`

$3

Create complex, conditional templates with inheritance and composition:

`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 } }
}]
};

// 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 }]
}]
};
`

$3

Handle large-scale generation with advanced caching and parallel processing:

`javascript
const generator = new RPGEventGenerator({
enableTemplateCaching: true,
enableEventCaching: true
});

// 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

$3

- Wiki Available: Comprehensive guides, tutorials, and examples available on the GitHub Wiki
- API Documentation: Complete TypeDoc reference available on GitHub Pages

$3

- 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

$3

- 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.

$3

`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
``

📄 License

MIT License - see LICENSE file for details.

---

Generate infinite possibilities with RPG Event Generator! 🎲✨