# debris What is left of people. Nothing in the debris field is wreckage. It is crockery, a shoe, a light fitting: the ordinary contents of a ship, spread out on the bottom by the current that sorted them and half-buried by a century of silt. ```luau local D = require("deadlight.wreck.debris") D.build(M) -- the whole field D.cup(M, at, tilt, scale) -- a White Star cup, handle and all D.shoeSole(M, at, yaw) -- the one object that says a person D.handwheel(M, at, axis) D.chandelierArm(M, at, yaw) D.CUP -- where shot 13 looks, and where the arm reaches ``` **`D.CUP` is a contract with the sub slice.** The manipulator arm articulates down over that exact point at 76-84 s, hesitates, and withdraws. **The four hero objects are strung along the line shot 12 creeps down** — the camera runs from (6.5, 249) to (2.0, 256) looking at (0, 262) — so the lens passes within two or three metres of each in the order the beat wants. A seventy-degree lens turns a teacup at eight metres into three pixels, so what carries the beat between them is a corridor dressed at plate-and-basin size, with the crockery, bottles, brass port rims and bunker coal that a liner actually spills. Everything else is scattered in drift LINES across the current, and every object has silt banked on its up-current side.

# surfaces Every surface the wreck wears, made from numbers. Nothing here is a file: four tiling textures are generated pixel by pixel at build time from a deterministic wrapping-lattice noise, uploaded with `renderer.texture.create`, and bound into runtime `pbr_layered` materials. The content is the code, so a rebuild always produces the same surfaces and there is no binary to keep in step with it. ```luau local S = require("deadlight.wreck.surfaces") local mats = S.build() -- memoised; safe from every awake mats.hull, mats.deck, mats.crusted, mats.rusticle, mats.steel, mats.silt, mats.porcelain, mats.brass, mats.leather, mats.voidBlack S.invalidate() -- drop the memo and re-derive on the next build ``` **The plate texture is a 3 x 3 BLOCK of plates**, not one. One plate per texture tiled onto plating repeats every two metres and the eye catches it instantly; nine plates, each carrying its own corrosion and its own rust, repeat every six and read as a hull. Meshes author UVs in plate units and scale them by `S.UV` (= 1 / `S.CELLS`) to match. **Authored for raking light at close range.** The film has no sun below 200 m: the submersible's three lamps are the only light in the world, they are 6-20 m away, and red dies first in the water. So roughness and normal detail carry the read and base colour barely does — the plate's height field is a seam groove around each plate with a double row of rivets inside it, pitted by a century of corrosion, and that is what a lamp crossing the side actually finds. **Rust is the surface, not a weathering pass over it.** `mats.hull`'s base layer is oxide over the whole plate and its top layer is the calcareous crust that grows on top where the current lets it settle; bare steel survives only on a broken edge, which wears `mats.steel`. `mats.voidBlack` is unlit black — what is behind an open porthole, a hawse pipe or a wheelhouse window, because a lamp six metres away must not find a wall there.

# fittings Everything bolted to the ship: the anchor still in its hawse, the forecastle's windlass and capstans and the chain faked on deck, the port rail with its bollards and bitts, the runs of portholes and the one hero deadlight whose cover hangs half open, and the bridge front with the officers' quarters behind it. ```luau local F = require("deadlight.wreck.fittings") F.buildPortholes(M) -- three rows a side, the hero deadlight among them local where = F.buildAnchor(M) -- returns { anchor, chainHead, flukeTip } F.buildForecastle(M) F.buildRail(M) F.buildBridge(M) F.chainRun(M, from, to, sag) -- studless link, every second one turned 90 degrees ``` `M` is a table of `deadlight.wreck.geom` meshes keyed by the material each will be drawn with — `hull`, `deck`, `steel`, `crust`, `void` — so the whole ship uploads as one mesh per material. **`F.DEADLIGHT` names the hero porthole** (z = 40, y = 14, port side). Shot 10 spends seven seconds on it, so the porthole run is PHASED to land a station exactly there rather than merely passing near it, and its cover is swung far enough past the vertical that the black opening is what the lens finds. **A hole is a cone, not a barrel.** A barrel's far wall faces away from the lens and a back-face cull sends the lamp straight through it onto the lit plating behind, so the hole reads white. Every opening here — porthole, hawse pipe, chain pipe, funnel casing — is driven back into the ship as a cone in `mats.voidBlack`. **`F.HAWSE` is where the anchor is**, on the hull's own surface eight metres abaft the stem. `Film.ANCHORS.PortAnchor` puts its fallback 13.2 m off the centreline, which is about five metres outboard of where the plating actually is at that station; `buildAnchor` returns the real place and the slice spawns the `PortAnchor` entity there, so a shot framed against the name frames the anchor rather than open water.

# geom A triangle-soup builder. Every piece of the wreck — plating, rivet steps, porthole rings, chain links, rusticles, a porcelain cup — is appended into one growing vertex/index buffer and uploaded once with `renderer.mesh.create`, so a ship of a hundred thousand triangles is a handful of draw calls. ```luau local G = require("deadlight.wreck.geom") local m = G.new() G.box(m, { 0, 0, 0 }, { 2, 1, 4 }) G.tube(m, { 0, 0, 0 }, { 0, 1, 0 }, 3.0, 0.4, 0.25, 12, true) local handle = G.upload(m) ``` **Shapes.** `box` / `boxIn` (axis-aligned, or in a frame), `tube` (a swept cone with optional caps), `sphere` (with a `squashY` for a dome or a lens), `torus`, `quad` (four world points, normal from the winding) and `quadNV` (four points each carrying its own normal — what keeps a lofted hull smooth across a station while its strake seams stay hard). **Frames.** `axisFrame(origin, forward, scale)` builds an orthonormal basis around a direction and `at(frame, a, b, c)` is a point in it, which is how a fitting is placed against a hull surface whose normal is not an axis. **UVs are in PLATE UNITS, not 0..1.** One unit of `u` is one strake and one unit of `v` is one plate length, so the seam grooves and rivet rows in `deadlight.wreck.surfaces`' plate texture land on the real seams of the real plating. `box`'s `uvScale` converts metres to those units for a fitting. Positions are world-space metres in the wreck's own frame; the slice offsets them by parenting the result under an anchor entity placed at the position `Film.ANCHORS` names.

# growth Rusticles: the thing on this wreck that is alive. A rusticle is a hanging column of iron-eating bacteria and their oxide, and on a real wreck it is the only thing that MOVES — it hangs from the plating, sways in the bottom current, and eventually parts under its own weight and falls its whole length. Every shot the wreck slice serves has rusticles in it and every one of them has to be moving. ```luau local Growth = require("deadlight.wreck.growth") Growth.clump(mesh, seed, count, scale) -- geometry hanging from the ORIGIN Growth.plan() -- deterministic placement, one per clump Growth.sway(clump, t) -- the rotation at film time t ``` **They are built as CLUMPS with the hang point at the mesh origin**, one entity each, so rotating the entity swings the whole clump the way a real one swings. The slice builds fourteen template meshes and reuses them across sixty-odd placements, which keeps the whole population to one upload per template. `plan()` festoons everything the lamps get near: down the whole port side, sparser to starboard for the wide shots, under the bulwark cap where shot 9 runs the camera past at deck height, along the torn break for shot 14, and under the bridge wings for shot 11. Its generator is a private LCG rather than `math.random`, because three other slices share this engine and the wreck has to look the same on every build. `sway` is a slow pendulum with a faster flutter on it, so two frames two seconds apart are never the same picture — and it is a function of film time alone, so two runs of the film are the same film.

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

# hull The shape of the ship, and the plating on it. `Hull.point(side, s, z)` is the whole hull as one function: `s` runs 0 at the keel to 1 at the sheer, `z` runs from the stem into the break at 190, and `side` is -1 for port and +1 for starboard. Everything else in the slice — the hawse pipe, the rail, the porthole rows, the rusticles' hanging points — asks this function where the surface is, so nothing is placed by a number typed twice. ```luau local Hull = require("deadlight.wreck.hull") Hull.sheerY(z) -- the weather deck's height along the ship Hull.stemZ(y) -- the raked leading edge at that height Hull.halfBeam(z, y) -- half the breadth at a station and a height Hull.deckEdge(side, z) -- where the rail and the bollards stand Hull.onShell(side, z, y, out) -- a fitting `out` metres clear of the plating ``` The builders append into a `deadlight.wreck.geom` mesh: `buildShell`, `buildBottom`, `buildStem`, `buildDeck`, `buildBulwark`, `buildBreak`. **The plating is built strake by strake with alternating in-and-out laps.** Every other strake stands 6 cm proud of its neighbours, exactly as a riveted hull is built, and between two strakes there is a real step face — so a lamp raking along the side catches a hard edge rather than a texture pretending to be one. UVs come out in plate units (u = strake index, v = z / `PLATE_LEN`), which is what lands the rivet rows on the real seams. **The aft end is a tear, not a cut.** Each strake ends at its own z and its lip is pulled inboard, so the break reads as peeled steel — the last thing the lamps come off in shot 14. The seafloor is y = 0 and `KEEL_Y` is -8.6, so eight and a half metres of the hull are under the silt, exactly as `Film.WORLD` states.