A local-first campaign copilot that helps a human Dungeon Master run a structured fantasy adventure—even if the table is new to tabletop role-playing.
Resonant Realms turns campaign setup, scene guidance, character math, dice resolution, session notes, and continuity into one repeatable workflow. The app can suggest what happens next, but the DM approves every ruling and narration before it becomes part of the campaign.
The included campaign is a seven-gate Hero's Journey built around the 44 cues from Letters and Sounds of the Alphabet. It is designed for ages 13–18 and uses mystery, sound, pattern recognition, and cooperative play rather than classroom-style drills.
Project status: Alpha / tester release candidate (
0.5.0). The core campaign loop is playable in the terminal and responsive browser PWA. It is ready for structured testing, not unattended production hosting.
Native Android and iOS tester applications are now under active development using a bundled Capacitor shell, the same reviewed Story Canvas, native Google identity, and unsigned cross-platform CI builds. Store distribution remains gated by publisher-owned cloud, OAuth, signing, and store accounts. Follow the Android and iOS development plan.
An invite-only Google Cloud pilot path is now included for controlled tester rehearsals. It uses Google Sign-In, Cloud Run, Cloud SQL for PostgreSQL, protected Cloud Storage artifacts, and Vertex AI through a service identity—testers do not provide a Gemini API key. See the Google private pilot runbook; this does not change the recommended local-first path for ordinary users.
Running a tabletop campaign asks one person to teach rules, improvise scenes, track characters, remember earlier choices, manage side quests, and keep the group moving. That is a steep learning curve for a first-time DM.
Resonant Realms gives the table a visible, guided loop:
- The app presents the scene and the current objective.
- A player describes what their hero does in ordinary language.
- The app may clarify shorthand, but it asks for approval before using inferred meaning.
- The DM reviews whether a roll is needed and may edit every suggested rule.
- The player rolls physical dice or uses the local digital roller.
- The DM approves the resulting narration and next story beat.
This keeps the software in a copilot role. It supports the DM; it does not replace them.
| Need at the table | Resonant Realms provides |
|---|---|
| Learn the flow quickly | A Story Canvas that explains the current phase and the next decision. |
| Understand a character | Editable SRD 5.2.1 character sheets with abilities, HP, AC, saves, skills, attacks, conditions, and spellcasting math. |
| Know when and what to roll | DM-reviewed ability checks, attacks, saving throws, DC/AC targets, modifiers, advantage, disadvantage, and physical or digital dice. |
| Interpret short player input | Approval-gated shorthand expansion; inferred intent is never silently accepted. |
| Keep the campaign coherent | Seven fixed milestones with flexible scenes, routes, allies, and side-quest recovery. |
| Remember what happened | Local transcripts, captions, summaries, unresolved threads, pacing advice, and continuity artifacts. |
| Prepare external updates | Human-reviewable D&D Beyond update packets and browser handoffs—never automated account mutation. |
| Use AI without surrendering control | Provider-neutral Cloud Assist with strict schemas, budgets, local validation, and deterministic fallback. |
| Work across devices | Terminal controls plus a responsive, installable browser PWA for desktop, phone, and tablet. |
The demo heroes include original, locally bundled profile portraits. Runtime gameplay does not send character images or descriptions to an image-generation service.
Prerequisites: Python 3.11, 3.12, or 3.13 and a current browser. Docker is also supported.
git clone https://github.com/IsaacSmothers602/REASONANT_REALM.git
cd REASONANT_REALM
.\app.ps1 install --without-audio
.\app.ps1 doctor
.\app.ps1 setup
.\app.ps1 start --opengit clone https://github.com/IsaacSmothers602/REASONANT_REALM.git
cd REASONANT_REALM
chmod +x app
./app install --without-audio
./app doctor
./app setup
./app start --openThe app opens at http://127.0.0.1:8000/. Start with the Story panel, then open Party to review the included character sheets.
To enable local speech-to-text later, run app.ps1 install and app.ps1 audio-setup on Windows, or ./app install and ./app audio-setup on macOS/Linux. See the complete installation guide for containers, LAN access, HTTPS, audio requirements, and troubleshooting.
The cloud path is intentionally fail-closed and requires a Google Cloud billing account plus a Web OAuth client. The preflight is read-only:
.\scripts\preflight_google_pilot.ps1After billing and the OAuth client are operator-approved, the deployment script provisions the dedicated pilot resources and prints the HTTPS service URL. Full commands, tester invite management, validation, cost controls, and rollback are in the hosted pilot runbook.
start --open Start the browser app after a health check
status Show process and health information
logs Read recent application logs
restart Restart without deleting campaign data
stop Stop the service and preserve campaign data
play Start or resume the campaign state
pause Pause the campaign state
Use app.ps1 <command> on Windows or ./app <command> on macOS/Linux.
flowchart LR
Table["DM and players"] --> UI["Story Canvas / terminal"]
UI --> Core["Deterministic campaign core"]
Core --> Data["Local SQLite and session files"]
Core -. "optional proposals" .-> AI["Gemini, Cloudflare, Groq, or local model"]
AI -. "validated draft" .-> Core
Core --> Review["DM approval gate"]
Review --> Story["Recorded outcome and next scene"]
Review -. "manual browser handoff" .-> DDB["D&D Beyond"]
- Local core: campaign state, rules math, event history, approvals, privacy filtering, and deterministic fallback.
- Optional AI: proposes bounded text or voice output. No model is authoritative for dice, safety, character data, or campaign progression.
- Human DM: approves interpretations, rolls, narration, encounters, external updates, and story advancement.
- D&D Beyond: remains a separate user-controlled website. Resonant Realms does not collect its passwords, cookies, or private API tokens.
Cloud Assist is optional. Supported remote providers are configured by the operator, and Google access can use local OAuth onboarding or an advanced API-key path. Credentials remain in the local backend and operating-system credential store, not in player records. Read Cloud Assist architecture and Gemini integration before enabling a provider.
Recording is never assumed. The DM and every current player must explicitly consent for each captured session. A session can use:
- live browser microphone capture;
- an uploaded recording from a phone or recorder; or
- a manually supplied transcript with no audio processing.
Speech-to-text runs locally by default with faster-whisper. Common emails, phone numbers, secrets, and long token-like values are redacted before transcript text reaches campaign-analysis modules. Artifacts stay under the local data/ directory unless the operator deliberately moves or publishes them.
Do not port-forward or publicly expose the built-in server. Trusted-LAN and phone instructions are documented in Installation, while recording, retention, and youth-safety boundaries are documented in Privacy and youth safety.
The included story has seven immutable milestones that cover all 44 phonics cues exactly once. The outcomes remain fixed so learning and narrative coverage can be verified; the path between them can adapt to player decisions.
| Gate | Story function | Cue IDs | Target day |
|---|---|---|---|
| The Beacons Wake | Ordinary World and Call | 1–6 | 4 |
| The Croaking Gate | Refusal, Mentor, Threshold | 7–12 | 8 |
| Road of Living Echoes | Tests, Allies, Enemies | 13–19 | 12 |
| The Clockwork Aerie | Approach | 20–26 | 16 |
| The Five Hidden Voices | Ordeal | 27–31 | 20 |
| The Chamber of Broken Breath | Reward and Transformation | 32–39 | 25 |
| Return of the Signal Crown | Road Back, Resurrection, Return | 40–44 | 30 |
A gaming day is registered only after the DM confirms the campaign and player updates. The campaign cannot exceed 30 completed gaming days, and day 30 cannot close before the final gate is reached.
Resonant Realms does not:
- replace a human DM, teacher, parent, guardian, or speech-language professional;
- automatically create or edit D&D Beyond accounts or characters;
- scrape D&D Beyond or call undocumented endpoints;
- redistribute rulebooks, maps, tokens, artwork, stat blocks, or paid content;
- covertly record players or claim to establish legal consent;
- perform emotion, deception, disability, mental-health, or disciplinary assessment;
- require a cloud model for the campaign to remain operable; or
- provide a hardened public internet server.
make verifyThe verification gate runs Ruff, strict mypy, automated tests with coverage, and repository policy checks. GitHub Actions mirrors the supported Python 3.11–3.13 matrix and also validates the container build.
The Python 3.12 CI job also builds and verifies a commit-identified portable tester ZIP, then uploads
the ZIP, release manifest, and SHA-256 sidecar as a 90-day GitHub Actions artifact for repository
collaborators after a merged main push or explicit workflow run. Pull requests verify the bundle
but do not publish a temporary merge-ref artifact. The archive includes a
private tester guide, an honest
known-issues ledger, and a data-safe rollback runbook.
Local release builders can run make tester-release tester-release-verify.
On Windows, a tester can extract the portable ZIP and double-click
START-RESONANT-REALMS.cmd. First launch installs the fast credential-free path without the
optional speech package and opens Quick Start; later launches reuse the installation. The supported
app.cmd controller remains the single implementation underneath the launcher. Double-click
STOP-RESONANT-REALMS.cmd to stop the local server while preserving campaign data.
Testers can open Tools → Download safe diagnostics or run
rr diagnostics --output resonant-realms-safe-diagnostics.json. This support file contains bounded
build/runtime health, aggregate campaign/session counts, audit gates, event-chain state, and safe
Cloud Assist status. It intentionally excludes identities, story text, player actions, credentials,
OAuth material, transcripts, audio, artifact content, session IDs, and local paths.
The same Tools card displays the exact packaged build ID and abbreviated commit so screenshots and
support reports can be matched to the downloaded tester artifact. Controller-launched Git checkouts
show the current commit too, with a .dirty suffix when tracked files differ; untracked user/runtime
files are intentionally ignored.
On first browser use, a plain-language chooser defaults to Local guidance. That path requires no account, API key, network, or model download and is enforced on every facilitator-draft request: zero remote provider attempts occur even when Google is connected. Gemini Assist is optional, sends only the anonymous lesson capsule after authorization, and retains deterministic local fallback. Only the selected mode name is stored in browser local storage.
Tools → Create feedback packet guides testers through category, impact, observed behavior, expected behavior, and reproduction steps. The app locally redacts common emails, phone numbers, secret/token patterns, current campaign/player/character identifiers and names, and known app data paths; then it downloads a JSON file with exact build identity and safe diagnostics. The report is not saved or uploaded. Automated redaction is limited, so the tester must confirm and repeat a human review before sharing it.
A genuinely empty data directory now opens a browser Quick Start instead of a broken Story Canvas. The wizard validates the complete 1–4 player roster before writing anything, confirms minor/guardian and user-controlled D&D Beyond boundaries, suggests a character name when omitted, builds world and lore, runs the quality audit, starts chapter one, then continues into the local or Gemini guidance choice. Existing campaigns are detected and never overwritten.
Chapter one opens in a real waiting state: the app tells the DM to ask “What do you do?”, selects the first player, and leaves the action field empty. Example wording appears only as a placeholder; no canned action is treated as if a player already said it.
The first-run guidance dialog includes a live readiness board for app health, active chapter, party count, reviewed character sheets, local/Gemini guidance, and session capture. It distinguishes essentials from optional improvements: unreviewed starter sheets or an unavailable live microphone do not falsely block play because editable/manual and file-import fallbacks remain available. Its single next-action button opens Party when sheets need review or focuses the real player-action field when the table is ready.
Key implementation concepts:
- a FastAPI PWA and Typer/Rich CLI share one campaign service;
- SQLite stores state and append-only hash-chained events;
- canonical YAML defines the 44 cues, seven gates, specialists, and quality rules;
- specialist “agents” are bounded modules for story, world, lore, continuity, pacing, privacy, and session artifacts—not independent accounts with unrestricted access;
- every generated recommendation crosses a human approval boundary before it affects play.
See Architecture, Quality plan, and Requirements traceability.
- Private tester guide
- Three-hour human four-player protocol
- Known issues
- Data-safe rollback
- Installation
- Operations runbook
- Audio and session pipeline
- Mobile acceptance
- Release checklist
- Roadmap
- Product brief
- Architecture
- Agent catalog
- Cloud Assist architecture
- Model and voice assessment
- D&D Beyond boundary
- Privacy and youth safety
- Threat model
- Contributing
The project code is available under the MIT License. Material derived from the System Reference Document 5.2.1 is used under the Creative Commons Attribution 4.0 International License; see NOTICE for the required attribution and trademark notice.
Resonant Realms is unofficial fan content and is not approved or endorsed by Wizards of the Coast.