Codex - flukeatzerocool/holonovel GitHub Wiki

Codex

Reference. For Game Masters. The Codex is a server-level persistent library of reusable game artifacts — NPCs, characters, scenes, encounters, lore, factions, countdowns, rooms, things, equipment, spells, relationships, voice profiles, and adventures. Capture content from any Novel and import it into any other Novel. Entries survive all Novels.

What the Codex is

The Codex lives at .holonovel-state/codex.json — it is a permanent store independent of any single Novel. Capture an NPC you created in one campaign, then import them into the next. Build a library of reusable scenes. Store a faction with its goals, resources, and clock. The Codex is your worldbuilding vault.

Codex entries carry a ruleset annotation — an entry created in a D&D Novel is tagged dnd5e. Ruleset-agnostic entries (rooms, scenes, generic NPCs without mechanical stats) carry no ruleset tag. The server prevents cross-ruleset contamination — importing a D&D spell codex entry into a Mothership Novel returns [STATE_CONFLICT].

Source: spec §5.6 (REQ-321, REQ-347, REQ-387).

Entry kinds

Fourteen kinds of artifact can be stored in the Codex:

Kind	What it stores	Example
`npc`	Named NPCs with stats, disposition, personality, and voice	A recurring innkeeper, a villain
`character`	Player characters, ready to import	A pre-built fighter
`scene`	Scene descriptions with location, time of day, atmosphere	"The haunted chapel at midnight"
`encounter`	Combat and social encounter templates	"Goblin ambush in the ravine"
`lore_entry`	Keyword-triggered lore entries	World history, faction secrets
`faction`	Factions with goals, resources, and clocks	"The Thieves Guild"
`countdown`	Countdown timer templates	"The ritual countdown: 6 ticks"
`room`	World-model rooms with descriptions	"The wizard's tower"
`thing`	World-model objects with properties	"The enchanted mirror"
`equipment`	Gear, weapons, and armor	A +1 longsword
`spell`	Spell entries	Fireball
`relationship`	Relationship links between entities	Ally and rival networks
`voice_profile`	Captured voice corrections	Corrected NPC dialogue
`adventure`	Adventure scaffolds and their content	The Dragon Hoard

Source: spec §5.6 (REQ-321).

Capturing content

Pull any Novel artifact into the Codex:

"Save that NPC to the Codex." "Capture this scene to the Codex." "Store the Thieves Guild faction in the Codex."

manage_codex (action: capture) tags the entry with the source Novel's ruleset. Voice feedback corrections — dialogue lines you've corrected during play — can also be captured back to the Codex, preserving the correction for future Novels.

Source: spec §5.6 (REQ-321, REQ-347).

Importing into a Novel

Materialize a Codex entry into your active Novel:

"Import the Thieves Guild from the Codex." "Bring in the haunted chapel scene."

manage_codex (action: import) creates a Novel copy — the Codex entry is unchanged. Ruleset-tagged entries can only be imported into Novels of the matching ruleset. Ruleset-agnostic entries (no tag) can be imported anywhere.

Source: spec §5.6 (REQ-321, REQ-387).

Managing the Codex

List entries: manage_codex (action: list) with optional kind and tag filters.

"Show me all my Codex NPCs." "List Codex encounters tagged 'horror'."

Inspect an entry: manage_codex (action: get) shows the full detail — every field, stat, and annotation.

"Show me the Codex entry for the Thieves Guild."

Update an entry: manage_codex (action: set) with the same parameters as creation. Overwrites in place.

Delete an entry: manage_codex (action: delete) removes it. Undo restores within the same connection.