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`…
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.
Interface
What this asset declares: the schema it conforms to, what it exposes, and the rendered structured payload.
conforms to
zero/source-extract/v2vnStage.stage, the public API of vnStage: staging for any visual novel. local V = require("vnStage.stage") V.configure({ cast = MyCast, places = MyPlaces }) -- once, at load V.place("forest", { transition = "crossfade" }) V.show("hero", "left", "smile", { enter = "drop", pose = "b" }) V.react("hero", "hop"); V.mood("golden"); V.weather("petals") Every call routes to one vnStage.vnStageRig component on the scene's stage root entity (added on first use, in play), so the stage holds a single state whichever Luau environment calls it. Calls in edit mode are no-ops. Everything is local to each player (unsynced entities).
listOf(reg: any) → any
| arg | type | description |
|---|---|---|
| reg | any |
configure(c: { [string]: any }) → void
Configure the stage with your cast and places registries (call at load).
| arg | type | description |
|---|---|---|
| c | { [string]: any } |
resolver(id: string, kind: string) → void
Registry names stay identity strings (the renderer and Model take them); asset.exists checks the art is there without pinning a dependency.
| arg | type | description |
|---|---|---|
| id | string | |
| kind | string |
rig( ) → any
call(method: string, ...: any) → any
| arg | type | description |
|---|---|---|
| method | string | |
| ... | any |
place(id: string, opts: { [string]: any }?) → void
Show a place (background). opts.transition (see presets.TRANSITIONS), opts.dur, opts.mood / opts.weather override the place's defaults.
| arg | type | description |
|---|---|---|
| id | string | |
| opts | { [string]: any }? |
setBackground(id: string, opts: { [string]: any }?) → void
| arg | type | description |
|---|---|---|
| id | string | |
| opts | { [string]: any }? |
mood(id: string, instant: boolean?) → void
Lighting mood / time of day (presets.MOOD_ORDER). Blends over ~1 s; instant = true snaps.
| arg | type | description |
|---|---|---|
| id | string | |
| instant | boolean? |
weather(id: string, instant: boolean?) → void
Weather / atmosphere (presets.WEATHER_ORDER); combine with "+", e.g. "rain+fog". "off" clears.
| arg | type | description |
|---|---|---|
| id | string | |
| instant | boolean? |
transition(style: string?, dur: number?, midFn: (() → void
Play a scene transition; midFn runs when the screen is covered (or at once for crossfade/push).
| arg | type | description |
|---|---|---|
| style | string? | |
| dur | number? | |
| midFn | (( |
show(castId: string, slot: string, expr: string?, opts: { [string]: any }?) → void
Show a cast member in a slot. opts: enter, flip, pose, dur. Already on stage: moves / re-expresses / re-poses in place.
| arg | type | description |
|---|---|---|
| castId | string | |
| slot | string | |
| expr | string? | |
| opts | { [string]: any }? |
hide(castId: string, opts: { [string]: any }?) → void
Remove a cast member. opts.exit (presets.EXITS), opts.dur.
| arg | type | description |
|---|---|---|
| castId | string | |
| opts | { [string]: any }? |
hideAll(opts: { [string]: any }?) → void
| arg | type | description |
|---|---|---|
| opts | { [string]: any }? |
expression(castId: string, expr: string) → void
Change expression in place (crossfades). Missing art falls back to the pose's neutral.
| arg | type | description |
|---|---|---|
| castId | string | |
| expr | string |
pose(castId: string, pose: string, expr: string?) → void
Change pose in place with a crossfade, optionally with a new expression.
| arg | type | description |
|---|---|---|
| castId | string | |
| pose | string | |
| expr | string? |
react(castId: string, kind: string) → void
A little reaction: presets.REACTIONS (hop, bounce, shake, nod, shiver, lean_in, sway, startle, sigh, puff, flinch, glow).
| arg | type | description |
|---|---|---|
| castId | string | |
| kind | string |
focus(castId: string?) → void
The speaker (nil / "narrator" = nobody); emphasis follows the current mode.
| arg | type | description |
|---|---|---|
| castId | string? |
emphasis(mode: string) → void
Speaker emphasis mode: presets.EMPHASIS (dim default, lift, scale, spotlight, rim, bob, silhouette, none).
| arg | type | description |
|---|---|---|
| mode | string |
shake(strength: number?, duration: number?) → void
| arg | type | description |
|---|---|---|
| strength | number? | |
| duration | number? |
pushIn(amount: number?, duration: number?) → void
| arg | type | description |
|---|---|---|
| amount | number? | |
| duration | number? |
pan(target: any, duration: number?) → void
Pan the camera toward a slot name or an x offset; resetCamera() returns.
| arg | type | description |
|---|---|---|
| target | any | |
| duration | number? |
resetCamera(duration: number?) → void
| arg | type | description |
|---|---|---|
| duration | number? |
flash(color: string?, duration: number?) → void
Colour flash: white gold cyan red rose black or "#rrggbb".
| arg | type | description |
|---|---|---|
| color | string? | |
| duration | number? |
impact(style: string?, castId: string?, strength: number?) → void
Anime impact frame (impactFrames when installed: speedBurst, radialBurst, invert, slash...) plus shake; castId aims it.
| arg | type | description |
|---|---|---|
| style | string? | |
| castId | string? | |
| strength | number? |
trance(on: boolean, opts: { [string]: any }?) → void
Trance mode: world drains to indigo, vignette closes, a glyph vortex spins. opts { hero, expr, x, vortex = { x, y, z } | false }.
| arg | type | description |
|---|---|---|
| on | boolean | |
| opts | { [string]: any }? |
fx(name: string) → void
One-shot FX: burst confetti glitch code_rain rising sparkle, plus any registered with registerFx / configure{fx}.
| arg | type | description |
|---|---|---|
| name | string |
prop(id: string, def: { [string]: any }?) → void
Place a prop in the stage (material identity, x/y/z/w/h world units, glow?) or remove it (def nil).
| arg | type | description |
|---|---|---|
| id | string | |
| def | { [string]: any }? |
screenProp(id: string, def: { [string]: any }?) → void
A prop at a screen rectangle { x, y, w, h } (fractions, top-left origin), floated in front of the stage. nil removes.
| arg | type | description |
|---|---|---|
| id | string | |
| def | { [string]: any }? |
registerFx(name: string, def: { [string]: any }) → void
| arg | type | description |
|---|---|---|
| name | string | |
| def | { [string]: any } |
registerMood(id: string, def: { [string]: any }) → void
| arg | type | description |
|---|---|---|
| id | string | |
| def | { [string]: any } |
registerWeather(id: string, def: { [string]: any }) → void
| arg | type | description |
|---|---|---|
| id | string | |
| def | { [string]: any } |
snapshot( ) → void
A plain table of the stage: { place, mood, weather, emphasis, speaker, trance, camera, actors = { { cast, slot, expr, pose, flip } } }.
restore(snap: { [string]: any }) → void
Rebuild the stage from a snapshot at once (no transition).
| arg | type | description |
|---|---|---|
| snap | { [string]: any } |
pictureOf(snap: { [string]: any }?) → void
A flat picture description of a snapshot, for drawing save-slot thumbnails in UI (works in edit too): { background = textureIdentity?, mood, weather, layers = { { src = textureIdentity, cast, x = centre 0..1, h = height 0..1 of the frame, bottom = image bottom 0..1 from the top (may exceed 1: sprites are knees-up), flip, speaker } } }.
| arg | type | description |
|---|---|---|
| snap | { [string]: any }? |
state( ) → void
Live state for tests: rig fields plus a report of cards and actors (nil outside play).
isReady( ) → boolean return rig
lists( ) → void
Sub-parts
Everything contained inside this part. Assets are composite children (clickable cards). Files are leaf payloads. Expand any row to view its source.
Showing up to 3 levels deep. Open a part to see what it holds further down.
Problems
Everything affecting this asset right now: its own problems, anything wrong inside it, and problems on its direct dependencies.
agent_score is exposed.+ quality × 0.35
+ performance × 0.25
± compat factor
Usability ratings
Did the part work as advertised when consumers tried to drop it in. Separate from upvotes: those are taste; this is "did it function".
Scoped to this part · feeds back into the world's score.