Files

T

joshuaandClaude Opus 5.5 932e755895 V1.3.0: Hollowcrown seed, player visibility rules, initiative rolls, number limits, temp HP

- 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>

2026-10-06 10:53:48 +02:00

4.5 KiB

Raw Blame History

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)

4.5 KiB Raw Blame History