# a_heavy_iron_cable_snapping_under_tensio
Managed audio asset. Edit the `.metadata` `settings` block to change compression.
# 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.
# a_tiny_antique_music_box_playing_a_slow
Managed audio asset. Edit the `.metadata` `settings` block to change compression.
# 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. |
# 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.
# heavy_steady_rain_falling_on_slate_roof
Managed audio asset. Edit the `.metadata` `settings` block to change compression.
# 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". |
# single_slow_water_drops_falling_into_a_s
Managed audio asset. Edit the `.metadata` `settings` block to change compression.
# a_single_heavy_thunderclap_cracking_then
Managed audio asset. Edit the `.metadata` `settings` block to change compression.
# a_steam_calliope_fairground_waltz_heard
Managed audio asset. Edit the `.metadata` `settings` block to change compression.
# 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.
# an_old_derelict_wooden_house_settling_at
Managed audio asset. Edit the `.metadata` `settings` block to change compression.
# 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. |