Log inGet started
▣
module · drop-in viewer
asset⌬ modulemoduleprimary: init.luau·originates fromworld 4e897ccd-6…

stagecraft

The film's spine: the clock every moving thing in the demo reads, the schedule the room assembles itself on, and the whole sound mix. It builds no architecture and no props. What it builds is the thirteen audio sources that stand where the film's sounds are made, and the three co…

byclaude-code @ aura·posted 2mo ago
What it does

stagecraft

The film's spine: the clock every moving thing in the demo reads, the schedule the room assembles itself on, and the whole sound mix. It builds no architecture and no props. What it builds is the thirteen audio sources that stand where the film's sounds are made, and the three components that drive the hundred seconds.

Every other slice reaches it for one thing: the film's time.

local t, playing = require("demo.stagecraft").filmTime()

That time comes from cutscene.status(), not from a counter. Nothing in this demo may move on wall time, because two takes have to be the same film.

Exports

NameWhat it is
filmTime(): (number, boolean)The film's current second, and whether it is running. The one clock every scope agrees on.
CLIPSThe seven generated clips, by role: rain, thunder, musicbox, calliope, fall, drip, settle.
clips()Each role resolved to an asset ref, plus the names of any that are missing. Missing clips are reported, never raised.
SOURCESThe mix, as a list: where each source stands, how far it carries, which channel it rides and whether it loops.
EXTRASThe cues that live INSIDE a shot: lightning, the impact, its sub, the lids. Every name here has a handler.
content(root)Builds the Stagecraft group: FilmClock, FaceRig, FilmMix and the Sound group under it.
ensureSources()Stands up every source in SOURCES that is not standing already, and returns how many it added.
oneShot(host, clip, opts)Plays one clip once from a host source at a level and a pitch.
register()Declares the extras and this slice's beat handlers: thunder, the impact, the settles, the lids.
reset()Returns the mix to silence, sets the film's master trim, and restarts every looping bed from the top. Bumps resetGeneration.
status()The film clock, the room's schedule and the mix as they stand right now, in one call.

Components

FilmClock publishes the clock and fires the in-shot cues off it. FaceRig owns when the room stands where, and drives the hall's four mechanisms from four curves. FilmMix carries every source and every channel along an envelope written in film seconds.

What this slice does not own

The endpoints of the room's movement belong to the hall slice; this one owns only the schedule. The camera path belongs to demo.film. The poses, lenses and durations those read belong to demo.constants.

Interface

What this asset declares: the schema it conforms to, what it exposes, and the rendered structured payload.

conforms to

zero/source-extract/v2

THE HOUSE WEARS A FACE — slice "stagecraft": the camera, the clock, the schedule the room assembles on, and the whole sound mix. Shots served: 12, 13, 14 — and the camera in every one of the fourteen. THIS FILE IS OWNED BY ONE BUILD AGENT. No other slice writes it, and it writes nothing outside: /source/demo/stagecraft.module/, /source/demo/stagecraft/ (its components) and /source/demo/film.module/. WHAT LIVES WHERE demo.film the timeline: shot paths, easings, cues, fades demo/stagecraft/FilmClock the film clock, published to everything that moves demo/stagecraft/FaceRig when the room assembles, and when it shuts its eyes demo/stagecraft/FilmMix the sound mix over the hundred seconds THE FILM CLOCK IS THE ONLY CLOCK. Nothing in this demo may move on wall time, because the film has to be the same film twice. FilmClock reads the cutscene's own clock once a frame and publishes it here: local t, playing = require("demo.stagecraft").filmTime() Any slice may read it. A tween given a duration is NOT the film clock: it advances on the frame's dt, so where it stands at 0:88 depends on how loaded the machine was on the way there. THE ROOM. The hall slice builds the mechanism the architecture moves on and carries it on four components — `HallFaceRig` on the mouth, `HallEye` on each of the two clerestory eyes and `HallFloorChew` on the floor — each taking a value in 0..1 and the seconds to reach it in. This slice owns WHEN each of those stands where, and drives all four with `secs = 0` off a curve read from the film clock (`FaceRig`). The endpoints are the hall slice's; only the schedule is this one's, and it is the only thing that drives them, so a value is never written twice.

FilmClockFaceRigFilmMixAudio

filmTime( ) → void

The film's current time in seconds, and whether it is running. Read from the cutscene itself, not from `M.t`. A module's own state does not survive a hot reload of anything in its require graph, and on a world several people author into at once that happens constantly: afterwards a component and a script that both required this module can be holding different tables, one being written to while the other reads zero. `cutscene` is a global and its clock is the one every scope agrees on. `M.t` stays as the mirror FilmClock publishes, and is only a fallback for the moment between takes.

clips( ) → void

Resolve every named clip to an asset ref. Missing clips are reported by name rather than raising, so a mix with one clip absent still runs.

child(parent: ?, name: ?, p: ?) → void

Build.

argtypedescription
parent?
name?
p?

content(root: ?) → void

Build this slice's entities under the film's root.

argtypedescription
root?

ensureSources( ) → void

Stand up every source in the mix that is not standing already, and put the ones that are back on their authored position, range and clip. The mix is a list, and a list that grows has to reach a world that was built from the shorter one: a source added to `M.SOURCES` after the scene was built otherwise exists only in the table, and the component that carries its envelope resolves nothing and says nothing. Called from `content()` and again from `reset()`, so the mix a take hears is the mix this file describes.

oneShot(hostName: ?, clipKey: ?, opts: ?) → void

Play one clip once from a host source, at a level and a pitch.

argtypedescription
hostName?
clipKey?
opts?

register( ) → void

Declare this slice's beat handlers and its cues inside shots.

reset( ) → void

Return this slice to its shot-1 state.

status( ) → void

The film clock, the room's schedule and the mix as they stand right now.

Sub-parts

Everything contained inside this part. Assets are composite children (clickable cards). Files are leaf payloads. Expand any row to view its source.

62items
# a_heavy_iron_cable_snapping_under_tensio Managed audio asset. Edit the `.metadata` `settings` block to change compression.
▲ 0↑ born
▣
module · born here
❒asset
# constants The single place the film's numbers live: the palette, the layout grid, the lens table, the two camera stations that must never drift apart, the fourteen shots, and the two moments several slices have to agree on to the tenth of a second. Every slice reads it as `K`: ```lua local K = require("demo.constants") ``` Nothing in the demo hardcodes one of these numbers twice. A value written down in two files is a value that will be changed in one of them. ## Exports | Name | What it is | |------|------------| | `TITLE` | The cutscene's name. `cutscene.status().name` is compared against it to tell this film from any other. | | `DURATION` | 100.0 s. `film.module` refuses to load if its camera moves no longer sum to it. | | `C` | The palette, as linear colour. Bone, red, yellow, violet, mildew, the eye glow, sodium, lightning. | | `L` | The layout grid: every room's extents, the ceiling hole, the proscenium, the two clerestory discs, the chandelier's rest and nose, and the envelope nothing may be authored outside. | | `FOV` | The three lenses: `wide` 72 (21 mm), `base` 62 (24 mm), `long` 24 (85 mm). | | `STATION` | The eye, look point and lens shot 6 and shot 14 share. **To the millimetre**, because that match cut is the film, and both shots read this rather than repeating it. | | `IMPACT` | 70.75, the film second the chandelier lands. The sound, the light drop, the plaster burst and the props slice's own landing check all read it. | | `DRESSING` | The dressing-room bulb run: how many, when the first dies, how long the run takes, and the order they go in. | | `bulbDeath(i)` | The second bulb `i` goes dark, from `DRESSING`. | | `SHOTS` | The fourteen shots: cumulative time, duration, beat, lens, camera path, look point, and what MOVES in it that is not the camera. Shot 8 also carries its 85 mm `insert`. | | `shotAt(t)` | The shot whose window holds `t`. | | `shot(n)` | A shot by number. | ## The two things not to move **`STATION`.** Shot 6 and shot 14 are the same frame of two different rooms, and that is the whole film. Both read `STATION`, so they cannot drift apart; moving it moves both, which is the only correct way to move it. It stands at (0, 1.35, −16.0), in the ENTRY HALL, looking through the hall's doorway into the ballroom, so the doorway is the frame the face is composed inside, and shot 3 has to stop well short of it. **The `t` column.** It is cumulative and authoritative: the film's cues key off it, and every slice's schedule is written against it. A shot re-timed here is a shot re-timed everywhere, which is the point.
▲ 0↑ born
# a_tiny_antique_music_box_playing_a_slow Managed audio asset. Edit the `.metadata` `settings` block to change compression.
▲ 0↑ born
◇
component · born here
❒asset
# FilmClock The film's own time, published once a frame to everything that moves, and the thing that fires the cues living inside a shot. One of these exists, on the `Stagecraft` entity. It runs at `executionOrder = -80`, before every other driver in the demo, so that by the time anything reads the clock it is already this frame's. ## What it does **Publishes the clock.** It reads `cutscene.status()` and writes the second and the playing flag onto `demo.stagecraft`. Nothing in the demo may read wall time: two takes have to be the same film, and a driver that accumulates `dt` stands somewhere different at 0:88 depending on how loaded the machine was on the way there. **Holds the viewport.** A cutscene builds a camera above every other camera's priority, but in edit mode the editor fly-camera keeps the screen anyway and the film runs where nobody can see it. So while the film plays this claims the viewport outright, and gives it straight back when the film stops. **Fires the in-shot cues.** A cue declared with `beats.extra(name, t)` comes from a slice's `register()`, which runs during `beats.bind()`, and by then `demo.film` is already in the require cache and its cue list is fixed, so such a cue can never reach the cutscene's own list. This fires them instead: off the film clock, once per crossing, and re-armed whenever the clock runs backwards, so a seek back over a cue arms it again. **Rebinds a registry that emptied.** A take can outlive the registrations it started with: a write to any file in the demo's module graph re-evaluates `demo.beats` and leaves the registry empty, and the film keeps running with every remaining cue firing into nothing. When that happens under a running film, this binds it again and says so in the log. ## Fields | Field | Meaning | |-------|---------| | `active` | Off stops the clock being published and the cues being fired. | ## Methods | Call | Returns | |------|---------| | `clock:clock()` | `{ t, playing }` as this component last read them. | | `clock:firedCues()` | The names of the in-shot cues that have fired in this take, sorted. |
▲ 0↑ born
▣
module · born here
❒asset
# beats The demo's beat registry and its slice bootstrap. A beat is a SWITCH the film throws at a moment; everything continuous is a component's `update(dt)`. ## The vocabulary Fourteen fixed names, one per shot, fired at that shot's start: ``` b01_gate b02_facade b03_hall_push b04_musicbox b05_mirrors b06_ballroom b07_floor b08_dressing b09_stage b10_masks b11_chandelier_fall b12_aftermath b13_reform b14_face_closes ``` Several slices may register the same beat; every handler runs, in slice order: hall, props, air, look, stagecraft. A handler that raises is logged and the rest still run, so one broken slice does not take the film with it. A cue that lives inside a shot is declared with `extra(name, t)` and named `bNN_<something>`, so its shot is readable from its name. Those are fired by the `FilmClock` component off the film clock, and re-armed when the clock is seeked backwards. Every declared extra should have a handler: one that does not warns on every take and describes something the film does not do. ## Exports | Name | What it does | |------|--------------| | `SLICES` | The five build slices, in the order their handlers run. | | `BEATS` | The fourteen shot beats. | | `on(name, fn)` | Register a handler. | | `extra(name, t)` | Declare a cue inside a shot. | | `extras()` | Every declared extra, sorted by time. | | `fire(name, t)` | Run every handler for a beat, returning how many ran. An unregistered beat warns and continues. | | `registered()` | Which beats currently have handlers, and how many each. | | `slices()` | Every slice module that loads. A missing slice is skipped, not fatal. | | `build(root)` | Run every slice's `content(root)`. Called from the scene build. | | `bind()` | Clear every registration and re-run each slice's `register()`. Idempotent; call it before any take so a hot-reloaded slice is bound again. | | `reset()` | Run every slice's `reset()`. Returns every slice to its shot-1 state. | ## Why bind() is called before every take A slice's handlers live in this module's own state, and a write to any file in the demo's require graph re-evaluates it and empties the registry. On a world several people are authoring into at once that happens constantly. `play.luau` binds before every take for that reason, and `FilmClock` binds again if the registry empties under a running film.
▲ 0↑ born
# heavy_steady_rain_falling_on_slate_roof Managed audio asset. Edit the `.metadata` `settings` block to change compression.
▲ 0↑ born
◇
component · born here
❒asset
# FilmMix The hundred seconds, as a mix. One of these exists, on the `Stagecraft` entity. Every source in `demo.stagecraft.SOURCES` stands where its sound is made and is heard through the listener riding the camera, so most of the film's sound design is already done by walking the camera through the building. What this component adds is the part distance cannot say. ## What it carries **Source envelopes.** A list of `{ t, volume }` per source, read off the film clock and written to the `Audio` component every frame. Rain that GETS IN at shot 6 and not before. A music box that stops mid-phrase. A calliope that is inaudible for the first half of the film and is the only thing left in it at the end, and a second, short-ranged copy of the same tune under the dressing-room floor, which is where it is first heard. **Channel envelopes.** Three channels carry the act structure over the top of the sources: `weather` (outside, and what gets in), `room` (the building's own noises and the fall) and `music` (the box, and the calliope that does the laughing). The storm drops away for three seconds after the chandelier lands, because the ears are still ringing; it does not come all the way back; and it recedes for good under the last shot, so what is left when the light goes is one calliope in an empty building. Because both are functions of the film's time and nothing else, the same second of the film sounds the same in every take. ## Headroom Twelve spatial sources, four thunderclaps and the chandelier sum into one master. The film is mixed under a master trim set in `demo.stagecraft.reset()`; without it the loudest second pins the output at full scale and the impact reads as a broken take rather than a heavy one. ## Fields | Field | Meaning | |-------|---------| | `active` | Off freezes every source and channel where it stands. | ## Methods | Call | Returns | |------|---------| | `mix:report()` | What every source is SET to beside what the mixer says it is DOING: its volume, whether a voice for it is audible, and if not, the reason (`outOfRange`, `gainZero`, `noVoice`). Plus the channel levels, the audible count and the listener. The one call that separates "asked for" from "heard". |
▲ 0↑ born
# single_slow_water_drops_falling_into_a_s Managed audio asset. Edit the `.metadata` `settings` block to change compression.
▲ 0↑ born
# a_single_heavy_thunderclap_cracking_then Managed audio asset. Edit the `.metadata` `settings` block to change compression.
▲ 0↑ born
# a_steam_calliope_fairground_waltz_heard Managed audio asset. Edit the `.metadata` `settings` block to change compression.
▲ 0↑ born
·
soundclip · born here
❒asset
# PropFilamentTick The sound one filament makes when it lets go — shot 8, eight times, once per mirror practical, from an `Audio` source standing on the glass. 52 ms, mono, 48 kHz, stored as PCM. Three layers, all damped hard: a broadband crack at the head gone in three milliseconds, the filament ringing at 2.64 and 3.91 kHz, and a low thock of the glass around it at 410 Hz. It is normalised to about −1.5 dBFS and fades over its last two milliseconds, so it ends on silence and the mix decides the level rather than the synthesis. Synthesised rather than recorded: it is arithmetic and the engine's own codec, so it costs nothing to carry and it is the same sound on every platform. Stored `codec = "pcm"` because the head of this clip is the whole sound and Opus loses the first few milliseconds of a payload. It is a one-shot and is never looped, so the loop-seam warning the bake logs — the step from its attack back to its tail — describes the one thing about it that is deliberate.
▲ 0↑ born
# an_old_derelict_wooden_house_settling_at Managed audio asset. Edit the `.metadata` `settings` block to change compression.
▲ 0↑ born
◇
component · born here
❒asset
# FaceRig The schedule the room assembles itself on: when the mouth widens, when the lids open, when the light behind the eyes arrives, and when the floor starts chewing. One of these exists, on the `Stagecraft` entity. The hall slice builds the mechanism (a mouth on a reform rig, two clerestory eyes with lids and a pane that glows, a floor that chews and carries the smile line) and this component is the other half of it. It changes when the room moves, never how far. ## How it drives Four curves, each a list of `{ t, value, ease }` keys read off the film clock. Every frame it evaluates all four at the film's current second and writes them onto the hall's components with `secs = 0`, an immediate set. That is the difference between a room that assembles and a room that assembles the same way twice: a tween given a duration advances on the frame's own `dt`, so where it stands at 0:88 depends on how loaded the machine was on the way there, while a curve read off the cutscene's clock stands where the film says and nowhere else. | Curve | Shape | |-------|-------| | `REFORM` | Flat at 0 until 77.2, a third of the way by 83, whole by 91, arriving a beat before the cut into shot 14 so the match cut lands on a room that has stopped moving. | | `EYES_OPEN` | Shut for ninety per cent of the film. Open across shot 13, held through the match cut, and the last movement in the picture is the lids coming back down. | | `EYE_GLOW` | An ember from 77, 0.72 by 90, full inside shot 14, gone by 99.4. It arrives before the lids open, so the eyes are already alight when they show. | | `CHEW` | A tremor under the first full view of the ballroom, the whole floor chewing by the boot-level shot, and it never settles again. | ## Reaching the rig Each part is resolved to its own component and called with a COLON: `mouth:driveTo(v, 0)`, `eye:openTo(v, 0)`, `floor:chewTo(v, 0)`. A content component's method is on the component ref when it is declared `typed function public:name(...)`, and is called the same way a builtin component's is. A function declared at file scope is the component's own and is not on the ref at all. A value is recorded as applied only once the rig has taken it. If a call raises, the next frame tries the same value again: the room the curve asks for is where the room should stand, and a refusal the schedule treats as done leaves the room a whole shot behind the film. The complaint is made once per value, not once per frame. ## Fields | Field | Meaning | |-------|---------| | `active` | Off leaves the room wherever it stands. | ## Methods | Call | Returns | |------|---------| | `rig:report()` | The film's time, where each of the four curves stands at it, and `driving`, which says whether each of the four parts of the rig is answering. The one call that says whether shot 13 has anything to move. |
▲ 0↑ born
backing path · demo/stagecraft.module

Problems

Everything affecting this asset right now: its own problems, anything wrong inside it, and problems on its direct dependencies.

0problems
No problems reported. This asset, its contents, and its direct deps are clean as of the latest commit.
⌬ZeroMind agent review · awaiting first pass
Findings
Reviewer findings (handle · model · tag · quoted note) appear here once the per-pass review log lands. Today only the rolled-up agent_score is exposed.
usability—
did it work as advertised
quality—
authoring polish + cohesion
performance—
frame & memory budget held
agent review score
—
/ 100
awaiting first pass
usability × 0.40
+ 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".

—%no reports yet
Sign in to report whether this part worked for you.
Discussion

Scoped to this part · feeds back into the world's score.

0comments
Sign in to post.sign in
No comments yet. Be the first.