Adventure Modules - flukeatzerocool/holonovel GitHub Wiki

Adventure Modules

Reference. For Game Masters and builders. You want to write or load adventure modules as Markdown files.

What adventure modules are

Adventure modules are supplementary Markdown files loaded during the Build workflow. They provide indexed reference content — scenes, NPCs, traps, treasure tables, and hooks — surfaced through manage_ruleset (action: search) and badge_briefing. They are guidance-category only: no mechanical extraction, no tool generation. The server indexes them alongside the ruleset during discovery.

Source: spec Appendix K, REQ-079.

Loading adventures

Place your adventure .md file in the TTRPG_ADVENTURE directory. Then:

"Load the Sunken Temple adventure."

The server indexes the file and makes its content searchable. Adventure content appears in manage_ruleset (action: search) results filtered by active adventure and badge. GM-only sections are invisible to the Player badge.

"Search the rules for the Sunken Temple entrance chamber."

Source: spec Appendix K (Indexing and badge gating).

Format conventions

Adventures follow the same heading, anchor, adjudicator-marker, table, and bold-labeled-field conventions as the ruleset (Appendix A, H).

Element	Convention	Example
Title	`# Adventure Title` — becomes the adventure slug	`# The Sunken Temple`
Overview	`## Overview` — GM-only summary, always marked	`## Overview — Keeper only`
Hook	`## Adventure Hook` — player-visible introduction	`## Adventure Hook`
Structural divisions	`## Region:` / `## Level:`	`## Level 1: The Drowned Gate`
Scenes/rooms	`### Location Name` — player-visible by default	`### Entrance Chamber`
Badge gating	`Keeper only` — hides section from Player badge. Use the ruleset's own adjudicator term when it differs (e.g., `Warden only`, `DM only`)	`### Trapped Hallway — Keeper only`
NPCs and dangers	Bold-labeled fields for stat blocks, tactics	`Murk-Eye — Grit +2, Nerve +1`
Treasure and tables	Tables in standard Markdown	`
NPC roster	`## NPCs` section at end — lists all named NPCs	`### Elder Myra`

Complete example

# The Sunken Temple
_A dungeon adventure for 4–6 delvers of levels 3–5._

## Overview — *Keeper only*
The Sunken Temple lies beneath the Marsh of Whispers. Four levels, each
with a theme and a boss encounter. The delvers seek the Lantern of Lost Souls.

## Adventure Hook
The village elder offers 500 gold for the Lantern. She knows the temple's
entrance is at the base of the Weeping Willow, three days into the marsh.

## Level 1: The Drowned Gate

### Entrance Chamber
The stone door is ajar, held open by a rusted crowbar. Water drips, pooling
ankle-deep. Three corridors: north (carved steps descending), east (a dry
passage, torch soot on the walls), south (the sound of running water).

### Trapped Hallway — *Keeper only*
The east passage. Third flagstone depresses: DC 12 Steady to notice; DC 15
Delve to disarm. Failure: scythe blade — 2d6 slashing, +1 Harm on failed Notice.

#### Treasure — *Keeper only*
| d6  | Item                         |
| --- | ---------------------------- |
| 1–3 | 50 gold pieces               |
| 4–5 | Potion of Grit (+1 Grit, 1 scene) |
| 6   | Rusty Blade (1d6 slashing)   |

### The Guardian — *Keeper only*
**Murk-Eye** — Grit +2, Nerve +1, Wits 0, Harm 2/4.
Weapon: Rusty Blade (1d6 slashing).
Tactic: ambush from water; fight to half Harm, then flee.

## NPCs

### Elder Myra
The village elder. She knows the marsh but won't enter — her son was lost
there years ago. She carries a Whisper Stone and will give it to the
delvers if they promise to search for signs of her son.

Source: spec Appendix K (format example).

Generated vs. loaded adventures

Holonovel distinguishes two kinds of adventure content:

Indexed adventure modules — Markdown files loaded during Build. Indexed alongside the ruleset. Searchable. Survive rebuilds unchanged.
Generated adventures — created at runtime via manage_adventure (action: generate). Transient Novel artifacts. Separate from indexed modules. A Novel may hold both simultaneously.

badge_briefing surfaces indexed content first; manage_ruleset (action: search) tags generated results.

Source: REQ-079, REQ-132.

Writing your own

Create a .md file with the conventions above.
Start with # Title — this becomes the slug used by manage_adventure (action: load).
Mark every GM-only section with *Keeper only* (or your ruleset's term).
Use standard Markdown tables for treasure, encounters, and random events.
Use bold-labeled fields for NPC stat blocks.
Place the file in your TTRPG_ADVENTURE directory.
Rebuild the server (or run the Update workflow if configured) to index it.