Dungeon Master Claude

AI-powered multiplayer D&D 5e, played entirely in the browser.

An AI Dungeon Master (powered by Ollama) narrates the story, responds to player actions, and drives the world forward. Multiple players connect simultaneously in real time — everyone sees the same narrative as it unfolds.

---

Features

• AI Dungeon Master — narrative responses generated by a local or remote Ollama model
• Real-time multiplayer — all players share the same chat, combat tracker, and campaign state via WebSockets
• Character builder — race, class, background, ability scores (standard array / point buy / roll), skills, inventory, actions, and spells
• Combat tracker — initiative order, HP tracking, status conditions, round counter
• Pause / resume — DM can pause the session and broadcast a notification to all players
• Player manual — full documentation in player_manual.md

---

Stack

Layer	Technology
Backend	Python 3.10+, FastAPI, python-socketio
Database	SQLite (aiosqlite)
Auth	JWT (python-jose)
LLM	Ollama (remote or local)
Frontend	Alpine.js, Tailwind CSS, Jinja2 templates
Optional RAG	ChromaDB + sentence-transformers

---

Quick Start

Prerequisites

• Python 3.10+
• Ollama running locally or on a remote host

Setup

# 1. Clone the repo
git clone https://github.com/jchaill/Dungeon_Master_Claude.git
cd Dungeon_Master_Claude

# 2. Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Configure environment
cp .env.example .env

Edit .env:

Variable	Description	Example
OLLAMA_HOST	URL of your Ollama server	http://localhost:11434
OLLAMA_MODEL	Model to use as DM	llama3.1:8b-instruct
DM_PASSWORD	Password for DM access	my-secret-pw
SECRET_KEY	Random string for JWT signing	some-long-random-string
DB_PATH	SQLite database path	data/campaigns.db

Start the Server

uvicorn src.main:socket_app --host 0.0.0.0 --port 8000

Open http://localhost:8000 in your browser. Share http://<your-ip>:8000 with your players.

---

Usage

See player_manual.md for full instructions covering:

• Joining and creating campaigns
• Building a character
• Playing the game and combat
• DM controls (pause, resume, combat management)

---

Project Structure

src/
├── api/          — HTTP routes and auth
├── managers/     — state, session, and combat managers
├── models/       — Pydantic models (campaign, character, session)
├── services/     — Ollama client, dice roller, rules engine, RAG
└── main.py       — FastAPI app + Socket.IO event handlers
templates/        — Jinja2 HTML templates
static/           — CSS and JS

---

License

MIT