- Python 100%
Kai
27af03e1a0
Phase 6 fix: combat + move + look actually work end-to-end. Combat resolver now constructs the RoundState the engine needs; move resolves player-spoken names to room ids; look returns the current room with theme and exits. The 'happy path' integration test was passing via the fallback chain (resolver raised, bus caught, returned MINOR_FAILURE) -- not because attacks actually resolved. Verified live: 6 Crawlers vs 1 mob. Crawler 4 rolled 14 vs 16 evade DC, hit for 5 damage. The other 5 missed. Mob HP 20 -> 15. Combat works. 2385 tests pass; 8 new; 0 regressions. See journal entries 012 and 013. |
||
|---|---|---|
| bot | ||
| design | ||
| docs/journal | ||
| engine | ||
| narrator | ||
| rules | ||
| server | ||
| ui | ||
| voice | ||
| .gitignore | ||
| AGENTS.md | ||
| IDEA.md | ||
| README.md | ||
| requirements.txt | ||
gamemaster
Procedural / AI-augmented game master for the Dungeon Crawler Carl RPG.
A local-first dungeon crawl GM built on a deterministic rules engine with an LLM narration layer strictly limited to flavor text. Mechanical resolution (combat, room generation, encounter tables, questline progression, stat changes) is pure data + seeded PRNG — no LLM in the loop. The LLM renders prose over mechanically-resolved outcomes; it does not invent them.
If a future session finds a contradiction between a doc and the code, the code wins — fix the doc.
Status
Phase 0 — design. Repo scaffolded; rules PDF pending upload by owner. No engine code yet.
What's here
| Path | Purpose |
|---|---|
rules/raw/ |
Source-of-truth PDF (uploaded by owner) + raw pdftotext dumps, page-mapped |
rules/systems/ |
One markdown file per extracted mechanical system (combat, exploration, etc.) |
rules/index.md |
Cross-system dependency map |
design/REPORT-rules-extraction.md |
Target: first deliverable — full mechanical systems inventory from the rulebook |
design/SPEC-*.md |
Triad output (architecture, agents, data model, UX review) |
engine/ |
Python, deterministic core (PRNG, dice, resolver, systems, content tables) |
narrator/ |
LLM layer, narrow job: outcome → prose |
server/ |
FastAPI: websocket game sessions, state machines |
ui/ |
React + Vite: map grid, player sheet, chat |
Workflow
This project follows a triad review pattern for the design phase (four
agents working in parallel, see design/SPEC-agents.md when it lands).
Implementation will be inline, sequential, journaled.
Journal protocol: every major change (phase, new feature, multi-commit
work) gets a docs/journal/YYYYMMDD-NNN-<topic>.md entry. Append-only.
Doctrine
See AGENTS.md for the hard rules. The non-negotiables:
- Determinism when it matters. Same seed → same dungeon. Always.
- LLM is narration-only. Never rolls dice, never picks encounters, never decides outcomes. It writes the prose the engine tells it to write.
- The PDF is the source of truth. We extract; we don't redesign.
- Seeds are first-class. Every generated artifact carries the seed that produced it. Save/load/rerun must work.
Quick start
git clone https://forgejo.j4f.org.uk/hraisikai/gamemaster.git
cd gamemaster
# Owner uploads rules PDF to rules/raw/ and pushes
# Then: pdftotext -layout rules/raw/source.pdf rules/raw/source.txt
License
TBD. The rulebook is the owner's property; the engine we write will be licensed separately (ask before open-sourcing).