air.module
README.md
air
The "air" slice of THE HOUSE WEARS A FACE — everything between the camera and a surface. The storm and its four strikes, rain outside and rain getting in from shot 6, the volumetric shafts and the dust turning in them, moths around the one live bulb, the plaster the ceiling throws when the chandelier goes, the water column of shot 12, height fog, and the wetness ramp that turns the ballroom floor from grey dust into a black mirror.
Shots served: 1, 2, 3, 6, 11, 12.
Exports
M.content(root)— builds the slice under the film's root as anAirgroup.M.register()— binds the beat handlers, and declares the four lightning cuesb01_flash(4.5 s),b02_flash(10.2 s),b06_flash(39.4 s) andb11_flash(74.8 s) viabeats.extra, so the film and the mix can key off the strikes.M.reset()— re-asserts every emitter's spec, puts the film clock back to zero, re-seats the moth swarm and stops the two one-shot bursts.M.applySpecs()— makes the live air match what the module authors, and returns the names it had to rebuild. Empty on a scene that kept its spec.M.specHolds(emitter, data)— whether one live emitter already carries the spec authored for it.M.status()— the film second the air is drawn at and every emitter's live rate. The one call to make when the air looks wrong.
How it is driven
One component owns the whole slice: demo.air.AirClock, on the Air group.
Everything is a pure function of the film clock, so two takes of the same second
draw the same air — the lightning envelope, the fog and wetness ramps, which
rain is falling and where, and the drift of the dust inside the shafts.
The film clock is the CUTSCENE's own second. While demo.film is playing the
air is drawn at cutscene.status().time, in edit and in play alike, so the
storm cannot drift away from the cut by a frame. Between takes the clock is held
at the component's previewT (35.0, the shot-6 station) so another slice
capturing the room sees a settled second, and AirClock:seek(t) moves that.
Every shot beat seeks, so a capture taken between takes settles at the shot the
beat names.
The emitters are a table, and it is applied twice
content() builds the twelve particle emitters from one EMITTERS table rather
than from twelve inline calls, and applySpecs() walks the same table against
the live scene.
It has to be applied twice because a built scene restores its entities from the
scene record, and a ParticleEmitter's record carries only its flat public
fields. The nested spec keys the component documents — shape, lifetime,
speed, size, squash, wind, color, transparency — do not survive the
round trip, and every emitter in a loaded world comes back a POINT emitter at the
schema's own defaults: lifetime 1.0–1.5 s, speed 2–4 m/s, no wind, no squash.
That is why the rain read as one searing vertical bar over the facade instead of
as rain — nine thousand drops falling from a single point. Filed as
OrigoZero/zero#12887.
applySpecs() compares every field the round trip is known to drop and rebuilds
the component where they differ, which is the one route that re-runs the spec
normalisation. It is idempotent: a second pass on a healthy scene rebuilds
nothing.
What it owns in the scene
| Entity | What it is |
|---|---|
Air_Atmosphere | HeightFog + VolumetricLighting — the scene's wet night air |
Air_Lightning | a distant light: the four strikes, driven by an envelope |
Air_RainCurtain | the exterior curtain; rides above the film's own camera station while the film is still outdoors |
Air_RainNear | the sheet at the lens — few, large, fast streaks three metres ahead of the camera, which is what makes the exteriors read as heavy rain |
Air_Eave1..3 | shot 2's three separate falls off the eaves |
Air_RainHole / Air_HoleSplash | the rope of rainwater through the ceiling hole, and what it throws back off the floor |
Air_WaterColumn / Air_ColumnSplash | shot 12: the rope becomes a column |
Air_MotesHall / Air_MotesBallroom | dust turning in the sodium shaft, and the ballroom's own air |
Air_Plaster / Air_GlassDust | shot 11's one-shot bursts, replayed by the b11_impact cue — the ceiling gives when the chandelier LANDS, 1.75 s after the cable parts, not when it starts to fall |
Air_ShaftFanlight / Air_ShaftHole / Air_ShaftColumn | the three volumetric shafts |
Air_Moths + 16 children | the swarm around the one live bulb |
Notes
- The shafts are raymarched, not billboards. Each
Air_Shaft*entity wears a cube that is only a bounding proxy;demo.air.lightshaftmarches a tapered cone inside it between the camera and whatever the frame already drew, so a shaft thickens through its middle, thins to nothing at its rim and stops at the floor it lands on. Draw them additive, front-culled,depth_compare: always. - A shaft is driven on per-instance lane 0, not through its material.
AssetRef:setPropertyin edit mode writes through to the asset on disk, so a per-frame drive rewritesmat.yamlfour times a second and replaces the authored resting values with animation frames (OrigoZero/zero#11264). Lane 0 carriesx= the clock the dust drifts on,y= added to the material's resting brightness. - Additive particles in a dark room saturate very fast. Rain at a high rate and full brightness stops reading as water and becomes a solid white bar. What reads as falling water is a LOW rate of short, half-transparent streaks with gaps between them; the gaps are the effect.
- Height fog lifts every black in the frame, and outdoors it also draws an
arc. Fog is applied to the sky as well as to the house, and the sky is a
dome: at the density that reads as wet night air across eighteen metres of
ballroom, the exteriors came back with a hard-edged band over the gate and a
black floor of 26 code values. The exterior number is therefore a tenth of the
interior one — 0.0013 until t = 14, ramping to 0.0148 by t = 74 — and that
ramp is the whole of Act I's legibility.
VolumetricLighting.lightScaleis well under 1 for the same reason: the look slice runs its practicals very hot, and scattering all of that turns every doorway into a glowing rectangle. - The raymarch budget is the browser's. 24 volumetric steps and 4 shadow taps over 70 m; the demo's medium is thin (0.011–0.030), which is the regime where a step count shows least. Peak particle count is the exteriors — RainCurtain 7000 + RainNear 1600 + three Eaves 1400 = 12,800 live at t = 0–12, falling to about 3,900 indoors and 7,500 across the fall.
- The wetness ramp is the builtin weather system
(
@builtin::systems.weather.weather), which is scene-wide:wetness0.26 → 0.94 andshelter0.96 → 0.16 across the film, so what the ceiling hole leaves exposed stops being sheltered as the rain gets in.