@driftengine/core 3.61.0

package/dist/render/camera.js

@@ -0,0 +1,304 @@
+import { mat4, vec3 } from 'gl-matrix';
+import { DEG_TO_RAD } from '../math/scalar.js';
+/** Reused by `project`; a per-call vec4 would allocate on every pointer move. */
+const projected = new Float32Array(4);
+/** Reused by `rayThrough`; this runs on every pointer move. */
+const nearPoint = new Float32Array(4);
+const farPoint = new Float32Array(4);
+/** One NDC point back through the inverse view-projection, with the perspective divide. */
+function unproject(out, inv, x, y, z) {
+    const w = inv[3] * x + inv[7] * y + inv[11] * z + inv[15];
+    const scale = w === 0 ? 1 : 1 / w;
+    out[0] = (inv[0] * x + inv[4] * y + inv[8] * z + inv[12]) * scale;
+    out[1] = (inv[1] * x + inv[5] * y + inv[9] * z + inv[13]) * scale;
+    out[2] = (inv[2] * x + inv[6] * y + inv[10] * z + inv[14]) * scale;
+}
+/**
+ * Perspective camera. Yaw/pitch convention: yaw 0 looks toward -Z, positive
+ * yaw turns right (+X); positive pitch looks up.
+ */
+export class Camera {
+    position = vec3.create();
+    yaw = 0;
+    pitch = 0;
+    fovYDeg = 70;
+    /**
+     * Near plane, metres — and the single biggest control this engine has over
+     * z-fighting.
+     *
+     * A conventional depth buffer spends its precision hyperbolically: the smallest
+     * separation it can resolve at distance `z` is about `z² / (near · 2^bits)`. At
+     * the old 0.1 that is a quarter of a millimetre at twenty metres, **1.5 mm at
+     * fifty, and 6 mm at a hundred** — so any two surfaces closer together than that
+     * are decided by float rounding, and which one a pixel shows changes as the
+     * camera moves — shown most clearly by a matched pair of screenshots of one seam
+     * from two angles, right in one and wrong in the other.
+     *
+     * Precision scales linearly with this number, so four times the near plane is
+     * four times the resolution at every distance, and it costs nothing. Safe at 0.4
+     * because a third-person boom never brings the eye closer than `BOOM_MIN` (0.9 m)
+     * to the character and keeps its own radius clear of surfaces — there is nothing
+     * legitimately within 40 cm of this camera to clip.
+     *
+     * It is a mitigation and not the cure. A 0.2 mm seam, which the daily generator
+     * does produce where two decks meet, still fights past about forty metres. The
+     * cure is a reversed-Z float depth buffer; see `docs/bugs/`.
+     */
+    near = 0.4;
+    far = 500;
+    forward = vec3.create();
+    view = mat4.create();
+    projection = mat4.create();
+    viewProjection = mat4.create();
+    invViewProjection = mat4.create();
+    /**
+     * Roll about the view direction, radians. Positive drops the right side.
+     * Render-only: nothing about the camera reaches the simulation.
+     */
+    roll = 0;
+    /**
+     * Point the camera at a world position from wherever it currently stands.
+     *
+     * Added because three callers had each derived this by hand and one of them got it
+     * wrong: a preview rig placed itself on a circle around its subject and computed a yaw
+     * that was exactly π out, so it rendered the inside of an empty box and the figure it was
+     * built to show was behind it. The trig is four lines and the sign conventions are this
+     * class's own — `yaw 0` looks toward −Z, positive yaw turns toward +X — so leaving every
+     * caller to rediscover them is leaving them a trap.
+     *
+     * Sets `yaw` and `pitch` only. Roll is a separate decision (it is a lean, not an aim),
+     * and `updateMatrices` still has to be called afterwards.
+     */
+    lookAt(x, y, z) {
+        const dx = x - (this.position[0] ?? 0);
+        const dy = y - (this.position[1] ?? 0);
+        const dz = z - (this.position[2] ?? 0);
+        const flat = Math.hypot(dx, dz);
+        // Straight up or down leaves yaw meaningless, so it is left as it was rather than
+        // snapped to zero — which would spin the view on the way past vertical.
+        if (flat > 1e-6)
+            this.yaw = Math.atan2(dx, -dz);
+        this.pitch = Math.atan2(dy, flat);
+    }
+    updateMatrices(aspect) {
+        const cosPitch = Math.cos(this.pitch);
+        const sinPitch = Math.sin(this.pitch);
+        const cosYaw = Math.cos(this.yaw);
+        const sinYaw = Math.sin(this.yaw);
+        vec3.set(this.forward, sinYaw * cosPitch, sinPitch, -cosYaw * cosPitch);
+        /*
+         * The view basis is derived from the angles, and **not** by aiming a look-at at
+         * `position + forward`, which is what this did for as long as it existed.
+         *
+         * A look-at builds its right axis by crossing the view direction with world up, so it has
+         * nothing to work with when the two are parallel — and at a pitch of ±π/2 they are. What
+         * hid that for so long is that `cos(π/2)` is 6.1e-17 rather than 0, so the horizontal part
+         * of the direction survives *if it survives the addition*, and in a `Float32Array` that
+         * depends on where the camera is standing: at the origin the epsilon is kept and the basis
+         * is fine, and past about half a metre on the axis in question it is rounded away, the
+         * cross product collapses to zero, and the view matrix is singular.
+         *
+         * A singular view does not draw a wrong picture, it draws none: every vertex lands on one
+         * point, so the frame keeps its clear colour, and `invert` below fails and silently leaves
+         * whatever the previous aim put in `invViewProjection` — which the sky pass then reads as
+         * though it were this one's. **Measured on a reflection probe**, whose up and down faces are
+         * the only two in the engine that ever aim straight at a pole: both came back holding one
+         * stale copy of a sideways face, in every world whose subject does not stand at the origin.
+         *
+         * Right is `(cos yaw, 0, sin yaw)` and does not depend on pitch at all, so it is unit length
+         * at every aim including both poles, and up follows from it and the direction. The result
+         * matches what the look-at produced everywhere the look-at was well defined, including the
+         * mirrored frame it gave past vertical, which `lean` keeps.
+         *
+         * What it gives up: a camera tilted past vertical still mirrors rather than rolling over the
+         * top, because that is the behaviour that shipped and nothing here aims there — every
+         * consumer clamps pitch well inside a quarter turn. A camera meant to loop, in a cockpit or
+         * a free-flight view, wants `lean` dropped and the basis carried continuously instead.
+         */
+        const lean = cosPitch < 0 ? -1 : 1;
+        let rightX = lean * cosYaw;
+        /* Level until something rolls it: right is horizontal at every pitch. */
+        let rightY = 0;
+        let rightZ = lean * sinYaw;
+        let upX = -lean * sinYaw * sinPitch;
+        let upY = lean * cosPitch;
+        let upZ = lean * cosYaw * sinPitch;
+        /*
+         * Up is rolled about the view direction rather than fixed to world up.
+         *
+         * A camera that stays level while the surface under the subject banks makes
+         * the *world* look like it is tilting, which is exactly backwards: the
+         * player is the thing that tilted. Rolling with them is what makes a banked
+         * corner read as leaning into it.
+         *
+         * Both axes turn together, which is the same rotation the previous construction reached by
+         * rolling world up and letting the look-at re-derive right from it — and unlike that one it
+         * still turns something when the camera is aimed at a pole.
+         *
+         * **The sign is the shipped one and it is the opposite of a positive rotation about the view
+         * direction**, which is worth stating because the construction this replaced carried a
+         * comment naming the positive form while its code computed the negative one. Following the
+         * comment turned every rolled frame the wrong way by twice the angle: measured as 384,242
+         * pixels of 921,600 on the one demo scene that rolls, against a floor of 47.
+         */
+        if (this.roll !== 0) {
+            const cosRoll = Math.cos(this.roll);
+            const sinRoll = Math.sin(this.roll);
+            const turnedRightX = rightX * cosRoll + upX * sinRoll;
+            const turnedRightY = upY * sinRoll;
+            const turnedRightZ = rightZ * cosRoll + upZ * sinRoll;
+            upX = upX * cosRoll - rightX * sinRoll;
+            upY = upY * cosRoll;
+            upZ = upZ * cosRoll - rightZ * sinRoll;
+            rightX = turnedRightX;
+            rightY = turnedRightY;
+            rightZ = turnedRightZ;
+        }
+        const eyeX = this.position[0] ?? 0;
+        const eyeY = this.position[1] ?? 0;
+        const eyeZ = this.position[2] ?? 0;
+        const forwardX = this.forward[0] ?? 0;
+        const forwardY = this.forward[1] ?? 0;
+        const forwardZ = this.forward[2] ?? 0;
+        /* Column major, and the third row is the direction negated: a view looks down -Z. */
+        const view = this.view;
+        view[0] = rightX;
+        view[1] = upX;
+        view[2] = -forwardX;
+        view[3] = 0;
+        view[4] = rightY;
+        view[5] = upY;
+        view[6] = -forwardY;
+        view[7] = 0;
+        view[8] = rightZ;
+        view[9] = upZ;
+        view[10] = -forwardZ;
+        view[11] = 0;
+        view[12] = -(rightX * eyeX + rightY * eyeY + rightZ * eyeZ);
+        view[13] = -(upX * eyeX + upY * eyeY + upZ * eyeZ);
+        view[14] = forwardX * eyeX + forwardY * eyeY + forwardZ * eyeZ;
+        view[15] = 1;
+        /*
+         * A **vertical** field of view, which is a promise worth stating because a consumer built an
+         * interface on it.
+         *
+         * Because the vertical extent is what is held, a projection keeps its top and bottom when the
+         * aspect changes and trades only horizontal. So a tall export is exactly what a centred
+         * rectangle of a wider preview sees, and a frame drawn over that preview is arithmetic rather
+         * than an approximation: no second render, no two paths to compare.
+         *
+         * The corollary belongs beside it. Only a *centred* crop of a symmetric frustum is itself a
+         * symmetric frustum; an off-centre one is sheared, which `perspective` cannot produce. A
+         * consumer wanting an off-axis preview needs `mat4.frustum`, which gl-matrix already exports
+         * and this engine does not wrap. Panning the camera instead is a real pan and lands in an
+         * export as one.
+         */
+        mat4.perspective(this.projection, this.fovYDeg * DEG_TO_RAD, aspect, this.near, this.far);
+        mat4.multiply(this.viewProjection, this.projection, this.view);
+        mat4.invert(this.invViewProjection, this.viewProjection);
+    }
+    /**
+     * Take a view and a projection that were computed somewhere else.
+     *
+     * **Because an XR eye cannot be described by this class, and this file already says why.**
+     * `updateMatrices` derives the view from yaw and pitch and the projection from
+     * `mat4.perspective`, and the note above it records the corollary: *only a centred crop of a
+     * symmetric frustum is itself a symmetric frustum; an off-centre one is sheared, which
+     * `perspective` cannot produce.* A headset's eye projection is exactly that shear, off-axis by
+     * the distance from the pupil to the display's centre, and its view comes from a pose no pair of
+     * Euler angles was ever asked to describe.
+     *
+     * So a supplied view is adopted rather than configured. Everything downstream reads `view`,
+     * `projection`, `viewProjection` and `invViewProjection`, so frustum culling, picking, the sky
+     * and every pass that samples the inverse keep working with nothing changed.
+     *
+     * **`position` and `forward` are decomposed back out**, and that is not a convenience. A view
+     * matrix is the inverse of the camera's world transform, so the eye is `-Rᵀt` and the direction
+     * is the third row negated. A consumer reading `camera.position` to place a listener or to score
+     * a level of detail would otherwise get whatever the last non-XR frame left there, which is a
+     * defect that looks like an audio bug rather than a camera one.
+     *
+     * **`yaw`, `pitch` and `roll` are deliberately left alone**, and reading them after this is
+     * reading the last angles somebody set. A supplied rotation may be one no Euler triple
+     * describes without a convention this class does not own, and inventing one here would put a
+     * second answer to "where is the camera looking" beside `forward`, which is derived from the
+     * matrix and is always right.
+     *
+     * `near` and `far` are not read and not written: the supplied projection carries its own depth
+     * range, which the runtime chose.
+     */
+    adoptView(view, projection) {
+        mat4.copy(this.view, view);
+        mat4.copy(this.projection, projection);
+        mat4.multiply(this.viewProjection, this.projection, this.view);
+        mat4.invert(this.invViewProjection, this.viewProjection);
+        /*
+         * The rotation is the upper-left 3x3 and it is orthonormal, so its inverse is its transpose
+         * and the eye falls out without a general inverse. Reading the matrix rather than inverting it
+         * also keeps this allocation-free, which matters because it runs once per eye per frame.
+         */
+        const v = this.view;
+        const rx = v[0], ry = v[4], rz = v[8];
+        const ux = v[1], uy = v[5], uz = v[9];
+        const bx = v[2], by = v[6], bz = v[10];
+        const tx = v[12], ty = v[13], tz = v[14];
+        vec3.set(this.position, -(rx * tx + ux * ty + bx * tz), -(ry * tx + uy * ty + by * tz), -(rz * tx + uz * ty + bz * tz));
+        /* The third row of the rotation is the camera's backward axis, so forward is its negation. */
+        vec3.set(this.forward, -bx, -by, -bz);
+    }
+    /**
+     * Where a world point lands on the canvas, in CSS pixels, or false if it is behind.
+     *
+     * For attaching DOM to a place in the world: a focus ring on a card, a label on a
+     * marker. The caller passes the CSS box rather than the drawing buffer, because the
+     * answer is for the document and the document does not know the device pixel ratio.
+     *
+     * **False rather than a coordinate when w <= 1e-6.** The perspective divide by a negative
+     * w mirrors the point through the origin, so a thing behind the viewer reports a
+     * perfectly plausible position on the opposite side of the screen. A caller that
+     * placed an affordance there would be putting it on the wrong object, which is worse
+     * than putting it nowhere.
+     */
+    project(out, x, y, z, cssWidth, cssHeight) {
+        const m = this.viewProjection;
+        const w = m[3] * x + m[7] * y + m[11] * z + m[15];
+        if (w <= 1e-6)
+            return false;
+        projected[0] = (m[0] * x + m[4] * y + m[8] * z + m[12]) / w;
+        projected[1] = (m[1] * x + m[5] * y + m[9] * z + m[13]) / w;
+        out[0] = (projected[0] * 0.5 + 0.5) * cssWidth;
+        out[1] = (0.5 - projected[1] * 0.5) * cssHeight;
+        return true;
+    }
+    /**
+     * The ray a pixel looks along, in world space.
+     *
+     * Two points are unprojected rather than one, because a direction cannot be recovered
+     * from a single unprojected point without knowing where the eye is in the same space —
+     * and for an orthographic camera there is no single eye at all. Unprojecting both ends
+     * of the depth range and subtracting is correct for either projection, which is why it
+     * is written this way for a camera that is currently only perspective.
+     *
+     * `cssX`/`cssY` are in the canvas's CSS box, so a caller hands over
+     * `event.clientX - rect.left` and nothing has to know the device pixel ratio.
+     */
+    rayThrough(origin, direction, cssX, cssY, cssWidth, cssHeight) {
+        const ndcX = (cssX / cssWidth) * 2 - 1;
+        const ndcY = 1 - (cssY / cssHeight) * 2;
+        unproject(nearPoint, this.invViewProjection, ndcX, ndcY, -1);
+        unproject(farPoint, this.invViewProjection, ndcX, ndcY, 1);
+        origin[0] = nearPoint[0];
+        origin[1] = nearPoint[1];
+        origin[2] = nearPoint[2];
+        let dx = farPoint[0] - nearPoint[0];
+        let dy = farPoint[1] - nearPoint[1];
+        let dz = farPoint[2] - nearPoint[2];
+        const length = Math.hypot(dx, dy, dz) || 1;
+        dx /= length;
+        dy /= length;
+        dz /= length;
+        direction[0] = dx;
+        direction[1] = dy;
+        direction[2] = dz;
+    }
+}

package/dist/render/causticsRenderer.d.ts

@@ -0,0 +1,63 @@
+import type { FrameView } from './frameView.ts';
+import type { Vec3 } from '../math/color.ts';
+import type { Atmosphere } from './atmosphere.ts';
+import type { SheetSpan } from './surfaceSheet.ts';
+/**
+ * A surface lit by nearby water: the floor of a pool, the bottom of a flooded
+ * corridor, the underside of a bridge, an arch, a jetty, a cave mouth.
+ *
+ * The caller submits the lit surface and says which body of water is throwing the
+ * light. Everything else — where the light lands, how sharp the net is, how it
+ * moves — comes from the wave field in `shaders/gerstner.ts`, which is the same
+ * field the water surface itself is displaced by.
+ *
+ * Either side of the surface works. The overhead case came first and passed for
+ * the whole feature for a while, but a pool floor is the same optics and by far
+ * the more ordinary sight; the sheet simply lies under the water instead of over
+ * it.
+ */
+export interface CausticSheet {
+    /** Cross-sections of the lit surface, in order. */
+    spans: readonly SheetSpan[];
+    /**
+     * Resting height of the water throwing the light.
+     *
+     * Per sheet rather than per draw, so one batch can carry surfaces above and
+     * below water at different heights — and so a caller cannot forget to keep the
+     * two in step, which is the whole contract of this feature: the pattern is only
+     * worth having because it is the crests the player can see.
+     */
+    waterY: number;
+}
+/**
+ * How far from the water the effect has died out.
+ *
+ * Not a fade for performance — a physical limit. The net spreads with distance and
+ * is gone by the time a soffit is a dozen metres up, or a pool that deep. A road
+ * bridge over a canal is around six, which is comfortably inside it; the fade
+ * starts at 45% of this so that distance is not already dimmed.
+ */
+export declare const CAUSTICS_MAX_DROP_M = 12;
+/**
+ * Cells across a lit surface.
+ *
+ * The pattern is a fragment computation, so this only has to be fine enough for
+ * the linear terms — distance fog and the edge fade — not for the waves.
+ */
+export declare const CAUSTICS_CELL_M = 3;
+export declare class CausticsRenderer {
+    private readonly program;
+    private readonly uniforms;
+    private readonly vao;
+    private readonly buffers;
+    private readonly vertexCount;
+    constructor(gl: WebGL2RenderingContext, sheets: readonly CausticSheet[]);
+    /**
+     * Add the water's light to an already-shaded scene. Draw after the opaque
+     * pass: this is light arriving at a surface, not the surface.
+     *
+     * @param strength scales the whole effect; 1 is the calibrated default.
+     */
+    draw(gl: WebGL2RenderingContext, camera: FrameView, timeSeconds: number, directionalDir: Vec3, directionalColor: Vec3, ambient: Vec3, atmosphere: Atmosphere, underwaterEnabled: boolean, windX?: number, windZ?: number, strength?: number): void;
+    dispose(gl: WebGL2RenderingContext): void;
+}

package/dist/render/causticsRenderer.js

@@ -0,0 +1,119 @@
+import { compileProgram, uniformLocations } from './shader.js';
+import { CAUSTICS_FRAG, CAUSTICS_VERT } from './shaders/caustics.js';
+import { bindAtmosphere } from './atmosphere.js';
+import { buildSheets } from './surfaceSheet.js';
+import { seaStateForWind } from './seaState.js';
+/**
+ * How far from the water the effect has died out.
+ *
+ * Not a fade for performance — a physical limit. The net spreads with distance and
+ * is gone by the time a soffit is a dozen metres up, or a pool that deep. A road
+ * bridge over a canal is around six, which is comfortably inside it; the fade
+ * starts at 45% of this so that distance is not already dimmed.
+ */
+export const CAUSTICS_MAX_DROP_M = 12;
+const MAX_DROP_M = CAUSTICS_MAX_DROP_M;
+/**
+ * Cells across a lit surface.
+ *
+ * The pattern is a fragment computation, so this only has to be fine enough for
+ * the linear terms — distance fog and the edge fade — not for the waves.
+ */
+export const CAUSTICS_CELL_M = 3;
+const CELL_M = CAUSTICS_CELL_M;
+/** Reused per frame: the colour of the light the water is reflecting. */
+const scratchTint = new Float32Array(3);
+export class CausticsRenderer {
+    program;
+    uniforms;
+    vao;
+    buffers = [];
+    vertexCount;
+    constructor(gl, sheets) {
+        this.program = compileProgram(gl, CAUSTICS_VERT, CAUSTICS_FRAG, 'caustics');
+        this.uniforms = uniformLocations(gl, this.program, 'causticsRenderer');
+        const mesh = buildSheets(sheets, CELL_M, (sheet, out) => {
+            out[0] = sheet.waterY;
+            out[1] = 0;
+        });
+        this.vertexCount = mesh.vertexCount;
+        const vao = gl.createVertexArray();
+        if (vao === null)
+            throw new Error('CausticsRenderer: createVertexArray failed');
+        this.vao = vao;
+        gl.bindVertexArray(vao);
+        const attach = (data, location, size) => {
+            const buffer = gl.createBuffer();
+            if (buffer === null)
+                throw new Error('CausticsRenderer: createBuffer failed');
+            this.buffers.push(buffer);
+            gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+            gl.bufferData(gl.ARRAY_BUFFER, data, gl.STATIC_DRAW);
+            gl.enableVertexAttribArray(location);
+            gl.vertexAttribPointer(location, size, gl.FLOAT, false, 0, 0);
+        };
+        attach(mesh.positions, 0, 3);
+        attach(mesh.locals, 1, 2);
+        attach(mesh.params, 2, 2);
+        gl.bindVertexArray(null);
+    }
+    /**
+     * Add the water's light to an already-shaded scene. Draw after the opaque
+     * pass: this is light arriving at a surface, not the surface.
+     *
+     * @param strength scales the whole effect; 1 is the calibrated default.
+     */
+    draw(gl, camera, timeSeconds, directionalDir, directionalColor, ambient, atmosphere, underwaterEnabled, windX = 0, windZ = 0, strength = 1) {
+        if (this.vertexCount === 0)
+            return;
+        const u = this.uniforms;
+        gl.useProgram(this.program);
+        gl.uniformMatrix4fv(u['uViewProj'] ?? null, false, camera.viewProjection);
+        gl.uniform3fv(u['uCameraPos'] ?? null, camera.position);
+        gl.uniform1f(u['uTime'] ?? null, timeSeconds);
+        gl.uniform1f(u['uMaxDrop'] ?? null, MAX_DROP_M);
+        gl.uniform1f(u['uStrength'] ?? null, strength);
+        gl.uniform3fv(u['uLightDir'] ?? null, directionalDir);
+        /*
+         * What the water is reflecting: the dominant source, plus a share of the
+         * ambient standing in for the sky itself.
+         *
+         * The ambient term is not decoration. Under a bridge at night the sun
+         * contributes nothing, and a caustic that switched off with the sun would
+         * take the best image in the game with it — while skylight on water is a real
+         * source, and it is what a phone camera sees under a bridge after dusk.
+         */
+        scratchTint[0] = (directionalColor[0] ?? 0) * 0.85 + (ambient[0] ?? 0) * 1.5;
+        scratchTint[1] = (directionalColor[1] ?? 0) * 0.85 + (ambient[1] ?? 0) * 1.5;
+        scratchTint[2] = (directionalColor[2] ?? 0) * 0.85 + (ambient[2] ?? 0) * 1.5;
+        gl.uniform3fv(u['uTint'] ?? null, scratchTint);
+        // The same sea state, from the same wind, as every other body of water.
+        const windSpeed = Math.hypot(windX, windZ);
+        const sea = seaStateForWind(windSpeed);
+        const inv = windSpeed > 1e-5 ? 1 / windSpeed : 0;
+        gl.uniform2f(u['uWindDir'] ?? null, inv === 0 ? 1 : windX * inv, inv === 0 ? 0 : windZ * inv);
+        gl.uniform1f(u['uWaveGain'] ?? null, sea.steepness);
+        bindAtmosphere(gl, u, atmosphere, camera.position[1] ?? 0, underwaterEnabled);
+        gl.enable(gl.BLEND);
+        gl.blendFunc(gl.ONE, gl.ONE);
+        /*
+         * No depth write, but depth *testing* stays on: the sheet sits a couple of
+         * centimetres under the surface it lights, so geometry in front of it — the
+         * character, a lamp, the bridge's own parapet — still occludes the light.
+         */
+        gl.depthMask(false);
+        gl.disable(gl.CULL_FACE);
+        gl.bindVertexArray(this.vao);
+        gl.drawArrays(gl.TRIANGLES, 0, this.vertexCount);
+        gl.bindVertexArray(null);
+        gl.enable(gl.CULL_FACE);
+        gl.depthMask(true);
+        gl.disable(gl.BLEND);
+    }
+    dispose(gl) {
+        for (const buffer of this.buffers)
+            gl.deleteBuffer(buffer);
+        gl.deleteVertexArray(this.vao);
+        gl.deleteProgram(this.program);
+    }
+}

package/dist/render/cinematicCamera.d.ts

@@ -0,0 +1,102 @@
+import type { ColliderSet } from '@driftengine/physics';
+import { Camera } from './camera.ts';
+import type { ShotParams } from './shotPlacement.ts';
+/**
+ * A camera that can be *cut*, for replays and cinematics.
+ *
+ * The gameplay camera has one job — keep the player able to read where they are
+ * about to land — so it is a single smoothed rig that never surprises anyone. A
+ * replay camera has the opposite job: it is a director, and its whole
+ * vocabulary is choosing a new angle at the right instant.
+ *
+ * Generic on purpose. A shot here is a placement rule and a subject; which shot
+ * suits a grapple, and when to cut, are the game's business. Nothing in this
+ * file knows what a character is. *Where* a shot puts the camera lives in
+ * `shotPlacement.ts`; this is the rig that moves onto it.
+ *
+ * The two hard requirements pull against each other. A **cut is instantaneous**
+ * — a cut that eases is a swoop, and it destroys the sync with the beat that an
+ * edit is built on. Motion **within** a shot is smoothed, because footage that
+ * steps judders exactly when somebody is watching it frame by frame. So the
+ * smoothing state is reset on a cut rather than smoothed through it.
+ */
+export type { ShotKind, ShotParams } from './shotPlacement.ts';
+export declare class CinematicCamera {
+    private readonly colliders;
+    readonly camera: Camera;
+    private shot;
+    private shotStartSec;
+    private nowSec;
+    /**
+     * Where the camera wants to be, and where it is looking.
+     *
+     * Springs rather than first-order lags, which is the fix for *"the transitions
+     * between them that it's like straight"*. A lag's speed is proportional to the
+     * error it has already built, so the only way it can travel at the subject's
+     * speed is to accumulate `speed / lambda` metres of error and hold it: a shot
+     * asking for a 7 m boom was measured sitting at 9.219 m behind a 14 m/s
+     * character, and re-accumulating that error as a straight slide after every cut —
+     * 7.000 → 8.317 → 9.213 over the second after it, peaking on frame 2 and
+     * decaying from there. A spring carries a velocity, so it rides along with a
+     * target that is moving instead of trailing it, and it accelerates into and
+     * settles out of the moves that remain.
+     */
+    private readonly followX;
+    private readonly followY;
+    private readonly followZ;
+    private readonly aimYaw;
+    private readonly aimPitch;
+    /** Place the rig outright on the next update, rather than moving it there. */
+    private fresh;
+    /**
+     * Whether that placement may keep travelling at the target's speed.
+     *
+     * The difference between the two ways a rig is placed, and only the caller
+     * knows which happened. A **cut** changes the shot while the subject carries on
+     * as it was, so the speed measured across the frame is real and the new shot
+     * should open already moving with it — otherwise every cut opens with the rig
+     * accelerating from a standstill, which is the slide this replaced. A **snap**
+     * is for a subject that teleported: there is no meaningful speed across that
+     * frame, and a rig that inherited one would coast off after the character's
+     * ghost.
+     */
+    private freshKeepsSpeed;
+    /** The arm out to the camera, and its speed limits. See `boom.ts`. */
+    private readonly boom;
+    /** Frozen for `flyby`, which watches from where it was placed. */
+    private readonly station;
+    private readonly pose;
+    private readonly previousPose;
+    private hasPreviousPose;
+    private readonly placement;
+    private readonly previousPlacement;
+    constructor(colliders: ColliderSet);
+    /**
+     * Switch shots, now.
+     *
+     * `atSec` is the shot's own start time, used by anything that animates within
+     * a shot — an orbit's angle, for instance — so a shot looks the same whenever
+     * in the run it is used.
+     */
+    cut(shot: ShotParams, atSec: number): void;
+    /**
+     * Drop the smoothing history, keeping the shot.
+     *
+     * For a subject that *teleports* — a character who died and is back on a
+     * checkpoint, or a scrub bar dropped somewhere else in the run. Smoothing
+     * across that is a camera flying the length of the route with nothing in
+     * frame, measured at 124 m inside a single shot, and it looks far more like a
+     * bug than a cut does.
+     *
+     * A threshold inside `update` would be the wrong place for this. Only the
+     * caller can tell a teleport from a legitimately fast frame: a replay catching
+     * up after a freeze advances several simulation ticks in one frame, and a
+     * browser that dropped a frame advances a dozen. That is also why this is not
+     * `cut` — the two differ over whether the speed across the frame means
+     * anything, and the caller is the only one who knows.
+     */
+    snap(): void;
+    /** Seconds since the current shot began. */
+    get shotAgeSec(): number;
+    update(frameDt: number, subjectX: number, subjectY: number, subjectZ: number, subjectYaw: number): void;
+}