Home - flukeatzerocool/holonovel GitHub Wiki

Holonovel

Holonovel is an MCP game server that reads tabletop RPG rulebooks and builds a running server — dice, combat, character management, rules lookup, narrative tools, world model, and campaign persistence. The engine enforces every rule. The AI narrates. Build a server for any rulebook — D&D 5e, Starfinder, or your own.

What ships in this repo

Server	What it is	Tools	Resources	Prompts
holonovel	Ruleset-free world-model base — rooms, things, exits, parser commands, narrative tools	30	38	5

The server runs from the specification (holonovel.md) — 517 requirements,

servers are rebuilt on demand.

What's here

You are a...	Start here
New to Holonovel — what is this and why should you care?	What Holonovel Is
Player — you want to play with an AI Game Master	Getting Started → Playing the Game → Character Creation
Game Master — you want to run worlds	World and Narrative Model → Novels → Game Mastering
Builder — you have rulebooks and want a server	Building a Server → Jobs → Tools
Server maintainer — your spec changed, your server needs to follow	Updating a Server
Playing a TTRPG — a full campaign, from your PDFs to your first session	Part 1: Setup → Part 2: The Novel

How this wiki works

Every page declares its type up front — Tutorial, How-to, Reference, or Explanation. This is the Diátaxis framework: tutorials teach, how-tos solve problems, references list facts, and explanations answer "why." Each page belongs to exactly one type. Look for the bold label at the top of every page to know what you're reading and whether it's for you.

Feature inventory

Resolution mechanics

Dice rolls with full transparency — every die face, modifier source, and outcome band. Saving throws, skill checks, weapon attacks, damage rolls. Deterministic RNG with seedable reproducibility. Advantage/disadvantage. Pre-narration validation rejects mechanically impossible results before you see them.

Characters

Step-by-step creation (stats → race → class → background → name) or single-call quick creation. Complete character sheets in ruleset-baseline format. Permanent roster surviving every rebuild. Import/export across campaigns. Voice examples and personality profiles control how the AI portrays each character.

Badges and roles

Four badges switched without restart: Player, Game Master, Observer, Editor. Server-side enforcement — GM secrets vanish from Player surface. AI takes the counterpart role by default. Observer mode lets the AI run both sides while you spectate. Adjustable autonomy controls AI independence.

World model

Rooms, exits, containers, supports, doors — a real containment graph, not prose. Parser commands: go north, take lamp, open chest, lock door, look. Exits connect automatically in both directions. Rooms track contents. Conventions drawn from the Inform interactive-fiction language.

Narrative tools

Scene state with description, location, time of day, atmosphere. Scene type tagging (combat, social, exploration, neutral). NPCs with stats, disposition, personality, voice examples, and independent memory. Lore entries trigger on keyword match. Countdowns escalate tension on schedule. Factions with standing and agendas. Secrets gated behind discovery. Relationships evolving between entities. Vows with milestone tracking. Story journal records decisions.

Combat

Turn order, initiative, condition tracking, automatic danger advancement. State survives server restarts. Conditions expire on schedule. Combat participant add/remove mid-encounter. Round-level and narrative countdowns.

Campaign persistence

Novels are structured save files — typed, validated, checksummed. Survive every server restart and rebuild. Export as JSON or Markdown. Import with dry-run, merge, or replace. Clone to branch. Checkpoints. Pause/resume context. Session recaps. Audit log with compression.

Codex

Server-level persistent artifact library. Fourteen entry kinds: NPCs, characters, scenes, encounters, lore, factions, countdowns, rooms, things, equipment, spells, relationships, voice profiles, and adventures. Capture from any Novel, import into any other. Ruleset-annotated to prevent cross-system contamination. Your worldbuilding vault.

Synthesis

Three tiers of optional enrichment: Ruleset Wisdom (vendor content from established TTRPG communities), External Synthesis (web-sourced GM advice), Internal Synthesis (generated from your Novel state). Inert by default — GM activates what matters. Each tier independently removable.

Build and verify

Convert PDF/HTML/web scrape to clean Markdown. Build reads any rulebook and constructs a server. Convergence loop iterates up to three attempts per metric until quality thresholds pass. The Pattern Buffer — 33 adversarial sub-workflows (29 ruleset-facing) — validates mechanical integrity, badge enforcement, state recovery, and combat endurance. Independent verification replays all workflows from a cold checkout.

Where everything lives

What	Where
Specification	`holonovel.md`
README (project overview)	`README.md`
Changelog	`CHANGELOG.md`
World-model base server	`holonovel/`
Issues	Issues