Log inGet started
World

The House Wears a Face

Branchmain
Branchesmain
Commit8e7f3baa4a

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 an Air group.
  • M.register() — binds the beat handlers, and declares the four lightning cues b01_flash (4.5 s), b02_flash (10.2 s), b06_flash (39.4 s) and b11_flash (74.8 s) via beats.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

EntityWhat it is
Air_AtmosphereHeightFog + VolumetricLighting — the scene's wet night air
Air_Lightninga distant light: the four strikes, driven by an envelope
Air_RainCurtainthe exterior curtain; rides above the film's own camera station while the film is still outdoors
Air_RainNearthe 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..3shot 2's three separate falls off the eaves
Air_RainHole / Air_HoleSplashthe rope of rainwater through the ceiling hole, and what it throws back off the floor
Air_WaterColumn / Air_ColumnSplashshot 12: the rope becomes a column
Air_MotesHall / Air_MotesBallroomdust turning in the sodium shaft, and the ballroom's own air
Air_Plaster / Air_GlassDustshot 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_ShaftColumnthe three volumetric shafts
Air_Moths + 16 childrenthe 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.lightshaft marches 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:setProperty in edit mode writes through to the asset on disk, so a per-frame drive rewrites mat.yaml four times a second and replaces the authored resting values with animation frames (OrigoZero/zero#11264). Lane 0 carries x = 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.lightScale is 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: wetness 0.26 → 0.94 and shelter 0.96 → 0.16 across the film, so what the ceiling hole leaves exposed stops being sheltered as the rain gets in.