# demo.props.dressing
The dressing room — shot 8. Build-time geometry plus the two constants the tick
sound is made of; the motion lives in `PropsDressing`.
## The layout
The glass lies in the world's YZ plane at `M.MIRROR_X` = 39.88, centred on
`M.CENTRE`, half `M.HALF_W` along Z and `M.HALF_H` along Y. The wall itself is
at x = 40, so the room is entered from the west and the mirror faces the camera
down the whole of shot 8.
`M.bulbRing()` is the thirty bulb positions in the order they ring the frame:
along the top from the far side, down the near side, back along the bottom, up
the far side. `PropsDressing` does not read that order — it assigns each bulb to
the mirror practical it stands under — but the ring is what makes the geometry
an unbroken frame.
## What it places
The foxed glass and its backing; the surround and its bulbs; eight greasepaint
handprints built at nothing, each a palm, a heel, four splayed fingers and a
thumb, half of them mirrored, so the bloom in shot 8 grows real hands rather
than blobs; the table and its pots, brushes and jar; the three-legged stool; and
a costume rail set back so the room has depth behind the mirror.
## The tick
`M.TICK_CLIP` names the clip a filament sounds when it lets go and
`M.TICK_AUDIO` is the source that sounds it — spatial, twelve metres of reach,
autoplay off, one-shot only. The source is added to `P_DressingMirror`, because
the glass is the thing that ticks.
# demo.props.kit
The props slice's shared floor: the material names, the two spawn helpers, the
deterministic noise, the film clock and the easings. Everything in the slice
requires it; it requires nothing.
## Materials
`M.MAT` maps a kit name (`brass`, `crystal`, `velvet`, `bulbLive`, ...) to the
`Prop*` material it stands for, and `M.mat(name)` resolves it. Nothing in the
slice names a colour twice: a prop names a kit material and the look of that
material is decided in one file.
## Spawning
`M.group(parent, name, p)` for an empty named child, `M.part(parent, name, opt)`
for a drawn primitive — `mesh`, `mat`, `p`, `s`, `r`, `visible`, `shadows`.
`M.rot(yaw, pitch, roll)` and `M.axis(ax, ay, az, angle)` return quaternions as
4-arrays, which is the shape `localRotation` takes.
## Deterministic noise
Nothing in this slice calls `math.random`: two takes of the film must be the
same film, so every scatter is a pure function of an index and a fixed salt.
`M.hash(i, salt)` in [0, 1), `M.span(i, salt, lo, hi)` mapped into a range, and
`M.stream(seed)` for a walker that advances the salt for you.
## The film clock
`M.now()` is the cutscene's time while a cutscene plays, and a free-running
accumulator otherwise, so a prop still moves for a capture taken by hand between
takes. `M.tick(dt)` advances that fallback and is called once a frame by
`PropsDriver` alone; `M.rewind()` puts it back to zero.
`M.since(t0)` is the seconds of film since a beat fired at `t0`, or -1 for "that
beat has not happened". A sequence keyed on it survives the clock being SEEKED:
land behind the beat and the sequence reads as un-fired again, which is what the
shot before it should look like, rather than freezing whatever pose the sequence
held when the clock jumped.
## Easing
`M.sat`, `M.ramp(t, a, b)`, `M.outCubic`, `M.inCubic`, `M.lerp3` — small, named
and shared, so a beat's ramp reads the same everywhere in the slice.
# 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.
# demo.props.stage
The stage behind the proscenium — shot 9. The curtain's surface, the animatronic
band's rig, the kit they play and the calliope pipes upstage.
## The curtain surface
`M.curtainPoint(u, v, suck, t)` is the whole cloth as a pure function: eleven
heavy vertical folds belled at the hem where the sheet drags the boards, a slow
travelling ripple so it is never dead between beats, and `suck` in 0..1 drawing
the whole sheet back onto the arch and pulling it taut — the hem lifting off the
boards and the folds closing as it goes.
It is a pure function because the build and `PropsStage` both evaluate it and
neither holds the other's state. The build places only `P_Curtain`; the
component lofts the mesh over `M.CURTAIN_COLS` x `M.CURTAIN_ROWS`, which is
written here and read there so the cloth has one shape rather than two.
## The band
Three automatons — drummer, horn, squeezebox — each a named rig of `waist`,
`shoulder_l/r`, `elbow_l/r`, `neck` and `jaw` children, which is the whole
contract `PropsStage` drives. The kit is a bass drum with a separate head
entity, a cymbal on a stand and a set of bellows, each named so the component
can find it: `P_BandDrumHead`, `P_BandCymbal`, `P_BandBellows`.
## The pipes
A calliope upstage that the film never shows working. It is the source the mix
places the distant waltz at, and it is there so the sound has somewhere to come
from.
# demo.props.shrouds
The dust-sheeted furniture in the entry hall — shot 3's whole population.
Build-time only; the breathing lives in `PropsDriver`.
## Seven, each on its own period
`M.SHROUDS` is the table: x, z, height, breadth, breath period and starting
phase, for a sideboard, a chair, something upright and tall, a chaise, a low
table, a stand and another chair, down both sides of the hall. The periods run
3.8 to 6.7 seconds and no two share a phase, so the hall reads as ribs rather
than as one machine — which is the only reason there are seven rather than one.
## One shroud
Something with corners under a sheet that is barely readable through it, the
sheet over it as a gathered form, and the folds that break its silhouette. The
period and the phase are written onto the entity as `breathPeriod` and
`breathPhase` attributes, and the rest yaw as `restYaw`, so `PropsDriver` reads
each shroud's own numbers off the entity rather than holding a second copy of
this table.
# demo.props.masks
Two hundred porcelain masks on the mirror corridor's wall — shot 10.
Build-time only; the ripple lives in `PropsMaskWall`.
## The run
`M.RUN` is the wall as a polyline in the XZ plane: the south wall at z = 2.92
running east, then the east return at x = 29.72 running back north, each segment
carrying the outward normal its masks rest facing and the share of the two
hundred it takes. The corner is what stops the field reading as a panel.
Rows are `M.ROWS` = 7 between `M.Y_LOW` and `M.Y_HIGH`; every other row is
staggered half a column and both axes are jittered, so the field reads as hung
rather than as a grid.
## One mask is one entity
Each mask carries `PropMaskFace.mesh` — a single relief `demo.props.meshgen`
authored and the world carries — so two hundred masks are two hundred instanced
draws of one geometry rather than twelve hundred primitives. About a fifth are
older and have gone the colour of bone.
## Attributes the ripple reads back
Every mask records the pose it was built at — `restYaw`, `restPitch`, `restRoll`
— so `PropsMaskWall` can return it there, and `coldMat`, the face it was built
with, so the hero mask's warm porcelain can be handed back when the shot is
restaged and a different mask becomes the hero.
# demo.props.musicbox
The music box and the console it stands on — shot 4. Build-time only; the
turning and the run-down live in `PropsMusicBox`.
## The movement
`M.PINS` rows of pins around the drum and `M.TEETH` teeth on the comb are the
two numbers the tune is made of: a tooth sees a row every 1/PINS of a turn, and
its offset along the comb is what turns a comb into a phrase. Both are read by
`PropsMusicBox`; nothing else should carry a second copy of them.
## What it places
The lacquered box with its lid thrown back, the movement plate, the pin drum
(`P_MusicBoxDrum`), the governor fan (`P_MusicBoxFan`, which runs nine times the
drum and is what makes it a blur), the comb and its numbered teeth
(`P_MusicBoxComb/tooth_N`), and the clown on its pin (`P_MusicBoxClown`) —
a ruffed ballerina figure with a pointed cap, turning slower than the drum.
The console under it is the shot's foreground: a table, a runner and the dust
that falls through the beam.
# demo.props.chandelier
The chandelier's geometry, the wreck it lands as, and the glass it throws.
Build-time only — every motion lives in `PropsChandelier`.
## The build
`M.build(parent)` places the pivot at the ceiling (`M.CEILING_Y` = 14) so a
swing is a rotation of the pivot, and hangs the body below it on a cable; the
body is what falls. Two brass tiers, twelve scrolled arms with an open elbow so
the room is visible THROUGH the chandelier, catenary swags of cut drops slung
between the arm tips, four rows of pendants and a fringe under the lower ring —
about 140 crystal drops in all, which is what catches the sodium and the
lightning and what reads as a chandelier from across a dark room.
One candle on arm 4 is still alight. It is the room's last practical before the
fall, it is what the moths in shot 6 orbit, and it is the only emissive surface
on the whole fixture.
## The wreck and the glass
`M.buildWreck(parent)` places both, inactive. The wreck is the same rings, column
and arms splayed and dropped, with a `BoxCollider` so it is a real obstruction
the rest of the room meets. The glass is `M.SHARDS` = 96 octahedra at their rest
positions.
`M.shardRest(i)` is where shard `i` comes to rest on the checkerboard, and its
size — pure arithmetic on the shard index against a fixed salt, so two takes
throw the same glass. `PropsChandelier` flies each shard from the impact point
to that rest position and leaves it there.