DiceTales

DiceTales Better DM AI Documentation

Overview

The Better DM AI (better-dm/js/betterDMAI.js) is an advanced campaign management system that combines sophisticated AI storytelling with structured campaign roadmaps. This system provides enhanced narrative coherence, dynamic campaign adaptation, and intelligent story arc management for complex, long-term RPG experiences.

Architecture

Core Components

System Integration

BetterDMAI Architecture:
├── Campaign Roadmap Manager    # Story structure and planning
├── AI Response Engine         # HuggingFace integration with roadmap awareness
├── Context Management         # Conversation history and plot tracking
├── Quality Assessment         # Response coherence and roadmap adherence
├── Dynamic Adaptation         # Real-time story adjustment
└── Emergency Systems          # Fallback responses and error handling

Key Features

🗺️ Campaign Roadmap Integration

Structured Story Planning:

Roadmap Structure:

campaignRoadmap: {
    title: "The Lost Crown of Valdris",
    theme: "Political intrigue and ancient magic",
    chapters: [
        {
            title: "The Mysterious Disappearance",
            objectives: ["Investigate the missing crown", "Meet key NPCs"],
            keyEvents: ["Discovery of magical traces", "First enemy encounter"],
            estimatedSessions: 2
        }
    ],
    keyNPCs: [...],
    majorLocations: [...],
    overarchingPlot: "..."
}

🧠 Advanced Context Management

Enhanced Memory System:

Context Building:

systemContext: {
    campaignOverview: "Current campaign summary",
    characterProgress: "Player character development",
    plotProgression: "Current story arc status",
    relationshipMap: "NPC relationship tracking",
    worldState: "Current world conditions"
}

📊 Response Quality Assessment

Multi-Metric Evaluation:

Quality Tracking:

responseQuality: {
    coherenceScore: 8.2,
    engagementScore: 7.8,
    roadmapAdherence: 9.1,
    averageScore: 8.4,
    trendDirection: 'improving'
}

🎯 Dynamic Story Adaptation

Intelligent Plot Adjustment:

Adaptation Mechanisms:

API Reference

Constructor

const betterDMAI = new BetterDMAI();

Core Methods

async initialize(campaignConfig)

Initializes the Better DM AI system with campaign configuration.

await betterDMAI.initialize({
    campaignPrompt: "A political conspiracy threatens the kingdom",
    characterInfo: characterData,
    setting: "medieval-fantasy",
    tone: "serious-dramatic"
});

async generateCampaignStart(character, campaign)

Generates the initial campaign story with roadmap integration.

const startStory = await betterDMAI.generateCampaignStart(character, campaign);

async processPlayerAction(actionData)

Processes player actions with roadmap awareness and dynamic adaptation.

const response = await betterDMAI.processPlayerAction({
    action: "Investigate the noble's private chambers",
    type: "exploration",
    context: "Political intrigue investigation"
});

async generateRoadmapAwareResponse(prompt, context)

Generates AI responses that consider campaign roadmap and story structure.

const response = await betterDMAI.generateRoadmapAwareResponse(
    "Player wants to confront the suspected traitor",
    {
        currentChapter: 2,
        plotProgression: "mid-investigation",
        keyNPCs: availableNPCs
    }
);

updateRoadmapProgression(playerChoice, outcome)

Updates campaign roadmap based on player decisions and story outcomes.

betterDMAI.updateRoadmapProgression(
    "Allied with the rebel faction",
    "Story arc shifts toward rebellion support"
);

Campaign Management

getCurrentCampaignState()

Returns comprehensive campaign state including roadmap progress.

const campaignState = betterDMAI.getCurrentCampaignState();

assessStoryCoherence(response, context)

Evaluates response coherence with ongoing story and roadmap.

const coherenceScore = betterDMAI.assessStoryCoherence(response, context);

generateAdaptiveChoices(currentSituation)

Creates player choice options that consider roadmap flexibility.

const choices = betterDMAI.generateAdaptiveChoices({
    situation: "Confronting the corrupt governor",
    availableApproaches: ["diplomatic", "aggressive", "stealthy"],
    roadmapImplications: "Chapter 3 climax"
});

Quality and Performance

evaluateResponseQuality(response, context)

Comprehensive response quality assessment.

const qualityReport = betterDMAI.evaluateResponseQuality(response, {
    playerAction: "Attempt to negotiate peace",
    expectedOutcome: "Diplomatic resolution or conflict escalation",
    roadmapAlignment: "Chapter 2 political subplot"
});

getPerformanceMetrics()

Returns system performance and quality metrics.

const metrics = betterDMAI.getPerformanceMetrics();

optimizeResponseGeneration()

Optimizes AI response generation based on performance data.

await betterDMAI.optimizeResponseGeneration();

Campaign Roadmap Features

📖 Structured Story Arcs

Chapter Organization:

Plot Thread Management:

👥 Advanced NPC Management

Comprehensive NPC Profiles:

keyNPCs: [
    {
        name: "Lord Commander Thane",
        role: "Antagonist/Complex Ally",
        motivation: "Protect kingdom at any cost",
        secrets: ["Secret alliance with neighboring kingdom"],
        relationshipArc: "Enemy -> Reluctant Ally -> Trusted Friend",
        appearanceSchedule: ["Chapter 1", "Chapter 3", "Finale"]
    }
]

Dynamic Relationship Evolution:

🌍 World State Management

Environmental Storytelling:

Political and Social Systems:

Advanced Features

🔄 Dynamic Story Adaptation

Player Agency Respect:

Roadmap Flexibility:

adaptationStrategies: {
    playerDeviatesFromPlan: "Modify roadmap to incorporate new direction",
    unexpectedChoice: "Generate consequences while maintaining story coherence",
    characterDeath: "Adapt story arc to continue without breaking narrative",
    majorPlotChange: "Restructure remaining chapters around new direction"
}

📊 Intelligent Quality Assessment

Multi-Dimensional Scoring:

Continuous Improvement:

🎭 Enhanced Character Development

Character Arc Integration:

Dynamic Character Challenges:

Configuration Options

Campaign Settings

const campaignConfig = {
    structure: {
        chaptersPerCampaign: 5,
        sessionsPerChapter: 3,
        keyEventsPerChapter: 4,
        maxNPCsPerChapter: 6
    },
    adaptation: {
        flexibilityLevel: 'high',
        playerAgencyPriority: 'maximum',
        roadmapStrictnessLevel: 'moderate',
        emergentStoryIntegration: true
    },
    quality: {
        minimumCoherenceScore: 7.0,
        minimumEngagementScore: 6.5,
        roadmapAdherenceThreshold: 0.7,
        autoImprovementEnabled: true
    }
};

AI Model Configuration

const aiConfig = {
    models: [
        'microsoft/GODEL-v1_1-large-seq2seq',
        'facebook/blenderbot-400M-distill',
        'microsoft/DialoGPT-large',
        'gpt2-large'
    ],
    temperature: 0.8,
    maxTokens: 300,
    maxRetries: 3,
    timeout: 60000
};

Usage Examples

Campaign Initialization

// Initialize Better DM AI
const betterDM = new BetterDMAI();

// Set up campaign
await betterDM.initialize({
    campaignPrompt: "Ancient evil awakens in the peaceful kingdom of Aldermere",
    characterInfo: {
        name: "Sir Gareth",
        class: "Paladin",
        background: "Noble",
        level: 1
    },
    setting: "medieval-fantasy",
    tone: "heroic-adventure"
});

// Generate campaign start
const startStory = await betterDM.generateCampaignStart(character, campaign);

Dynamic Story Processing

// Process player action with roadmap awareness
const playerAction = {
    action: "Attempt to infiltrate the cult's secret meeting",
    type: "stealth",
    context: "Investigation of mysterious disappearances"
};

const response = await betterDM.processPlayerAction(playerAction);

// Evaluate response quality
const quality = betterDM.evaluateResponseQuality(response, {
    expectedCoherence: 8.0,
    roadmapAlignment: "Chapter 2 investigation phase",
    playerEngagement: "high-stakes infiltration"
});

// Update roadmap based on outcome
if (response.includes("successfully infiltrated")) {
    betterDM.updateRoadmapProgression(
        "Gained access to cult secrets",
        "Accelerate to Chapter 3 confrontation"
    );
}

Advanced Campaign Management

// Get comprehensive campaign state
const campaignState = betterDM.getCurrentCampaignState();

// Generate adaptive choices
const choices = betterDM.generateAdaptiveChoices({
    situation: "Discovered the cult leader's true identity",
    possibleApproaches: ["immediate confrontation", "gather more evidence", "seek allies"],
    roadmapConsiderations: "Chapter climax approaching"
});

// Monitor performance metrics
const metrics = betterDM.getPerformanceMetrics();
if (metrics.averageEngagement < 7.0) {
    await betterDM.optimizeResponseGeneration();
}

Integration Points

🎮 Game State Integration

🧠 Memory System Integration

📊 Quality Monitoring

Best Practices

Campaign Design

  1. Flexible Planning: Create roadmaps that allow for player agency
  2. Character Integration: Design story arcs that utilize character backgrounds
  3. Meaningful Choices: Ensure player decisions have lasting consequences
  4. Adaptive Storytelling: Be prepared to modify plans based on player actions

Quality Management

  1. Regular Assessment: Monitor response quality metrics consistently
  2. Player Feedback: Incorporate player satisfaction into quality evaluation
  3. Continuous Improvement: Use performance data to refine AI parameters
  4. Balance Structure: Maintain story coherence while allowing creative freedom

Performance Optimization

  1. Efficient Context: Build focused, relevant context for AI prompts
  2. Model Selection: Choose appropriate AI models for different story phases
  3. Quality Thresholds: Set realistic quality standards for automated assessment
  4. Response Caching: Cache and reuse successful response patterns

Troubleshooting

Common Issues

Roadmap Adherence Problems:

Quality Score Issues:

Performance Concerns:

Debug Functions

// Test roadmap generation
betterDM.debugRoadmapGeneration(campaignPrompt, characterInfo);

// Validate quality assessment
betterDM.debugQualityEvaluation(sampleResponse, context);

// Monitor performance metrics
betterDM.debugPerformanceMetrics();

Future Enhancements

Planned Features

  1. Machine Learning Adaptation: AI-powered roadmap optimization
  2. Multi-Character Campaigns: Support for party-based adventures
  3. Cross-Campaign Continuity: Persistent world across multiple campaigns
  4. Advanced NPC AI: Individual AI personalities for major NPCs
  5. Dynamic World Events: AI-generated background events and consequences

Technical Improvements

  1. Enhanced Prediction: Better player choice prediction algorithms
  2. Real-time Optimization: Live AI parameter adjustment
  3. Advanced Metrics: Deeper quality assessment and player satisfaction tracking
  4. Performance Scaling: Optimization for longer, more complex campaigns

Conclusion

The Better DM AI represents the next evolution in AI-powered tabletop gaming, combining structured campaign management with flexible, adaptive storytelling. By integrating comprehensive roadmap planning with intelligent AI responses, it creates complex, engaging RPG experiences that respond dynamically to player choices while maintaining narrative coherence and long-term story satisfaction.