# deadlight.sub.rig The submersible *Nautile*, built out of primitives, plus the five emitters it puts into the water. ```luau local Rig = require("deadlight.sub.rig") local h = Rig.build() -- idempotent: an existing Nautile is taken away first ``` `build()` returns the handles the driver writes to: the root, the three thruster hubs, the three lamp pivots, the beacon, the four arm joints, and the five particle systems (`beamPort`, `beamStbd`, `beamSpot`, `wash`, `ballast`). ## The vehicle's local frame `-Z` is the way it faces — the same convention the wreck's bow uses and the one `Transform.quatFromBasis` calls forward. `+Y` is up through the sail, `+X` is starboard. The hull is 8.2 m long, 2.9 m across the fairing and 3.6 m from the skids to the beacon, which is the envelope the shot list is framed against: shot 3 puts the camera 1.7 m to port of the root, just outside the skin. The landing gear sits 1.1 m under the origin, because `Film.SUB_PATH` puts the origin 1.1 m off the silt in the debris field. ## Materials Nine `.material` assets under `deadlight/sub/materials/`, authored by `build()` with `overwrite = true`. They are referenced by their FULL identity (`deadlight.sub.materials.dl_sub_foam`): a bare leaf that also exists elsewhere in the world is ambiguous, and a `Model` handed the ambiguous name keeps the raw string unresolved and renders untextured. On the pbr shader `emissive` is the glow COLOUR and `emissive_intensity` is how hard it glows. There is no `emissive_color`. ## The lamps `face = "Back"` on every `SpotLight` — that is the lamp's local `-Z`, the direction the vehicle is aimed along. `"Front"` is `+Z` and shines out of the stern ([#8632](https://github.com/OrigoZero/zero/issues/8632)). Each lamp carries a **beam cone**: a dense additive emitter firing along the lamp's own axis, its particles widening and dimming down the cone. The engine's participating medium reports active and never dispatches ([#7760](https://github.com/OrigoZero/zero/issues/7760)), so the beam is the suspended matter drawn rather than a fog march — which also means the specks in it drift, and a marched medium's never would. The emitters are bare `particles.create` calls with `autoUpdate = false`: the clock belongs to the film, and `SubRig` steps each of them by exactly `Film.DT` per film frame.

# deadlight.sub.drive How the Nautile moves, aims and articulates — pure functions of film time. Nothing here touches an entity, so every number in the vehicle's performance can be checked without a scene. ```luau local Drive = require("deadlight.sub.drive") Drive.forward(41.0) -- unit heading Drive.rotation(41.0) -- { x, y, z, w } Drive.thrust(41.0) -- 0..1, drives props and wash Drive.lampGain(41.0) -- { port, stbd, spot }, 0..1 Drive.lampRange(41.0) -- ({ port, stbd, spot } metres, beamThrow) Drive.lampCone(41.0) -- { { outerDeg, innerDeg }, ... } Drive.lampTargets(41.0) -- world points the lamps are aimed at, or nils Drive.reach(80.0) -- how far the manipulator is out, 0..1 Drive.armPose(80.0, v) -- { yaw, shoulder, elbow, wrist } radians Drive.beacon(20.4) -- the one strobe ``` ## The one rule Position comes from `Film.subPoseAt(t)` and is never adjusted. The camera is framed against those keys, so the vehicle rides them exactly and expresses itself entirely in rotation. ## Heading `Film.SUB_PATH` is a polyline with three deliberate CUTS in it — keys a hundredth of a second apart. A cut is a change of shot, not a movement, so the heading is read off the segment the vehicle is actually flying and never across the jump, and the turn into the next segment is eased over the last 1.6 s of the current one. Movement I is a ballasted descent, not flight. Reading the heading off the path there would stand the vehicle on its nose for twenty-four seconds, so it hangs level and turns slowly on its own axis, easing into the path heading across the last second before the cut at 24 s. ## The manipulator A two-bone solve toward the cup — the wreck slice's `PorcelainCup` if it is in the world, otherwise the contracted debris-field point the shot is framed on — blended against a stowed pose by `reach(t)`. `reach` IS the performance: out over the first 40% of shot 13, a hesitation with a tremor that gives a little and does not commit, and back over the last 30%. ## Note on ramps `smooth(edge0, edge1, x)` here guards its denominator by magnitude, not by `math.max`. Several of these ramps DESCEND, and a `math.max(1e-6, …)` guard silently turns a falling ramp into a step at `edge0` that never comes back down.

# film The shared constants and the film clock for DEADLIGHT. Every slice of the demo reads this module and nothing restates its numbers. It holds three things: - The timing spine — the 14 shots, their durations and their windows. `Film.SHOTS`, `Film.shotAt(t)`, `Film.window(n)`, `Film.movementAt(t)`. Durations live here and nowhere else. - The world contract — the shared coordinate frame (`Film.WORLD`), the named entities each slice owns (`Film.NAMES`), the submersible's contracted path (`Film.SUB_PATH` / `Film.subPoseAt(t)`), the anchor fallbacks that let the film play while it is still being built (`Film.ANCHORS`), the palette (`Film.PALETTE`) and the water's optics (`Film.WATER`). - The clock — a fixed 1/24 s step advanced once per RENDERED frame by `deadlight.FilmDirector`, never from wall time. 2,256 rendered frames is exactly the 94-second film, every time. ```luau local Film = require("deadlight.film") Film.restart() -- t := 0, every slice resets, playing := true Film.seek(48.0) -- deterministic scrub to a moment Film.status() -- where the film is and who has joined it Film.register("abyss", { -- join from your own component's awake() reset = function() end, tick = function(t, dt) end, shot = function(n, tLocal) end, }) ``` Handlers run inside `pcall`, so one slice erroring cannot stop the film for the others. Registering a name twice replaces its handlers.