What is Dungeon Grimoire?
Dungeon Grimoire is a unified campaign management platform for D&D 5e. The DM gets a rich authoring and live-play toolkit; players get a separate, role-appropriate portal with real-time data sync. It covers the entire campaign lifecycle — from world-building through live combat — in a single app.
This repository is public for transparency. See Licensing for usage terms.
Features
For Dungeon Masters
| Area | What's included |
|---|
| Campaign hub | Dashboard, session notes (rich text, AI image gen), pinned quests, party presence |
| World-building | Hierarchical Atlas (17 location types), kanban Quest Log, Factions with directional relations |
| NPCs | Full character sheets, force-directed Relationship Web, AI NPC Generator, stat block with bestiary import |
| Party & Characters | Initiative + HP tracker, full D&D 5e character sheet (Wild Shape, level-up wizard), Hall of Heroes |
| Combat | Bestiary with 12 SRD presets + Open5e sync, Encounter Builder (factions, boss mechanics, pre-scripted events), live Encounter Runner |
| Items & Spells | Item Vault with dual-image ID system, Spellbook with Spell Level Advisor, Workshop crafting recipes |
| Dungeon Building | Features, Traps (CR Advisor), Puzzles with hint reveals, Roll Tables, Loot Tables with claimable drops |
| Publishing | Scriptorium document editor (PDF export, PHB themes), Card Forge (MTG + Tarot print sheets), The Mint (VTT tokens + coins), Illuminator (canvas image processing) |
| DM Screen | Reliquary — quick reference, SRD compendium, custom Tracker builder for homebrew mechanics |
| Soundboard | Ambient scenes + music playlists, Spotify integration |
| Calendar | Custom world calendar — define your own months, intercalary days, and year length; month grid + Chronicle timeline view; ships with 9 built-in D&D settings (Faerûn, Eberron, Greyhawk, Dragonlance, Ravenloft, Planescape, Spelljammer, Dark Sun, Mystara) plus a fully custom option |
For Players
Players join any campaign for free via an invite link and get their own portal:
- Character sheet — owned and edited by the player; Wild Shape, spells, crafting all player-controlled
- Paper doll inventory — 11 anatomical slots, attunement tracker, carry weight, coin purse
- Live encounter view — real-time combat tracker with turn notifications and monster discovery
- Journal — private + shared entries with party journal aggregation
- Reliquary — read-only house rules, SRD reference, Character Codex
- Puzzles — hint reveals pushed by the DM in real time
- Shapeshifter disguise — player-controlled; other players see the fake species profile; DM always sees the truth
Tech Stack
| Layer | Technology |
|---|
| Frontend | Vue 3 + TypeScript + Vite (Rolldown) |
| Styling | Tailwind CSS v4 — config in CSS via @theme, no tailwind.config.js |
| Components | Reka UI (shadcn-vue style, headless) |
| State | Pinia (UI) + TanStack Query (server/async) |
| Router | Vue Router 5 |
| Backend | Supabase — PostgreSQL + Auth + Realtime + Storage + Edge Functions |
| Linting | oxlint |
Architecture diagrams (system context, internal layers, third-party
integrations, release pipeline) live in
context/architecture/.
Pricing
| Plan | Who | What |
|---|
| Free DM | Dungeon Masters | 1 campaign, 10 NPCs, 3 custom monsters, 5 encounters, 3 Scriptorium docs, 10 notes, 20 sounds, 1 soundboard page, 3 playlists |
| Pro DM | Dungeon Masters | Unlimited content + 1,500 AI credits/month (monthly allowance, resets each cycle) |
| Player | Anyone | Always free — join any campaign with an invite link |
AI credits are also sold as permanent packs that never expire — purchased credits act as an overage buffer on top of the monthly Pro allowance. Spends draw from the expiring monthly bucket first.
Full pricing at dungeongrimoire.com/pricing.
Development Setup
⚠️ Self-hosting requires a license. See Licensing before proceeding.
# Prerequisites: Node 24+, Docker, and the Supabase CLI
npm install
npm run db:start # boot local Postgres, Auth, Storage, and Studio
npm run dev # dev server against local Supabase
npm run build # production build (vue-tsc + vite build)
npm run lint # oxlint
npm test # vitest
Hosted development is deliberately explicit. Copy .env.example to
.env.local, fill in the hosted project values, and run:
npm run dev:hosted
Remote migrations are applied by CI after changes reach main; do not push the
working tree's pending migrations manually.
Local Development (against a local Supabase copy)
Day-to-day development should run against a local Supabase stack, not the
production database. The local stack is a full, throwaway copy of the schema
(all migrations replayed) that you can reset freely.
Prerequisites: Docker running, the Supabase CLI installed, and the project
linked once (supabase link --project-ref <ref>).
npm run db:start # boot the local stack (Postgres, Auth, Storage, Studio…)
npm run db:status # print local URLs + keys (Studio at <http://127.0.0.1:54323>)
npm run dev # run the app against the local stack (vite --mode localdb)
npm run dev:local # explicit alias for the same local mode
npm run dev:hosted # opt in to the hosted credentials from .env.local
npm run db:reset # wipe + replay all migrations (+ seed.sql if present)
npm run db:stop # tear the stack down
npm run dev and npm run dev:local use the isolated
config/env/localdb/.env file (committed; the CLI's universal local defaults —
safe, not secrets). The separate environment directory prevents Vite from also
loading the gitignored hosted values in .env.local. Only
npm run dev:hosted opts into the hosted project.
Seed it with a copy of the remote (tester accounts + app data — no
production customer data exists pre-launch):
npm run db:pull # dumps remote auth+public data → supabase/seed.sql (gitignored)
npm run db:reset # rebuilds the local DB and loads seed.sql
The dump is anonymized before it lands (#652). db:pull chains
scripts/anonymize-seed.ts, which rewrites every email address in seed.sql to
user-<n>@example.invalid. The reason to pull remote data is its volume and
shape, not its identities — and an address copied onto a laptop is outside every
control that applies to production: no retention period, and out of reach of
account erasure, which cannot follow someone into a local file.
One address is kept so the seeded account is still yours to sign into: your
git config user.email. Export SEED_KEEP_EMAILS (comma-separated) if the
account you log in with locally is not your git identity. db:reset re-checks
the file first and refuses to seed a dump that still holds real addresses —
which is what you want if you ever run supabase db dump by hand and bypass the
chained step. To fix one up after the fact:
npm run db:anonymize # rewrite in place (idempotent)
npm run db:anonymize -- --check # just report; exit 1 if any real address survives
db:pull needs the remote DB password (the CLI prompts, or set
SUPABASE_DB_PASSWORD). It excludes the config/reference tables that migrations
already seed — the -x flags in the script are the list; it has grown past
what is worth restating here, so read it there. Those tables are populated
identically by migrations on both sides, so dumping them too would collide on
primary keys at db:reset. If you add a new migration-seeded config table, add
it to the -x list. If you already hold a dump taken before a table joined
that list, delete its INSERT INTO "public"."<table>" statement or re-pull —
otherwise the next db:reset fails on the duplicate key.
plans is the newest entry and the reason the rule matters: it was reference
data with no migration behind it, so a fresh database had an empty plan
catalogue and the first signup died on
user_subscriptions_plan_id_fkey. Seeded by
20260809151956_seed_plan_catalogue.sql and excluded from the dump since.
If the auth portion of the dump errors, narrow it to --schema public and create
tester accounts locally instead (local signup confirmation emails land in Mailpit
at http://127.0.0.1:54324).
Why the baseline squash omits the storage schema: a full supabase db dump captures the service-managed storage schema, which a local
supabase start cannot replay (the migration role can't create in / own the
storage schema — that schema is provided by the storage service). The baseline
keeps only the app's storage.objects RLS policies; the schema itself
comes from the service. This keeps local replay green and leaves the remote
untouched.
Project Structure
src/
├── assets/ # Tailwind v4 @theme tokens + global CSS
├── ai/ # AI generation composables + provider adapters
├── cartographer/ # Tile-pack authoring engine
├── components/ # Feature components (npcs/, monsters/, encounters/, …)
├── composables/ # TanStack Query hooks, in per-domain subfolders (a few UI/platform primitives stay at the root)
├── data/ # Static data tables (no logic)
├── directives/ # Vue directives (tooltip, roll mode, …)
├── layouts/ # DefaultLayout (DM), PlayerLayout, AuthLayout
├── levelup/ # Level-up wizard
├── lib/ # Cross-cutting infra + feature subsystems
├── manual/ # In-app user manual (markdown)
├── router/ # Routes + auth guard
├── rules/ # Pure D&D 5e rules computation
├── settings/ # Campaign-setting definitions
├── stores/ # Pinia: auth, campaign, ui, encounterRun, …
├── types/ # TypeScript types per feature domain
└── views/ # Page views per feature area
supabase/
├── functions/ # Deno Edge Functions (AI, Stripe, storage, email, MCP)
├── migrations/ # Timestamped SQL migrations
├── tests/ # pgTAP suites
└── checks/ # Deploy-gating content integrity checks
context/
├── architecture/ # System diagrams + outage triage (start here)
├── features/ # Per-feature agent-readable documentation
└── compliance/ # AI Act register, provenance, retention
Licensing
The source code is published for transparency and community trust — not as open source.
You may: read and study the code.
You may not (without written permission): run, deploy, self-host, modify, distribute, or build products based on this codebase.
Two ways to use Dungeon Grimoire legitimately:
- Use the hosted service at dungeongrimoire.com under its Terms of Service.
- Obtain a license — contact [email protected].
See LICENSE for the full terms.
Contributing
Contributions are welcome! Bug fixes, new features, and improvements can all be submitted as pull requests. For larger changes it's worth opening an issue first so we can align before you invest the time.
By submitting a pull request you agree that your contribution is assigned to Crocode B.V. and may be used, modified, and relicensed by Crocode B.V. under any terms. You retain the right to be credited as a contributor.
