D&D Adventure with DM Aiden

An AI-powered Dungeons & Dragons experience featuring DM Aiden, an interactive AI Dungeon Master that guides players through a voice-controlled 4-room dungeon escape adventure using SignalWire's AI Agent technology.

Key Features

• AI Dungeon Master: ElevenLabs voice synthesis for dramatic storytelling and natural conversation
• Hybrid Character Creation: AI-triggered popup interface with call hold/resume functionality
• Voice-First Interaction: Complete game control through voice commands with rich visual feedback
• Player-Controlled Dice Rolling: Voice-activated dice rolling with visual animations
• Demo-Optimized Experience: 12-15 minute adventure with guaranteed success path

Documentation

For complete setup instructions, gameplay guide, and technical details, visit:

📖 Full Documentation

Requirements

• Python 3.8+
• SignalWire account with API credentials
• Modern web browser with WebRTC support
• Microphone and speaker/headphones

Key Design Decisions

1. Hybrid Character Creation System

• Decision: AI-triggered popup interface with call hold/resume functionality
• Rationale: Shows off utilization of SignalWire REST API in a unique fashion, in this case to retrieve character info from end user.
• Implementation: AI pauses call using REST API, frontend shows popup, user fills form, call resumes automatically
• Benefit: Maintains voice-first experience while enabling complex data entry that would be tedious via voice.

2. Linear Room Progression with Explicit State Management

• Decision: Fixed 4-room sequence with SWAIG function-controlled advancement
• Rationale: Prevents player confusion and ensures demo completion within short time frame.
• Implementation: progress_to_next_room function validates completion criteria before advancing to next segment.
• Benefit: Guaranteed success path with clear objectives, significantly reducing possibility of player getting stuck

3. Player-Controlled Dice Rolling

• Decision: Voice commands trigger dice rolls instead of automatic rolling by AI
• Rationale: Maintains player agency and authentic D&D experience as DungeonMasters never roll for players.
• Implementation: "Roll a dice" commands call roll_dice_with_character function with visual feedback
• Benefit: Player feels in control of their character's destiny, authentic tabletop RPG experience

4. Dual-Client Architecture (Voice + REST)

• Decision: SignalWire WebRTC for voice communication + REST API for call management
• Rationale: WebRTC enables real-time voice interaction while REST provides programmatic control
• Implementation: Separate signalwire_client.py wrapper for hold/resume/inject operations
• Benefit: Sophisticated call state management during character creation without interrupting voice flow

5. Context Steps with Validation Criteria

• Decision: Each room has explicit completion criteria and valid next steps defined
• Rationale: Ensures linear progression and greatly reduces chance of skipping content or getting confused
• Implementation: .set_step_criteria() and .set_valid_steps() methods enforce progression rules
• Benefit: Consistent demo experience across all playthroughs, reliable content delivery

6. SWML Event-Driven UI Updates

• Decision: Backend sends real-time user_events to trigger frontend visual updates
• Rationale: Synchronizes game state between AI conversation and visual interface seamlessly
• Implementation: SWML events update character sheets, dice displays, room progression in real-time
• Benefit: Rich visual feedback enhances voice interaction without breaking voice-first paradigm

7. Demo-Optimized Game Mechanics

• Decision: Simplified D&D rules with guaranteed success paths and low difficulty
• Rationale: 12-15 minute demo window requires streamlined mechanics accessible to non-D&D players
• Implementation: Low AC/HP enemies, progressive hints for puzzles
• Benefit: Engaging D&D experience that's accessible to newcomers while showcasing core mechanics

8. Single-File Game Content Management

• Decision: All D&D data centralized in dnd_content.json configuration file
• Rationale: Enables easy content updates without code changes or deployment
• Implementation: JSON file loaded at startup containing character classes, races, encounters, equipment
• Benefit: Non-technical content updates, easy customization, clear separation of data and logic

9. FastAPI for Unified Web and API Serving

• Decision: Single server handles both static file serving and SignalWire webhook endpoints
• Rationale: Simplifies deployment and reduces infrastructure complexity for demos
• Implementation: FastAPI serves HTML/CSS/JS files while providing /dnd/ prefixed API endpoints
• Benefit: One-command deployment, unified authentication, simplified networking configuration

10. Error Recovery and Graceful Degradation

• Decision: Application functions even with missing optional features or configuration
• Rationale: Ensures reliable demo experience in various environments and incomplete setups
• Implementation: Try-catch blocks with fallbacks, optional SignalWire REST features, default configurations
• Benefit: Demo works reliably regardless of setup completeness, better developer experience

These design decisions create a robust, demo-friendly D&D experience that showcases advanced SignalWire capabilities while remaining accessible and reliable for presentation purposes.

Security

The application includes:

• SSL/TLS encryption support
• Basic authentication for API endpoints
• CORS configuration
• Request validation and sanitization

Requirements

• Python 3.8+
• SignalWire account with API credentials (required for character creation)
• Modern web browser with WebRTC support
• Microphone and speaker/headphones for voice interaction