joshuaandClaude Opus 5.5
932e755895
- Hollowcrown: The Rift Between Worlds as its own seed (npm run seed:hollowcrown), built from the campaign book: pools, 58 monsters, 57 NPCs, 28 locations, 72 encounters with rewards, and DM notes. Shared seeding logic moved to prisma/seedCampaign.js. - What players can see: only encounters their own character is in; only the pool entries their character holds (plus starting options while building); only locations their character has been to; no invite code; no gold, inventory or money log of other players' characters. Socket events carry ids only and campaign rooms are members-only. - Encounters have a location; while one is in progress its characters are there, and visits are remembered. - Campaign setting to show players a health bar only for monsters and NPCs. - Initiative is entered as the d20 roll (1-20) and the bonus is added; players can enter their own character's roll. - Number fields enforce their limits when typing, and the API enforces the same limits. - Temp HP shows on HP bars and absorbs damage before real HP. - All packages at version 1.3.0. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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 # adds the admin account + the Aldenfell campaign if missing (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 admin account — see the seed script's console output for credentials and invite code), and start playing.
The seed only adds: it never touches an existing account or campaign, so it is
safe to run on a server with real data. It skips the campaign if the admin
already has an active "Aldenfell"; archive or delete that one in the app
(Campaign Settings) and run it again for a fresh copy. SEED_ADMIN_EMAIL,
SEED_ADMIN_PASSWORD and SEED_ADMIN_NAME set the account it creates.
npx prisma db seed -- --reset wipes every user and campaign first.
A second campaign, Hollowcrown: The Rift Between Worlds, has its own seed and is not part of the default one. It follows the same rules (it only adds, and skips if the admin already has an active Hollowcrown):
cd backend
npm run seed:hollowcrown
On a server, apply new migrations with npx prisma migrate deploy. Change
your password from the account page (click your name in the top bar).
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)