DungeonGPT

DungeonGPT is a minimalist, DnD-inspired web adventure where an AI narrator drives the story and you answer in a chat-like interface. It blends lightweight rules, dice rolls, and cinematic illustrations for a fast, story-first experience.

Disclaimer

This is NOT an official Dungeons & Dragons rules implementation. I have never played DnD and do not know all the nuances, so the rules here are a simplified, homebrew-like system that only feels similar to DnD. Think of it as a narrative game with an AI game master.

Highlights

• AI narrator (GPT-5.2) with structured replies and 3 concise action options.
• Player-driven chat flow with short, punchy responses.
• Character creation with class, race, portrait, and custom stats.
• Dice system (d20 for success/failure, d6 for damage/quantity) with stat modifiers.
• Story illustrations (1536x1024) generated in the background.
• Enemy tracking with portraits and HP.
• Optional voice output (TTS) with voice selection and volume control.
• Voice narration and story illustrations add extra immersion as the adventure unfolds.
• Saved characters, saved adventures, and session switching.

Tech Stack

• Backend: FastAPI (Python)
• Frontend: React + Vite
• Models: GPT-5.2 (narration), gpt-image-1.5 (images), gpt-4o-mini-tts (voice)

Local Setup

Backend

cd backend
python -m venv .venv
.\.venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env

Set OPENAI_API_KEY in backend/.env.

Run the API:

uvicorn app.main:app --reload --port 8010

Frontend

cd frontend
npm install
copy .env.example .env
npm run dev

Open http://localhost:5173.

How to Play

1. Create or select a hero.

• Choose class and race (or type a custom one), write a short description, and set your stats.
• Generate a portrait from a prompt or upload your own image.

2. Start a new adventure.

• Write a short adventure seed and press "Start adventure".

3. Play through the story in chat.

• Read the narrator's reply.
• Pick one of the 3 suggested actions or type your own.
• Dice rolls (d20/d6) appear in chat as results; the story text itself does not show the rolls.

4. Watch the right panel.

• Illustration updates happen in the background (first turn and then every 10 turns by default).
• Track enemies and their HP.
• Track your HP; when it drops to 0, the story ends.

5. Continue or switch adventures.

• Sessions are saved automatically.
• Use the left sidebar to switch between adventures.

Configuration

Key settings live in backend/.env:

• STORY_MODEL (default: gpt-5.2)
• STORY_REASONING_EFFORT (default: low)
• IMAGE_MODEL (default: gpt-image-1.5)
• TTS_MODEL (default: gpt-4o-mini-tts)
• IMAGE_QUALITY (default: low)
• IMAGE_SIZE (default: 1024x1024)
• ILLUSTRATION_SIZE (default: 1536x1024)
• ILLUSTRATION_EVERY (default: 10)
• CORS_ORIGINS (default: http://localhost:5173)

Frontend API base can be set in frontend/.env via VITE_API_BASE_URL.

Notes

• Illustrations are generated on the first turn and then every 10 user turns by default.
• The narrator avoids long replies (max 5 sentences) and keeps the pace brisk.