# furrow.sand The film's airborne substrate: every emitter FURROW has, the numbers they are made of, and the one verb that poses them all for a film second. `Sand.component` is the long-lived context that calls this; nothing here reads a clock of its own. ## Verbs | call | what it does | |---|---| | `sand.create(particles)` | build every emitter once. Returns the emitter set. | | `sand.step(S, t, step, camX, camY, camZ, density)` | pose everything for film second `t` and advance it by `step`. | | `sand.burst(S, x, y, z, count, spread)` | throw a burst of sand at a point. | | `sand.plates(S, x, y, z, radius, count)` | throw a fan of crust plates. | | `sand.audit(t)` | every emitter running at film second `t`, without disturbing the film. | | `sand.destroy(S)` | release every GPU buffer. | ## Reading the shot table `sand.shotAt(t)` gives the set-up index and how far through it the film is. `sand.camPoint(i, u)` and `sand.lookPoint(i, u)` read `film.shots`' `pos` and `look`, both of which take a point, a list of points walked as a polyline, or an entity NAME string — all three shapes are read here so no caller has to know which a given set-up used. ## The tuning block Everything a viewer sees is at the top of `init.luau`: - `GAIN` — one multiplier over every airborne colour. The particle sprite shader is unlit, so a grain's colour is the colour it draws at. - `WIND_DIR` / `WIND_CALM` / `WIND_GALE` — one wind for the whole film, whose speed rides `film.clarity(t)`. - `CRESTS` — the eleven dune crests that smoke, sampled off the baked heightfield as local maxima outside the pan. - `FURROW_PATH` — where the ridge stands, keyframed. - `HAZE` — one row per set-up, because a shot 4 cm off the crust and a shot 320 m up need motes four orders of magnitude apart in size. This table is what makes something airborne in every single frame of the film. ## Authoring `sand.previewAt = <film second>` runs the slice from that instant at `sand.previewRate`, in edit mode as well as play, so any moment can be framed without waiting for the film. `nil` gives the clock back to the film. `sand.at` reports the film second the sand last posed itself for.

# furrow.collapse The order in which the salt pan is destroyed on camera. A list of one-shot BEATS, each pinned to a `film.mark`: the ground giving way under the rig, the eighteen masts going down west to east, the rig dropping out of the bottom of frame, the pan floor doming and shedding its crust, the breach, and the head coming down 300 m out. `step` fires the ones the clock has just crossed and nothing else, so the film destroys the place the same way every run and a beat that moves in `film.mark` moves here with it. ## Verbs | call | what it does | |---|---| | `collapse.create()` | build the schedule. | | `collapse.step(C, S, t)` | fire every beat the clock has just crossed. `S` is the sand slice's emitter set. | | `collapse.rearm(C, from)` | re-arm every beat at or after `from`, so a held preview instant repeats its collapse instead of firing it once. | ## What a beat fires - `effects.play` on the shipped catalogue, repurposed. `combat.impact` at `surface = "dirt"` throws no sparks and a slow brown cloud, which is a collapsing ground rather than a gunshot; `combat.shockwaveRing` in the pan's own gypsum colour is the pressure front running out across the flat. - The sand slice's own burst and crust-plate emitters, through `sand.burst` and `sand.plates`. Both are fired from the component's `update`. An effect played from a one-shot script is registered and never stepped. ## Where the masts are `film.geo.mastFrom`, `mastTo` and `mastCount`. The masts themselves belong to another slice; this reads the same geography they are placed against, so a burst lands at a mast's foot without either slice knowing about the other.

# filmClock <!-- 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.