Holonovel README

Holonovel

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

Start with the project wiki — it routes players, Game Masters, and builders by task.

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 mechanics — 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
  • Holodeck
  • Novel
  • Synthesis
• How it compares — evaluators
• License — reference

Run a server

Install

A fresh install is playable without a rulebook. On first start the server seeds Torre Nosferatu, a tutorial Novel, and open_session resumes it in one call; set TTRPG_STARTER_NOVEL=off to start with an empty world instead.

The base server runs the Holodeck. Rooms, objects, exits, and containment form a real state graph, while scenes, NPCs, lore, and a story journal layer on top, so narration is grounded in stored facts rather than prior chat turns. Requires Node.js 22+.

npx -y holonovel

Add to your MCP client:

{
  "mcpServers": {
    "holonovel": {
      "command": "npx",
      "args": ["-y", "holonovel"]
    }
  }
}

Clients with their own configuration shape (for example a type plus a command array) take the same command and arguments. From a source checkout, run cd holonovel && npm install && npm run start, then point the client at npx tsx src/index.ts in that directory.

Campaign data defaults to the operating system's user-data directory: ~/.local/share/holonovel on Linux, ~/Library/Application Support/holonovel on macOS, or %LOCALAPPDATA%\holonovel on Windows. Set TTRPG_DATA_DIR to override it. An existing .holonovel-state/ beside the server is preserved. A container or hosted deploy keeps that directory inside the container, so point TTRPG_DATA_DIR at a mounted volume to keep campaigns across restarts.

Setup details and first-run checks: Getting Started guide.

Install a ruleset

A ruleset package is a declarative bundle produced by the Build workflow. Copy it into the server's ruleset install directory and the server registers it. That directory is inside the state directory — by default the per-user data location described above.

Packages load lazily: a ruleset's tools and index are read only when you open a campaign bound to it, so unused packages cost nothing at startup. Install, remove, and list packages from the server's own tools, or move files and restart.

Campaign data and installed packages stay in the state directory, outside the server tree, so updating Holonovel leaves both intact. The Building a Server guide covers packaging a rulebook.

How it works

Holonovel is one pipeline — Convert, Build, Holodeck, Novel, Synthesis — that turns a rulebook into a running table.

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.

"Convert the files in ruleset/dnd5e/ to Markdown for the D&D 5e ruleset." "Convert the HTML export in ruleset/starfinder/ for the Starfinder ruleset."

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 the Markdown in ruleset/dnd5e/ into a holonovel." "Package ruleset/starfinder/ as a second ruleset alongside D&D 5e."

One spec reads any rulebook, and the build produces zero hand-written code.

Holodeck

The Holodeck is the narrative world model — the core engine that drives the simulation. It turns a saved Novel into a running game. Every part of a campaign is structured state: rooms, objects, exits, and containment in the spatial model; scenes, NPCs, lore, factions, secrets, vows, countdowns, relationships, decisions, and the story journal in the narrative model; mechanics and ruleset voice alongside them. None is decoration. Each has a defined effect on the others.

That effect is what makes Holonovel an engine. A scene sets the place and cast and activates lore whose triggers match its text. An NPC carries identity, disposition, relationships, and a location, so moving them changes who is present and who can speak. A secret stays hidden until knowledge and trigger conditions allow it to surface. A vow creates a decision the Game Master must honor. A countdown advances on schedule and fires its result into the world. A mechanical outcome — damage, a destroyed object, a doused light — mutates the state it touches. The story journal records the consequence, and later scenes can recall it.

The engine evaluates these couplings. The AI narrates the result. Nothing is left to a "remember this" instruction, and nothing drifts between turns. The MCP server is one adapter over the engine; the Novel is the portable program.

Parser commands act on the spatial model with real containment logic. Go north. Take the lantern. The room, the object, and the inventory are stored records, not claims in narration. Exits connect in both directions, containers hold what they hold, and doors stay locked until something unlocks them. The spatial conventions are drawn from Inform, the interactive-fiction language behind decades of text-adventure classics.

"Go north into the flooded ossuary." "Set the scene here — the ossuary reeks of stale incense and old water." "Have Sister Mora follow me into the ossuary." "Ask Sister Mora what she knows about the buried order." "Advance the reliquary countdown by one day."

The Holodeck is the live simulation; the Novel is its save file.

Novel

A Novel is the save file for a Holodeck game, and it stores the configuration that shapes that game. Server settings supply defaults; each Novel overrides them where the setting is campaign-scoped, and every change is saved with the campaign.

Who plays is configurable. A badge sets your seat at the table and what that seat can see: Player is in the story as a character, Game Master sees and controls the world, Observer watches while the AI runs both roles, and Editor steps outside the story to manage the save. The server enforces the boundary, so GM-only secrets do not leak to the Player badge. Each Novel carries its own active badge, and four autonomy sliders decide how much the AI handles alongside it: level (auto-play, prompt on mechanical actions, or manual), confirmation (execute, confirm, or prompt), safety (safe, moderate, or hardcore), and creativity (predictable, standard, or chaotic). The sliders compose with any badge, so a human can hand off one character, all NPCs, or the whole table without changing seats. The Game Mastering guide covers running the world from the opposite side.

How the story behaves is configurable. Player signals set pace, difficulty, tone, focus, and boundaries. A narrative directive tunes pacing, autonomy, world reactivity, and synthesis in plain language; matching keywords take effect mechanically, and anything else becomes guidance for the narrator. Behavioral settings cover whether the world reacts, whether NPCs and factions pursue goals on their own, when synthesis refreshes, how much memory each tier retains, and whether moments record automatically. Point of view can lock to the active character or stay omniscient, and social scenes can use a manual, natural, list, or pooled speaker order.

What content appears is configurable. A Novel binds to one ruleset at creation and can add supplementary rulesets without changing that binding. The categories used to organize available actions can be reassigned per Novel, and briefing order, enabled action patterns, and journal detail decide which guidance surfaces during play.

Export as JSON or Markdown. Import with merge, replace, or dry-run. Clone, checkpoint, and roll back. A clone carries the full configuration.

"Let the AI run all NPCs and player characters, but pause for mechanical decisions." "Make the game faster and darker, with harder fights." "Let the world react and NPCs act independently; use the rulebook's voice patterns." "Run synthesis whenever the scene changes." "Clone this Novel with its settings."

Every Novel-scoped setting is saved with the Novel, so a clone or checkpoint preserves the exact game you configured.

Synthesis

Synthesis deepens the Holodeck beyond mechanics. Ruleset Wisdom comes from the rulebook and any vendor package during Build — voice examples from example-of-play dialogue, lore templates from setting descriptions, action patterns from resolution sequences, and narrative voice profiles from inspirational media citations. It is build output, active by default, and survives every rebuild and synthesis reversion.

The Synthesis run adds two layers on demand. External research collects web-sourced GM advice, actual-play breakdowns, and designer notes, tagged with source URLs, confidence scores, and freshness timestamps. Internal synthesis reads the Novel itself for patterns the table has already produced. Both are inert by default: the Game Master activates what fits and deactivates what does not, and that activation state is saved with the Novel. Re-running synthesis replaces inactive items and preserves active ones. Reverting removes the synthesis layers; Ruleset Wisdom and player-authored items persist.

Synthesis can run on demand, at the start of a session, or after a scene change.

"Research horror one-shot pacing and actual-play examples, tagged with sources." "Enable the horror pacing guidance that fits this campaign." "Run synthesis after every scene change."

Ruleset Wisdom, synthesis layers, and player-authored items coexist in the Novel without replacing one another.

How it compares

Rules engines serve one system. Storytellers improvise mechanics. Holonovel does neither: any rulebook becomes enforced mechanics, a spatial world, and a saved campaign. Across the TTRPG MCP servers reviewed in October 2026, no other reviewed server combined rulebook ingestion, spatial containment, and server-side role enforcement — for D&D 5e, Starfinder, or your own book. Questions about a specific table's setup? See the FAQ.

License

Canonical origin: git.gay/flukeatzerocool/Holonovel.

Holonovel is MIT-licensed. Built from:

• D&D 5e SRD v5.1 (CC BY 4.0 + OGL 1.0a, Wizards of the Coast)
• Graham Nelson's Inform (Artistic License 2.0, Graham Nelson)
• if-craft-corpus (CC BY 4.0, pvliesdonk)
• dmcp (MIT, Shawn Rushefsky)
• lonelog (CC BY-SA 4.0, zeruhur)
• 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, Adam Koebel)
• Fate SRD (CC BY 3.0, Evil Hat Productions)
• Ironsworn SRD (CC BY 4.0, Shawn Tomkin)

RSS. Last updated: 2026-10-31.