@driftengine/core 3.61.0

package/dist/render/waterRenderer.js

@@ -0,0 +1,165 @@
+import { compileProgram, uniformLocations } from './shader.js';
+import { PATCH_RESOLUTION, buildUnitSheet, buildWaterGrid } from './waterGrid.js';
+import { WATER_FRAG, WATER_VERT } from './shaders/water.js';
+import { bindAtmosphere } from './atmosphere.js';
+import { bindPointLights } from './lightBudget.js';
+import { DEFAULT_RENDER_QUALITY } from './renderQuality.js';
+import { createResolvedWater, resolveWater, waterAppearance } from './waterDraw.js';
+/** Vertices per side of a bounded body's sheet. A pool is not an ocean. */
+export class WaterRenderer {
+    program;
+    uniforms;
+    vao;
+    /** A unit sheet, scaled per draw: every bounded body shares this one mesh. */
+    patchVao;
+    patchIndexCount;
+    buffers = [];
+    indexCount;
+    cellSize;
+    nearHalfExtent;
+    farHalfExtent;
+    reflectionFilterTaps;
+    /** Refilled per draw rather than allocated; see `createResolvedWater`. */
+    resolved = createResolvedWater();
+    /**
+     * @param resolution cells per side of the wave-bearing near sheet.
+     * @param nearExtent total width of that sheet, in world metres.
+     * @param farHalfExtent how far the flat skirt carries the ocean out. There is
+     *   no point setting this far beyond the camera's far plane — geometry past it
+     *   is clipped, not drawn — so this only has to outrun the fog. See
+     *   `buildWaterGrid` for why these are two meshes and not one.
+     */
+    constructor(gl, resolution = 128, nearExtent = 500, farHalfExtent = 4000, reflectionFilterTaps = DEFAULT_RENDER_QUALITY.waterReflectionFilterTaps) {
+        this.program = compileProgram(gl, WATER_VERT, WATER_FRAG, 'water');
+        this.uniforms = uniformLocations(gl, this.program, 'waterRenderer');
+        this.reflectionFilterTaps = reflectionFilterTaps;
+        const grid = buildWaterGrid(resolution, nearExtent, farHalfExtent);
+        // Exactly the near cell size: snapping by anything else re-samples the wave
+        // field as the camera moves, which reads as the surface swimming.
+        this.cellSize = grid.cellSize;
+        this.nearHalfExtent = grid.nearHalfExtent;
+        this.farHalfExtent = grid.farHalfExtent;
+        const indices = grid.indices;
+        this.indexCount = indices.length;
+        const vao = gl.createVertexArray();
+        if (vao === null)
+            throw new Error('WaterRenderer: createVertexArray failed');
+        this.vao = vao;
+        gl.bindVertexArray(vao);
+        const gridBuffer = gl.createBuffer();
+        if (gridBuffer === null)
+            throw new Error('WaterRenderer: createBuffer failed');
+        this.buffers.push(gridBuffer);
+        gl.bindBuffer(gl.ARRAY_BUFFER, gridBuffer);
+        gl.bufferData(gl.ARRAY_BUFFER, grid.offsets, gl.STATIC_DRAW);
+        gl.enableVertexAttribArray(0);
+        gl.vertexAttribPointer(0, 2, gl.FLOAT, false, 0, 0);
+        const indexBuffer = gl.createBuffer();
+        if (indexBuffer === null)
+            throw new Error('WaterRenderer: createBuffer failed');
+        this.buffers.push(indexBuffer);
+        gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, indexBuffer);
+        gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, indices, gl.STATIC_DRAW);
+        gl.bindVertexArray(null);
+        /*
+         * And the unit sheet every bounded body is drawn from. One mesh in [-1, 1],
+         * scaled by the body's own half-extent in the vertex shader — so a fountain
+         * costs a uniform rather than a mesh, and a hundred puddles cost the same.
+         */
+        const patch = buildUnitSheet(PATCH_RESOLUTION);
+        this.patchIndexCount = patch.indices.length;
+        const patchVao = gl.createVertexArray();
+        if (patchVao === null)
+            throw new Error('WaterRenderer: createVertexArray failed');
+        this.patchVao = patchVao;
+        gl.bindVertexArray(patchVao);
+        const patchGrid = gl.createBuffer();
+        if (patchGrid === null)
+            throw new Error('WaterRenderer: createBuffer failed');
+        this.buffers.push(patchGrid);
+        gl.bindBuffer(gl.ARRAY_BUFFER, patchGrid);
+        gl.bufferData(gl.ARRAY_BUFFER, patch.offsets, gl.STATIC_DRAW);
+        gl.enableVertexAttribArray(0);
+        gl.vertexAttribPointer(0, 2, gl.FLOAT, false, 0, 0);
+        const patchIndices = gl.createBuffer();
+        if (patchIndices === null)
+            throw new Error('WaterRenderer: createBuffer failed');
+        this.buffers.push(patchIndices);
+        gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, patchIndices);
+        gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, patch.indices, gl.STATIC_DRAW);
+        gl.bindVertexArray(null);
+    }
+    /**
+     * Draw the surface. Call *after* the sky: water writes depth and is occluded
+     * by geometry in front of it, but its far edge fades out, and that fade needs
+     * the sky already behind it to blend into.
+     */
+    draw(gl, camera, timeSeconds, settings, directionalDir, directionalColor, ambient, atmosphere, underwaterEnabled, reflection, lights = null, lightFalloff = 'smooth', windX = 0, windZ = 0) {
+        const u = this.uniforms;
+        const reflectionReady = reflection?.isReadyFor(settings.level) ?? false;
+        gl.useProgram(this.program);
+        gl.uniformMatrix4fv(u['uViewProj'] ?? null, false, camera.viewProjection);
+        gl.uniformMatrix4fv(u['uReflectionViewProj'] ?? null, false, reflection?.viewProjection ?? camera.viewProjection);
+        gl.uniform3fv(u['uCameraPos'] ?? null, camera.position);
+        gl.uniform1f(u['uTime'] ?? null, timeSeconds);
+        /*
+         * Where the sheet is laid, and how far one unit of it reaches. The ocean
+         * snaps to whole cells under the camera — anything else re-samples the wave
+         * field as it moves, which reads as the surface swimming — and a bounded body
+         * simply sits where it was put.
+         */
+        /* Laid and settled in `waterDraw.ts`, so both backends get the same sea. */
+        const w = resolveWater(settings, camera.position[0] ?? 0, camera.position[2] ?? 0, this.cellSize, this.nearHalfExtent, this.farHalfExtent, windX, windZ, this.resolved);
+        gl.uniform2fv(u['uGridOrigin'] ?? null, w.origin);
+        /* Pairs since 2026-08-28: a body is bounded along each of its own axes, and the direction
+           those axes take is the fourth of them. The ocean passes one number twice. */
+        gl.uniform2fv(u['uGridSpan'] ?? null, w.span);
+        gl.uniform2fv(u['uGridHalf'] ?? null, w.half);
+        gl.uniform2fv(u['uNearHalf'] ?? null, w.nearHalf);
+        gl.uniform2fv(u['uGridForward'] ?? null, w.forward);
+        /*
+         * `uGridScale` used to be uploaded here and is not, because the shader stopped reading it
+         * when the grid snapping moved to the CPU. The uniform went on being written to a location
+         * that no longer existed, which uploads to nothing and says nothing.
+         */
+        const look = waterAppearance(settings);
+        gl.uniform1f(u['uNadirOpacity'] ?? null, look.nadirOpacity);
+        gl.uniform1f(u['uVisibility'] ?? null, look.visibility);
+        gl.uniform1f(u['uMirror'] ?? null, look.mirror);
+        gl.uniform2fv(u['uWindDir'] ?? null, w.windDir);
+        gl.uniform1f(u['uWaveGain'] ?? null, w.waveGain);
+        gl.uniform1f(u['uFoamGain'] ?? null, w.foamGain);
+        gl.uniform1f(u['uWaterLevel'] ?? null, settings.level);
+        gl.uniform3fv(u['uDeepColor'] ?? null, settings.deepColor);
+        gl.uniform3fv(u['uShallowColor'] ?? null, settings.shallowColor);
+        gl.uniform3fv(u['uDirectionalDir'] ?? null, directionalDir);
+        gl.uniform3fv(u['uDirectionalColor'] ?? null, directionalColor);
+        gl.uniform3fv(u['uAmbient'] ?? null, ambient);
+        // Water is lit by the world's lamps as well as by its sky. Indoors they are all of it.
+        bindPointLights(gl, u, lights, lightFalloff);
+        bindAtmosphere(gl, u, atmosphere, camera.position[1] ?? 0, underwaterEnabled);
+        gl.activeTexture(gl.TEXTURE0);
+        gl.bindTexture(gl.TEXTURE_2D, reflectionReady && reflection !== null ? reflection.texture : null);
+        gl.uniform1i(u['uReflectionMap'] ?? null, 0);
+        gl.uniform1i(u['uReflectionEnabled'] ?? null, reflectionReady ? 1 : 0);
+        gl.uniform2f(u['uReflectionTexelSize'] ?? null, reflectionReady && reflection !== null ? 1 / reflection.textureWidth : 1, reflectionReady && reflection !== null ? 1 / reflection.textureHeight : 1);
+        gl.uniform1i(u['uReflectionFilterTaps'] ?? null, this.reflectionFilterTaps);
+        gl.enable(gl.BLEND);
+        gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+        // Waves are displaced far enough that back faces show at grazing angles.
+        gl.disable(gl.CULL_FACE);
+        gl.bindVertexArray(w.bounded ? this.patchVao : this.vao);
+        gl.drawElements(gl.TRIANGLES, w.bounded ? this.patchIndexCount : this.indexCount, gl.UNSIGNED_INT, 0);
+        gl.bindVertexArray(null);
+        gl.enable(gl.CULL_FACE);
+        gl.disable(gl.BLEND);
+        gl.bindTexture(gl.TEXTURE_2D, null);
+    }
+    dispose(gl) {
+        for (const buffer of this.buffers)
+            gl.deleteBuffer(buffer);
+        gl.deleteVertexArray(this.vao);
+        gl.deleteVertexArray(this.patchVao);
+        gl.deleteProgram(this.program);
+    }
+}

package/dist/render/wind.d.ts

@@ -0,0 +1,45 @@
+/**
+ * One wind, sampled by everything that moves in it.
+ *
+ * Grass, foliage, smoke, clouds and water all bend to weather. If each system
+ * animates on its own noise they disagree — smoke drifting one way while grass
+ * leans another is the single clearest tell that a scene is a collection of
+ * effects rather than a place. So the signal lives here, once, and every
+ * consumer samples it.
+ *
+ * Cyclic by construction: the sum of a fundamental and integer harmonics
+ * repeats exactly at the fundamental's period. That matters because a run is
+ * recorded and replayed — a replay watched an hour later must see the same gust
+ * the character did, and a signal that drifts cannot offer that.
+ *
+ * Game-agnostic: a profile carries no date, no biome, no game-specific meaning.
+ */
+export interface WindProfile {
+    /** Prevailing direction; normalised on sampling, so any non-zero pair works. */
+    directionX: number;
+    directionZ: number;
+    /** Speed with no gust, in metres per second. */
+    baseSpeed: number;
+    /** Peak deviation from the base, either way. */
+    gustSpeed: number;
+    /** How far the direction swings from prevailing, radians. */
+    directionWander: number;
+    /** Period after which the whole signal repeats exactly. */
+    cycleSeconds: number;
+    /** Offset into the cycle, so two profiles are not in lockstep. */
+    phase: number;
+}
+export interface WindState {
+    velocityX: number;
+    velocityZ: number;
+    /** Magnitude of the velocity, always non-negative. */
+    speed: number;
+    /** Gust component alone, -1..1, for effects that want the deviation. */
+    gust: number;
+}
+export declare function createWindState(): WindState;
+/**
+ * Sample the profile at a time. Writes into `out` and allocates nothing — this
+ * runs every frame for every system that cares about weather.
+ */
+export declare function sampleWind(profile: WindProfile, timeSeconds: number, out: WindState): void;

package/dist/render/wind.js

@@ -0,0 +1,32 @@
+export function createWindState() {
+    return { velocityX: 0, velocityZ: 0, speed: 0, gust: 0 };
+}
+/**
+ * Sample the profile at a time. Writes into `out` and allocates nothing — this
+ * runs every frame for every system that cares about weather.
+ */
+export function sampleWind(profile, timeSeconds, out) {
+    if (!(profile.cycleSeconds > 0)) {
+        throw new Error('WindProfile.cycleSeconds must be positive');
+    }
+    const fundamental = (Math.PI * 2) / profile.cycleSeconds;
+    const t = timeSeconds + profile.phase;
+    /*
+     * Integer harmonics only. A non-integer multiple would give a signal that
+     * looks organic but never actually closes, so a replay hours later would show
+     * different weather from the run it is replaying.
+     */
+    const a = Math.sin(fundamental * t);
+    const b = Math.sin(fundamental * 2 * t + 1.1);
+    const c = Math.sin(fundamental * 3 * t + 2.7);
+    // Weights sum to 1, so the gust stays inside ±gustSpeed however the
+    // harmonics happen to line up.
+    const gust = a * 0.55 + b * 0.3 + c * 0.15;
+    const speed = Math.max(0, profile.baseSpeed + gust * profile.gustSpeed);
+    const baseAngle = Math.atan2(profile.directionZ, profile.directionX);
+    const angle = baseAngle + (b * 0.6 + c * 0.4) * profile.directionWander;
+    out.gust = gust;
+    out.speed = speed;
+    out.velocityX = Math.cos(angle) * speed;
+    out.velocityZ = Math.sin(angle) * speed;
+}

package/dist/render/windField.d.ts

@@ -0,0 +1,34 @@
+import type { WindProfile, WindState } from './wind.ts';
+/**
+ * The world's wind, as one value passed to everything that moves in it.
+ *
+ * Six draw calls each taking two or three loose floats is a contract nobody can
+ * see: the rule "everything shares one wind" lives only in the discipline of
+ * whoever writes the next call site. As a type it is checkable at a glance, and
+ * adding a seventh consumer is a matter of accepting the same object rather
+ * than remembering to pass matching numbers.
+ *
+ * Sample once per frame and pass it down. A system that samples its own is a
+ * second wind however identical the inputs, because nothing then guarantees the
+ * two stay in step.
+ */
+export interface WindField extends WindState {
+    /**
+     * Accumulated travel, for anything positioned by wind rather than displaced
+     * by it — clouds, most obviously.
+     *
+     * Accumulated rather than derived from `velocity x time`, and that is the
+     * whole reason this lives on the type. The bearing wanders, so multiplying a
+     * *changing* direction by an absolute clock jumps whatever it positions the
+     * instant the direction moves, by an amount proportional to how long the game
+     * has been running. It is invisible in a short test and violent later.
+     */
+    driftX: number;
+    driftZ: number;
+}
+export declare function createWindField(): WindField;
+/**
+ * Advance the field one frame. `driftScale` converts wind speed into travel for
+ * whatever the drift is positioning.
+ */
+export declare function advanceWindField(field: WindField, profile: WindProfile, timeSeconds: number, frameDt: number, driftScale: number): void;

package/dist/render/windField.js

@@ -0,0 +1,13 @@
+import { sampleWind } from './wind.js';
+export function createWindField() {
+    return { velocityX: 0, velocityZ: 0, speed: 0, gust: 0, driftX: 0, driftZ: 0 };
+}
+/**
+ * Advance the field one frame. `driftScale` converts wind speed into travel for
+ * whatever the drift is positioning.
+ */
+export function advanceWindField(field, profile, timeSeconds, frameDt, driftScale) {
+    sampleWind(profile, timeSeconds, field);
+    field.driftX += field.velocityX * driftScale * frameDt;
+    field.driftZ += field.velocityZ * driftScale * frameDt;
+}

package/dist/render/windStreakDraw.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Visible wind: how much of it to show, where it has drifted to, and its lattice.
+ *
+ * **Three rules and one geometry, held once for both backends.** Each of them is the kind of
+ * thing a second implementation gets *nearly* right, which is the failure mode `AGENTS.md`
+ * 2026-08-13 is about: debris that thins in at a different wind speed, or travels at a
+ * different rate from the clouds, is weather that does not cohere, and nothing raises.
+ */
+/** What the caller wants of a lattice, before any of it reaches the device. */
+export interface WindStreakSettings {
+    /** How many streaks the lattice holds. */
+    count?: number;
+    /** Side of the box that follows the camera, metres. */
+    cellSize?: number;
+    /** Wind speed at which streaks begin to appear. */
+    onsetSpeed?: number;
+    /** Wind speed at which they are at full strength. */
+    fullSpeed?: number;
+}
+/**
+ * The defaults, in one place because two copies is two thresholds.
+ *
+ * Calibrated against the wind the game actually produces rather than against a
+ * plausible-sounding number. An early pass used an onset of 3.4 and full strength at 8 while
+ * the windiest day of the year peaked at 7.3, so the effect would have shipped essentially
+ * invisible. Raised again afterwards: at the lower onset it showed on ordinary breezy days,
+ * where visible debris is not what a breeze looks like. It belongs to storms, which is also the
+ * only time it is telling the player anything.
+ */
+export declare const WIND_STREAK_DEFAULTS: {
+    readonly count: 520;
+    readonly cellSize: 110;
+    readonly onsetSpeed: 6;
+    readonly fullSpeed: 11;
+};
+/** Six vertices a streak, as two triangles. Shared so both backends build one lattice. */
+export declare const WIND_STREAK_CORNERS: readonly (readonly [number, number])[];
+/** The two static attribute streams a lattice is drawn from: the corner, and which streak. */
+export interface WindStreakLattice {
+    readonly corners: Float32Array;
+    readonly indices: Float32Array;
+    readonly vertexCount: number;
+}
+/**
+ * Build the lattice for `count` streaks.
+ *
+ * Nothing here is per frame: the whole effect is a repeating box that follows the camera and
+ * wraps, computed in the vertex shader from an index and the clock, so this runs once and the
+ * frame loop uploads nothing.
+ */
+export declare function buildWindStreakLattice(count: number): WindStreakLattice;
+/** What one frame's draw needs beyond the camera and the tint. */
+export interface ResolvedWindStreaks {
+    /** How visible the wind is right now, 0 to 1. */
+    strength: number;
+    /** Where the field has drifted to, in metres. */
+    driftX: number;
+    driftZ: number;
+    /** Whether the draw is worth making at all. A calm day costs no draw, not a faded one. */
+    visible: boolean;
+}
+export declare function createResolvedWindStreaks(): ResolvedWindStreaks;
+/** How visible the wind is at one speed. Its own function because callers size budgets on it. */
+export declare function windStreakStrength(speed: number, onsetSpeed: number, fullSpeed: number): number;
+/**
+ * Settle a frame's streaks into a target the caller owns.
+ *
+ * **`submerged` is decided by the engine and not by the call site.** Every pass already knows
+ * where the waterline is, and leaving it to each caller is how one of them ends up raining dust
+ * into the sea. Nothing blows through water: it is the kind of detail that, once noticed,
+ * cannot be unnoticed.
+ */
+export declare function resolveWindStreaks(speed: number, driftX: number, driftZ: number, onsetSpeed: number, fullSpeed: number, submerged: boolean, out: ResolvedWindStreaks): ResolvedWindStreaks;

package/dist/render/windStreakDraw.js

@@ -0,0 +1,86 @@
+/**
+ * Visible wind: how much of it to show, where it has drifted to, and its lattice.
+ *
+ * **Three rules and one geometry, held once for both backends.** Each of them is the kind of
+ * thing a second implementation gets *nearly* right, which is the failure mode `AGENTS.md`
+ * 2026-08-13 is about: debris that thins in at a different wind speed, or travels at a
+ * different rate from the clouds, is weather that does not cohere, and nothing raises.
+ */
+/**
+ * The defaults, in one place because two copies is two thresholds.
+ *
+ * Calibrated against the wind the game actually produces rather than against a
+ * plausible-sounding number. An early pass used an onset of 3.4 and full strength at 8 while
+ * the windiest day of the year peaked at 7.3, so the effect would have shipped essentially
+ * invisible. Raised again afterwards: at the lower onset it showed on ordinary breezy days,
+ * where visible debris is not what a breeze looks like. It belongs to storms, which is also the
+ * only time it is telling the player anything.
+ */
+export const WIND_STREAK_DEFAULTS = {
+    count: 520,
+    cellSize: 110,
+    onsetSpeed: 6,
+    fullSpeed: 11,
+};
+/**
+ * How far the debris field trails the wind's own accumulated drift.
+ *
+ * Debris rides the same drift the clouds do, multiplied, so near and far weather travel
+ * together instead of at two unrelated rates. A second copy of this number is exactly that
+ * disagreement, and it would read as the sky and the air being blown by different winds.
+ */
+const DRIFT_GAIN = 14;
+/** Six vertices a streak, as two triangles. Shared so both backends build one lattice. */
+export const WIND_STREAK_CORNERS = [
+    [-1, -1],
+    [1, -1],
+    [1, 1],
+    [-1, -1],
+    [1, 1],
+    [-1, 1],
+];
+/**
+ * Build the lattice for `count` streaks.
+ *
+ * Nothing here is per frame: the whole effect is a repeating box that follows the camera and
+ * wraps, computed in the vertex shader from an index and the clock, so this runs once and the
+ * frame loop uploads nothing.
+ */
+export function buildWindStreakLattice(count) {
+    const perStreak = WIND_STREAK_CORNERS.length;
+    const corners = new Float32Array(count * perStreak * 2);
+    const indices = new Float32Array(count * perStreak);
+    let c = 0;
+    let i = 0;
+    for (let streak = 0; streak < count; streak++) {
+        for (const corner of WIND_STREAK_CORNERS) {
+            corners[c++] = corner[0];
+            corners[c++] = corner[1];
+            indices[i++] = streak;
+        }
+    }
+    return { corners, indices, vertexCount: count * perStreak };
+}
+export function createResolvedWindStreaks() {
+    return { strength: 0, driftX: 0, driftZ: 0, visible: false };
+}
+/** How visible the wind is at one speed. Its own function because callers size budgets on it. */
+export function windStreakStrength(speed, onsetSpeed, fullSpeed) {
+    const t = (speed - onsetSpeed) / Math.max(fullSpeed - onsetSpeed, 1e-4);
+    return Math.min(Math.max(t, 0), 1);
+}
+/**
+ * Settle a frame's streaks into a target the caller owns.
+ *
+ * **`submerged` is decided by the engine and not by the call site.** Every pass already knows
+ * where the waterline is, and leaving it to each caller is how one of them ends up raining dust
+ * into the sea. Nothing blows through water: it is the kind of detail that, once noticed,
+ * cannot be unnoticed.
+ */
+export function resolveWindStreaks(speed, driftX, driftZ, onsetSpeed, fullSpeed, submerged, out) {
+    out.strength = windStreakStrength(speed, onsetSpeed, fullSpeed);
+    out.driftX = driftX * DRIFT_GAIN;
+    out.driftZ = driftZ * DRIFT_GAIN;
+    out.visible = !submerged && out.strength > 0.001;
+    return out;
+}

package/dist/render/windStreakRenderer.d.ts

@@ -0,0 +1,37 @@
+import type { FrameView } from './frameView.ts';
+import type { Vec3 } from '../math/color.ts';
+import { type WindStreakSettings } from './windStreakDraw.ts';
+import type { WindField } from './windField.ts';
+/**
+ * Makes the wind visible once it is strong enough to be worth seeing.
+ *
+ * The threshold matters as much as the effect. Debris in a light breeze is
+ * visual noise across the whole game; debris only when it is genuinely blowing
+ * is information — it tells the player why their glide is drifting, at the one
+ * moment they need to know.
+ *
+ * **The thresholds, the drift rate and the lattice are in `windStreakDraw.ts`**, so the WebGPU
+ * pass shows the same weather rather than its own approximation of it.
+ */
+export type WindStreakOptions = WindStreakSettings;
+export declare class WindStreakRenderer {
+    private readonly program;
+    private readonly uniforms;
+    private readonly vao;
+    private readonly buffers;
+    private readonly vertexCount;
+    private readonly count;
+    /** Exposed so callers can size their own budgets against it. */
+    private readonly cellSize;
+    private readonly onsetSpeed;
+    private readonly fullSpeed;
+    constructor(gl: WebGL2RenderingContext, options?: WindStreakOptions);
+    /** How visible the wind is right now, 0 when there is nothing to show. */
+    strengthFor(speed: number): number;
+    /** Refilled per call rather than allocated; this is a per-frame path. */
+    private readonly resolved;
+    draw(gl: WebGL2RenderingContext, camera: FrameView, wind: WindField, timeSeconds: number, tint: Vec3, 
+    /** True when the camera is below the waterline. */
+    submerged?: boolean): void;
+    dispose(gl: WebGL2RenderingContext): void;
+}

package/dist/render/windStreakRenderer.js

@@ -0,0 +1,86 @@
+import { compileProgram, uniformLocations } from './shader.js';
+import { WIND_STREAK_FRAG, WIND_STREAK_VERT } from './shaders/windStreaks.js';
+import { WIND_STREAK_DEFAULTS, buildWindStreakLattice, createResolvedWindStreaks, resolveWindStreaks, windStreakStrength, } from './windStreakDraw.js';
+export class WindStreakRenderer {
+    program;
+    uniforms;
+    vao;
+    buffers = [];
+    vertexCount;
+    count;
+    /** Exposed so callers can size their own budgets against it. */
+    cellSize;
+    onsetSpeed;
+    fullSpeed;
+    constructor(gl, options = {}) {
+        this.count = options.count ?? WIND_STREAK_DEFAULTS.count;
+        this.cellSize = options.cellSize ?? WIND_STREAK_DEFAULTS.cellSize;
+        this.onsetSpeed = options.onsetSpeed ?? WIND_STREAK_DEFAULTS.onsetSpeed;
+        this.fullSpeed = options.fullSpeed ?? WIND_STREAK_DEFAULTS.fullSpeed;
+        this.program = compileProgram(gl, WIND_STREAK_VERT, WIND_STREAK_FRAG, 'windStreaks');
+        this.uniforms = uniformLocations(gl, this.program, 'windStreakRenderer');
+        const lattice = buildWindStreakLattice(this.count);
+        const { corners, indices } = lattice;
+        this.vertexCount = lattice.vertexCount;
+        const vao = gl.createVertexArray();
+        if (vao === null)
+            throw new Error('WindStreakRenderer: createVertexArray failed');
+        this.vao = vao;
+        gl.bindVertexArray(vao);
+        const attach = (data, location, size) => {
+            const buffer = gl.createBuffer();
+            if (buffer === null)
+                throw new Error('WindStreakRenderer: 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(corners, 0, 2);
+        attach(indices, 1, 1);
+        gl.bindVertexArray(null);
+    }
+    /** How visible the wind is right now, 0 when there is nothing to show. */
+    strengthFor(speed) {
+        return windStreakStrength(speed, this.onsetSpeed, this.fullSpeed);
+    }
+    /** Refilled per call rather than allocated; this is a per-frame path. */
+    resolved = createResolvedWindStreaks();
+    draw(gl, camera, wind, timeSeconds, tint, 
+    /** True when the camera is below the waterline. */
+    submerged = false) {
+        /* Chosen in `windStreakDraw.ts` so both backends show the same weather. */
+        const settled = resolveWindStreaks(wind.speed, wind.driftX, wind.driftZ, this.onsetSpeed, this.fullSpeed, submerged, this.resolved);
+        if (!settled.visible)
+            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.uniform2f(u['uWind'] ?? null, wind.velocityX, wind.velocityZ);
+        gl.uniform2f(u['uDrift'] ?? null, settled.driftX, settled.driftZ);
+        gl.uniform1f(u['uSpeed'] ?? null, wind.speed);
+        gl.uniform1f(u['uStrength'] ?? null, settled.strength);
+        gl.uniform1f(u['uCount'] ?? null, this.count);
+        gl.uniform1f(u['uCellSize'] ?? null, this.cellSize);
+        gl.uniform1f(u['uTime'] ?? null, timeSeconds);
+        gl.uniform3fv(u['uTint'] ?? null, tint);
+        gl.enable(gl.BLEND);
+        gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+        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);
+    }
+}