@driftengine/core 3.61.0

package/dist/render/seaState.js

@@ -0,0 +1,34 @@
+/**
+ * Wind speed at which the sea is fully developed. Beyond it, waves stop
+ * growing — a real fetch-limited sea saturates, and more importantly the
+ * islands sit about 1.8 m above the waterline, so an unbounded swell would
+ * flood the route and turn weather into a movement bug.
+ */
+const FULLY_DEVELOPED = 7;
+/** Never completely flat: dead-still water reads as glass, not as calm. */
+const MINIMUM_STEEPNESS = 0.35;
+const MAXIMUM_STEEPNESS = 1.35;
+/** Whitecaps need real wind; ripples do not break. */
+const FOAM_THRESHOLD = 2.5;
+export function seaStateForWind(windSpeed) {
+    const t = Math.min(Math.max(windSpeed, 0) / FULLY_DEVELOPED, 1);
+    return {
+        steepness: MINIMUM_STEEPNESS + (MAXIMUM_STEEPNESS - MINIMUM_STEEPNESS) * t,
+        foam: Math.min(Math.max((windSpeed - FOAM_THRESHOLD) / (FULLY_DEVELOPED - FOAM_THRESHOLD), 0), 1),
+    };
+}
+/**
+ * The same surface state, asked for directly instead of derived from wind.
+ *
+ * Shares this module's floor and ceiling so an indoor body and an outdoor one at the
+ * same roughness look the same — the point is where the number *comes from*, not a
+ * second scale with its own feel. Foam is deliberately reachable: a sluice or a pump
+ * outfall breaks without any wind at all.
+ */
+export function seaStateForAgitation(agitation) {
+    const t = Math.min(Math.max(agitation, 0), 1);
+    return {
+        steepness: MINIMUM_STEEPNESS + (MAXIMUM_STEEPNESS - MINIMUM_STEEPNESS) * t,
+        foam: Math.min(Math.max((t - 0.55) / 0.45, 0), 1),
+    };
+}

package/dist/render/segmentQuads.d.ts

@@ -0,0 +1,29 @@
+import type { BoltSegments } from './boltPool.ts';
+/**
+ * How a list of segments becomes triangles, held once for every renderer that draws one.
+ *
+ * **Four vertices a segment rather than instancing**, because a segment's two endpoints *are*
+ * its geometry: there is no repeated base shape to instance, and an instanced version would
+ * upload the same two positions per vertex anyway.
+ *
+ * Shared by arcs and by lines, which want the same quad and nothing else in common: an arc is
+ * additive, unlit, over-bright and jittered along its own path, and a line is a flat fogged
+ * colour with a clean edge. Two copies of the corner table would be two different meshes for
+ * the same segment, which is the mistake `waterGrid.ts` was extracted after catching in the
+ * act, a patch resolution of 48 against 24.
+ */
+/** Four vertices a segment: both ends, both sides, as (along, side). */
+export declare const SEGMENT_CORNERS: readonly (readonly [number, number])[];
+/** The static half of a batch: which end and side each vertex is, and the triangle list. */
+export interface SegmentQuads {
+    readonly corners: Float32Array;
+    readonly indices: Uint32Array;
+}
+export declare function buildSegmentQuads(capacity: number): SegmentQuads;
+/**
+ * Expand this frame's segments to their four vertices each, into arrays the caller owns.
+ *
+ * Returns how many segments were written, which is the pool's count clamped to the batch's
+ * capacity — a pool that overruns loses its tail rather than the frame.
+ */
+export declare function expandBoltSegments(data: BoltSegments, capacity: number, from: Float32Array, to: Float32Array, arc: Float32Array): number;

package/dist/render/segmentQuads.js

@@ -0,0 +1,75 @@
+/**
+ * How a list of segments becomes triangles, held once for every renderer that draws one.
+ *
+ * **Four vertices a segment rather than instancing**, because a segment's two endpoints *are*
+ * its geometry: there is no repeated base shape to instance, and an instanced version would
+ * upload the same two positions per vertex anyway.
+ *
+ * Shared by arcs and by lines, which want the same quad and nothing else in common: an arc is
+ * additive, unlit, over-bright and jittered along its own path, and a line is a flat fogged
+ * colour with a clean edge. Two copies of the corner table would be two different meshes for
+ * the same segment, which is the mistake `waterGrid.ts` was extracted after catching in the
+ * act, a patch resolution of 48 against 24.
+ */
+/** Four vertices a segment: both ends, both sides, as (along, side). */
+export const SEGMENT_CORNERS = [
+    [0, -1],
+    [1, -1],
+    [1, 1],
+    [0, 1],
+];
+export function buildSegmentQuads(capacity) {
+    const corners = new Float32Array(capacity * 4 * 2);
+    const indices = new Uint32Array(capacity * 6);
+    for (let s = 0; s < capacity; s++) {
+        const v = s * 4;
+        for (let c = 0; c < 4; c++) {
+            const corner = SEGMENT_CORNERS[c];
+            corners[(v + c) * 2] = corner[0];
+            corners[(v + c) * 2 + 1] = corner[1];
+        }
+        const i = s * 6;
+        indices[i] = v;
+        indices[i + 1] = v + 1;
+        indices[i + 2] = v + 2;
+        indices[i + 3] = v;
+        indices[i + 4] = v + 2;
+        indices[i + 5] = v + 3;
+    }
+    return { corners, indices };
+}
+/**
+ * Expand this frame's segments to their four vertices each, into arrays the caller owns.
+ *
+ * Returns how many segments were written, which is the pool's count clamped to the batch's
+ * capacity — a pool that overruns loses its tail rather than the frame.
+ */
+export function expandBoltSegments(data, capacity, from, to, arc) {
+    const count = Math.min(data.count, capacity);
+    for (let s = 0; s < count; s++) {
+        const fx = data.from[s * 3];
+        const fy = data.from[s * 3 + 1];
+        const fz = data.from[s * 3 + 2];
+        const tx = data.to[s * 3];
+        const ty = data.to[s * 3 + 1];
+        const tz = data.to[s * 3 + 2];
+        const along = data.along[s];
+        const fade = data.fade[s];
+        const seed = data.seed[s];
+        const gain = data.brightness[s];
+        for (let c = 0; c < 4; c++) {
+            const v = s * 4 + c;
+            from[v * 3] = fx;
+            from[v * 3 + 1] = fy;
+            from[v * 3 + 2] = fz;
+            to[v * 3] = tx;
+            to[v * 3 + 1] = ty;
+            to[v * 3 + 2] = tz;
+            arc[v * 4] = along;
+            arc[v * 4 + 1] = fade;
+            arc[v * 4 + 2] = seed;
+            arc[v * 4 + 3] = gain;
+        }
+    }
+    return count;
+}

package/dist/render/shader.d.ts

@@ -0,0 +1,5 @@
+/** Shader compilation with fail-fast diagnostics (init-time only, never per-frame). */
+export declare function compileProgram(gl: WebGL2RenderingContext, vertexSource: string, fragmentSource: string, label: string): WebGLProgram;
+export declare function setUniformStrictMode(on: boolean): void;
+/** Locations of every active uniform, keyed by name. */
+export declare function uniformLocations(gl: WebGL2RenderingContext, program: WebGLProgram, label?: string): Record<string, WebGLUniformLocation>;

package/dist/render/shader.js

@@ -0,0 +1,172 @@
+/** Shader compilation with fail-fast diagnostics (init-time only, never per-frame). */
+export function compileProgram(gl, vertexSource, fragmentSource, label) {
+    const vs = compileStage(gl, gl.VERTEX_SHADER, vertexSource, `${label}.vert`);
+    const fs = compileStage(gl, gl.FRAGMENT_SHADER, fragmentSource, `${label}.frag`);
+    const program = gl.createProgram();
+    if (program === null)
+        throw new Error(`[${label}] createProgram failed`);
+    gl.attachShader(program, vs);
+    gl.attachShader(program, fs);
+    gl.linkProgram(program);
+    gl.deleteShader(vs);
+    gl.deleteShader(fs);
+    if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
+        const log = gl.getProgramInfoLog(program);
+        gl.deleteProgram(program);
+        throw new Error(`[${label}] link failed: ${log ?? 'no log'}`);
+    }
+    return program;
+}
+/**
+ * Whether a uniform lookup that cannot reach the GPU is reported.
+ *
+ * Two ways it cannot: the program has no such uniform, or the program is not the one
+ * currently bound. Both upload nothing; only the second one leaves a GL error behind.
+ *
+ * **Why this exists.** `gl.uniform*(null, value)` is legal and does *nothing*: no error,
+ * no warning, no exception. Every uniform in this renderer is written through
+ * `uniforms['name'] ?? null`, so a name that stops matching — renamed, optimised out,
+ * spelled for a different driver's convention — silently stops being uploaded, and the
+ * effect it drove quietly ceases to exist. There is no symptom except a picture that is
+ * subtly or completely wrong, and no thread from the picture back to the cause.
+ *
+ * That is not a hypothetical. It has now cost this project a trample field that shipped
+ * uploading to nothing, and a night spent on a black courtyard while four separate
+ * theories were argued from source because nothing anywhere said a word.
+ *
+ * Off by default, because a renderer that warns in a frame loop is its own problem, and
+ * because deliberate optional lookups exist — a shader compiled without point shadows
+ * genuinely has no `uPointShadowIndex[0]`. On, it names the program and the uniform once
+ * each, which is enough to find it and quiet enough to leave on while looking.
+ */
+let strictUniforms = false;
+const reportedMisses = new Set();
+export function setUniformStrictMode(on) {
+    strictUniforms = on;
+    if (!on)
+        reportedMisses.clear();
+}
+/** Locations of every active uniform, keyed by name. */
+export function uniformLocations(gl, program, label = 'program') {
+    const locations = {};
+    const count = gl.getProgramParameter(program, gl.ACTIVE_UNIFORMS);
+    for (let i = 0; i < count; i++) {
+        const info = gl.getActiveUniform(program, i);
+        if (info === null)
+            continue;
+        const location = gl.getUniformLocation(program, info.name);
+        if (location === null)
+            continue;
+        locations[info.name] = location;
+        /*
+         * An array uniform is registered under **both** spellings, whichever one the driver
+         * reported it under.
+         *
+         * Passing `undefined` (or `null`) to `uniformNfv` is a **silent no-op**: the uniform
+         * never gets its data, there is no GL error, nothing throws, and the effect simply
+         * does not exist. That is how a trample field for the foliage once shipped uploading
+         * to nothing while every test passed and the console stayed clean.
+         *
+         * The subtlety, and the reason this is written symmetrically, is that **the reported
+         * name is not portable**. GLES 3.0 §2.12.6 lets an implementation return an active
+         * array's name either as `uThing[0]` or as bare `uThing`, and both are conformant.
+         * ANGLE — so every desktop browser, and Chrome on Android — returns the subscript.
+         * WebKit's Metal backend, so every browser on iOS, returns the bare name.
+         *
+         * Assuming the subscript cost a fortnight. On iOS the whole point-light system
+         * uploaded to `null`: positions, colours, radii and weights all stayed at zero, so
+         * point lights contributed exactly nothing. A scene with a sun looked perfect, and a
+         * scene lit only by lamps rendered its geometry to ambient alone — a dark room with
+         * its fire still burning, because emission needs no light to arrive. It reproduced on
+         * nothing the author owned, and it could not show up in any diagnostic, because from
+         * the API's point of view nothing went wrong.
+         *
+         * Registering both means no caller can hold it wrong, and no caller has to know a
+         * WebGL naming convention in order to write to an array — that is a fact about the
+         * API, not about the shader anybody is trying to use.
+         */
+        const subscript = info.name.indexOf('[');
+        if (subscript > 0) {
+            const bare = info.name.slice(0, subscript);
+            if (locations[bare] === undefined)
+                locations[bare] = location;
+        }
+        else if (info.size > 1) {
+            /*
+             * `size` is what separates an array reported bare from an ordinary scalar, which
+             * the name alone cannot: it is the element count, and it is 1 for everything that
+             * is not an array. Registering `uViewProj[0]` for a matrix would be harmless but
+             * meaningless, and a lookup map that answers to names nothing declared is a map
+             * that stops being evidence of what the shader contains.
+             */
+            const subscripted = `${info.name}[0]`;
+            if (locations[subscripted] === undefined)
+                locations[subscripted] = location;
+        }
+    }
+    if (!strictUniforms)
+        return locations;
+    /*
+     * A proxy rather than a changed call site, deliberately: the point is to cover *every*
+     * lookup in the renderer, including the ones nobody thought to check, and a guard that
+     * has to be adopted one call at a time protects only the places somebody already
+     * suspected.
+     */
+    return new Proxy(locations, {
+        get(target, key) {
+            if (typeof key !== 'string')
+                return target[key];
+            if (!(key in target)) {
+                const at = `${label}.${key}`;
+                if (!reportedMisses.has(at)) {
+                    reportedMisses.add(at);
+                    console.warn(`Renderer: \`${label}\` has no uniform \`${key}\`. Writing to it does nothing — ` +
+                        `WebGL treats a missing location as a silent no-op, so whatever this drove is ` +
+                        `simply absent.`);
+                }
+            }
+            else if (gl.getParameter(gl.CURRENT_PROGRAM) !== program) {
+                /*
+                 * The other half of the same failure, and the one that leaves evidence somewhere
+                 * else entirely.
+                 *
+                 * A location belongs to the program it was queried from, so writing it while a
+                 * different program is bound uploads nothing and raises `INVALID_OPERATION`. The
+                 * shape it takes in a renderer: one pass binds its program once and every other
+                 * pass interrupts it, so a call made after an interruption addresses a program
+                 * that has not been current since — and then draws through whichever program *is*
+                 * bound, because a draw call takes the program it finds rather than the one whose
+                 * uniforms were just written.
+                 *
+                 * Worth reporting separately from a missing name because the damage travels. A
+                 * pending GL error is not attached to the call that raised it: the next
+                 * `getError` anywhere in the codebase reads it and concludes that whatever *it*
+                 * was checking has failed. One such check read exactly this error as a driver
+                 * refusing to resolve depth, and switched an effect off for the session.
+                 */
+                const at = `${label}.${key}@program`;
+                if (!reportedMisses.has(at)) {
+                    reportedMisses.add(at);
+                    console.warn(`Renderer: \`${label}.${key}\` was looked up while a different program is ` +
+                        `bound. A uniform location belongs to its own program, so this write uploads ` +
+                        `nothing, raises INVALID_OPERATION, and leaves an error for the next ` +
+                        `getError anywhere to misread. Bind \`${label}\` first.`);
+                }
+            }
+            return target[key];
+        },
+    });
+}
+function compileStage(gl, type, source, label) {
+    const shader = gl.createShader(type);
+    if (shader === null)
+        throw new Error(`[${label}] createShader failed`);
+    gl.shaderSource(shader, source);
+    gl.compileShader(shader);
+    if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+        const log = gl.getShaderInfoLog(shader);
+        gl.deleteShader(shader);
+        throw new Error(`[${label}] compile failed: ${log ?? 'no log'}`);
+    }
+    return shader;
+}

package/dist/render/shaders/ambientOcclusion.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Ambient occlusion from depth: the estimate, and the blur that makes it usable.
+ *
+ * Contact shading — the darkening where two surfaces meet, under a wheel arch, along a panel
+ * gap, where a plinth stands on a floor. It is most of what makes a model sit in a room
+ * rather than float in it, and its absence does not read as a missing effect. It reads as
+ * the geometry having been pasted over the picture.
+ *
+ * **Two passes rather than one, and that is the whole design decision.** Occlusion estimated
+ * inside the composite pass and used directly was built first and looked at: twelve depth
+ * samples per pixel is a noisy estimate of a smooth quantity, and a frame of it is salt and
+ * pepper over every surface. Every renderer that ships this blurs it, and a blur needs the
+ * estimate to exist somewhere first. So the estimate lands in its own single-channel target,
+ * gets smoothed by a separable pass that will not cross a depth edge, and the composite
+ * multiplies by the result.
+ *
+ * The pairing that makes twelve taps enough: the sampling directions are turned by a
+ * rotation that repeats every four pixels, and the blur runs over eight. Every four-pixel run
+ * contains all sixteen rotations exactly once, so averaging one recovers a sixteen-times-denser
+ * kernel; averaging two also halves what is left of the noise, and — the part that decides the
+ * width — leaves a pixel hard against a silhouette with four consecutive taps still on its own
+ * side of the edge. Neither half works alone: a random per-pixel rotation leaves noise the blur
+ * can only soften, and a window narrower than two periods leaves the tile itself on screen
+ * wherever the depth test cuts the window short, as a dotted line along every edge.
+ */
+/**
+ * The estimate. Writes one channel: 1 is open sky, 0 is fully enclosed.
+ *
+ * The estimator is the Alchemy/scalable-AO one — for each neighbour, the vector v from this
+ * surface to it, weighted max(0, v·n) / (v·v). Two properties earn it its place over a
+ * hemisphere of offset points: nothing has to be oriented, so there is no tangent frame and
+ * no rotation matrix per pixel, and the 1 / v·v term falls away on its own, so a neighbour
+ * further off contributes less without a second range test doing it by hand.
+ */
+export declare const AO_FRAG: string;
+/**
+ * One direction of the blur. Run twice, across and then down.
+ *
+ * Separable, so a four-wide square costs eight taps rather than sixteen, and **depth-aware**,
+ * so it does not carry a car's occlusion out onto the wall behind it. That second part is
+ * what separates a blur from a smear: an ordinary gaussian over this estimate produces a
+ * dark halo around every silhouette, which is more obviously wrong than the noise it was
+ * added to remove.
+ */
+export declare const AO_BLUR_FRAG: string;