Experience the future of tabletop RPG gaming with intelligent AI assistance, persistent world memory, and seamless multi-language support.
ShadowRealms AI is a revolutionary platform that transforms traditional tabletop RPG gaming by integrating advanced AI technology. Our system acts as an intelligent Dungeon Master, providing dynamic storytelling, character development, and world-building assistance while maintaining complete campaign continuity through advanced memory systems.
| AI Dungeon Master | Persistent Worlds | Smart Dice System |
|---|---|---|
| Intelligent NPC behavior and dynamic storytelling | ChromaDB-powered memory for campaign continuity | Automated dice rolling with context awareness |
| Multi-Language | Real-time Performance | Secure & Private |
|---|---|---|
| Global accessibility with translation pipelines | Optimized for 5-10s responses, 30-60s for complex tasks | Local AI processing, no data leaves your system |
For comprehensive documentation, detailed setup instructions, and complete feature overview, please refer to our complete documentation:
- Testing Guide - Comprehensive testing documentation
- Contributing Guidelines - How to contribute to the project
- Changelog - Detailed version history and updates
- Docker Setup Guide - Environment configuration
git clone https://github.com/Somnius/shadowrealms-ai.git
cd shadowrealms-ai
docker-compose up -dAccess Points:
- Frontend: http://localhost:3000
- Backend API: http://localhost:5000
- ChromaDB: http://localhost:8000
Last Updated: 2025-01-09
Progress: Phase 2 Complete - Phase 3A Frontend Development Started
| Foundation | AI Services | Web Interface |
|---|---|---|
| Complete Docker environment with all 6 services stable | Both LM Studio (3 models) and Ollama (1 model) fully working | React application serving through nginx proxy |
| Backend API with authentication and RAG integration | ChromaDB vector memory system fully functional | Production-ready reverse proxy configuration |
| SQLite schema with ChromaDB fully operational | Smart Model Router for intelligent model selection | JWT-based user management with role-based access |
| Campaign Management API | Memory Search & Context Retrieval | RAG-Powered AI Responses |
| Vector Embeddings | Persistent AI Memory | Context-Aware Generation |
| API Response Consistency | Character Creation Schema | 100% User Experience Tests |
| Rule Book Integration | ChromaDB Storage Issues | Content Retrieval System |
| Frontend Development | Testing Infrastructure | Documentation |
|---|---|---|
| React component architecture | Jest testing framework setup | Comprehensive testing documentation |
| TypeScript integration | Component testing suite | API documentation updates |
| State management with Redux | Service layer testing | Development guides |
| UI/UX improvements | Authentication testing | Deployment documentation |
| White Wolf Character System | Narrative Combat | World Building with Admin Control |
|---|---|---|
| WoD character sheets (priority) | Turn-based narrative combat | Location & NPC management |
| d10 dice pools with difficulty | XP cost AI assistance | Admin verification system |
| Character progression tracking | Environmental factors | Procedural generation with approval |
| Multiplayer Support | Advanced AI | Content Creation |
|---|---|---|
| Real-time collaboration | Enhanced NPC behavior | Custom rule system support |
| Session management | Dynamic world events | Community content sharing |
| Voice integration | Advanced storytelling | Mod support |
graph TB
A[Frontend React App] --> B[Nginx Reverse Proxy]
B --> C[Flask Backend API]
C --> D[Smart Model Router]
C --> E[RAG Service]
C --> F[SQLite Database]
C --> G[Redis Cache]
E --> H[ChromaDB Vector DB]
D --> I[LM Studio Models]
D --> J[Ollama Models]
K[GPU Monitor] --> C
L[System Monitor] --> C
| D&D 5e | White Wolf | Custom Systems |
|---|---|---|
| Complete D20 system integration | D10 dice pool mechanics | Flexible rule system support |
| Character classes and races | Vampire, Werewolf, Mage support | Custom dice mechanics |
| Spell and ability management | Storytelling system integration | Homebrew rule compatibility |
- Docker & Docker Compose
- 16GB+ RAM (recommended)
- NVIDIA GPU with 16GB+ VRAM (for optimal AI performance)
- Linux/macOS/Windows with WSL2
# Clone the repository
git clone https://github.com/Somnius/shadowrealms-ai.git
cd shadowrealms-ai
# Start all services
docker-compose up -d
# Check service status
docker-compose ps- Access the Frontend: Open http://localhost:3000
- Create Your Campaign: Set up your first RPG campaign
- Configure AI Models: Ensure LM Studio and Ollama are running
- Start Playing: Begin your AI-assisted RPG adventure!
We welcome contributions from the RPG and AI communities! Whether you're a developer, game designer, or AI enthusiast, there's a place for you in ShadowRealms AI.
This project is licensed under the MIT License - see the LICENSE file for details.
