# 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.