joshuaandClaude Opus 5.5
4a6a09bae8
Characters - Builder: pick-then-Next on every step with live preview, Back button, plain-language help throughout, and "Suggest for me" for ability scores - Motivation is picked from a list; new steps for special abilities, background and appearance, all composed from fixed lists and DM-only to edit afterwards - Copy a character to another campaign - Characters can give gold, weapons, items and spells to each other - Money tracker: gold only changes through a logged ledger - Fixes: level/XP/location are DM-only, HP stays within 0..max, physical dice ability rolls, every die is rolled once Gear - DM-managed item pool; weapons, items and spells are handed out by the DM - Starting-option flag per pool entry - Gear levels 1-9 per held copy with a damage ladder, growth rate and starting level; spells gated by spell level with a fixed damage value - Spell library carries default damage; damage is picked from a list Encounters - Battle and NPC quest modes, turn tracking, scene description, DM notes - NPCs, richer combatant cards, conditions from a list - Rewards (gold, weapons, items) lined up and awarded, with gold splitting - Character HP is shared between the sheet and the encounter - Monster stat blocks and NPC secrets are never sent to players Other - Dice roller on every page - Docs for characters, weapons, spells, items, encounters, monsters and NPCs, with full lists generated from the data (npm run docs:lists) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
3.6 KiB
The Sunken Reach — D&D 5e Campaign Manager
A web app for a D&D 5e Dungeon Master and their players to run a campaign together: campaign management, a guided dice-roll character builder, live character sheets, a mid-combat "quick stats" panel, weapons/inventory/spells, monsters, and a real-time encounter/combat tracker.
How it works
/docs describes the app as it currently behaves, one subject per file:
| Document | Covers |
|---|---|
docs/CHARACTERS.md |
Building a character, every number on the sheet, levels, money, permissions |
docs/WEAPONS.md |
The weapon pool, weapon levels and how damage grows |
docs/SPELLS.md |
The spell list, who can use which spells, the spell library |
docs/ITEMS.md |
The item pool and character inventory |
docs/ENCOUNTERS.md |
Battles and NPC quests, turns, rewards, what players see |
docs/MONSTERS.md |
The monster list and built-in bestiary |
docs/NPCS.md |
Non-player characters |
CLAUDE_BUILD_PROMPT.md, docs/GAME_RULES_REFERENCE.md and
docs/ROLL_YOUR_CHARACTER.md are the original specifications the first
version was built from. The app has since moved on in places (gear levels,
the builder's story steps, picking a motivation); the documents above are the
current behaviour.
Stack
- Backend: Node.js + Express, JavaScript, Prisma ORM, PostgreSQL, Socket.io, JWT auth (bcrypt + jsonwebtoken), zod validation.
- Frontend: React + Vite + TypeScript, React Router, TanStack Query, socket.io-client.
Prerequisites
- Node.js 18+ (tested on Node 22)
- A running PostgreSQL instance (local install, Docker, or a hosted service like Neon/Supabase)
First-time setup
npm install # installs both workspaces (backend + frontend)
# Backend: point at your Postgres instance and run migrations
cd backend
cp .env.example .env # edit DATABASE_URL and JWT_SECRET
npx prisma migrate dev --name init
npx prisma db seed # creates a demo campaign + demo users (see output for login/invite code)
# Frontend
cd ../frontend
cp .env.example .env # defaults to http://localhost:4000, adjust if needed
Running in dev
In two terminals, from the repo root:
npm run dev:backend # Express + Socket.io on http://localhost:4000
npm run dev:frontend # Vite dev server, prints its own port (5173 by default)
Open the frontend URL, register an account (or log in with the seeded demo users — see the seed script's console output for credentials and invite code), and start playing.
Tests
cd backend
npm test
The calculation engine (src/game/calculations.js) is fully unit tested and
runs with no external dependencies. The route-level integration tests in
src/routes/api.integration.test.js need a real, migrated database reachable
via DATABASE_URL — they skip themselves gracefully (with a console warning)
if the DB isn't reachable, so npm test still passes in an environment with
no database configured.
Project layout
/backend — Express + Prisma API, Socket.io server
/prisma — schema.prisma, seed.js
/seed-data — reference JSON (weapons seeded per-campaign; species/classes/skills
are ported into src/game/data/*.js and used directly by the
calculation engine, not stored as DB rows)
/src
/game — calculations.js (the ONLY place D&D formulas live) + buildFlow.js
/middleware — auth + campaign/character authorization
/routes — auth, campaigns, characters, encounters, notes
/sockets — Socket.io room wiring
/frontend — React + Vite + TypeScript app
/docs — game rules & character-builder specs (reference material)