# Rules
The constants and rules of *Kicked Out of the Hero's Party*: art-direction sentence, palette, stage camera and slot layout, cast, Whisper commands and their unlock levels, XP curve, mana formula, guild ranks F..S, whisper reward formula, guild shop, chapter list, and the shape of a fresh save. Pure data and pure functions; every slice reads it, only the plan owner edits it.
# UI
Interface contract, see /zero/source/design/spec.md.
# ch1
Scene script for Chapter 1, *The Cursed Rusty Sword*: Mira registers Ren at Guild Rank F, the `rusty_sword` whisper, an optional potion-audit side job, then the first interlude where the old party loses to a slime without Ren's buffs. A list of `game.story.Script` steps run by `game.story.Director`.
# Whisper
`game.whisper.Whisper`, the Software Whisper minigame of *Kicked Out of the Hero's Party*.
The target floats in a holographic scan window in the centre (drawn by the stage for the five story targets, by this screen for every other puzzle) and splits into floating cyan code panels; the right-hand command codex (gold-filigree indigo glass) holds READ / EDIT / PATCH, the segmented Mana meter with its spend preview, the Whisper Lv badge and gold. A goal banner with a progress chip runs across the top and a whisper log along the bottom. Puzzle content is data in `game.whisper.Puzzles`.
## API (contract in design/spec.md)
- `start(puzzleId, onResult)`, opens the whisper; calls `Stage.whisperMode(true)`, `Stage.fx("code_rain")`, `Audio.sfx("whisper_on")`. `onResult(Result)` fires after the end card (2.4 s success, 3.0 s crash, 1.8 s out of Mana). A `start` that supersedes a running whisper delivers `{ success = false, reason = "aborted" }` to the old callback.
- `isActive()`, `abort()` (closes silently, no callback).
- `Result = { success, reason? ("mana" | "crash" | "aborted"), manaLeft, manaMax, difficulty }`. Never grants rewards.
- Extras for tools/tests: `lastResult()`, `snapshot()` (`puzzle step steps mana manaMax tool pending values read ended focus navShow hover mode preview broke compiled`), `puzzles()`.
## Reading it at a glance
- The GOAL is the largest text on screen, with a `done / total` chip for the furthest-along solve condition (and `STEP n / m` on multi-step puzzles).
- Lines the solve conditions name keep full cyan; flavour lines are dimmed. Hidden key lines carry an `ENCRYPTED` tag.
- After READ, a faulty line turns red with a `SUSPICIOUS` tag and its note; the Debugger's Lens marks faults with a gold "!" from the start.
- Mana cost is previewed on hover / focus of a command and while a write is pending: the segments it would spend glow gold and `EDIT −2 → 15 left` reads under the meter.
- A pending EDIT / PATCH previews its effect before it is confirmed: the line shows `old → new` (old struck through) and the options strip reads `Write curse = false · −2 Mana → 15 left`.
## Feedback
- **Success (compile):** every code panel snaps green with a `COMPILED` tag and a staggered pop, the target transforms (`art/<id>_after.texture` fades in over it), a `COMPILED · 0 errors` card drops in, stage flash + shake, an impactFrames rays burst (local) and a juiceKit `flashLevelUp` (local), `code_patch` + `level_up` sfx.
- **Glitch:** the line flickers red and shakes with a `REJECTED` tag; the spent Mana chunk shatters off the meter in red; the log turns red.
- **Crash:** the line takes the fatal value, turns red with a `FATAL` tag and its error, then the SYSTEM ERROR card shows `RUNTIME ERROR · line N`, the broken code (`✖ curse = nil`) and the readable error before `onResult` hands over to the System Error screen.
## Input
| | Mouse | Keyboard | Gamepad | Touch |
|---|---|---|---|---|
| move focus | hover | arrows, Tab / Shift+Tab | d-pad, left stick |, |
| confirm | click | Enter, Space | A (south) | tap |
| back / cancel | Cancel chip | Esc, Backspace | B (east) | Cancel chip |
| READ / EDIT / PATCH | click card | R / E / P | X / Y / RB (LB cycles) | tap card |
| pick option | click (hover previews) | 1–9, or focus + Enter | focus + A | first tap previews, second writes |
Focus walks the code lines and the command rail (left/right switches between them on landscape; on portrait the rail is below the lines, so down from the last line enters it). A pending write makes the options strip modal. The focus ring only appears once a key or pad is used, and a real mouse move hands control back to the pointer. The reader's own input is blocked while a whisper is active (`UI` `blocking`).
## Layouts
- **wide** (landscape ≥ 900 × 640 pt): art centre, panels left/right, codex rail right.
- **compact** (very wide, short screens): lines in a column, a narrow command rail on the right.
- **portrait** (W < H): one column on a ~430 pt design width scaled up to the canvas (text stays readable, targets ≥ 48 pt), small target painting, lines, options, log, Mana, and the **command rail along the bottom**. Resizes / rotations re-lay out live.
## Art
`art/<id>.texture`, target illustrations (dark indigo `#0b0d26` backdrop); `art/<id>_key.texture`, the stage's keyed versions; `art/<id>_after.texture`, the transformed target shown at the compile moment. Side-quest targets: `bakery_oven guild_ledger gorvin_hammer archive_seal garden_fountain` (+ `_after`). `codex_corner`, `codex_sigil`, the codex frame.
UI: screen `whisper_mode` at layer 90, callbacks prefixed `wsp:` through `ui.registerCallbackEnv("whisper", …)`; element ids `wsp_cmd_<READ|EDIT|PATCH>`, `wsp_line_<lineId>`, `wsp_opt_<n>`, `wsp_cancel`, `wsp_mana`, `wsp_mana_preview`, `wsp_opt_preview`, `wsp_progress`, `wsp_end_title`, `wsp_end_line`, `wsp_rail`.
# Stage
Interface contract, see /zero/source/design/spec.md.
# sq_fountain
Side quest scene script for *Kicked Out of the Hero's Party*: **The Fountain That Spits Coins**, the palace wishing fountain with a minimum spend, with Mira (whisper `garden_fountain`). Sets `sq_fountain` (the King mentions it) and `mira_wish`. Listed in `game.story.SideQuests`, offered on the guild hub board and run by `game.story.Director` like a chapter (pays its board reward once on `complete`), then back to the hub.
# sq_archive
Side quest scene script for *Kicked Out of the Hero's Party*: **The Sealed Ledger of Radiant Dawn**, Seraphine's sealed record in the guild archive (whisper `archive_seal`). Sets `sq_archive` = `filed` | `kept`: the receipt for her jailbroken sword, used in the finale. Listed in `game.story.SideQuests`, offered on the guild hub board and run by `game.story.Director` like a chapter (pays its board reward once on `complete`), then back to the hub.
# sq_oven
Side quest scene script for *Kicked Out of the Hero's Party*: **The Oven That Only Burns**, market baker Hilde's oven set to 900 (whisper `bakery_oven`). Sets `sq_oven_bread` (bread for Mira; read in ch3). Listed in `game.story.SideQuests`, offered on the guild hub board and run by `game.story.Director` like a chapter (pays its board reward once on `complete`), then back to the hub.
# sq_ledger
Side quest scene script for *Kicked Out of the Hero's Party*: **Mira's Impossible Ledger**, the guild at midnight, pennies rounded into the old guildmaster's pocket (whisper `guild_ledger`). The quiet Mira scene; sets `sq_ledger_secret` (read in the Rewritten Party ending). Listed in `game.story.SideQuests`, offered on the guild hub board and run by `game.story.Director` like a chapter (pays its board reward once on `complete`), then back to the hub.
# ch2
Scene script for Chapter 2, *The Bridge Golem's Bug*: Ren and Mira at Millbrook Crossing, the `bridge_golem` whisper (an off-by-one patrol that smashes the bridge), an optional golem-ferry bonus, then the interlude where the old party finds itself downgraded and sees Ren rising on the rank board. Steps from `game.story.Script`, run by `game.story.Director`.
# game.stage.Cast
Data registry read by the stage (vnStage) and the story. See init.luau.
# ch3
Scene script for Chapter 3, *A Rigged Duel*: Dorian challenges Ren in the arena under a contract spell rigged `winner = challenger`; the `rigged_duel` whisper makes it fair; a mercy-or-stakes choice; then the interlude where the broke party plans the King's Hall confrontation. Steps from `game.story.Script`, run by `game.story.Director`.
# prologue
Scene script for the Prologue, *Five Million and One Exile*: the dungeon exit right after the dragon falls, the 5,000,000 G bounty, Seraphine, Gorvin and Dorian kicking Ren out, the READ tutorial (`party_buffs`: every buff reads `source = REN`), Ren leaving. A list of `game.story.Script` steps run by `game.story.Director`.
# Audio
The sound of *Kicked Out of the Hero's Party*: crossfaded music cues, looping ambience beds, one-shot sfx that duck the music, voiced story lines, and the SETTINGS volumes. Contract in `design/spec.md`. Everything is local to the peer and a no-op outside play; the voices spawn under a runtime `AudioRig` entity.
## Music: `Audio.music(cue?, fade?)`
Three decks, equal-power crossfade (default 1.5 s); each track loops by crossfading into itself 5 s before its measured end.
| cue | mood |
|---|---|
| `title` | sweeping bittersweet main theme |
| `dungeon` | dark dragon-crypt drones |
| `tension` | confrontation / humiliation underscore |
| `guild` | cozy lute-and-fiddle guild/tavern theme |
| `whisper` | ethereal harp + glassy synth (Software Whisper) |
| `battle` | boss battle |
| `triumph` | victory fanfare |
| `ending` | emotional ending |
| `gentle` | slice-of-life: acoustic guitar, warm piano, light flute (everyday calm) |
| `sad` | slow solo piano + cello, lonely but not hopeless |
| `mystery` | muted harp, celesta, pizzicato, investigation / suspicion |
| `night` | soft e-piano and nylon guitar, moonlit and reflective |
## Ambience: `Audio.ambience(id?)`
Three decks, 2 s crossfade, 4 s self-crossfade loop. `nil` stops.
| id | bed |
|---|---|
| `dungeon` | stone hall: torches, echoing drips, wind through the exit arch |
| `crypt` | sealed crypt, close and dry: dust and grit trickling, single drips, a cold draft |
| `guild` | busy guild hall: crowd murmur, mugs, hearth, counter bell |
| `guild_night` | guild after hours: hissing lanterns, a few hushed tables, quiet hearth |
| `forest` | river forest by the Riverford bridge |
| `arena` | duel arena crowd |
| `city` | capital at dusk: bells, wind, distant crowd |
| `throne` | vast throne hall |
| `night` | summer night: cricket chorus, frogs, far owl, firefly shimmer |
| `market` | midday market: merchants calling, coins, carts, awnings |
| `tavern` | rowdy tavern: laughter, tankards, fireplace (no music) |
| `archive` | hushed archive: candle flutter, page turns, quill, creaking shelves |
| `rain` | steady rain on cobbles and roofs, gutters, one far thunder |
| `garden` | morning palace garden: songbirds, fountain, bees |
Aliases: `fireflies`/`crickets` → `night`, `lanterns` → `guild_night`, `library` → `archive`, `birds` → `garden`, `bustle` → `market`, `inn` → `tavern`, `storm` → `rain`, `drips` → `crypt`.
## Sfx: `Audio.sfx(id, volume?)`
`blip advance click hover whisper_on whisper_off code_read code_edit code_patch glitch error coins level_up rank_up slam laugh door sword chapter`. Per-id level, rate limit and pitch jitter; whisper/reward/drama sfx duck the music (attack 80 ms, release 0.7 s).
## Voice
- `Audio.voice(id)` → boolean: the cue-sheet voices and per-character reaction barks in `Audio.VOICE` (`seraphine_useless`, `bark_<cast>`).
- `Audio.voiceLine(lineId)` → boolean: the voice of a story line, when one exists (see the convention below). Stops any line still speaking, ducks music to 0.3 while it plays, and mutes the typing blips.
- `Audio.voicePlaying()` → boolean, `Audio.voiceRemaining()` → seconds left (0 when silent): auto mode waits on these.
- `Audio.stopVoice()` cuts the speaking line (advance / skip). `Audio.hasVoiceLine(lineId)` → boolean.
### Dropping in a voice actor's files
Every `say` / narration step has a stable line id `<chapter>.<nnn>` (for example `ch1.004`, `prologue.012`; the story writes them in `game/story`). Its voice is the soundClip named after the id with every `.` (and `-`, `/`, space) replaced by `_`, inside `game/audio/voice/`:
```
game/audio/voice/ch1_004.mp3 → imported as game/audio/voice/ch1_004.soundClip → plays on line "ch1.004"
game/audio/voice/prologue_012.wav → game/audio/voice/prologue_012.soundClip → "prologue.012"
```
Drop the audio files (mp3/wav/ogg) into `game/audio/voice/`; the importer makes the soundClips. No code change: the folder is listed by `asset.list` with literal selectors and re-listed (at most every 4 s) when a line has no voice yet, so files added while the game runs speak on their next line. Record dry, mono or stereo, peaking around −3 dBFS; lines play at a fixed gain on the `voice` bus. A line with no file simply plays nothing.
## Settings
`Audio.setMasterVolume(v)`, `setMusicVolume(v)`, `setSfxVolume(v)`, `setVoiceVolume(v)`, `setVolume(bus, v)` with `bus` = `master | music | sfx | voice` (0..1), `getVolumes()` → `{ master, music, sfx, voice }`. They drive the engine mixer channels (`music`, `sfx`, `ambience` follows sfx, `voice`), saved per player in runtime_data `kohp/audio`.
`Audio.stopAll(fade?)`, `Audio.debugState()` (decks, gains, duck, settings) for tests.
Clips live beside it in `music/`, `ambience/`, `sfx/` and `voice/` (all generated with audio_gen; `sfx/blip_tick` is the single tick cut from `sfx/blip`). The original cues' levels were set from measured RMS; the 2026-11 additions (`gentle sad mystery night`, the eight new beds) are set by ear against them.
# ending
Scene script for the Epilogue, *Not Your Buff Anymore*: Ren at Rank S, the old party begs him back, he declines (callbacks to prologue choices), then the ending/credits screen. Steps from `game.story.Script`, run by `game.story.Director`.
# finale
Scene script for the Finale, *Root Access*: the Dragon Bounty hearing in the King's Hall turns into trial by combat with the old party; Ren rewrites the fight live (`final_seraphine` whisper) and the bounty is awarded to him. Steps from `game.story.Script`, run by `game.story.Director`.
# SideQuests
The optional Guild side quests of *Kicked Out of the Hero's Party*, offered on the hub board between chapters. `SideQuests.list` is the data (id, title, giver, place, blurb, required rank, chapter it unlocks after, whisper puzzle, reward); `SideQuests.board()` answers the board the hub UI draws, `{ id, title, giver, place, blurb, rank, after, reward = {xp, gold, renown}, done, locked, lockReason }` per quest; `SideQuests.available()` the ones takeable now.
Each quest is a scene script under `game/story/sidequests/` run by `game.story.Director` (hub pick `kind = "side"`), with its own whisper puzzle in `game.whisper.Puzzles`; its reward is paid once on completion and its flags (`sq_*`) are read by later chapters and the endings.
# Routes
The route meters and the ending rule of *Kicked Out of the Hero's Party*. Two meters live in `game.State` flags: **mercy** (`aff_mercy`, + forgiving the old party, − punishing it) and **mira** (`aff_mira`, trust with Mira). Story choices nudge them through `affect = { mercy = n, mira = n }` on a choice option or the `Script.affect` step; the Director calls `Routes.affect`.
`Routes.decide()` picks the ending: **rewrite** ("Rewritten Party", Ren forgives and builds a new party with Mira) when mercy ≥ `MERCY_FOR_REWRITE` and mira ≥ `MIRA_FOR_REWRITE`, else **legend** (Ren declines the party). `Routes.unlock(id)` / `Routes.unlocked()` keep which endings each player has reached in their own runtime_data (`kohp/endings`), surviving NEW GAME.
# State
Live progression for *Kicked Out of the Hero's Party*: Whisper level and XP, gold, renown (guild rank), shop upgrades, story flags, current chapter and checkpoint. Mutate only through its functions (`addXp`, `addGold`, `addRenown`, `setFlag`, `setCheckpoint`, `completeChapter`, `buy`); subscribe with `onChange(fn(key, data))`, keys `xp levelUp gold renown rankUp flag checkpoint chapter shop saved loaded reset`. Saved per player in `runtime_data` at `kohp/save`.
# sq_hammer
Side quest scene script for *Kicked Out of the Hero's Party*: **A Hammer Too Heavy**, Gorvin, anonymously, in the tavern; his hammer counts his armour twice since Iron Hide expired (whisper `gorvin_hammer`). Sets `sq_hammer` and `gorvin_knows`; Gorvin refuses to fight in the finale. Listed in `game.story.SideQuests`, offered on the guild hub board and run by `game.story.Director` like a chapter (pays its board reward once on `complete`), then back to the hub.