# 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.
# Puzzles
`game.whisper.Puzzles`, the data for every Software Whisper puzzle, read by `game.whisper.Whisper`. Pure data, no UI.
A puzzle names its target illustration (`game.whisper.art.<id>` texture), difficulty, intro/success lines, optional `grants` (commands awakened early) and `allowed` (commands usable), and a list of steps. Each step has a goal, its code lines (field or logic, hidden until READ, with `edit` / `patch` option lists whose `effect` is nil, `"glitch"` or `"crash"`) and `solveWhen`, an OR-list of AND-conditions on line values or READ lines. The format is documented at the top of `init.luau`.
Puzzles: `party_buffs` (prologue, READ only: every buff says `source = REN`), `rusty_sword` (ch1: `curse = true` → `false`), `bridge_golem` (ch2: off-by-one patrol loop, EDIT the bound or PATCH the smash handler), `rigged_duel` (ch3: Dorian's contract; EDIT `winner` and `damage`, or PATCH `contract.enforce`), `final_seraphine` (finale, three live steps: revoke buffs, blunt the Holy Sword, PATCH her Judgement).
# UI
Interface contract, see /zero/source/design/spec.md.
# 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`.
# 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.
# 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`.
# Director
Runs *Kicked Out of the Hero's Party* from `boot()` (called by `scenes/main.scene/entrypoint.luau` in play): title screen → prologue → chapter 1 → guild hub ↔ chapters 2, 3 and the finale (gated by guild rank) → ending → title.
It is a script runner: each chapter is a data module under `game/story/chapters/` (steps from `game.story.Script`), executed one step at a time in a task that parks on the UI / Whisper callbacks. It owns rewards (from `Rules.whisperReward` into `game.State`, with toasts, level-up and rank-up beats), checkpoints (each chapter start, each labelled checkpoint, and before every whisper), System Error retry, and CONTINUE (fast-forwards the chapter's staging up to the saved checkpoint, then plays on).
`Director.status()` reports where the run is (screen, chapter, step, the last line said) for tests; `Director.trace()` the last 200 beats.