vnStage
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.…
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
- Install vnStage (search ZeroMind for "visual novel stage"); screenWipes comes along.
- Give your scene a camera named
StageCameraand an empty root entity namedStage(a playerless scene). - In play (your story module or the scene's entrypoint):
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;registerTabfor 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.texturefor glyph weather.- Guide: Visual novel stage: character expressions, poses, scene transitions and weather effects.
Showcase
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.
Scoped to this part · feeds back into the world's score.