io.github.flukeatzerocool/holonovel

Holonovel

The Holodeck for your rulebooks — rules enforced, worlds remembered.

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
  • Install
  • Install a ruleset
• How it works — evaluators
  • Convert
  • Build
  • World
  • Novel
  • Synthesis
• How it compares — evaluators

Run a server

Install

Install the base server and play — no rulebook required. The first start seeds a ruleset-free tutorial Novel, Torre Nosferatu, so a fresh install opens on a world you can enter immediately; set TTRPG_STARTER_NOVEL=off to skip it.

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 24+ required. New to the server? Start with the Getting Started guide.

cd holonovel
npm install
npm run start

Add to your MCP client:

"holonovel": {
  "type": "local",
  "command": ["npx", "tsx", "src/index.ts"],
  "cwd": "<path>/holonovel",
  "environment": {
    "TTRPG_NOVEL": "default"
  },
  "enabled": true
}

Install a ruleset

The Build workflow turns a rulebook into a declarative package. Drop the package into the server's ruleset install directory and the running server registers it. That directory lives inside the server's state directory, which defaults to a per-user data location outside the project tree (or .holonovel-state/ when the server runs outside one). 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. The Building a Server guide walks a rulebook from PDF to package.

Your campaign data and installed packages live in that state directory, outside the server tree — updating holonovel never touches them.

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. Multi-column pages are read in the right order, and tables split across page breaks are reassembled. Scanned pages fall back to OCR. The output is structurally sound — headings resolve and references trace.

"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, indexed Markdown ready for the build.

Build

Build reads that Markdown and extracts the mechanics. Dice procedures, combat systems, spell catalogues, equipment tables, condition tracks — modeled elements become tools, resources, or prompts in a declarative ruleset package, while anything that can't be modeled stays searchable. Guidance prose becomes narrative material. The discovery engine reads the source in chunks, measures extraction confidence, and works until the mechanical sections are accounted for. 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 reads any rulebook, and the build produces zero hand-written 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. Its conventions are drawn from Inform, the interactive-fiction language behind decades of text-adventure 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.

"Go north." "Take the lantern from the sarcophagus." "Look around." "Open the iron door." "Examine the runes carved into the altar."

The map is real state, not narration.

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. The Game Mastering guide covers running a world from the opposite side of the screen.

"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."

The campaign persists on the server as structured, queryable state.

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

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. Questions about a specific table's setup? See the FAQ.

Canonical origin: git.gay/flukeatzerocool/Holonovel. The project wiki routes players, Game Masters, and builders by task.

License: MIT. Built from: Graham Nelson's Inform (Artistic License 2.0), D&D 5e SRD v5.1 (CC BY 4.0 + OGL 1.0a), 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: Starforged SRD (CC BY 4.0, Shawn Tomkin), Sly Flourish Lazy GM Resource Document (CC BY 4.0, Mike Shea), The Alexandrian (CC BY 4.0, Justin Alexander), Dungeon World SRD (CC BY 3.0, Sage LaTorra and Adam Koebel), Fate SRD (CC BY 3.0, Evil Hat Productions), Ironsworn SRD (CC BY 4.0, Shawn Tomkin). RSS. Last updated: 2026-10-22.