# 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.
# 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.
# reader
The public API of vnReader: `setup` a game, then `say`, `choose`, backlog, auto/skip, hide UI, save/load (slots, quick, auto), gallery, settings, system menu, themes and the showcase picker. Runs one input loop that reads keyboard, mouse wheel, gamepad and touch swipes. Called by the game's own UI module (`require("vnReader.reader")`); see the package README for every function and config field.
# Kit
The UI slice's style kit: palette (from `game.Rules.PALETTE`), the chosen fonts (Cinzel Decorative for the logo, Cinzel for display type, PT Serif for prose, JetBrains Mono for code), gold-filigree SVG ornaments (corners, dividers, diamonds, coin, rose, shield, lock, icons) and small node builders (label, box, svg, image, entrance/idle animations, gold-framed buttons) that every screen in `game.ui.UI` is assembled from.
# store
Per-player persistence for vnReader: get/set under the local player's own `runtime_data.player` data (saves, settings, read lines), falling back to memory when no player identity exists (edit mode, headless tests).
# game.stage.Cast
Data registry read by the stage (vnStage) and the story. See init.luau.
# 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.
# 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.
# vnStage.stage
The public API of vnStage: `configure{cast=, places=}` once, then `place`, `show`/`hide`/`expression`/`pose`/`react`/`focus`/`emphasis`, `mood`, `weather`, `transition`, camera beats (`shake`, `pushIn`, `pan`, `resetCamera`, `flash`, `impact`), `trance`, `fx`, `prop`/`screenProp`, `snapshot`/`restore`, `state`, `lists`. Called by a game's story code; routes every call to the `vnStageRig` component on the scene's stage root, in play.
# 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.
# game.stage.Places
Data registry read by the stage (vnStage) and the story. See init.luau.
# vnReader: the reading layer for any visual novel
Everything a player touches while reading a visual novel, as one installable package: the **dialogue box** (name plate, narrator style, typewriter, click-to-continue indicator), **choice cards**, the **backlog** (with voice replay and optional jump-back), **auto** (waits for the voice clip), **skip** (read text only by default), **hide UI**, **save/load slots** with a stage picture, chapter title, play time and date in **four layouts**, **quick save / quick load**, an **autosave** slot, a **gallery**, a **settings** screen, a **system menu**, **nine themes** and **mouse, keyboard, gamepad and touch** input on portrait and landscape screens.
It knows nothing about any one game: the game passes its cast (names, colours), its gallery, and callbacks for its own state, stage snapshot and loading. Every screen is local to the player whose machine draws it and every save, setting and read-line record is kept in **that player's own data** (`runtime_data.player`), so in a multiplayer world nobody's screen or progress touches anyone else's.
Pairs with **vnStage** (staging: cast, backgrounds, moods, transitions, `snapshot()`/`restore()`); the save screen draws a vnStage snapshot as layered pictures.
## Quick start
```lua
local Reader = require("vnReader.reader")
Reader.setup({
id = "mygame", -- storage namespace (per player)
theme = "animeGlass", -- any of Reader.themes()
cast = { mira = { name = "Mira", color = "#f2c46b" }, ren = { name = "Ren", color = "#3ff0e8" } },
snapshot = function() return require("vnStage.stage").snapshot() end,
castTexture = function(id, pose, expr) return "mygame.sprites." .. id .. "_" .. expr end,
placeTexture = function(place) return "mygame.backgrounds." .. place end,
saveData = function() return { chapter = currentChapter, step = currentStep } end,
chapterTitle = function() return "Chapter 1, The Guild" end,
onLoad = function(game, slot) resumeStory(game) end, -- you resume your own story
onTitle = function() showMyTitle() end,
})
Reader.say("narrator", "The lanterns flicker.", function()
Reader.say("mira", "Welcome to the guild!", function()
Reader.choose("Take the job?", {
{ id = "yes", text = "Sign the contract" },
{ id = "no", text = "Walk away", locked = false },
}, function(id) print("picked", id) end)
end, "ch1.002")
end, "ch1.001")
```
## API (`vnReader.reader`)
| Call | What it does |
|---|---|
| `setup(config)` | Configure for a game (fields below). Loads the player's settings and read-lines. |
| `say(speaker, text, onDone, lineId?)` | One line. `lineId` (stable, e.g. `"ch1.004"`) drives read/unread skip, voice and backlog replay. `opts` may also be `{ lineId, voice = false }`. |
| `choose(prompt, options, onPick)` | Choice cards; `options = {{ id, text, locked? }}`. Skip and auto stop here. |
| `hideDialogue()`, `hideChoice()`, `advance()` | Take the box down / the cards down / advance as a click would. |
| `setAuto(on)`, `setSkip(on)`, `setHidden(on)` | Auto mode, skip mode, hide-UI. |
| `openLog()`, `openSaves("save"\|"load")`, `openSettings(tab?)`, `openGallery()`, `openMenu()`, `confirm(text, onYes, onNo?)`, `back()`, `closeAll()` | The overlay screens (a stack; Esc / B goes back). |
| `save(slot)`, `load(slot)`, `slot(slot)`, `deleteSlot(slot)`, `hasSaves()`, `quickSave()`, `quickLoad()`, `capture()` | Slots are numbers `1..pages*perPage`, plus `"quick"` and `"auto"`. |
| `beginSession(seconds?)`, `endSession()`, `playTime()` | Play-time clock shown on slots. |
| `set(key, value)`, `settings()` | Settings (persisted per player). |
| `setTheme(name)`, `themes()`, `registerTheme(name, tokens)` | Themes. |
| `setSaveLayout("grid"\|"list"\|"book"\|"carousel")` | Save-screen layout. |
| `pictureOf(snapshot)` | Stage snapshot → `{ background, layers = {{ src, x, h, aspect, flip }} }`. |
| `showcasePicker(opts?)`, `hidePicker()`, `demo(kind)` | A floating picker that flips every theme and save layout live, with buttons that show a sample line, choice, saves, load, log, settings, menu and gallery. |
| `debugState()` | `{ dialogue, auto, skip, hidden, choice, stack, logLines, theme, saveLayout, playTime }` for tests. |
### `setup` config
`id` (storage namespace), `theme`, `themes` (extra themes by name), `cast` (table or `fn(id)` → `{ name, color, heightScale? }`), `narrators` (speaker ids drawn as narration), `gallery` (list or fn → `{{ id, name, src, unlocked = bool|fn }}`), `pages` (6), `perPage` (6), `snapshot` (fn → stage snapshot), `picture` (fn(snapshot) → picture, overrides the default reader), `castTexture(id, pose, expr)`, `placeTexture(placeId)`, `slots` (slot name → 0..1 across the frame), `spriteAspect` (0.5), `saveData` (fn → your game's state for the slot), `chapterTitle` (fn), `onLoad(game, slotData)`, `onTitle` (adds *Title Screen* to the menu), `canSave` (fn), `blocking` (fn: true while your own screen owns input), `voice = { play(lineId, speaker, text) → seconds|true|nil, stop() }`, `volumes = { set(bus, v) }` (buses `master music sfx voice`), `sfx(kind, vol)` (kinds `blip advance click hover open back save load`), `toast(kind, text)`, `menuItems` (`{{ id, text, icon, onPick }}`), `jump(lineId)` (enables the backlog's jump button), `defaults` (setting defaults), `layers`, `maxBoxWidth`, `fontSize(portrait)`, `previewSpeaker`, `menuTitle`, `wheelAdvances` (true), `centerNarration`.
## Themes
`animeGlass` (frosted glass, pastel light), `fantasy` (dark oak and gilt, wax-red ribbon), `parchment` (paper and ink), `scifi` (holographic cyan, scan line), `pixel` (8-bit RPG window), `minimal` (editorial gradient band, one red accent), `manga` (ink balloon, slab plates), `cozy` (peach and sage, hearts). A game adds its own with `registerTheme(name, tokens)`, tokens it leaves out come from `base`; `buildPlate`, `boxDecor` and `panelDecor` hooks add ornaments. Tokens are listed at the top of each entry in `themes.module`.
## Save layouts
`grid` (3×2 cards; 2×3 on portrait), `list` (rows with a wide thumbnail and the last line), `book` (an open book: the focused slot's picture on the left page, the page's slots listed on the right), `carousel` (one big card with neighbours peeking, dots, arrows / shoulder buttons). Six pages of six slots plus a **Q** page with the quick and auto slots. Overwrite and delete always ask first.
## Input
| | Keyboard / mouse | Gamepad | Touch |
|---|---|---|---|
| Advance | Enter, Space, click, wheel ↓ | A | tap |
| Auto | A | X | Auto button |
| Skip | hold Ctrl; S toggles | hold R2 | Skip button |
| Backlog | L, ↑, wheel ↑ | Y, LB | swipe up (down closes) |
| Hide UI | H, Delete | Select, RB | Hide button |
| Quick save / load | F5 / F9 | menu | menu |
| Menu / back | Esc | Start / B | Menu button |
| Choices | 1–9, ↑↓ + Enter | d-pad + A | tap |
| Pages / tabs | Q / E | LB / RB | tabs |
On touch surfaces and phone-sized screens the quick bar becomes 48 px icon buttons above the box and every menu button grows to 48 px. Layout follows `ui.screenSize()` and `ui.safeArea()` and re-lays out on rotation.
## What's inside
- `reader.module`, the API above, dialogue, choices, input loop, saves.
- `screens.module`, backlog, save/load layouts, gallery, settings, menu, confirm.
- `themes.module`, the nine themes and their tokens.
- `kit.module`, themed node builders, icons, the layered save picture.
- `store.module`, per-player persistence.
- Guides: `vn-reader-text-box-backlog-saves.guide` (how to use it) and `make-a-visual-novel-chapter.guide` (worked example with vnStage).
- `build-visual-novel-chapter.workflow`, the stages of building a chapter, as a runnable workflow.
## Known limits
- Voice length comes from the game's `voice.play` return value; return the clip length for auto to wait exactly.
- The backlog keeps the last 300 lines of the session (not saved with slots).
# vnStage: visual-novel staging for any VN world
vnStage turns a camera and an empty `Stage` entity into a premium anime visual-novel stage: painted backgrounds that read with depth, character sprites from **your own cast registry** with poses and expressions, and a wide vocabulary of staging, every look switchable by one word. Everything it spawns is a local, unsynced child of the stage root, so in a multiplayer world every visitor plays their own story.
Version **1.0.1**. Depends on **screenWipes** (five of the transitions); uses **impactFrames** for `impact()` when the world has it.
## Install and start
1. Install vnStage (search ZeroMind for "visual novel stage"); screenWipes comes along.
2. Give your scene a camera named `StageCamera` and an empty root entity named `Stage` (a playerless scene).
3. In play (your story module or the scene's entrypoint):
```luau
local V = require("vnStage.stage")
V.configure({ cast = require("my.Cast"), places = require("my.Places") })
V.place("school_roof", { transition = "crossfade" })
V.show("hero", "left", "smile", { enter = "drop", pose = "b" })
V.focus("hero"); V.react("hero", "hop")
V.mood("golden"); V.weather("petals")
```
Registry shapes, **cast**: `list[castId] = { name, color "#rrggbb", heightScale, defaultPose, poses = { [pose] = { [expr] = textureIdentity } } }`, optionally `material(cast, pose, expr) -> materialIdentity` for authored materials; **places**: `list[placeId] = { texture, material?, mood?, weather?, name? }`. Either the module (with `.list`) or the bare list works. Green-key art (`#00FF00`) is keyed by default; `sprite = { chromaKey = false }` for alpha PNGs.
## API (`vnStage.stage`)
| call | does |
|---|---|
| `configure{ cast, places, slots?, slotDepth?, root?, camera?, background?, backgroundZ?, sprite?, defaults?, castStyle?, placeStyle?, moodAlias?, weatherAlias?, fx? }` | set up (once, at load) |
| `place(id, { transition?, dur?, mood?, weather? })` / `setBackground` | show a place with its default mood + weather |
| `show(cast, slot, expr?, { enter?, flip?, pose?, dur? })` | enter, or move / re-express / re-pose in place |
| `hide(cast, { exit?, dur? })`, `hideAll({ exit? })` | leave |
| `expression(cast, expr)`, `pose(cast, pose, expr?)` | crossfade in place (missing art → the pose's neutral) |
| `react(cast, kind)` | a little reaction |
| `focus(cast?)`, `emphasis(mode)` | speaker and how it stands out |
| `mood(id, instant?)`, `weather(id, instant?)` | light / time of day; atmosphere (`"rain+fog"` combines) |
| `transition(style, dur?, midFn?)` | a scene transition; midFn runs at full cover |
| `shake`, `pushIn`, `pan(slot or x)`, `resetCamera`, `flash(color)`, `impact(style?, cast?)` | camera beats |
| `trance(on, { hero, expr, x, vortex })` | world drains to indigo, glyph vortex, hero steps forward |
| `fx(name)`, `registerFx`, `registerMood`, `registerWeather` | one-shots and your own presets |
| `prop(id, def?)`, `screenProp(id, def?)` | sprite props in the stage / at a screen rectangle |
| `snapshot()` → `{ place, mood, weather, emphasis, speaker, trance, camera, actors = { { cast, slot, expr, pose, flip } } }`, `restore(snap)` | save-slot pictures and resume |
| `state()`, `lists()`, `isReady()` | inspection and menus |
## The variants
- **Entrances (18)**: fade, slide_left, slide_right, slide, slide_up, drop, pop, zoom, dissolve, blur, walk, spin, flash, glitch, rise, peek, shadow, none.
- **Exits (16)**: fade, slide_left, slide_right, slide, slide_down, jump, shrink, zoom, dissolve, blur, walk, spin, flash, glitch, sink, none.
- **Emphasis (8)**: dim (default), lift, scale, spotlight, rim, bob, silhouette, none.
- **Reactions (12)**: hop, bounce, shake, nod, shiver, lean_in, sway, startle, sigh, puff, flinch, glow.
- **Moods (17)**: neutral, dawn, morning, day, noon, golden, dusk, night, moonlit, torchlit, candle, lanterns, royal, storm (lightning), crimson, sepia (flashback), indigo (whisper). Aliases: sunset, golden_hour, flashback, whisper, evening, candlelight...
- **Weather (19)**: off, dust, crypt_dust, lantern_motes, bokeh, petals, leaves, fireflies, rain, storm, snow, embers, ash, fog, god_rays, sand, code_glyphs, glyphs_faint, sparkles. Aliases: dust_motes, sakura, mist, sparks, glyphs...
- **Transitions (20)**: cut, fade, fade_white, crossfade, wipe_left, wipe_right, iris, blinds, pixelate (screenWipes), slide_left, slide_right (push), ink, shatter, glitch, zoom_blur, diamonds, clock, curtain, brush, heart.
- **Camera**: shake, pushIn, pan, reset, flash, impact.
- **FX**: burst, confetti, glitch, code_rain, rising, sparkle (+ registered).
## Depth
The camera breathes; the background shader slides the painting's lower rows further than its horizon (pseudo-depth parallax); a 2.5D foreground card near the lens frames the stage with soft dark edges, mood-tinted light shafts and haze; weather spans several depths. Characters take the mood's light, rim light and grade.
## Contents
- `stage.module`, the API above. `presets.module`, every list and preset as data.
- `vnStageRig.component`, the runtime (added for you).
- `showcase.module`, on-screen panel flipping through everything (mouse, touch, keyboard, gamepad; `registerTab` for other packages).
- `shaders/`, `vnSprite` (keyed sprite with dissolve, silhouette, glitch, blur, outline glow), `vnBackground`, `vnForeground`, `vnField` (14 particle modes), `vnOverlay` (flash, spotlight, 10 shader transitions), `vnGrade` (post grade). `glyph_atlas.texture` for glyph weather.
- Guide: **Visual novel stage: character expressions, poses, scene transitions and weather effects**.
## Showcase
```luau
require("vnStage.showcase").open({ cast = Cast, places = Places, castOrder = { "hero", "rival" }, start = "school_roof" })
```
Q/E (or PageUp/PageDown, gamepad shoulders) switch tabs, arrows / d-pad pick, Enter / Space / A plays, A / Y toggles auto-play, H / Select hides the panel; tap or click anything.