jncchds/adnd repository overview

⁠ADnD — AI-Powered TTRPG Platform

ADnD is a multiplayer tabletop RPG platform where a configurable AI Game Master runs your campaign. Players connect in real time over WebSockets, roll dice, manage characters, and watch the story unfold — all driven by an LLM backend you choose and control.

⁠Features

• AI Game Master — powered by Ollama, LM Studio (any OpenAI-compatible endpoint), OpenAI, or Google AI Studio
• Real-time multiplayer — SignalR WebSocket hub; all events broadcast instantly
• Full combat tracker — initiative, turns, HP, conditions, death saves, action economy
• Plot Intelligence — RAG-backed plot threads with automatic momentum tracking and LLM-driven adaptation
• Character sheets — attributes, skills, spells, inventory, backgrounds, custom fields
• Multi-system — D&D 5e, Pathfinder 2e, Call of Cthulhu 7e, and custom systems
• Durable sagas — Wolverine/PostgreSQL-backed AI work queue; no lost narration on restart
• JWT auth — refresh token rotation, encrypted API keys at rest (AES-256-GCM)
• Whispers — private GM-to-player and player-to-player messaging
• Secret dice rolls — result visible only to roller and GM
• Session recaps — on-demand or automatic "previously on..." summaries

⁠Quick Start

⁠Prerequisites

• Docker + Docker Compose v2+

⁠1. Configure environment

cp .env.example .env

Edit .env and fill in:

Optional settings (see .env.example for the full list):

⁠2. Start the stack

docker compose up --build

This builds the .NET server (which also builds the Vite client inside Docker) and starts PostgreSQL. EF Core migrations run automatically on first start.

Open http://localhost:5010⁠ in your browser.

⁠3. First-time setup

1. Register an account at /register
2. Go to LLM Presets and add your LLM backend (Ollama, LM Studio, OpenAI, or Google AI Studio)
3. Go to Dashboard, create a game, select your preset
4. Share the invite code with players and start the game

⁠LLM Provider Setup

⁠EF Core Migrations

Migrations are applied automatically on startup. To generate a new migration:

docker compose run --rm app-sdk dotnet ef migrations add <Name> --project src/Adnd.Server

⁠Architecture

Browser (React 19 + MUI)
    │
    ├── REST  /api/**          — CRUD, auth, admin
    └── WebSocket /gamehub     — SignalR real-time events
                    │
            Adnd.Server (.NET 10)
                    │
            ┌───────┴────────┐
            PostgreSQL 17     Wolverine message bus
            + pgvector        (PostgreSQL-backed sagas)

Key design principles:

• Everything is a Message — dice rolls, combat events, narration all flow through the message feed
• Server-side dice only — no client-side RNG
• LLM calls are durable — Wolverine sagas survive restarts
• Docker-first — no local dev workflow needed; docker compose up --build is the only workflow

⁠Endpoints

⁠Tech Stack

⁠GitHub

https://github.com/jncchds/adnd⁠