Repository navigation
Game Mastering
How-to. For Game Masters. You know how to play. This page covers every GM tool — scenes, NPCs, lore, countdowns, combat, campaigns, and safety nets. Everything is done by talking. The engine handles the state.
In a traditional TTRPG, the GM tracks everything in their head. In most AI roleplaying tools, the GM tracks everything by typing it into prompts and hoping the AI remembers. In Holonovel, the engine tracks everything for you — structured, queryable, permanent. You set the scene. You create the NPCs. You trigger the lore. The engine remembers it all. The AI narrates from it.
A Novel is your campaign container — one file on disk holding the party, NPCs, scenes, lore, combat, and everything else. Multiple Novels coexist without leaks.
"Start a new game called the Dragon Tomb." "Switch to my other campaign." "Resume the Ravenloft game."
Novels survive every server restart and rebuild. Export to JSON or Markdown,
import back with merge, replace, or dry-run. End a Novel and it moves to
.trash/ with a configurable retention period — nothing is permanently deleted
unless you want it to be.
Source: spec §5.9 (REQ-088, REQ-095, REQ-096, REQ-117), README.md §2 (Novel, State & Recovery).
"Set the scene: a flooded ossuary. The air is thick with old incense. Water drips from the ceiling. Three stone sarcophagi line the walls."
The scene description governs lore trigger matching, action suggestion context, and tool ordering in the GM briefing. Set location, time of day, and atmosphere as structured fields. Scene types tag the narrative mode — combat, social, exploration, neutral, or compound (e.g., "combat" + "social" for a duel amidst negotiation).
Every scene change records a transition hook in the audit log. Narrative countdowns tick automatically on scene transitions. Suppress the hook for detail updates within the same scene.
Source: spec §5.6 (REQ-076, REQ-076a), §5.8 (REQ-087, REQ-125), README.md §2 (Narrative Management).
"An acolyte named Sister Mora steps out of the shadows. She's terrified, not hostile."
NPCs carry stats, disposition, location, personality, and voice examples. Voice examples are dialogue snippets tagged with scene context — they teach the AI how the NPC speaks, not just what the AI knows about them. When the NPC speaks in-character, examples render ahead of trait descriptions.
"Make Sister Mora sound like this: [dialogue examples]"
NPCs maintain independent memories of their interactions with the party. The
engine records what each NPC witnessed and tracks their disposition
automatically — threaten the blacksmith and disposition shifts to hostile.
Help them and it shifts toward friendly. This isn't a prompt instruction.
It's structured state that persists across scenes and sessions. Every
subsequent interaction reflects these changes without you needing to manually
update anything.
Source: spec §5.6 (REQ-077, REQ-126, REQ-127, REQ-311), README.md §2 (Narrative Management).
The engine maintains a Campaign Memory — a fact store organized per NPC, per plot thread, and per location. Every significant event is recorded automatically: NPC X said Y to character Z in scene W. Faction standing changes. Clues discovered. Relationships formed. This memory survives rebuilds and is reinjected as canonical context in your GM briefing, prioritized by relevance to the current scene.
You never need to remember what happened 12 scenes ago. The engine remembers for you.
Source: REQ-310.
The world doesn't freeze when the party leaves. Between scenes, NPCs pursue their goals. Faction agendas advance. Consequences from player actions ripple through connected entities. The blacksmith the party threatened might have fled town. The rival faction the party ignored might have consolidated power.
You see these changes in the World in Motion section of your GM briefing,
with options to accept, modify, or defer each one. The engine proposes.
You decide.
Source: REQ-233a.
The AI's narrative prose is archived for the audit log and story journal but is not re-injected as raw text into future context windows. What enters the next context is the structured state delta — the facts, not the prose. This is the architecture that breaks the copy-of-a-copy loop: characters don't converge toward the model's default voice because the AI's own past output isn't contaminating the window.
Source: spec §7.3a.
Lore entries fire when keywords match the current scene. They appear in the GM briefing at the right moment — no need to remember what's relevant.
"When anyone mentions the ossuary, remind me: the drowned priests still pray down here."
Entries have configurable priority (sort order in briefing), stickiness (stay visible for N briefings after keywords leave the scene), and badge scope (GM-only or shared with players). A token budget caps lore output — when entries exceed the budget, low-priority ones are omitted and reported.
Groups organize entries by theme — faction lore, location lore, plot threads.
manage_lore (action: toggle) enables or disables individual entries without deleting them.
Source: spec §5.8 (REQ-083), README.md §2 (Narrative Management).
Escalate tension on a schedule:
"The ritual completes in five rounds. Start the countdown." "The ship hull buckles. It'll hold for three more hits."
Two types: round (decrements per combat round) and narrative (decrements on scene transitions). Direction: decrement (counts down to zero) or increment (progress clocks, counts up). Badge scope: GM-only for hidden threats, shared for player-visible tension.
Expired countdowns fire an audit entry and free their name slot. A new countdown with the same name creates a fresh timer — not a reactivation.
Source: spec §5.6 (REQ-073), §5.8 (REQ-125), README.md §2 (Narrative Management).
Standing instructions that shape every GM response:
"The ossuary is sacred ground. Desecration will have consequences." "Sister Mora knows more than she's saying. She's watching the party."
Directives are stacked arrays — each has a label and instruction. Duplicate labels replace the prior entry. They're GM-only; players never see them.
Source: spec §5.8 (REQ-081), README.md §2 (Narrative Management).
"Roll initiative. The goblins ambush from the treeline."
You list participants and dangers — the AI handles the rest. Turn order, condition tracking, HP, automatic danger advancement. Tie-break: entity before NPC before danger, then alphabetical. Combat state survives server restarts. Bleeding stops when the rules say it does. Paralysis expires on schedule. You focus on tactics.
End combat with an outcome — the AI records it and increments the total rounds counter for session metadata.
Source: spec §5.6 (REQ-043), README.md §2 (Combat).
Generate an adventure:
"Generate an adventure: a heist at the wizard's auction."
One sentence becomes a campaign scaffold — scenes, NPCs, hooks. The whole outline in one call. Generated adventures are transient Novel artifacts, distinct from indexed adventure modules.
Generate encounters one at a time:
"Create an encounter: the party enters the flooded crypt."
Each encounter is a single undoable step — scene + NPC + lore entry, all snapshotted together.
Load adventure modules:
"Load the Dragon Tomb adventure."
Adventure modules are Markdown files in the TTRPG_ADVENTURE directory.
They follow the Adventure Module Format — see Adventure Modules
for the reference.
Source: spec §5.6 (REQ-079, REQ-132), README.md §2 (Adventures & Encounters).
You run the show, but you're not forced to stay in one badge:
- Game Master badge — your default. Full access. You narrate, the AI plays the characters.
- Player badge — switch to experience the game from the other side. The AI becomes your GM.
- Observer badge — sit back and watch the AI run the entire table, playing both Player and Game Master while you spectate. Set your autonomy level to control how much the AI acts independently vs. defers to you for mechanical decisions.
The AI's narrative role is the counterpart of the active badge by default. You
can lock it to a fixed role via TTRPG_AI_ROLE.
Source: REQ-304, REQ-305, REQ-306.
Characters only know what they were present for. The engine tracks entity presence per scene and gates knowledge accordingly. A scouting rogue sees things the party doesn't. An NPC absent from a scene doesn't learn what happened there. This makes split-party play mechanically sound — no more "pretending" characters don't know things.
Source: REQ-307, REQ-308.
"Export the entire campaign."
Export your Novel as JSON or Markdown — a single file containing every character, NPC, scene, lore entry, countdown, and combat state. Import with three modes:
- dry-run — validate without changing state
- merge — add entries, skip conflicts
- replace — overwrite everything
Round-trip fidelity is guaranteed — export as Markdown, re-import, get the same state.
Source: spec §5.9 (REQ-096), Appendix Q (Novel Interchange Format).
"Recap the session." "How's the game looking?"
Session recaps summarize recent activity. manage_session (action: health) reports the
spec_health summary — per-Novel metrics: NPC count, lore count, audit log size,
snapshot depth, file size, and a healthy flag.
Source: spec §5.9 (REQ-093, REQ-097).
- Adventure Modules — adventure file format reference
- Novels — lore export and import
- Playing the Game — the player side
Last updated: 2026-10-12.
Holonovel Wiki
Tutorials
For Players
For Game Masters
For Builders
Meta