AI-DnD is an autonomous, AI-driven D&D campaign simulator that dynamically generates and evolves its own worlds, histories, and characters. This isn’t just a text-based RPG—it’s a self-running, self-documenting AI Dungeon Master that creates, plays, and archives full campaigns without human input.
- Autonomous World-Building – AI characters make decisions, track history, and generate lore in real time.
- Integrated Generative AI – Features standalone interfaces for chatting with Google's Gemini models and generating professional game assets.
- Obsidian Integration – All campaign events, journals, and lore are automatically saved as Markdown files for easy visualization and review.
- Sentinel Class – A monitoring system that ensures narrative and game consistency, acting as a meta-DM assistant.
- Modular Architecture – Flexible and expandable, allowing for custom modules and mechanics.
Interact directly with the Gemini 2.5 Flash model in a modern, local web interface.
# Make script executable first: chmod +x start_gemini_chat.sh
./start_gemini_chat.shPower photorealistic asset generation for your game frontend.
cd backend
./start_server.sh
# Then open http://localhost:8000/retro-adventure-game.htmlMonitor parallel pixel art generation jobs.
# Terminal 1: Start HTTP server
cd dashboards && python3 -m http.server 8080
# Terminal 2: Start Actions server
python3 scripts/pixellab_actions.py --serve
# Open: http://localhost:8080/pixellab_dashboard.html- Installation
- Gemini Chat Interface ⭐ NEW
- Image Generation API ⭐ NEW
- PixelLab Integration
- Obsidian Setup
- Usage
- Modules
- Configuration
- Contributing
- License
To set up AI-DnD on your local machine:
git clone [https://github.com/ctavolazzi/AI-DnD.git](https://github.com/ctavolazzi/AI-DnD.git)
cd AI-DnD
pip install -r requirements.txtA modern, standalone chat interface for conversing with Google's Gemini 2.5 Flash model. This tool is perfect for testing AI interactions, prototyping NPC dialogue, or just chatting with the model outside of the main game loop.
- 💬 Real-time Chat - Instant responses from Gemini 2.5 Flash.
- 🎨 Modern UI - Beautiful gradient design with smooth animations.
- 💾 Context-Aware - Remembers conversation history for coherent replies.
- 🔒 Secure Storage - API key stored locally in your browser.
- 📱 Responsive - Works flawlessly on desktop and mobile.
- Get an API Key: Get your free key from Google AI Studio.
- Launch: Run
./start_gemini_chat.shOR directly opengemini-chat.htmlin your browser. - Connect: Paste your API key into the settings panel and connect.
📖 Full Documentation: See GEMINI_CHAT_README.md for technical details.
AI-DnD includes a powerful, dual-engine image generation system designed for creating professional D&D artwork on the fly.
Utilizes Google's Gemini model to generate stunning, photorealistic scenes, landscapes, and item artwork. It powers the visuals in the retro-adventure-game.html frontend.
Recommended Backend (FastAPI): The robust, production-ready server featuring SQLite caching, WebP image optimization, and database migrations.
# Start the FastAPI backend
cd backend
./start_server.sh
# Access the game at http://localhost:8000/retro-adventure-game.html
# Access API docs at http://localhost:8000/docs(A simpler Flask backend is also available for standalone demos in nano_banana_server.py)
Specializes in generating retro pixel art characters, sprites, animations, and tilesets via MCP server integration.
See the detailed PixelLab Integration section below for usage capabilities.
→ View Complete Image Generation API Docs
This comprehensive guide includes endpoint references, frontend usage examples, troubleshooting steps, and best practices for both engines.
AI-DnD is designed to integrate seamlessly with Obsidian, allowing it to generate Markdown-based campaign logs, character journals, and world-building documents in real time.
- Install Obsidian: Download from obsidian.md.
- Create Vault: Create a new vault where AI-DnD will store campaign logs.
- Configure Path: In the AI-DnD
config.jsonfile, set theobsidian_vault_pathto your chosen Obsidian vault directory. - Run & Observe: Start a campaign. AI-DnD will generate auto-linked Markdown files in your vault as the game progresses.
AI-DnD includes complete PixelLab integration with both MCP and direct API access, enabling AI-powered pixel art generation for game development.
Interactive web-based dashboard for parallel pixel art generation with character rotation!
Instructions located in the Quick Start section above.
Features:
- 🎨 Parallel Job Queue - Run up to 3 character generations simultaneously
- 🔄 Character Rotation - Rotate completed characters to all 8 directions
- 📊 Real-time Monitoring - Live status updates and comprehensive logging
- 💾 Job History - Persistent storage with automatic backups
See dashboards/README.md for complete documentation.
Comprehensive testing framework for PixelLab API endpoints:
# Run character generation tests
curl http://127.0.0.1:8787/test/character_generation | jqSee pixellab_tests/README.md for full documentation.
Decision matrix for evaluating implementation options based on impact vs. energy cost.
See tasks_config.json for example configuration.
Comprehensive test suite for generating top-down, isometric, and platformer tilesets and complete dungeon maps.
See tests/pixellab_map_test/README.md for documentation.
AI-DnD integrates with PixelLab's Model Context Protocol (MCP) server. This allows you to use Claude Code to generate assets using natural language prompts like: "Create a pixel art wizard character with 8 directions".
Check .mcp.json at the project root for configuration.
To start the main AI-DnD simulation loop:
- Launch the main program script (e.g.,
python main.py). - Select a pre-made campaign scenario or create a new one.
- Observe the AI-driven adventure unfold in your terminal.
- Open your linked Obsidian vault to view real-time, formatted campaign logs.
- Character Management – AI-driven player/NPC attributes, actions, and memory.
- Combat System – Simulated D&D battle mechanics with turn-based AI decision-making.
- Dungeon Master AI – Generates and narrates the world dynamically.
- Game State Manager – Controls the flow of time, events, and interactions.
- Sentinel System – Monitors game consistency and flags discrepancies.
Modify settings in the config.json file to customize:
- Campaign difficulty and AI randomness.
- Journal update frequency.
- Obsidian vault path.
- API keys for Gemini and PixelLab services.
Contributions are welcome! To contribute:
- Fork the repository.
- Create a new branch for your feature or bug fix.
- Submit a pull request with a clear description of changes.
This project is licensed under the MIT License. See the LICENSE file for details.