- Python 82.6%
- JavaScript 8.4%
- CSS 6%
- HTML 2.9%
- Dockerfile 0.1%
| 5E srd | ||
| prompts | ||
| static | ||
| templates | ||
| .env.example | ||
| .gitignore | ||
| abilities.py | ||
| AGENTS.md | ||
| ai_analyzer.py | ||
| AUDIT.md | ||
| behavior.py | ||
| creature.py | ||
| definitions.py | ||
| dice.py | ||
| docker-compose.yml | ||
| Dockerfile | ||
| extract_srd.py | ||
| main.py | ||
| mechanics.py | ||
| messages.py | ||
| PLAN-web-ai-integration.md | ||
| PROGRESS.md | ||
| RCA-001-Undefined-Team-Roster-and-Backend-Category-Mismatch.md | ||
| README.md | ||
| requirements.txt | ||
| structured_logger.py | ||
| ui.py | ||
| weapons.py | ||
| web_app.py | ||
| world.py | ||
DnD5e-CombatSimulator
D&D 5e Creature Combat Simulator
A Python tool for simulating Dungeons & Dragons 5th edition encounters between creatures. The core engine runs on Python 3.6+ with no external dependencies; the web UI and AI analysis layer run in a Docker container on Python 3.12.
Why does this exist?
This script is mainly created as a DM tool for simulating encounters between different types of creatures. Want to know how a level 8 Barbarian with a magical Greataxe +2 and his Dire Wolf companion can stand against a Mammoth? How about a Purple Worm vs. 30 zombies? Just run the script and see.
Running with Docker (recommended for the web UI)
The fastest way to run the full simulator with the web interface and AI analysis is via Docker Compose.
1. Clone the repo
git clone https://git.gi7b.org/justin-admin/DnD5e-CombatSimulator.git
cd DnD5e-CombatSimulator
2. Configure environment variables
Copy the example environment file and add your DeepSeek API key:
cp .env.example .env
Edit .env:
DEEPSEEK_API_KEY=sk-...
PORT=7681
HOST=0.0.0.0
The DeepSeek key is required for the AI Analysis panel in the web UI. The rest of the simulator works without it.
3. Build and run
docker compose up -d
The web UI is available at http://localhost:7681.
4. Check health
curl http://localhost:7681/api/health
5. Stop
docker compose down
Production deployment
This project is deployed as a Docker service on PC02 (192.168.196.189), port 7681, and exposed publicly at:
Nginx Proxy Manager on PC03 terminates SSL and proxies to PC02:7681. To redeploy the live instance:
- Push changes to
git.gi7b.org/justin-admin/DnD5e-CombatSimulator. - On PC02, pull the latest code in
/home/user/docker/dndsim/. - Rebuild and restart the container:
cd /home/user/docker/dndsim docker compose down docker compose up -d --build - Verify:
curl http://localhost:7681/api/healthshould return200.
Running locally without Docker
For the original command-line simulator only (no web UI, no AI analysis):
python3 main.py
Run simulate() in main.py to start a simulation. Call list_creatures() to see implemented creatures. More documentation is in main.py.
Web UI features
- Creature browser with full stat blocks
- Team builder for arbitrary party sizes
- Combat simulation with detailed log
- Animated map replay with turn slider
- SRD rules and how-to tabs
- AI analysis panel (DeepSeek API key required)
Features
- Movement in two-dimensional world (flying/burrowing not yet implemented)
- Possibility to create battles between parties of arbitrary size
- Create approximations of player characters by combining already defined creature, ability and weapon objects (see definitions.py)
- Most of the crucial D&D mechanics defined
Caveats
Creature behavior is very straightforward. Thus the results are not always comparable one-to-one to Pen & Paper encounters.
Known bugs
- If a creature has swallowed other creatures and dies, the swallowed creatures end up in the same coordinates.
TODO
- Spell casting
- Flying and burrowing
- More creatures
- Implement creature size on the map (now all take same amount of space)