Local-First AI · TTRPG Systems · Runtime Architecture
Black Dice Engine
A tabletop RPG platform that coordinates narration, player companion screens, dice and campaign state, session memory, and optional AI or locally generated scene media. The rules services—not the language model—control the game state.
At a glance
Role
Solo product architect and gameplay-systems engineer
Status
Early prototype with a game server, GM dashboard, player companion, session state, and dice endpoints
Stack
Node.js, TypeScript, local web clients, structured campaign storage, and media adapters
Technical Rule
AI may suggest actions, but deterministic services validate dice, permissions, and campaign state
What It Solves
AI-assisted tabletop tools can drift, forget canon, invent contradictory state, or mix private material into remote services. Traditional virtual tabletops also split narration, memory, media generation, rules bookkeeping, and player sheets across too many disconnected apps.
Black Dice Engine brings those responsibilities into one local runtime: the GM gets live narration support and deterministic state tools; players get lightweight companion views; the campaign gets structured memory; and generated content flows through clear schemas, permissions, and approvals.
Brand mark, not the main product story
Product Pillars
GM Command Center
A dashboard for scene framing, live narration support, party state, hidden notes, dice logs, memory review, and approvals for heavier media jobs.
Player Companion
Phone/tablet views for character sheets, status, rolls, submitted actions, handouts, and player-visible scene updates over the local network.
Local-First Runtime
Campaign databases, generated media, models, secrets, and private PDFs stay outside Git and on the host machine unless remote services are explicitly enabled.
Architecture
The core architecture is intentionally not a tangled mesh. The GM dashboard and player phones talk to one local game server. The game server coordinates dice, state, memory, AI, media, runtime health, and persistence.
-> local game server
-> dice, state, memory, AI, and media services
-> database and local asset folders
-> WebSocket updates back to clients
Game Server
Single API boundary for the GM dashboard, player phones, WebSocket updates, permissions, and service orchestration.
Dice + State Services
Dice parsing, roll history, explicit state events, inventory/resource updates, conditions, initiative, quest flags, and auditability.
Memory Service
Campaign canon, summaries, unresolved threads, NPC facts, locations, faction state, and session history stay structured instead of becoming loose chat history.
AI + Media Adapters
Local LLM adapters, optional director calls, ComfyUI scene generation routing, and local audio cues sit behind approvals and runtime health checks.
Current Prototype
The repository includes the first local prototype: a Node/TypeScript game server with health, runtime-status, session-snapshot, and dice-roll endpoints, plus small GM dashboard and player companion shells.
The next major work is integrating persistence, local model adapters, ComfyUI routing, campaign memory ingestion, permissions, imports, and hardened runtime recovery.
Engineering Lessons
Do not make the LLM the source of truth
The AI may propose narration, dice calls, memory updates, or state changes. The game server validates and applies mechanics through explicit services.
Keep player-visible and GM-only data separate
A table tool has real privacy boundaries: hidden notes, future reveals, private character details, and imported material cannot leak into companion views.
Graceful degradation matters
If image generation, audio, or a local model fails, the session should keep running. Runtime health, reconnect state, and backups are part of the design.
Portfolio Relevance
This is portfolio-worthy because the hard part is orchestration: player input to GM reasoning, dice/rules/state tools, memory updates, media jobs, campaign logs, and the next turn. It shows product architecture, local-first privacy thinking, schema-driven AI boundaries, runtime reliability, and gameplay systems design in one project.
View GitHub Repository