Playing a TTRPG Setup

Playing a TTRPG, Part 1: Setup

Tutorial. For new players and builders. You have Node.js 20+, an MCP-capable AI client, and a legal copy of a tabletop RPG. I'll use Mothership as our example throughout, but everything here works for any game you own. By the end, you'll have a running game server — your rulebooks converted to Markdown and built into a playable ruleset.

The easiest way through this tutorial is to let your AI read it. Have your AI follow along page by page — that's the advantage of agentic AI. You supervise and make the calls; the AI drives the tools and asks you the built-in questions as they come up.

What you're about to do

Holonovel turns tabletop roleplaying game (TTRPG) rulebooks into a running game server. The engine enforces every rule. The AI narrates. You talk. The dice decide.

To show you how it works, I'm going to walk you through one specific game: Mothership, a sci-fi horror RPG from Tuesday Knight Games. You roll a d100 and try to get under your Stat or Save. Failure costs you Stress, and Stress becomes Panic. In Part 2, I'll play through the official introductory adventure, Another Bug Hunt, with you.

Don't let the Mothership focus throw you. If your shelf holds D&D 5e, Starfinder, or anything else, the steps are identical — swap in your books and your slug and keep going. I'm just using Mothership because it's a nice, compact example.

This part covers the first two sessions:

1. Session 1 — Convert. Turn your rulebook PDFs into Markdown.
2. Session 2 — Build. Turn that Markdown into a ruleset server, extract Ruleset Wisdom, and optionally add community GM advice.

Each session runs the same two-step rhythm: plan first, then execute. I plan in Plan mode with a fast model, then execute in Build mode with a capable one.

Your AI setup

This section is my setup, not a requirement. Holonovel MCP works with any MCP-capable AI client — Opencode, Zed, Claude Desktop, Continue, Cursor, and others. I use Opencode, and sometimes Zed. Opencode Go supplies many models; DeepSeek Flash and Pro are just the two I happen to use. Any capable model completes this tutorial.

Two client features matter, whatever you run:

• Plan mode. Read-only. The AI reads and reasons but changes nothing. I use it to plan a session before I start.
• Build mode. Full access. The AI reads, writes files, and runs commands. I use it to execute.

Models have a thinking setting. High thinking means the AI reasons deeply before answering. No thinking means it answers immediately.

Here's the routing I use across both articles — my preference, not a rule:

Step	Mode	Model	Thinking
Plan a setup session	Plan	DeepSeek Flash	High
Run a setup session	Build	DeepSeek Pro	High
Play the game	Build	DeepSeek Flash	None

The logic: planning wants cheap reasoning; executing wants capability; playing wants speed. Horror pacing suffers if the AI stops to philosophize in the middle of a panic check, so play drops thinking to none.

Source: Opencode documentation (modes and thinking).

What you need

1. Node.js 20 or newer. Run node --version to check. Get it at nodejs.org if needed.

2. An MCP-capable AI client with a capable model. Holonovel MCP works with Opencode, Zed, Claude Desktop, and other MCP clients — any model that can follow instructions and call tools.

3. A legal copy of the game you're building. For our example, that's Mothership. The boxed set includes the Player's Survival Guide, the Warden's Operations Manual, the Warden's Screen, and character sheets — plus the Another Bug Hunt module. Whatever you choose, you just need the books you plan to play.

A note on your PDFs

You own the books you convert. Converting them to Markdown for your own local server is a personal-use task. The converted files stay on your machine. Do not redistribute them — the books remain the publisher's work. This is true for Mothership and for every other rulebook I mention here.

Install Holonovel

Clone the repository, then install and start the server.

git clone ssh://git@git.gay/flukeatzerocool/Holonovel.git
cd Holonovel/holonovel
npm install
npm run start

Connect the server to Opencode by adding a block to your MCP (Model Context Protocol) config — the file is ~/.config/opencode/opencode.json.

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

Replace /path/to/Holonovel/holonovel with the actual path on your machine. The MCP block goes in your client's config — ~/.config/opencode/opencode.json for Opencode, ~/.config/zed/settings.json for Zed. Restart your client. Your campaign data and installed rulesets live under .holonovel-state/, outside the server tree, so updating Holonovel never touches them.

Most tuning lives in TTRPG_* environment variables on the server command and in files under .holonovel-state/. You rarely need to touch these by hand — the server asks for the rest through its built-in prompts.

Source: README.md §1 (Quick start), spec §2.

Session 1: Convert your PDFs to Markdown

What Convert is

Convert is a workflow that takes PDFs, HTML, or web pages and produces clean Markdown. Column detection restores reading order in multi-column layouts, and multi-page table reassembly merges table fragments split across page breaks. Scanned pages fall back to OCR (optical character recognition). The result is structurally sound — headings resolve and references trace.

For our Mothership example, I run it on the books I'll play with:

• Player's Survival Guide — the core rules and character creation.
• Warden's Operations Manual — the referee's rules.
• Another Bug Hunt — the adventure module.

The Warden's Screen and character sheets are optional. Convert what you plan to use. With any other game, it's the same idea — core rules first, then the modules and supplements you actually intend to play.

Plan it

Mode: Plan. Model: DeepSeek Flash. Thinking: High.

Before converting, I tell the AI what I want to happen. I decide the source and the target ruleset, and name them. For our example, I'd say:

"Convert my Mothership books to Markdown."

Swap in your own books and your own ruleset name — the shape stays the same.

Execute it

Mode: Build. Model: DeepSeek Pro. Thinking: High.

Switch to Build mode, then start the workflow. Continuing our example:

"Convert these PDFs to Markdown."

The AI asks the Convert intake questions up front — source type, source path(s), and the ruleset name — and records your answers before touching anything. The workflow runs per source and validates each file's structure before handoff. When it finishes, I have Markdown that the Build workflow can read.

Your options

• Which books. Core rules are required. Adventure modules and supplements are optional, and each becomes searchable content the server indexes.
• Source format. PDF is the common case. HTML and web pages convert the same way.
• Validation. If a converter drops headings or tables, the workflow re-runs with a validated converter rather than hand-editing the output.

Source: spec §6.1 (Convert workflow), Appendix G (source conversion), Appendix H (preparation checklist).

Session 2: Build the ruleset

What Build is

Build reads your Markdown and extracts the mechanics. Dice procedures, combat systems, equipment tables, condition tracks — modeled elements become a tool or resource, and what cannot be modeled stays searchable. Guidance prose becomes narrative material. Nothing is invented to fill a gap.

The result is a declarative ruleset package, installed to .holonovel-state/rulesets/<slug>/. For our example, that's .holonovel-state/rulesets/mothership/.

Plan it

Mode: Plan. Model: DeepSeek Flash. Thinking: High.

I review my converted Markdown before building. I confirm the books are complete and the file names are clear, then decide on the ruleset slug — the short name the server uses. For Mothership, mothership is the natural choice. For D&D 5e it'd be dnd5e; for Starfinder, starfinder.

Execute it

Mode: Build. Model: DeepSeek Pro. Thinking: High.

Start the build with the entry point. It records my answers and prints the workflow to follow.

npm run build-ruleset mothership=YOUR-BOOKS-DIRECTORY

Replace YOUR-BOOKS-DIRECTORY with the folder holding your converted Markdown — and replace mothership with your own slug.

Or say it in plain language:

"Build me a ruleset package from these files."

The build runs in phases:

1. Intake. The AI asks its intake batch up front and records the answers in DECISIONS.md before anything starts: which workflows to run, the slug=path ruleset pair, your AI client, where to save data, and what to call the server — plus an advanced set (build mode, version, world-surface prominence) you can accept as-is or override.
2. Discovery. The AI reads your books and extracts concepts (stats, saves, conditions), entities (classes, monsters, NPCs), actions (checks, attacks, tables), and the core resolution mechanic. It labels each with a confidence score and cites its source.
3. Construction. The AI writes the server: the index, the search and lookup tools, the dice and combat tools, the character tools, and the prompts.
4. Verification. The convergence loop measures extraction and construction quality and iterates until thresholds pass or the three-attempt cap is reached.
5. The Pattern Buffer. Adversarial checks hammer the server — tool sweeps, combat endurance, badge boundaries, corrupted-state recovery.

I get a running server for my game, plus a model of what was extracted (RULESET_MODEL.md) and a record of every decision (DECISIONS.md).

Source: spec §6 (Build process), README.md §2 (Build).

What Build extracts — our Mothership example

The discovery phase reads the Player's Survival Guide and extracts the mechanics from the book — stats, saves, classes, health, stress, the d100 roll-under, skills, and gear — and builds them into the server. You don't type these yourself; the server carries them, and Build pulls the same kind of content from any rulebook you feed it.

Source: Mothership Player's Survival Guide (converted Markdown, 01_players_survival_guide.md).

Ruleset Wisdom

Build also extracts what the book sounds like, not only what it says. Voice examples come from example-of-play dialogue. Lore templates come from setting descriptions. Action patterns come from resolution sequences. This is Ruleset Wisdom — the genre conventions of your rulebook, rendered mechanically. It is always present and survives every rebuild and synthesis reversion.

A second source, vendor content, adds craft advice from open-source TTRPG communities — GM principles from Dungeon World, node-based design from The Alexandrian, lazy-prep shortcuts from Sly Flourish. It is tagged with its source and processed alongside your books.

Source: spec §11.4 (Ruleset Wisdom), README.md §2 (Synthesis).

Synthesis (optional)

Synthesis is the optional tail of the build session. I run it after a clean build, or skip it and run it later without rebuilding.

What Synthesis is

Synthesis enriches the server with advice, not rules. It runs after a clean build and adds supplementary content to the GM's briefing. Everything it adds is inert by default — I activate what I want.

It has three tiers:

Tier	Source	Removable
Ruleset Wisdom	Your rulebooks and vendor craft content	No — build output
External Synthesis	Web research — GM advice, actual-play notes	Yes — manage_synthesis (action: revert)
Internal Synthesis	Your own Novel state — NPCs, lore, journal	Yes — independently

Plan it

Mode: Plan. Model: DeepSeek Flash. Thinking: High.

I decide which tier I want. For a first game, I skip external research and let Ruleset Wisdom carry the genre. I can run Synthesis later without rebuilding.

Execute it

Mode: Build. Model: DeepSeek Pro. Thinking: High.

"Synthesize the server with community GM advice."

Or revert it if it becomes noise:

"Revert all Synthesis content."

Ruleset Wisdom persists through a revert. Only the enrichment is removed.

Source: spec §11 (Synthesis), Synthesis.

Where you are now

Your game server is running. Your rulebooks are converted and built. For our example, the slug mothership is installed and ready — and if you used a different game, your own slug is sitting there instead.

Next, we build the campaign — the Novel. Create it, load the adventure, run session zero, and build the crew. Continue to Playing a TTRPG, Part 2: The Novel.

See also

• Building a Server — the full build pipeline, phase by phase
• Synthesis — the three tiers in detail
• What Holonovel Is — why the engine enforces and the AI narrates
• Getting Started — installing and connecting the base server

Maintenance notes

Deliberate departures to preserve across future updates:

• "Your AI setup" is the author's setup, not a requirement. Do not re-harden it into an Opencode Go or DeepSeek dependency — any MCP client and model works.
• Prompt examples are intentionally terse. Do not expand them back into paragraph-length examples.

Last updated: 2026-10-12.