@driftengine/core 3.61.0

package/dist/render/boltPool.js

@@ -0,0 +1,259 @@
+import { hashToUnit } from '../core/rng.js';
+/** Round up to the next `2^k + 1`, the node count subdivision lands on exactly. */
+function subdivisionNodes(want) {
+    let spans = 1;
+    while (spans + 1 < want)
+        spans *= 2;
+    return spans + 1;
+}
+export class BoltPool {
+    options;
+    segments;
+    nodeCount;
+    segmentsPerBolt;
+    /** Node positions, `capacity * nodeCount * 3`. */
+    nodes;
+    /** Both ends, held so a re-strike draws a new path between the same points. */
+    ends;
+    age;
+    /** Per-arc lifetime, so a volley is not a row of identically-timed flashes. */
+    life;
+    seed;
+    brightness;
+    /** Seconds until this arc re-draws its path. */
+    restrike;
+    next = 0;
+    constructor(options) {
+        this.options = options;
+        const { capacity } = options;
+        if (!Number.isInteger(capacity) || capacity <= 0) {
+            throw new Error('A bolt pool needs a positive integer capacity.');
+        }
+        if (options.lifeSec <= 0)
+            throw new Error('Bolts need a positive lifetime.');
+        if (options.nodes < 3)
+            throw new Error('A bolt needs at least three nodes.');
+        this.nodeCount = subdivisionNodes(options.nodes);
+        this.segmentsPerBolt = this.nodeCount - 1;
+        const total = capacity * this.segmentsPerBolt;
+        this.nodes = new Float32Array(capacity * this.nodeCount * 3);
+        this.ends = new Float32Array(capacity * 6);
+        this.age = new Float32Array(capacity).fill(Infinity);
+        this.life = new Float32Array(capacity).fill(options.lifeSec);
+        this.seed = new Float32Array(capacity);
+        this.brightness = new Float32Array(capacity);
+        this.restrike = new Float32Array(capacity);
+        this.segments = {
+            from: new Float32Array(total * 3),
+            to: new Float32Array(total * 3),
+            along: new Float32Array(total),
+            fade: new Float32Array(total),
+            seed: new Float32Array(total),
+            brightness: new Float32Array(total),
+            count: 0,
+            capacity: total,
+        };
+    }
+    /** How many arcs are alive. */
+    get live() {
+        let count = 0;
+        for (let i = 0; i < this.age.length; i++) {
+            if (this.age[i] < this.life[i])
+                count++;
+        }
+        return count;
+    }
+    /**
+     * Strike an arc between two points.
+     *
+     * `seed` drives the path instead of `Math.random`, so a caller inside a
+     * deterministic system can pass a tick count and get the same lightning twice.
+     */
+    strike(x0, y0, z0, x1, y1, z1, seed, brightness = 1, 
+    /**
+     * Multiplier on the pool's lifetime for this arc alone.
+     *
+     * A volley of arcs that all die on the same frame reads as one object being
+     * switched off, which is the most predictable thing a flash can do. Varying it
+     * per strike is the cheapest way to make a burst decay like several discharges.
+     */
+    lifeScale = 1) {
+        const i = this.next;
+        this.next = (this.next + 1) % this.options.capacity;
+        const e = i * 6;
+        this.ends[e] = x0;
+        this.ends[e + 1] = y0;
+        this.ends[e + 2] = z0;
+        this.ends[e + 3] = x1;
+        this.ends[e + 4] = y1;
+        this.ends[e + 5] = z1;
+        this.age[i] = 0;
+        this.life[i] = this.options.lifeSec * lifeScale;
+        this.seed[i] = seed;
+        this.brightness[i] = brightness;
+        this.restrike[i] = 0;
+        this.drawPath(i, seed);
+    }
+    /**
+     * Age every arc, re-strike the ones whose path is due, and rebuild the
+     * segment arrays.
+     *
+     * Compacting as it goes, like the particle pool: live segments are written to
+     * the front, so a draw submits exactly the live count and a dead arc costs one
+     * loop iteration.
+     */
+    update(dt) {
+        const o = this.options;
+        const out = this.segments;
+        const restrikeEvery = o.restrikeHz > 0 ? 1 / o.restrikeHz : Infinity;
+        let count = 0;
+        for (let i = 0; i < this.age.length; i++) {
+            const age = this.age[i];
+            const life = this.life[i];
+            if (age >= life)
+                continue;
+            const next = age + dt;
+            if (next >= life) {
+                this.age[i] = life;
+                continue;
+            }
+            this.age[i] = next;
+            let due = this.restrike[i] - dt;
+            if (due <= 0) {
+                /*
+                 * A fresh path between the same two ends. The seed advances with the
+                 * strike count so consecutive paths differ, and it stays a pure function
+                 * of the arc's own seed and how many times it has been redrawn — nothing
+                 * a replay cannot reproduce.
+                 */
+                due += restrikeEvery;
+                this.drawPath(i, this.seed[i] + Math.round(next * o.restrikeHz) * 31.7);
+            }
+            this.restrike[i] = due;
+            /*
+             * Fade is the arc's own envelope: a fast attack to full and a longer decay,
+             * because that is the shape of a discharge and a linear fade reads as a
+             * light being turned down. Squared on the way out so the tail is short.
+             */
+            const t = next / life;
+            const fade = t < ATTACK ? t / ATTACK : 1 - ((t - ATTACK) / (1 - ATTACK)) ** 2;
+            const base = i * this.nodeCount * 3;
+            for (let s = 0; s < this.segmentsPerBolt; s++) {
+                const a = base + s * 3;
+                const b = a + 3;
+                const w = count * 3;
+                out.from[w] = this.nodes[a];
+                out.from[w + 1] = this.nodes[a + 1];
+                out.from[w + 2] = this.nodes[a + 2];
+                out.to[w] = this.nodes[b];
+                out.to[w + 1] = this.nodes[b + 1];
+                out.to[w + 2] = this.nodes[b + 2];
+                out.along[count] = (s + 0.5) / this.segmentsPerBolt;
+                out.fade[count] = fade;
+                out.seed[count] = this.seed[i];
+                out.brightness[count] = this.brightness[i];
+                count++;
+            }
+        }
+        out.count = count;
+    }
+    /** Drop everything, for a respawn or a scene change. */
+    clear() {
+        this.age.fill(Infinity);
+        this.segments.count = 0;
+        this.next = 0;
+    }
+    /**
+     * Lay one arc's nodes out: the straight line, then mid-point displacement.
+     *
+     * Displacement is perpendicular to the span and halves with each subdivision,
+     * which is what gives an arc detail at every scale instead of one big zigzag —
+     * the same construction a fractal terrain uses, in one dimension. The ends
+     * never move, because they are where the arc was asked to strike.
+     */
+    drawPath(index, seed) {
+        /*
+         * Integer seed for the mixer. Truncating is deliberate: the caller's seed is a tick
+         * count plus strides, so its integer part already carries every bit of the variation
+         * and a mixer wants an integer.
+         */
+        const intSeed = seed | 0;
+        const e = index * 6;
+        const x0 = this.ends[e];
+        const y0 = this.ends[e + 1];
+        const z0 = this.ends[e + 2];
+        const x1 = this.ends[e + 3];
+        const y1 = this.ends[e + 4];
+        const z1 = this.ends[e + 5];
+        const base = index * this.nodeCount * 3;
+        const last = this.nodeCount - 1;
+        const dx = x1 - x0;
+        const dy = y1 - y0;
+        const dz = z1 - z0;
+        const span = Math.hypot(dx, dy, dz) || 1;
+        // Two directions across the span, so displacement is not stuck in a plane.
+        const ax = Math.abs(dy) < 0.9 * span ? 0 : 1;
+        let px = ax === 0 ? -dz : dy;
+        let py = ax === 0 ? 0 : -dx;
+        let pz = ax === 0 ? dx : 0;
+        let plen = Math.hypot(px, py, pz) || 1;
+        px /= plen;
+        py /= plen;
+        pz /= plen;
+        // The third axis of the frame, so the two offsets are independent.
+        const qx = (dy / span) * pz - (dz / span) * py;
+        const qy = (dz / span) * px - (dx / span) * pz;
+        const qz = (dx / span) * py - (dy / span) * px;
+        for (let n = 0; n <= last; n++) {
+            const t = n / last;
+            const o = base + n * 3;
+            this.nodes[o] = x0 + dx * t;
+            this.nodes[o + 1] = y0 + dy * t;
+            this.nodes[o + 2] = z0 + dz * t;
+        }
+        /*
+         * Roughness and persistence, both drawn from the arc's own seed.
+         *
+         * Without these every path is the *same shape* differently placed: one fixed jitter
+         * and one fixed halving per level give every arc an identical fractal character, and
+         * the eye reads character long before it reads position. `jitter` becomes the mean
+         * of a range, and how fast the displacement decays per subdivision varies too — a
+         * low persistence gives one big lazy kink, a high one gives a dense crackle, and
+         * mixing them is what makes a volley look like several unrelated discharges.
+         */
+        const roughness = 0.45 + hashToUnit(intSeed + 31337) * 1.5;
+        const persistence = 0.36 + hashToUnit(intSeed + 6971) * 0.34;
+        const reach = span * this.options.jitter * roughness;
+        let stride = last;
+        let amplitude = reach;
+        while (stride > 1) {
+            const half = stride >> 1;
+            for (let n = half; n < last; n += stride) {
+                const o = base + n * 3;
+                const lo = base + (n - half) * 3;
+                const hi = base + (n + half) * 3;
+                // The mid-point of its two neighbours, displaced across the span.
+                const mx = (this.nodes[lo] + this.nodes[hi]) * 0.5;
+                const my = (this.nodes[lo + 1] + this.nodes[hi + 1]) * 0.5;
+                const mz = (this.nodes[lo + 2] + this.nodes[hi + 2]) * 0.5;
+                const u = hashToUnit(intSeed + n * 6151) * 2 - 1;
+                const v = hashToUnit(intSeed + n * 7919 + 104729) * 2 - 1;
+                this.nodes[o] = mx + (px * u + qx * v) * amplitude;
+                this.nodes[o + 1] = my + (py * u + qy * v) * amplitude;
+                this.nodes[o + 2] = mz + (pz * u + qz * v) * amplitude;
+            }
+            stride = half;
+            amplitude *= persistence;
+        }
+    }
+}
+/**
+ * Share of the lifetime spent rising to full brightness.
+ *
+ * Almost none. A discharge is *already* at full brightness by the time anything can
+ * see it — the rise is microseconds — so an attack long enough to perceive reads as a
+ * lamp being switched on. What the eye actually reads as lightning is an instant onset
+ * and a decay, and this being too slow was part of why the first version looked like
+ * drawn lines rather than flashes.
+ */
+const ATTACK = 0.04;

package/dist/render/boom.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The four numbers above, as something a caller can set.
+ *
+ * **The defaults are written for an arm of several metres and they do not scale down.** The speed
+ * ceilings are stated in metres a second, which is the unit that matters for a crane and the wrong
+ * one for an arm shorter than a hand: on a 170 mm boom neither ceiling ever binds, only the damping
+ * acts, and the trade the ceilings were chosen for is not the trade being made. Reported from
+ * outside on a 46 mm subject — a lip sweeping across a 170 mm arm left the eye **71 mm inside the
+ * wall on the first tick and inside it at all for 78 ticks of 120, 1.30 seconds** — which on a
+ * subject that small renders the inside of the masonry: a black screen with the game running
+ * perfectly behind it.
+ *
+ * **`Infinity` is the immediate answer and needs no special case.** `damp` is
+ * `lerp(a, b, 1 - exp(-lambda dt))`, so an infinite lambda returns the target exactly, and an
+ * infinite speed leaves the clamp unbounded. A rig that must come out of a wall on the tick it
+ * touches one passes `retractLambda: Infinity, retractSpeed: Infinity` and keeps the easing on the
+ * way back out, which is the half that stops the picture pumping.
+ */
+export interface BoomTiming {
+    /** How eagerly the arm shortens against an obstruction. Higher is quicker. */
+    readonly retractLambda: number;
+    /** And how eagerly it lengthens once the obstruction clears. Lower is gentler. */
+    readonly extendLambda: number;
+    /** A ceiling on how fast it may shorten, in metres a second. */
+    readonly retractSpeed: number;
+    /** And on how fast it may lengthen. */
+    readonly extendSpeed: number;
+}
+/** What every rig got before the timings could be set, and what one that says nothing still gets. */
+export declare const DEFAULT_BOOM_TIMING: BoomTiming;
+export declare class Boom {
+    /** How much of the arm is currently extended, 0–1. */
+    fraction: number;
+    private readonly timing;
+    constructor(timing?: Partial<BoomTiming>);
+    /** Place the arm outright, for a cut or a teleport. */
+    reset(fraction: number): void;
+    /**
+     * Move toward `clear` — the fraction of the arm that is unobstructed, already
+     * clamped by the caller to whatever minimum its framing needs.
+     *
+     * `lengthM` is the arm's full length, because the speed limit is stated in
+     * metres and a fraction covers more ground on a longer arm.
+     */
+    step(clear: number, lengthM: number, dt: number): number;
+}

package/dist/render/boom.js

@@ -0,0 +1,81 @@
+import { withDefaults } from '../core/withDefaults.js';
+import { clamp, damp } from '../math/scalar.js';
+/**
+ * The arm between a camera and what it is looking at, and how fast it may change
+ * length.
+ *
+ * Every third-person rig needs the same thing: shorten against geometry so the
+ * camera is never inside a wall, and do it *gradually*, because the raw answer
+ * from a collision query is a step function. This was written twice — once
+ * correctly in the replay camera, after it was reported as juddering and jumpy,
+ * and once not at all in the gameplay camera, which applied the query's
+ * fraction directly and popped by up to 4 m whenever a railing swept across it.
+ * One implementation, so a third rig cannot get it wrong again.
+ *
+ * Stateful and long-lived, hence a class: one per rig, mutated in place, nothing
+ * allocated per frame.
+ */
+/**
+ * How fast the boom changes length: quick to come in, slow to go back out.
+ *
+ * Asymmetric because the two directions have different failure modes. Coming in
+ * late means a frame or two looking through a post, which reads as a lens flare;
+ * going out early means the camera lunges away from the subject the instant an
+ * obstruction clears, which reads as the camera being kicked. So retraction is
+ * roughly twice as eager as extension, and neither is instant.
+ */
+const RETRACT_LAMBDA = 14;
+const EXTEND_LAMBDA = 6;
+/**
+ * And a ceiling on how fast it may travel, in metres per second.
+ *
+ * Damping alone is not enough, because damping is proportional: a 12 m boom asked
+ * to retract to its minimum still moves 2.2 m on the first frame, which is the
+ * same pop an octave quieter. A speed limit makes the guarantee absolute and
+ * states it in the unit that matters — the camera is an arm on a crane, and a
+ * crane has a top speed.
+ *
+ * The cost is honest and worth naming: a boom that genuinely needs its full
+ * length taken away, because the subject has gone behind a wall, spends about a
+ * second getting there and can be inside that wall while it does. That is the
+ * right trade. The obstruction is almost always a lamp post or a railing sweeping
+ * across the line for a few frames — where a speed limit removes the artefact
+ * completely — and a moment of seeing through a post is a lens artefact, where a
+ * 5 m lurch is a broken camera.
+ */
+const RETRACT_SPEED = 12;
+const EXTEND_SPEED = 5;
+/** What every rig got before the timings could be set, and what one that says nothing still gets. */
+export const DEFAULT_BOOM_TIMING = {
+    retractLambda: RETRACT_LAMBDA,
+    extendLambda: EXTEND_LAMBDA,
+    retractSpeed: RETRACT_SPEED,
+    extendSpeed: EXTEND_SPEED,
+};
+export class Boom {
+    /** How much of the arm is currently extended, 0–1. */
+    fraction = 1;
+    timing;
+    constructor(timing = {}) {
+        this.timing = withDefaults(DEFAULT_BOOM_TIMING, timing);
+    }
+    /** Place the arm outright, for a cut or a teleport. */
+    reset(fraction) {
+        this.fraction = fraction;
+    }
+    /**
+     * Move toward `clear` — the fraction of the arm that is unobstructed, already
+     * clamped by the caller to whatever minimum its framing needs.
+     *
+     * `lengthM` is the arm's full length, because the speed limit is stated in
+     * metres and a fraction covers more ground on a longer arm.
+     */
+    step(clear, lengthM, dt) {
+        const coming = clear < this.fraction;
+        const timing = this.timing;
+        const eased = damp(this.fraction, clear, coming ? timing.retractLambda : timing.extendLambda, dt);
+        const step = ((coming ? timing.retractSpeed : timing.extendSpeed) * dt) / (lengthM || 1);
+        this.fraction = clamp(eased, this.fraction - step, this.fraction + step);
+        return this.fraction;
+    }
+}

package/dist/render/camera.d.ts

@@ -0,0 +1,119 @@
+import { mat4, vec3 } from 'gl-matrix';
+import type { ReadonlyMat4 } from 'gl-matrix';
+/**
+ * Perspective camera. Yaw/pitch convention: yaw 0 looks toward -Z, positive
+ * yaw turns right (+X); positive pitch looks up.
+ */
+export declare class Camera {
+    readonly position: vec3;
+    yaw: number;
+    pitch: number;
+    fovYDeg: number;
+    /**
+     * 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: number;
+    far: number;
+    readonly forward: vec3;
+    readonly view: mat4;
+    readonly projection: mat4;
+    readonly viewProjection: mat4;
+    readonly invViewProjection: mat4;
+    /**
+     * Roll about the view direction, radians. Positive drops the right side.
+     * Render-only: nothing about the camera reaches the simulation.
+     */
+    roll: number;
+    /**
+     * 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: number, y: number, z: number): void;
+    updateMatrices(aspect: number): void;
+    /**
+     * 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: ReadonlyMat4, projection: ReadonlyMat4): void;
+    /**
+     * 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: Float32Array | number[], x: number, y: number, z: number, cssWidth: number, cssHeight: number): boolean;
+    /**
+     * 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: Float32Array, direction: Float32Array, cssX: number, cssY: number, cssWidth: number, cssHeight: number): void;
+}