@driftengine/core 3.61.0

package/dist/render/textLayout.js

@@ -0,0 +1,201 @@
+import { countCells, forEachCell, measureText, GLYPH_HEIGHT } from '../geometry/pixelFont.js';
+/**
+ * Where a string becomes cells, for both backends.
+ *
+ * **Nothing here names a device.** Laying a message out is arithmetic over the pixel font —
+ * which cells are lit, how wide the result is, which character each cell belongs to for the
+ * arrival stagger — and it produced the same two arrays whichever API was going to upload
+ * them. Keeping it in the WebGL2 class meant a second backend would have had to reimplement
+ * it, and the rule this repository learned the hard way is that anything both backends decide
+ * lives in one module and is bound twice. `waterGrid.ts` and `plumeGeometry.ts` are the same
+ * shape.
+ *
+ * A backend owns the buffers and the pipeline; this owns what goes in them.
+ */
+/**
+ * How many cells one text object may hold.
+ *
+ * Sized for a long notification rather than a paragraph — this is a display face for short
+ * shouted strings, and anything approaching a sentence should be DOM text, which is what a
+ * screen reader can read and a translator can translate.
+ */
+export const MAX_CELLS = 900;
+export const DEFAULT_TEXT_STYLE = {
+    cellSize: 6,
+    charOffset: 0,
+    color: [1, 1, 1],
+    glow: 0.5,
+    alpha: 1,
+    reveal: 1,
+    spin: 0,
+    punch: 0,
+    bob: 0,
+};
+/** Width of a string in pixels at a given cell size, without laying it out. */
+export function textWidthPx(text, cellSize) {
+    return measureText(text) * cellSize;
+}
+export function textHeightPx(cellSize) {
+    return GLYPH_HEIGHT * cellSize;
+}
+export class TextLayout {
+    /** Reused every upload; text changes far too often to allocate per change. */
+    cells = new Float32Array(MAX_CELLS * 2);
+    chars = new Float32Array(MAX_CELLS);
+    instanceCount = 0;
+    /** Characters in the current content, for the per-character stagger. */
+    charCount = 1;
+    lastKey = '';
+    widthCells = 0;
+    /** Width of the last laid-out string, in pixels at a given cell size. */
+    widthPx(cellSize) {
+        return this.widthCells * cellSize;
+    }
+    /**
+     * Lay a string out, and say whether anything moved.
+     *
+     * **The return value is the whole point of the skip.** Most frames show the same message as
+     * the frame before, and re-uploading a buffer to say so is the sort of cost that only shows
+     * up on a phone. The arrays are reused in place, so a caller has no other way to tell.
+     */
+    setText(text) {
+        if (text === this.lastKey)
+            return false;
+        this.lastKey = text;
+        this.widthCells = measureText(text);
+        /*
+         * Truncate rather than throw: a frame with a clipped message is better than a frame that
+         * does not render, and this is a display face being handed runtime strings.
+         */
+        if (countCells(text) > MAX_CELLS)
+            this.instanceCount = 0;
+        let index = 0;
+        forEachCell(text, (x, y, charIndex) => {
+            if (index >= MAX_CELLS)
+                return;
+            this.cells[index * 2] = x;
+            this.cells[index * 2 + 1] = y;
+            this.chars[index] = charIndex;
+            index++;
+        });
+        this.instanceCount = index;
+        this.charCount = Math.max(1, text.length);
+        return true;
+    }
+    /**
+     * A solid rectangle of cells, for a keycap or a backing plate.
+     *
+     * Not text. A run of block glyphs looks like the same thing and is not: glyphs are spaced a
+     * cell apart, so the "plate" comes out striped and sized in whole glyph widths rather than
+     * in cells — which is exactly how the first keycap ended up wider than the word it was
+     * behind.
+     *
+     * `bottomCell` is where the rectangle starts vertically, in the same baseline-relative cells
+     * the glyphs use, so -1 gives a cell of padding below.
+     */
+    setPlate(widthCells, heightCells, bottomCell) {
+        const key = `plate:${widthCells}:${heightCells}:${bottomCell}`;
+        if (key === this.lastKey)
+            return false;
+        this.lastKey = key;
+        this.widthCells = widthCells;
+        let index = 0;
+        for (let x = 0; x < widthCells && index < MAX_CELLS; x++) {
+            for (let y = 0; y < heightCells && index < MAX_CELLS; y++) {
+                this.cells[index * 2] = x;
+                this.cells[index * 2 + 1] = bottomCell + y;
+                /*
+                 * One "character", so a plate arrives as a single unit rather than assembling column
+                 * by column behind the word it belongs to.
+                 */
+                this.chars[index] = 0;
+                index++;
+            }
+        }
+        this.instanceCount = index;
+        this.charCount = 1;
+        return true;
+    }
+}
+/** A unit cube centred on the origin: six faces, two triangles each. */
+function buildCube() {
+    const faces = [
+        {
+            normal: [0, 0, 1],
+            corners: [
+                [-1, -1, 1],
+                [1, -1, 1],
+                [1, 1, 1],
+                [-1, 1, 1],
+            ],
+        },
+        {
+            normal: [0, 0, -1],
+            corners: [
+                [1, -1, -1],
+                [-1, -1, -1],
+                [-1, 1, -1],
+                [1, 1, -1],
+            ],
+        },
+        {
+            normal: [1, 0, 0],
+            corners: [
+                [1, -1, 1],
+                [1, -1, -1],
+                [1, 1, -1],
+                [1, 1, 1],
+            ],
+        },
+        {
+            normal: [-1, 0, 0],
+            corners: [
+                [-1, -1, -1],
+                [-1, -1, 1],
+                [-1, 1, 1],
+                [-1, 1, -1],
+            ],
+        },
+        {
+            normal: [0, 1, 0],
+            corners: [
+                [-1, 1, 1],
+                [1, 1, 1],
+                [1, 1, -1],
+                [-1, 1, -1],
+            ],
+        },
+        {
+            normal: [0, -1, 0],
+            corners: [
+                [-1, -1, -1],
+                [1, -1, -1],
+                [1, -1, 1],
+                [-1, -1, 1],
+            ],
+        },
+    ];
+    const positions = [];
+    const normals = [];
+    for (const face of faces) {
+        const [a, b, c, d] = face.corners;
+        /*
+         * Wound clockwise, which is backwards — deliberately. The vertex shader flips Y to put the
+         * origin at the top left, and a mirror reverses winding, so faces authored the usual way
+         * come out back-facing and every one of them is culled. The symptom is text that renders
+         * with no GL error and no pixels, which is a genuinely difficult thing to look at and
+         * diagnose.
+         */
+        for (const corner of [a, c, b, a, d, c]) {
+            positions.push(corner[0], corner[1], corner[2]);
+            normals.push(face.normal[0], face.normal[1], face.normal[2]);
+        }
+    }
+    return {
+        positions: new Float32Array(positions),
+        normals: new Float32Array(normals),
+        vertexCount: positions.length / 3,
+    };
+}
+/** Unit cube, as position/normal pairs. Two triangles per face. Built once, shared by both. */
+export const TEXT_CUBE = buildCube();

package/dist/render/textRenderer.d.ts

@@ -0,0 +1,32 @@
+import type { TextStyle } from './textLayout.ts';
+export declare class TextRenderer {
+    private readonly gl;
+    private readonly program;
+    private readonly uniforms;
+    private readonly vao;
+    private readonly cellBuffer;
+    private readonly charBuffer;
+    private readonly buffers;
+    private readonly layout;
+    constructor(gl: WebGL2RenderingContext);
+    /** Width of the last laid-out string, in pixels at a given cell size. */
+    widthPx(cellSize: number): number;
+    /**
+     * Lay a string out. The upload is skipped when the text has not changed, because most frames
+     * show the same message as the frame before and re-uploading a buffer to say so is the sort
+     * of cost that only shows up on a phone.
+     */
+    setText(text: string): void;
+    /** A solid rectangle of cells, for a keycap or a backing plate. See `TextLayout.setPlate`. */
+    setPlate(widthCells: number, heightCells: number, bottomCell: number): void;
+    /**
+     * @param originX left edge, in pixels from the left of the viewport.
+     * @param originY baseline, in pixels from the top.
+     */
+    draw(viewportWidth: number, viewportHeight: number, originX: number, originY: number, style: TextStyle, timeSec: number): void;
+    dispose(): void;
+    /** Both instance buffers, from the arrays the layout filled in place. */
+    private upload;
+    private staticAttribute;
+    private instanceAttribute;
+}

package/dist/render/textRenderer.js

@@ -0,0 +1,176 @@
+import { MAX_CELLS, TEXT_CUBE, TextLayout } from './textLayout.js';
+import { compileProgram, uniformLocations } from './shader.js';
+import { TEXT_FRAG, TEXT_VERT } from './shaders/text.js';
+/**
+ * Text as geometry, on WebGL2.
+ *
+ * Every lit cell of every glyph is an instanced cube, so a message catches light, has depth,
+ * and can rotate — rather than being a flat sticker over a flat-shaded world. One draw call
+ * per string.
+ *
+ * **The layout is not here.** Which cells are lit is arithmetic over the pixel font and is the
+ * same on either backend, so it lives in `textLayout.ts` and this owns only the buffers, the
+ * program and the state the draw needs. See that file for why.
+ *
+ * Reached through `renderer.createText()` and the renderer's own `setText` / `drawText` /
+ * `disposeText`, never constructed by a caller: a caller holding a context is a caller pinned
+ * to one backend, which is what kept `showroom` on WebGL2.
+ */
+/** WebGL2's clip space is the shader's own, so the correction it binds is nothing. */
+const TEXT_IDENTITY = new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+export class TextRenderer {
+    gl;
+    program;
+    uniforms;
+    vao;
+    cellBuffer;
+    charBuffer;
+    buffers = [];
+    layout = new TextLayout();
+    constructor(gl) {
+        this.gl = gl;
+        this.program = compileProgram(gl, TEXT_VERT, TEXT_FRAG, 'text');
+        this.uniforms = uniformLocations(gl, this.program, 'textRenderer');
+        const vao = gl.createVertexArray();
+        if (vao === null)
+            throw new Error('Failed to create text VAO');
+        this.vao = vao;
+        gl.bindVertexArray(vao);
+        this.staticAttribute(0, TEXT_CUBE.positions, 3);
+        this.staticAttribute(1, TEXT_CUBE.normals, 3);
+        this.cellBuffer = this.instanceAttribute(2, MAX_CELLS * 2, 2);
+        this.charBuffer = this.instanceAttribute(3, MAX_CELLS, 1);
+        gl.bindVertexArray(null);
+    }
+    /** Width of the last laid-out string, in pixels at a given cell size. */
+    widthPx(cellSize) {
+        return this.layout.widthPx(cellSize);
+    }
+    /**
+     * Lay a string out. The upload is skipped when the text has not changed, because most frames
+     * show the same message as the frame before and re-uploading a buffer to say so is the sort
+     * of cost that only shows up on a phone.
+     */
+    setText(text) {
+        if (this.layout.setText(text))
+            this.upload();
+    }
+    /** A solid rectangle of cells, for a keycap or a backing plate. See `TextLayout.setPlate`. */
+    setPlate(widthCells, heightCells, bottomCell) {
+        if (this.layout.setPlate(widthCells, heightCells, bottomCell))
+            this.upload();
+    }
+    /**
+     * @param originX left edge, in pixels from the left of the viewport.
+     * @param originY baseline, in pixels from the top.
+     */
+    draw(viewportWidth, viewportHeight, originX, originY, style, timeSec) {
+        if (this.layout.instanceCount === 0 || style.alpha <= 0)
+            return;
+        const gl = this.gl;
+        gl.useProgram(this.program);
+        gl.bindVertexArray(this.vao);
+        /*
+         * Text gets a fresh depth buffer rather than no depth test at all.
+         *
+         * Turning depth off entirely is the obvious move and it is wrong: the cubes are solid, so
+         * with nothing sorting them the last face in the buffer wins and every letter renders as
+         * one flat facet. Clearing depth puts the whole message in front of the scene while still
+         * letting its own geometry sort against itself, which is what gives the glyphs their edges.
+         */
+        // The mask goes up *before* the clear. `glClear` respects it, and the pass that ran before
+        // this one — the plumes — leaves depth writes disabled, so clearing first silently did
+        // nothing and the text was depth-tested against whatever the scene had already written. It
+        // rendered on some frames and not others, with no GL error either way.
+        gl.depthMask(true);
+        gl.clear(gl.DEPTH_BUFFER_BIT);
+        gl.enable(gl.DEPTH_TEST);
+        /*
+         * **The equal-admitting compare in whichever direction this context tests.** Text lies flush on
+         * the surface it labels, so it needs the case that keeps a coplanar fragment — `LEQUAL` where
+         * nearer is smaller and `GEQUAL` where nearer is larger. Derived from the compare already set
+         * rather than named, because this file has no way to know which way the frame is drawing and a
+         * constant here silently drops every glyph on a reversed one.
+         */
+        const current = gl.getParameter(gl.DEPTH_FUNC);
+        const reversed = current === gl.GREATER || current === gl.GEQUAL;
+        gl.depthFunc(reversed ? gl.GEQUAL : gl.LEQUAL);
+        gl.enable(gl.BLEND);
+        gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+        setVec2(gl, this.uniforms['uViewport'], viewportWidth, viewportHeight);
+        setVec2(gl, this.uniforms['uOrigin'], originX, originY);
+        setFloat(gl, this.uniforms['uCellSize'], style.cellSize);
+        // Far enough that a whole line barely converges, near enough that a rotating character
+        // reads as turning rather than shearing.
+        setFloat(gl, this.uniforms['uDepth'], Math.max(viewportWidth, 600) * 1.4);
+        setFloat(gl, this.uniforms['uReveal'], style.reveal);
+        setFloat(gl, this.uniforms['uCharCount'], Math.max(1, style.charSpan ?? this.layout.charCount));
+        setFloat(gl, this.uniforms['uCharOffset'], style.charOffset ?? 0);
+        setFloat(gl, this.uniforms['uSpin'], style.spin);
+        setFloat(gl, this.uniforms['uPunch'], style.punch);
+        setFloat(gl, this.uniforms['uBob'], style.bob);
+        setFloat(gl, this.uniforms['uTime'], timeSec);
+        setFloat(gl, this.uniforms['uGlow'], style.glow);
+        setFloat(gl, this.uniforms['uAlpha'], style.alpha);
+        /* Identity: this backend's clip space is the one the shader was written against. */
+        const correction = this.uniforms['uClipCorrection'];
+        if (correction !== undefined)
+            gl.uniformMatrix4fv(correction, false, TEXT_IDENTITY);
+        const color = this.uniforms['uColor'];
+        if (color !== undefined) {
+            gl.uniform3f(color, style.color[0], style.color[1], style.color[2]);
+        }
+        gl.drawArraysInstanced(gl.TRIANGLES, 0, TEXT_CUBE.vertexCount, this.layout.instanceCount);
+        gl.bindVertexArray(null);
+    }
+    dispose() {
+        const gl = this.gl;
+        for (const buffer of this.buffers)
+            gl.deleteBuffer(buffer);
+        this.buffers.length = 0;
+        gl.deleteVertexArray(this.vao);
+        gl.deleteProgram(this.program);
+    }
+    /** Both instance buffers, from the arrays the layout filled in place. */
+    upload() {
+        const gl = this.gl;
+        const count = this.layout.instanceCount;
+        gl.bindBuffer(gl.ARRAY_BUFFER, this.cellBuffer);
+        gl.bufferSubData(gl.ARRAY_BUFFER, 0, this.layout.cells, 0, count * 2);
+        gl.bindBuffer(gl.ARRAY_BUFFER, this.charBuffer);
+        gl.bufferSubData(gl.ARRAY_BUFFER, 0, this.layout.chars, 0, count);
+    }
+    staticAttribute(location, data, size) {
+        const gl = this.gl;
+        const buffer = gl.createBuffer();
+        if (buffer === null)
+            throw new Error('Failed to create text buffer');
+        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);
+        return buffer;
+    }
+    instanceAttribute(location, floats, size) {
+        const gl = this.gl;
+        const buffer = gl.createBuffer();
+        if (buffer === null)
+            throw new Error('Failed to create text buffer');
+        this.buffers.push(buffer);
+        gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+        gl.bufferData(gl.ARRAY_BUFFER, floats * 4, gl.DYNAMIC_DRAW);
+        gl.enableVertexAttribArray(location);
+        gl.vertexAttribPointer(location, size, gl.FLOAT, false, 0, 0);
+        gl.vertexAttribDivisor(location, 1);
+        return buffer;
+    }
+}
+function setFloat(gl, location, value) {
+    if (location !== undefined)
+        gl.uniform1f(location, value);
+}
+function setVec2(gl, location, x, y) {
+    if (location !== undefined)
+        gl.uniform2f(location, x, y);
+}

package/dist/render/thirdPersonCamera.d.ts

@@ -0,0 +1,272 @@
+/** Collision-safe, configurable third-person orbit camera rig. */
+import type { BoomTiming } from './boom.ts';
+import type { ColliderSet } from '@driftengine/physics';
+import type { GroundSurface } from '../physics/ribbonSurface.ts';
+import { Camera } from './camera.ts';
+export interface ThirdPersonCameraOptions {
+    boomDistance: number;
+    boomRadius: number;
+    boomMinDistance: number;
+    positionLambda: number;
+    fovLambda: number;
+    pitchMin: number;
+    pitchMax: number;
+    initialPitch: number;
+    initialFovYDeg: number;
+    /**
+     * How fast the arm may change length. Absent keeps the numbers every rig had.
+     *
+     * **The defaults are written for an arm of several metres**, where the speed ceilings bind and
+     * the obstruction is a railing sweeping across for a few frames. On a short arm neither ceiling
+     * binds, only the damping acts, and easing into a wall is the wrong trade — see `BoomTiming`,
+     * which carries the measurement and the immediate-retract spelling.
+     */
+    readonly boomTiming?: Partial<BoomTiming>;
+    /**
+     * Whether the rig damps the roll it is handed. Absent means yes, which every rig had.
+     *
+     * **False is for a caller that has already damped it**, and that is not a niche: a consumer with
+     * a comfort setting on roll applies the same value to a first-person view, so a roll damped again
+     * here is damped twice and the setting stops meaning what it is asserted to mean. The rig's own
+     * damping exists so a subject snapping between surfaces cannot snap the view; a caller that has
+     * solved that itself is not asking for it twice.
+     */
+    readonly dampRoll?: boolean;
+}
+/**
+ * Something that can say how far an arm gets before it hits the world.
+ *
+ * **An alternative to the `ColliderSet`, on the seam `surface` already uses.** The rig tests its
+ * arm with `segmentHit` against a set of boxes, and a consumer whose world is a `PhysicsWorld`
+ * does not have one — so using the rig meant building and maintaining a second copy of the world
+ * for the camera alone, which is a cost large enough to have kept one consumer off the rig
+ * entirely.
+ *
+ * A segment and a radius in, metres along it or null out. Metres rather than a fraction because
+ * that is what a raycast answers and the rig knows its own length; null rather than the length
+ * because "nothing was hit" and "something was hit at the far end" are different facts, and a
+ * caller should not have to encode the first as the second.
+ */
+export interface BoomObstruction {
+    distance(fromX: number, fromY: number, fromZ: number, alongX: number, alongY: number, alongZ: number, radius: number): number | null;
+}
+/**
+ * Generic camera mechanism. The caller supplies its already-resolved target
+ * height and desired FOV, keeping crouch rules and speed effects in the game.
+ */
+export declare class ThirdPersonCamera {
+    private readonly colliders;
+    private readonly options;
+    private readonly surface;
+    /**
+     * A world query for the arm, instead of the collider set.
+     *
+     * Fourth and defaulted, so no existing call site changes — the same shape `surface` was added
+     * in. When it is given, `colliders` is not consulted at all: a caller with one has the whole
+     * world behind it and a set of boxes beside it would be a second, partial answer to the same
+     * question. See `BoomObstruction` for why one consumer could not supply the set.
+     */
+    private readonly obstruction;
+    readonly camera: Camera;
+    private smoothX;
+    private smoothY;
+    private smoothZ;
+    /**
+     * Where the target was last frame, so its velocity can be differenced out of it.
+     *
+     * **Differenced here rather than asked of the caller**, because every caller already hands the
+     * target over each frame and a second parameter for something derivable from the first is a
+     * signature every consumer has to be told about. It is exact for a target moving smoothly, which
+     * a vehicle under a fixed step with interpolation is: the engine's own harness measures the
+     * subject holding its world speed to within a twentieth of a per cent through frame jitter that
+     * moves this camera by 5%.
+     */
+    /**
+     * The frame the arm is built in. World axes unless a caller says otherwise.
+     *
+     * **The arm used to be a spherical boom about world Y** — `-sin(yaw) cos(pitch)`, `-sin(pitch)`,
+     * `cos(yaw) cos(pitch)` — so a subject standing on a wall or a ceiling got an arm that still
+     * swung about world up, and the rig placed the eye through the surface the subject was standing
+     * on. `groundClear` cut the arm where the eye would go under the deck, which is the same
+     * assumption a second time.
+     *
+     * The rig already anticipated this case and stopped one step short of it: `targetRoll`'s comment
+     * says the rig knows nothing about banked surfaces, only that a camera can be tilted, and damps
+     * roll here so a subject snapping between surfaces cannot snap the view. The arm is carried the
+     * same distance now. Yaw and pitch keep their meaning and become angles inside this frame, so a
+     * caller that never sets one gets exactly the arm it always got.
+     */
+    boomUpX: number;
+    boomUpY: number;
+    boomUpZ: number;
+    /**
+     * The frame's forward, **readable because a caller that sets one needs to know what it became**.
+     *
+     * Both `setBoomUp` and `setBoomForward` orthogonalise against the other axis, so what the rig
+     * holds is rarely the vector it was handed — and a caller computing a roll, or asking where its
+     * subject's heading ended up, needs the one the arm is actually built from. Assigning these
+     * directly does not rebuild the frame; the two setters are what keep the three axes orthonormal.
+     */
+    boomForwardX: number;
+    boomForwardY: number;
+    boomForwardZ: number;
+    private boomRightX;
+    private boomRightY;
+    private boomRightZ;
+    private lastTargetX;
+    private lastTargetY;
+    private lastTargetZ;
+    private fov;
+    private roll;
+    private snapped;
+    /**
+     * The arm out to the camera, and its speed limits.
+     *
+     * This rig used to apply the collision query's fraction directly. The query is a
+     * step function — a railing either blocks the arm or it does not — so the camera
+     * jumped by up to 4 m in a single frame every time one swept across it. That is
+     * the same artefact the replay camera was fixed for after it was reported as
+     * juddering and jumpy; this rig simply never got the fix, and a railed descent
+     * is where it would be worst.
+     */
+    private readonly boom;
+    /** Reused by the ground query; the rig allocates nothing per frame. */
+    private readonly groundHit;
+    /**
+     * @param surface The walkable ground, where the caller has one. **Not optional in
+     * practice**, and the reason is worth stating: `colliders` is not the whole world.
+     * A consumer whose drivable surface is a banked ribbon cannot put it in the collider
+     * set — a world-axis box around a banked cross-section has a flat lid at its highest
+     * corner, which is floor where nothing is drawn and a wall where the next slab's lid
+     * stands above the character's feet. So that surface is invisible to `segmentHit`, and a
+     * boom tested only against boxes passes straight through the deck.
+     *
+     * Which is exactly what it did. On a descent, pitching the view down put the eye
+     * *under the track*, with the deck between the camera and the character: the rig sees the
+     * underside of the surface instead of the character, because dynamic surfaces are not
+     * part of what it tests against. Worse in replays, where the camera moves far more than
+     * a player ever moves it.
+     */
+    constructor(colliders: ColliderSet, options: Readonly<ThirdPersonCameraOptions>, surface?: GroundSurface | null, 
+    /**
+     * A world query for the arm, instead of the collider set.
+     *
+     * Fourth and defaulted, so no existing call site changes — the same shape `surface` was added
+     * in. When it is given, `colliders` is not consulted at all: a caller with one has the whole
+     * world behind it and a set of boxes beside it would be a second, partial answer to the same
+     * question. See `BoomObstruction` for why one consumer could not supply the set.
+     */
+    obstruction?: BoomObstruction | null);
+    /**
+     * Place the rig outright on the next update instead of gliding to it.
+     *
+     * The first update already does this — a camera that eases in from the origin
+     * on the first frame of a session is a swoop nobody asked for. This re-arms it,
+     * for a subject that has *moved without travelling*: a scrub bar dropped
+     * somewhere else in a replay, or a character put back on a checkpoint. Smoothing
+     * across that is a camera flying the length of the route with nothing in frame,
+     * which the replay camera has already been measured doing at 124 m in a single
+     * shot.
+     *
+     * Only the caller can tell that apart from a legitimately fast frame, which is
+     * why it is a method here rather than a distance threshold in `update`.
+     */
+    /**
+     * How far out the arm may reach before the eye would drop below the ground, as a
+     * fraction of its length. 1 when the ground is nowhere near it.
+     *
+     * Sampled from the far end inward and returned on the first clear station, because the
+     * useful answer is the *longest* arm that works. `boomRadius` of clearance, so the eye
+     * stops above the deck rather than grazing it — the same margin the box query uses.
+     */
+    private groundClear;
+    /**
+     * Point the boom's up at a direction; the rest of the frame follows it.
+     *
+     * **Forward is carried from the frame it had rather than derived from a world axis**, which is
+     * what makes a body walking from a floor onto a wall and onto a ceiling continuous. Deriving it
+     * from a fixed reference would be one line shorter and would put a pole wherever `up` lined up
+     * with that reference: the arm would swing through a half turn as a subject crossed it, on a rig
+     * whose whole job is that the view does not snap.
+     *
+     * The fallbacks are only reached when the carried forward has become parallel to the new up,
+     * which a continuous rotation cannot do in one step and a teleport can. World Z first and world
+     * X behind it, so there is always an answer and it is never a normalised zero.
+     *
+     * A zero-length vector keeps the frame it had, for the reason `setUp` on the character
+     * controller gives: a NaN basis is a camera that is nowhere, and every number downstream of it
+     * reads as a rig that has failed rather than as an argument that was refused.
+     */
+    setBoomUp(x: number, y: number, z: number): void;
+    /**
+     * Point the boom's forward at a direction; the up is kept and the arm is rebuilt around it.
+     *
+     * **For a subject that has a heading of its own, which the carried forward cannot express.**
+     * `setBoomUp` keeps whatever forward the frame had, re-projected — the right default, because it
+     * is what makes a body walking from a floor onto a wall continuous, and because most subjects
+     * have no heading to speak of. What it cannot say is "behind *this*": a yaw of π puts the eye
+     * opposite a forward the caller never chose and, until this existed, could not read either. A
+     * subject spawning face-on to a wall got a shot framed at random, and a caller trying to work out
+     * how far to roll so that the support surface sits at the bottom of the picture had to know where
+     * the arm was — an azimuth measured from an axis nothing reported.
+     *
+     * **This is not a reversal of the carried forward and does not change it for anyone.** A caller
+     * that never calls this carries its forward exactly as before, and one that does still has it
+     * re-orthogonalised by every `setBoomUp` — the heading is a direction in the world, and the frame
+     * it lands in is the surface's.
+     *
+     * A zero-length vector, or one parallel to the current up, keeps the frame it had. **Deliberately
+     * not the fallback chain `setBoomUp` uses**, and the asymmetry is the point: that method must
+     * produce *some* forward because the up is what changed and a frame needs one, so an arbitrary
+     * axis is better than none. Here the forward is the argument, and answering a direction the
+     * caller did not ask for is precisely the failure this exists to fix.
+     */
+    setBoomForward(x: number, y: number, z: number): void;
+    /**
+     * Build the three axes from an up and a candidate forward, or answer false and change nothing.
+     *
+     * Shared by both setters so that "orthogonalised against the other axis" means one piece of
+     * arithmetic rather than two that have to be kept in step. False is the parallel case: there is
+     * no forward perpendicular to an up it is already parallel to, and what each caller does about
+     * that is the one thing they do differently.
+     */
+    private setBasis;
+    snap(): void;
+    /**
+     * How much of the arm is clear of the world, from whichever source the rig was given.
+     *
+     * The injected query wins outright where there is one, for the reason its own type gives: a
+     * caller with the whole world behind it does not also want a partial answer from a box set.
+     */
+    private blockedFraction;
+    update(frameDt: number, yaw: number, pitch: number, targetX: number, targetY: number, targetZ: number, targetFovYDeg: number, 
+    /**
+     * Roll, radians. The caller's policy: this rig knows nothing about banked
+     * surfaces, only that a camera can be tilted. Damped here rather than by
+     * the caller so a subject snapping between surfaces cannot snap the view.
+     */
+    targetRoll?: number): void;
+    /**
+     * Point the camera back down the arm, in the frame the arm was built in.
+     *
+     * **The arm moved into the boom's basis and the aim did not, and that half-migration is what this
+     * closes.** `update` placed the eye using `boomRight`/`boomUp`/`boomForward` and then set
+     * `cam.yaw`, `cam.pitch` and `cam.roll` — which `Camera.updateMatrices` reads against the *world*
+     * axes. The two agree only while up is world Y. With up at +X, an arm built at yaw 0 lies along
+     * the frame's forward while a camera at yaw 0 looks down world −Z: a right angle apart, so the
+     * rig put the eye in the right place and rendered the scene beside the subject, with no error
+     * anywhere. Reported from outside, where recovering the aim meant inverting this rig's own boom
+     * formula from outside it, against a sign convention nothing stated.
+     *
+     * **Derived rather than taken, so `update`'s signature is unchanged** — the same property R2 held
+     * to when it added `setBoomUp` rather than a `basis` parameter.
+     *
+     * The decomposition is exact and is the inverse of `updateMatrices`' own construction: forward
+     * fixes yaw and pitch, and the roll is the angle from the basis that construction would build at
+     * those two onto the up the arm was built against. **At the world basis every line here returns
+     * what was passed in**, which is asserted rather than assumed — `up` is world Y orthogonalised
+     * against forward, which is precisely the up `updateMatrices` derives, so the base roll is zero
+     * and the caller's damped roll is all that is left.
+     */
+    private aimAlongArm;
+}