Badges - flukeatzerocool/holonovel GitHub Wiki

Badges

Explanation. For players and Game Masters. You've heard the term "hat" used interchangeably — badges are hats. This page explains what badges are, why they exist, and how they work.

What badges are

A badge is a role the server enforces. Four badges, switched without restart. Badge gating is not a prompt instruction — it is enforced server-side. The response the player sees never leaks what the GM knows.

Badges are a narrative-integrity feature, not a security boundary. set_badge is always callable by design — Holonovel targets solo play where the same person wears both roles.

Source: spec §5.5 (REQ-031, REQ-032, REQ-066), Appendix P.

The four badges

Editor badge

When the Editor badge (the none role) is active, you have full access to every tool. This is where you set up the campaign:

"Start a new Novel called the Dragon Tomb." "Load the Sunken Temple adventure." "Set the scene: the village of Marshfen. Evening. The innkeeper eyes the party with suspicion." "Create an NPC: Elder Myra, the village elder. She knows the marsh."

Build the world, create characters, load adventures, import lorebooks. When everything is ready, activate a badge to begin the story. Your Novel returns to the Editor badge after every manage_novel (action: end) call and when you resume an existing Novel — you're at the table with the mat, the minis, and the rulebook open, deciding what comes next.

Player badge

"Put on my Player badge. Let's play."

Wearing the Player badge means you are in the story. The AI's narrative role becomes Game Master by default. Your tool surface narrows to player tools — character sheets, dice rolls, rules lookups, action suggestions, player signals, and shared lore. GM-only content vanishes. The enforcement is server-side — even error messages are badge-filtered so GM-only spell names don't appear in "Did you mean?" hints.

Game Master badge

"Put on the Game Master badge. I need to fix something."

Full access to every tool. You narrate, build the world, control NPCs, set scenes, trigger lore, manage combat. The AI's narrative role becomes Player by default — it inhabits the characters rather than running the table. Switch to GM whenever you need to correct state, inject a complication, or look behind the screen.

Observer badge

"Observer mode. Let the AI run the table."

The AI plays both Player and Game Master while you watch. You have read-only access to the Novel. The engine proposes actions, the AI narrates outcomes, and you step in for mechanical decisions at your chosen autonomy level. The observer sees combined surfaces: scene state and type from both perspectives, entity presence and personality from the Player surface, narrative threads from both, and an omniscient orientation directive telling the AI to narrate from above.

Source: spec §5.5 (REQ-305, REQ-306, REQ-366).

AI role

The AI's narrative role is the counterpart of your active badge by default:

Your badge	AI role
Player	Game Master — narrates the world, runs NPCs, adjudicates rules
Game Master	Player — inhabits characters, describes intent, defers to you for outcomes
Observer	Both — plays Player and Game Master simultaneously

You can lock the AI to a fixed role via the TTRPG_AI_ROLE environment variable. With TTRPG_AI_ROLE=game_master, the AI always narrates as GM regardless of your badge. With TTRPG_AI_ROLE=player, the AI always plays characters.

Source: spec §5.5 (REQ-304).

Autonomy

Configurable AI decision delegation via four sliders, set through natural language:

"Set autonomy to full. Let the AI handle everything." "Autonomy: mechanical decisions only. I'll handle the roleplay." "Safety: hardcore. I want real stakes." "Creativity: chaotic. Surprise me."

Slider	Values	What it controls
`level`	`full` / `mechanical_prompt` / `manual`	How much the AI auto-plays vs. defers to you
`confirmation`	`auto` / `confirm` / `prompt`	Whether the AI asks before making changes
`safety`	`safe` / `moderate` / `hardcore`	Content boundaries for AI narration
`creativity`	`predictable` / `standard` / `chaotic`	How much the AI introduces unexpected elements

Autonomy is Novel-scoped, GM-only, and persisted to disk. The mechanical_prompt setting pauses only for TTRPG mechanics — world-model and narrative actions are never paused.

Source: spec §5.5 (REQ-305, REQ-306).

Knowledge gating

Characters only know what they were present for. The engine tracks entity presence per scene.

If your rogue scouts ahead alone, the rest of the party doesn't learn what they discovered. The engine gates knowledge by who was present. An NPC absent from a scene doesn't learn what happened there. Split-party play is mechanically sound — no pretending characters don't know things.

The register signal separates in-character communication from out-of-character discussion. In meta register, tool output is bare mechanical information with no narrative framing.

Source: spec §1 (REQ-307, REQ-308).