# film <!-- zero:scaffolded-readme --> <!-- Replace the line below with what this module provides and who consumes it, then delete both comment lines. --> TODO: describe this module.

# ashbloom.light.look The look of *Ashbloom*, as arithmetic. `look.at(t)` takes film-seconds and answers with one flat table holding every number the rig will push that frame — the key light, the fill, the ambient, the atmosphere, the fog, the exposure, the lens, the bright pass, the grade, the vignette and the shadow config. Nothing here touches the engine. Any moment of the film can be read back without a frame going by: ```lua local look = require("ashbloom.light.look") local L = look.at(115) print(L.movement, L.key.intensity, L.ambient.intensity) --> bloom 0.081 0.011 ``` ## The two inversions The film's light source inverts twice, and both inversions live in this file. **Moon → sun.** There is exactly ONE shadow-casting directional light in the world, `key`. It is the moon through movements I–III and the sun from `t = 146`, which is where the key's own intensity has fallen to about a hundredth of peak — the shadow direction swings while nothing is casting one. The SKY is driven separately (see below), which is what lets a night sky sit over a crater that a moon is throwing cascaded shadows into. **Borrowed light → the garden's own.** `nightGate(t) = 1 - 0.97 * film.glow(t)` multiplies the moon, the fill and the cold ambient. The plants do not add light in movement III, they REPLACE it: at `t = 115` the key sits at 0.081 against a peak of 4.0 and the only thing lighting the geometry is the geometry. ## The sky's own illuminant `atmosphere.sunDirection` / `sunIntensity` / `sunColor` are stated outright rather than read off the scene's sun. Before `film.DAWN` the illuminant is the MOON — the deep blue of a moonlit night is the same Rayleigh scattering as a daytime sky, five magnitudes down, and the moon's true angular radius (0.0047 rad) puts a disc in frame. After it, the illuminant is the sun. The swap lands on the cut into shot 21 with both ends near zero. ## Where the lights stand | | azimuth | elevation | | |---|---|---|---| | moon | 305° | 27° | clears the 19.5° rim by seven degrees, so it rakes | | sun | 55° | `film.sunElevation(t)`, −9° → +14° | over the north-east rim | | fill | 150° | 22° | cold, opposite, casts nothing | Both key sources stand north. The film's bookend wides look south from 92 m up on the north rim; a key from the south would give them a frame of shadowed inner wall. ## The depth-of-field rack `RACK` holds one row per shot — where the lens is focused, in metres, the aperture, and how far the defocus may go. The FOCAL LENGTH is never authored: it is derived from the shot's own vertical fov against a full-frame sensor (`focalFor`), so a lens change by the camera slice moves the defocus with it instead of leaving the two disagreeing. `focusTo` racks focus across a shot. `dofAt(t, override)` layers the camera slice's rack over this one, row by row. ## The four looks `LUT_NAMES` / `LUT_GRADES` are the per-movement colour tables, built through `@builtin::modules.lut` and installed under `/source/ashbloom/light/looks/`. The continuous grade in `at()` does the moment-to-moment work; these carry the character each movement's film stock would have had.

# ashbloom.camera.rack The lens and the ears of Ashbloom's 25 set-ups. The set-ups themselves are not here. They are data — the `pos` / `look` / `fov` / `ease` keys on each row of `film.SHOTS` — because the cutscene Runtime under `AshbloomDirector` is what poses the camera, and it reads that table directly. This module owns the two things that ride on those set-ups and cannot be expressed as a row in a table. ## The lens `sensorHeight` is full frame, so every shot's focal length falls out of the field of view it was composed at: ``` f = 12 / tan(fov / 2) -- 24° -> 56 mm, 14° -> 98 mm, 68° -> 18 mm ``` which keeps the lens honest through shot 13's 30° → 40° ramp, where a hand-written focal length would drift away from the framing mid-shot. Focus is racked to the subject: the distance from the shot's eye to the point it is looking at, re-evaluated every frame, so a shot that dollies pulls focus as it travels. `RACK[n]` states only what the optics cannot derive — the aperture, where the plane of focus sits along the eye → subject ray, and the blur ceiling: | | shots | f-stop | |---|---|---| | macro | 2, 9, 12, 15, 20, 23 | f/1.4 – f/1.8 | | close | 6, 8, 13, 16, 18, 24 | f/2.0 – f/2.8 | | middle | 3, 10, 11, 19 | f/4 | | wide | 1, 4, 14, 21, 25 | f/5.6 | | very wide | 5, 7, 17, 22 | f/8 | It drives `@builtin::systems.depthOfField.depthOfField` directly rather than through a `DepthOfField` component. The component pushes its fields only when they CHANGE, so the two do not fight; but one authoring surface per system is the rule, and for this system the camera slice is it. ## The ears The scene's single `AudioListener` is re-posed on every cut, so the soundscape turns with the film. It does **not** re-parent to the cutscene camera. That camera is temporary and is despawned when the playback releases its stage, which would take the world's only listener with it. One departure from riding the camera exactly: two set-ups stand a quarter of a kilometre outside the crater, and a listener out there hears no garden. The ears are pulled along the eye → subject ray until they are within 30 m of what the shot is looking at. Close shots are unaffected; the wides hear the bowl they are framing. ## The guards A camera inside the rock renders a flat single-colour frame and every read-back in the engine reports it as correct, so two checks answer for it: ```lua local rack = require("ashbloom.camera.rack") rack.probe(110) -- eye / at / fov / focal length / f-stop at a film time rack.clearances() -- how far each of the 25 eyes clears the crater surface ``` `clearances()` asks `ashbloom.crater.craterGeo.groundY` — the same profile and warp the crater mesh was cut from — at thirteen points across every shot. Under 0.40 m is inside the 34 cm ash mantle. The stage repeats the check on each cut and says so in the log, and it warns once per anchor when a shot anchor moves more than 2 m from where the set-ups were composed. ## Joining in ```lua rack.install() -- registers the "camera" stage at order 15; idempotent ``` `AshbloomCamera.component` calls it, so a freshly loaded world has the lens and the listener without anyone requiring this module by hand.

# stages <!-- zero:scaffolded-readme --> <!-- Replace the line below with what this module provides and who consumes it, then delete both comment lines. --> TODO: describe this module.