Log inGet started
Package

props.module

Newest version

README.md

props — THE HOUSE WEARS A FACE, slice "props"

Everything in Merriweather Hall that is not architecture and not weather: the dust-sheeted furniture that breathes, the music box and its turning clown, the bulb-lined dressing mirror and its failing run, the wall of two hundred porcelain masks, the animatronic band, the red curtain that inhales, and the chandelier — its cable, its fall, and the glass it throws.

Serves shots 4, 6, 8, 9, 10, 11, 12 and 13 — the chandelier is in four of them: it swings at the station in 6, falls in 11, lies wrecked under 12 and is re-hung as the face's nose in 13.

Exports

  • M.content(root) — build the slice's entities under the film's root. Called from the scene build, in slice order.
  • M.register() — declare the slice's beat handlers. Each one marks the film-clock time a sequence began.
  • M.reset() — put every prop back to its shot-1 state. Called before each take.
  • M.get(componentName) -> component | nil — the live instance of one of the slice's six components.
  • M.status() -> table — what the slice is doing right now: the film clock, the chandelier's phase, height and landing time, how many bulbs are out and whether the filament tick can sound, how many masks are facing the lens and which one is the warm hero, how flat the curtain is, and the entity count.

Every method the slice calls across a file boundary is declared typed function public:name(...) and called ref:name(...). A method declared at file scope belongs to the component and is not on the ref, and a call to one raises — which is how, before this pass, the chandelier never fell, the masks never turned, the curtain never inhaled and M.reset() reset nothing.

How it is put together

The build places geometry; six components move it. Each has exactly one instance, on the thing it moves:

componenthost entitywhat it drives
PropsDriverPropsthe slice's film clock, and the hall's breathing shrouds
PropsMusicBoxP_MusicBoxSetthe pin-drum, the comb, the governor, the clown on its pin
PropsDressingP_Dressingthe bulb run, the greasepaint handprints, the rocking stool
PropsMaskWallP_MaskWallthe ripple that turns two hundred masks to the lens
PropsStageP_Stagethe curtain cloth (a runtime mesh, re-lofted at 24 Hz) and the band
PropsChandelierP_ChandelierPivotthe swing, the fall, the shatter, the re-hang

Every one of them reads one clock, demo.props.kit.now(), which is the cutscene's while a cutscene is playing and the slice's own free-running accumulator otherwise. Nothing in the slice reads wall-clock time and nothing calls math.random: every scatter is kit.hash(index, salt), so two takes throw the same glass.

kit.since(t0) is how a beat-triggered sequence measures its own age. It answers -1 when the film clock is behind the beat, so seeking back before shot 11 puts the chandelier back on its cable instead of freezing the wreck on the floor.

Notes

  • Both per-frame hooks fire in both modes (issue #2743), so every component here names the mode its tick belongs to. Without that the bodies — and the film clock — run twice a frame.
  • The masks are one entity each, drawing one mesh (PropMaskFace, authored by demo.props.meshgen). Built from primitives they were seven entities each, and two hundred of those is 1400 entities for one wall.
  • The chandelier's fall is arithmetic on the film clock, not the rigid-body solver. The solver does not step in edit mode — Physics.worldState() reports stepping = false and builds no bodies at all — and the film has to be the same hundred seconds twice.
  • The chandelier lands at K.IMPACT. That second is the film's, not this slice's: the light drops to a third there, the plaster and glass burst there, and the sub lands there. PropsChandelier:landingAge() reads what the layout actually gives, and the two have to agree — 69.0 + 1.749 = 70.749.
  • The dressing bulbs are the one sequence keyed on the FILM clock rather than on its beat, because K.DRESSING is shared with the look slice's eight mirror practicals. Glass and light go out together or the frame shows a lit bulb throwing no light.
  • After editing any module under /source/demo/props/, rebuild the scene (layers.active.asset:build()); a module a build requires does not rebuild the scene by itself.