Game Masters Dream

Overview

Game Masters Dream is a full-stack web application built for tabletop RPG game masters to run live sessions. It centralises every tool a GM needs at the table — initiative and combat management, real-time multiplayer maps with player tokens, a soundboard, shared dice rolls, AI-powered content generators, a battle map builder, and a searchable rules reference — in a single application optimised for speed during a live game.

The app supports six RPG systems out of the box (D&D 5e, D&D 2024, Pathfinder 1e/2e, Starfinder, Dungeon World) through a plug-in architecture that makes adding new systems a single-file change. Campaign data is stored locally in IndexedDB for offline use, while live sessions and user accounts use Neon PostgreSQL and PartyKit for real-time WebSocket multiplayer.

Tech Stack

• Next.js 16 / React 19 — App Router with both server components and client-side campaign routes.
• TypeScript — Full type safety across components, stores, API routes, and realtime types.
• Tailwind CSS 4 / shadcn/ui — Dark RPG aesthetic with four switchable color themes (Ink, Ember, Forest, Arcane) in both light and dark modes.
• Zustand 5 — Global state management with Dexie.js (IndexedDB) persistence for offline-first campaign data.
• PartyKit — WebSocket server for real-time multiplayer: map sync, token positions, dice broadcasting, soundboard control, and presence.
• NextAuth — Authentication with session management and invite-based campaign sharing.
• Neon PostgreSQL — Cloud database for user accounts, campaign memberships, and invite tokens.
• Konva / react-konva — 2D canvas powering the battle map builder and live session map with moveable player tokens.
• React Flow — Node-graph canvas for the storyboard mind-map with Excel-style worksheet tabs.
• @dnd-kit — Accessible drag-and-drop for the initiative tracker.
• Google Gemini — AI-assisted NPC generation, encounter building, and quick map generation via /api/generate/npc.
• jsPDF — Client-side PDF export for battle maps (single-page and multi-page tiled print).
• Playwright / Vitest — End-to-end and unit test coverage.

Features

Battle Scene Manager — Initiative tracker with HP tracking, expandable stat blocks, combat log, status effects, and an optional turn timer. Combatants can be added from the campaign's NPC roster or created on the fly.

Live Session Mode — Real-time multiplayer via PartyKit WebSockets. The GM starts a session and shares a join link; connected players see the same map with their character token, roll dice that broadcast to everyone, and hear audio from the GM's soundboard. The GM's panel shows presence, a shared roll feed, map controls, and a video share button.

Battle Map Builder — Grid-based tile map editor with a tile palette, right-click erase, auto-expand/shrink grid, zoom, and export to PNG or multi-page printable PDF. Imported custom assets are stored in a separate IndexedDB store.

Storyboard — Mind-map canvas with Excel-style worksheet tabs. Node types cover characters, locations, events, sessions, and battles. Built on React Flow with full drag, connect, and label-edit support.

Rules Navigator — Tabbed SRD reference (Combat, Exploration, Social, Characters) with fuzzy search, bookmarks, and a system-specific quick-start guide per RPG system. Rules corpus is a structured JSON file per system, loaded at runtime.

Emergency GM Tools — One-click AI generators powered by Google Gemini for NPCs (with stat blocks), random encounters, and improvised locations. All generation is optional and API-key gated so the app works fully offline without it.

Characters — Per-campaign NPC roster with stat blocks, party member tagging, and companion tracking. Characters feed into the Battle Scene Manager and the live session token system.

Soundboards — Per-campaign audio track library supporting uploaded files and YouTube links. Tracks can be played locally or broadcast to all players in a live session.

Session Records — A log of every live session per campaign with start/end time and duration. Used to build a session history and as the anchor for session notes.

Session Zero — Static onboarding checklist and campaign FAQ for new campaigns, covering safety tools, expectations, and house rules.

Key Challenges

Real-time multiplayer across GM and player views: PartyKit handles the WebSocket layer. The GM controls the authoritative state (map, tokens, audio, initiative) and broadcasts deltas; players receive updates and render them locally. The LiveSessionContext wraps the PartyKit client and exposes typed hooks (broadcastRoll, broadcastAudio, updateToken, etc.) so any component can participate in the session without knowing the transport details.

Canvas rendering at scale in the live session: The live map canvas (Konva) runs inside a multiplayer session where token positions update in real time from multiple clients. Token photo data is compressed to base64 JPEG before being shared over WebSocket to keep packet size manageable. Konva's layer system separates the static grid and terrain from the dynamic token layer so only token updates trigger a repaint.

Plug-in game system architecture: Each RPG system is a TypeScript file implementing a GameSystem interface and registered in a central registry. The NPC generator, rules navigator, campaign creation form, and quick-start guide all read from the registry — adding a new system requires no changes outside the src/lib/systems/ directory.

Offline-first with cloud accounts: Campaign data (NPCs, maps, encounters, storyboard nodes) lives in IndexedDB via Dexie and is fully usable without a network connection. User authentication and campaign sharing use Neon PostgreSQL via NextAuth. The two data layers are kept separate: local writes never block on the network, and cloud account state is only needed for sharing features.

Multi-page PDF export: Battle maps can span grids larger than a single printed page. The exporter calculates tile boundaries, renders each page section to an offscreen Konva stage, encodes it as a JPEG, and assembles the pages into a single PDF using jsPDF — all client-side with no server round-trip.

Outcomes

All core GM tools are functional. Live multiplayer sessions run with real-time token positions, shared dice rolls, and synchronized soundboard control across the GM and any number of connected players. The app works fully offline for solo prep and switches to connected mode when a session starts. Six RPG systems ship with full rules corpora and quick-start guides, and the plug-in pattern keeps adding more straightforward.