DiceTales

DiceTales Main AI System Documentation

Overview

The Main AI System (advanced/js/ai.js) is the core storytelling engine of DiceTales, powered by HuggingFace’s advanced language models. This system provides human-like conversational AI with comprehensive memory integration, plot grounding, and dynamic storytelling capabilities.

Architecture

Core Components

Model Priority Queue

The system uses a prioritized list of HuggingFace models:

  1. microsoft/GODEL-v1_1-large-seq2seq - Primary conversational AI
  2. facebook/blenderbot-400M-distill - Optimized dialogue generation
  3. microsoft/GODEL-v1_1-base-seq2seq - Balanced performance model
  4. facebook/blenderbot-1B-distill - Large-scale conversational model
  5. microsoft/DialoGPT-large - Proven conversational model
  6. microsoft/DialoGPT-medium - Medium-sized reliable model
  7. gpt2-large / distilgpt2 - General purpose fallback models

Key Features

🤖 Human-Like Conversational AI

Advanced Models: Uses state-of-the-art conversational models specifically designed for natural dialogue generation.

Context Integration: Builds comprehensive prompts including:

💭 Enhanced Response Processing

Quality Enhancement Pipeline:

  1. Context Assembly: Builds comprehensive prompt with character and memory data
  2. API Request: Sends request to HuggingFace models with fallback handling
  3. Response Enhancement: Cleans and enhances raw AI output for immersion
  4. Memory Extraction: Automatically extracts important information for storage
  5. Display Processing: Formats response for game interface display

Meta-Commentary Filtering: Removes AI artifacts and improves immersion:

🧠 Memory System Integration

Comprehensive Context Building:

🎭 CHARACTER PROFILE: [Name, Class, Level, Background, Current Status]
📊 ABILITY SCORES: [STR, DEX, CON, INT, WIS, CHA with current values]
❤️ HEALTH STATUS: [Current/Max HP, conditions, injuries]
🎒 INVENTORY: [Equipped items, carried equipment, special items]
🧠 RECENT DECISIONS: [Last 3 significant choices and consequences]
👥 KEY RELATIONSHIPS: [Important NPCs and relationship status]
🔍 DISCOVERIES: [Recent findings and their significance]
🎯 SKILLS USED: [Frequently used skills and success patterns]
📖 ACTIVE PLOTS: [Current story threads and objectives]
🗺️ LOCATION CONTEXT: [Current area and relevant locations]

Automatic Information Tracking:

⚙️ Configuration Options

Conversation Settings:

conversationConfig: {
    maxContextLength: 2048,
    temperature: 0.8,
    topP: 0.9,
    repetitionPenalty: 1.1,
    maxNewTokens: 150,
    doSample: true,
    numBeams: 3
}

Memory Configuration:

memoryConfig: {
    maxConversationHistory: 20,
    plotContextWindow: 5,
    characterMemoryDepth: 10
}

API Reference

Constructor

const aiManager = new AIManager();

Core Methods

async initialize()

Initializes the AI system and tests model connections.

await aiManager.initialize();

async startCampaign()

Starts a new campaign with initial story generation.

await aiManager.startCampaign();

async processPlayerAction(actionData)

Processes player actions and generates AI responses.

await aiManager.processPlayerAction({
    action: "Search the ancient ruins",
    type: "exploration",
    diceRoll: { result: 15, sides: 20 }
});

buildMemoryContext(character, campaign)

Builds comprehensive memory context for AI prompts.

const context = aiManager.buildMemoryContext(character, campaign);

async callAI(messages)

Makes API calls to HuggingFace models with fallback system.

const response = await aiManager.callAI([
    { role: 'system', content: 'You are a helpful DM.' },
    { role: 'user', content: 'What happens next?' }
]);

Testing and Debugging

Browser Console Functions

// Test AI response system
testAI()

// Test specific player action
testPlayerAction("examine the room")

// Test memory system functionality
testMemory()

// Toggle fallback mode for testing
enableFallbackMode()
disableFallbackMode()

Setting-Specific Storytelling

The AI system adapts its storytelling style based on campaign settings:

Medieval Fantasy

Modern/Urban Fantasy

Sci-Fi Space

Eldritch Horror

Performance Optimization

Model Warmup

await aiManager.warmupHuggingFaceModel();

Context Management

Error Handling

Integration Points

Memory Manager

Character System

Game State

Best Practices

Prompt Engineering

Response Quality

Performance Monitoring

Troubleshooting

Common Issues

No AI Response:

Poor Response Quality:

Memory Integration Issues:

Debug Functions

// Test AI system status
aiManager.debugTest()

// Check memory integration
aiManager.testMemorySystem()

// Validate response pipeline
aiManager.testAIResponse("look around")

Future Enhancements

Planned Features

  1. Fine-tuned Models: Custom models trained on RPG content
  2. Emotion Tracking: Character emotional state integration
  3. Multi-Character Voices: Different AI personalities for NPCs
  4. Advanced Plot Generation: AI-driven story arc development
  5. Real-time Learning: System adaptation based on player preferences

Configuration Extensions

Conclusion

The Main AI System provides the core intelligence behind DiceTales’ immersive storytelling experience. By combining modern conversational AI with comprehensive memory management and context awareness, it delivers human-like interactions that maintain plot consistency and character development throughout extended gaming sessions.