rpg-event-generator 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Decept1kon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,430 @@
+# RPG Event Generator
+
+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
+
+```bash
+npm install rpg-event-generator
+```
+
+```javascript
+import { RPGEventGenerator, generateRPGEvent } from 'rpg-event-generator';
+
+// Quick single event
+const event = generateRPGEvent({
+  age: 25,
+  gold: 500,
+  influence: 15,
+  career: 'merchant'
+});
+
+console.log(event.title); // "Golden Opportunity"
+console.log(event.description); // Procedurally generated description
+console.log(event.choices); // Array of choices with effects
+
+// Advanced usage with custom generator
+const generator = new RPGEventGenerator({
+  stateSize: 2,
+  trainingData: ['Your custom story fragments...']
+});
+
+// Generate multiple events
+const events = generator.generateEvents({
+  age: 30,
+  gold: 1000,
+  influence: 25,
+  career: 'knight',
+  skills: { combat: 60, diplomacy: 40 }
+}, 3);
+```
+
+## 📖 Usage Examples
+
+### 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.",
+//   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,
+//   urgency: "normal",
+//   theme: "adventure",
+//   context: { /* player context used */ }
+// }
+```
+
+### Context-Aware Events
+
+```javascript
+const playerContext = {
+  age: 35,
+  gold: 2500,
+  influence: 40,
+  reputation: 25,
+  career: 'noble',
+  skills: {
+    diplomacy: 70,
+    combat: 45,
+    intrigue: 30
+  },
+  relationships: [
+    { name: 'Lord Harrington', type: 'ally', relationship: 60 },
+    { name: 'Lady Beaumont', type: 'lover', relationship: 45 }
+  ],
+  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
+```
+
+### Custom Training Data
+
+```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'
+];
+
+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;
+}
+```
+
+## 📊 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
+
+## 🔮 Future Enhancements
+
+- **Thematic Training Sets**: Fantasy, Sci-fi, Historical themes
+- **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
+
+---
+
+**Generate infinite adventures with RPG Event Generator!** ⚔️📚✨