Holonovel README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Holonovel listing page.
Holonovel
Build the Holodeck. Load your campaign.
A holonovel is a Star Trek holodeck program — an interactive story where you step inside as a character and the rules govern. Holonovel builds the server (the Holodeck). Your campaign is the program (the Novel). Your rulebooks become the engine — D&D 5e, Starfinder, or the game on your shelf. Your books. Your server. Your Holodeck.
Table of contents
- Run a server — operators
- How it works — evaluators
- How it compares — evaluators
- Contribute — contributors
Run a server
Install
The base server — a world-model MCP with rooms, things, exits, parser commands, narrative tools, and out-of-the-box mechanics from Fate, Ironsworn, and Blades in the Dark (Fudge dice, momentum, and stress tracks, no ruleset required). Install it, then install any number of ruleset packages — each drops in alongside the base and never modifies it. Node.js 20+ required.
Add to your MCP client:
Install a ruleset
The Build workflow turns a rulebook into a declarative package. Drop the package
into the install directory — .holonovel-state/rulesets/<slug>/ by default — and
the running server registers it. Packages load lazily: a ruleset's tools and index
hydrate only when you open a campaign bound to that ruleset, so stacking many
packages costs you nothing up front. Install, remove, and list packages from the
server tools, or just move files and restart.
Your campaign data and installed packages live under .holonovel-state/, outside
the server tree — updating holonovel never touches them.
Build your own rulebook
To start a build, run the entry point — it records the intake and prints the workflow to follow (see the spec's Workflow Runbooks appendix for the full happy path):
How it works
Holonovel is one pipeline — Convert, Build, World, Novel, Synthesis — that turns a rulebook into a running table. Badge enforcement runs across all of it, server-side.
Convert
Convert takes PDFs, HTML, and web scrapes and turns them into clean Markdown. Column detection reassembles tables across page breaks. OCR catches text embedded in images. The output is structurally sound — every heading resolved, every reference traced.
"Take the Dungeon Master's Guide — every chapter, every table, every sidebar — and make it a clean source file the server can build from." "Convert this PDF to Markdown, and reassemble the tables that break across pages."
Clean Markdown, ready to build.
Build
Build reads that Markdown and extracts every mechanic. Dice procedures, combat systems, spell catalogues, equipment tables, condition tracks — every structured element becomes a tool, resource, or prompt in a declarative ruleset package. Guidance prose becomes narrative material. The discovery engine samples the source, measures extraction confidence, and iterates until every mechanical section is accounted for. What can't be modeled stays searchable — nothing is fabricated to fill a gap.
"Build me a ruleset package from these files." "Extract every mechanic from this rulebook — the dice, the combat, the spells — into a ruleset package."
One spec. Any rulebook. Zero code.
World
The world model is a spatial simulation layer — rooms, exits, containers, supports, doors. Every object knows where it is and what it contains. The server maintains a real containment graph, not a paragraph of prose it hopes the AI remembers. The world model is powered by the Inform programming language — the same engine behind decades of interactive fiction classics.
Parser commands navigate the world with real containment logic. Go north. The room is there. Take the lantern. It moves from the sarcophagus to your inventory. Open containers, lock doors, examine surroundings. Exits connect automatically in both directions. Most AI RPG tools have no spatial model — the AI pretends to remember where things are.
"Go north." "Take the lantern from the sarcophagus." "Look around." "Open the iron door." "Examine the runes carved into the altar."
Your map is real.
Novel
A Novel is your entire campaign — party, NPCs, scenes, lore, combat state, world model, story journal, factions, secrets, everything. The narrative model gives your world depth: scenes set the stage, NPCs carry personality profiles and dialogue voice, lore entries fire automatically when keywords match, factions track standing, secrets gate knowledge, vows bind quests, countdowns escalate on schedule. The story journal records decisions, moments, and consequences — a narrative memory that survives every rebuild.
A Novel lives on the server. It survives restarts, rebuilds, and session breaks. Export as JSON or Markdown. Import with merge, replace, or dry-run modes. Clone to test a story branch. Set checkpoints before pivotal moments. Undo any mutation. A Novel is not a chat log — it is a structured save file. Other tools ask the AI to remember your world. Holonovel writes it to the server — structured, queryable, permanent.
Every Novel has four badge settings. Player. Game Master. Observer. Editor. Switch between them at any time — no restart, no reload. The AI takes the opposite role automatically: when you're the player, the AI is your GM. Badge gating is not a prompt instruction. It is enforced server-side — the GM's secrets, lore entries, and narrative directives never leak to the Player badge.
"Set the scene: a flooded ossuary beneath the old cathedral. The air is thick with stale incense and something older." "A figure emerges from the shadows — Sister Mora, an acolyte of the buried order. She's terrified, not hostile." "I swear a vow to recover the Saint's Reliquary before the next full moon." "Switch to the Game Master badge. I need to set up the next scene." "Pace: I want things to move faster."
Your campaign. On the server. Forever.
Synthesis
Synthesis deepens your campaign through two source categories. Ruleset Wisdom is extracted from your rulebooks during Build — voice examples from example-of-play dialogue, lore templates from setting descriptions, action patterns from resolution sequences, narrative voice profiles from inspirational media citations. It persists as first-class server behavior — the Holodeck renders your rulebook's own genre conventions mechanically. Ruleset Wisdom survives every rebuild and synthesis reversion.
External research runs on demand — web-sourced GM advice, actual-play breakdowns, designer notes. Tagged with source URLs, confidence scores, and freshness timestamps. Every synthesis item is inert by default. The GM toggles what matters on and off at runtime. Re-running synthesis replaces inactive items while preserving everything the GM has activated. Revert synthesis removes external research — Ruleset Wisdom persists.
"Find me GM advice and play examples for running horror one-shots." "Research how other tables handle horror pacing, and tag what you find with sources."
The game evolves without losing what you've built.
How it compares
| Category | What you're used to | How Holonovel differs |
|---|---|---|
| AI storytelling apps | Freeform AI storytellers — invent rules, forget consequences | Your rulebooks. Real dice. Real conditions. Not AI improv. |
| Generic LLM chat | Forgets conditions mid-combat, invents spells, drifts from the ruleset | The server remembers every rule you gave it. Deterministic dice. Conditions that don't vanish mid-fight. |
| First-generation rules MCP servers | Hand-built for one edition of one game. Rules lookup and nothing else. | Not locked to one system. One spec reads any rulebook — D&D 5e, Starfinder, or whatever's on your shelf. |
Every tool in this space asks you to pick. Rules engines serve one system and stop there. AI storytellers improvise mechanics as they go. Holonovel doesn't pick. The server enforces every mechanic. The AI narrates. The Novel preserves everything — D&D 5e, Starfinder, or your own rulebook.
Contribute
Improve the spec
| Command | What it checks |
|---|---|
npm run fmea | REQ-level failure mode and effects |
npm run validate --traceability | Full REQ↔test↔workflow traceability |
npm run graph-deps | REQ dependency graph (DOT/Graphviz) |
Edit files in spec/. Run npm run assemble before committing. Do not edit
holonovel.md directly — it is generated from spec/ source files.
Canonical origin: git.gay/flukeatzerocool/Holonovel. This GitHub repository is a push-only mirror (synced by scripts/push-pipeline.sh) that also hosts the npm and MCP-registry publish workflow (.github/workflows/publish.yml).
Guides for players, Game Masters, and builders live in the project wiki.
License: MIT. Built from: Graham Nelson's Inform (Artistic License 2.0), if-craft-corpus (CC BY 4.0), dmcp (MIT, Shawn Rushefsky), lonelog (CC BY-SA 4.0), BitD SRD (CC BY 3.0, John Harper), Ironsworn SRD (CC BY 4.0, Shawn Tomkin), Fate SRD (CC BY 3.0, Evil Hat Productions). RSS. Last updated: 2026-09-07.