@driftengine/core 3.61.0

package/dist/render/resolutionGovernor.js

@@ -0,0 +1,144 @@
+/**
+ * Hold a frame budget by moving the drawing-buffer scale, and nothing else.
+ *
+ * This is the safety net the GPU-budget design asks for, and the reason it is worth
+ * having is that it works on hardware nobody here owns — including hardware that does not
+ * exist yet. One of the three players whose reports started that design found the cure by
+ * hand: they shrank the browser window until the game was smooth. This does the same
+ * thing without asking anyone to.
+ *
+ * **Pure by design: no GL, no DOM, no clock.** Frame times come in, a new scale comes
+ * out, and the caller decides what to do with it. That is what makes it testable at all,
+ * because every device it exists for is one no test machine has.
+ *
+ * **Asymmetric on purpose.** Dropping is fast, because a player at 6 fps needs relief
+ * now. Raising is slow and waits behind several consecutive good windows, because a
+ * resolution that oscillates is more visible than one that is slightly too low.
+ */
+import { withDefaults } from '../core/withDefaults.js';
+/**
+ * Deliberately hard to trigger. Work through what a healthy machine has to do to move it.
+ *
+ * At 120 fps, sixty frames is half a second. To drop one step a machine must spend **thirty
+ * of those sixty frames over 40 ms**, then do it again in the very next window: roughly a
+ * full second in which half the frames missed 25 fps. Nothing transient does that. A
+ * garbage collection is one frame, a shader compile is a handful, another application
+ * grabbing the GPU for a moment is a fraction of a window, and every one of them leaves the
+ * share far under a half.
+ *
+ * The devices this exists for are not marginal and do not need a sensitive trigger.
+ * `NFD6QQ`'s Adreno 619 held **156.66 ms** — every frame long, a share of 1.0 — so it
+ * clears two windows without ambiguity while a busy desktop never clears one.
+ *
+ * The 0.5 floor is `RESOLUTION_MIN` from the game's own settings screen, so the governor can
+ * never take a player somewhere they could not have gone themselves.
+ */
+export const DEFAULT_GOVERNOR_LIMITS = {
+    budgetMs: 40,
+    badShare: 0.5,
+    minScale: 0.5,
+    windowFrames: 60,
+    badWindows: 2,
+    dropStep: 0.25,
+    raiseStep: 0.125,
+    raisePatience: 4,
+};
+export class ResolutionGovernor {
+    limits;
+    ceiling;
+    current;
+    frames = 0;
+    longFrames = 0;
+    badWindows = 0;
+    goodWindows = 0;
+    constructor(ceiling, limits = {}) {
+        this.limits = withDefaults(DEFAULT_GOVERNOR_LIMITS, limits);
+        this.ceiling = ceiling;
+        this.current = ceiling;
+    }
+    get scale() {
+        return this.current;
+    }
+    /**
+     * The player's own ceiling moved.
+     *
+     * A *lower* ceiling applies at once, because their choice is authority and waiting a
+     * window to honour it would be ignoring them. A *higher* one is only a permission: it
+     * does not raise the current scale, because jumping up would undo a drop the device had
+     * already earned. The patience path decides whether it can afford to climb back.
+     */
+    setCeiling(ceiling) {
+        this.ceiling = ceiling;
+        if (this.current > ceiling)
+            this.current = ceiling;
+    }
+    /** Start the window again, leaving the scale where it is. */
+    reset() {
+        this.frames = 0;
+        this.longFrames = 0;
+        this.badWindows = 0;
+        this.goodWindows = 0;
+    }
+    /**
+     * One frame. Returns the new scale when it changed and `null` when it did not, so the
+     * caller does no GL or DOM work on an ordinary frame.
+     *
+     * `playable` exists because of `DZTF9F`, where an RTX 3060 filed a report calling
+     * itself unplayable from a menu: a menu frame and a hidden-tab frame are not verdicts
+     * about the machine. A governor that believed them would soften a game running
+     * perfectly, which is the same false positive with a more visible symptom.
+     */
+    sample(frameMs, playable) {
+        if (!playable)
+            return null;
+        this.frames++;
+        /*
+         * A *share* of long frames, not the worst one.
+         *
+         * The worst frame in a window was the first version of this and it was wrong in the
+         * one way that matters: with any budget near the vsync interval, a single hitch on an
+         * otherwise perfect machine drops a resolution step. "The worst frame decides" is the
+         * right rule for *diagnosing* a device, because a mean hides a machine that is fine
+         * until something happens, and it is the wrong rule for a *control loop*, which has to
+         * ignore everything it cannot act on. A share ignores hitches by construction.
+         */
+        if (frameMs > this.limits.budgetMs)
+            this.longFrames++;
+        if (this.frames < this.limits.windowFrames)
+            return null;
+        const share = this.longFrames / this.frames;
+        this.frames = 0;
+        this.longFrames = 0;
+        if (share >= this.limits.badShare) {
+            /*
+             * A bad window is evidence, not a decision. It takes `badWindows` of them in a row,
+             * so a world build or a tab coming back cannot move anything on its own.
+             */
+            this.goodWindows = 0;
+            this.badWindows++;
+            if (this.badWindows < this.limits.badWindows)
+                return null;
+            this.badWindows = 0;
+            const next = Math.max(this.limits.minScale, this.current - this.limits.dropStep);
+            if (next === this.current)
+                return null;
+            this.current = next;
+            return this.current;
+        }
+        /*
+         * A window that was not bad clears the run of bad ones. Two bad windows separated by a
+         * good one are two hiccups, and treating them as a streak would mean any long enough
+         * session eventually drops the resolution of a machine that never needed it.
+         */
+        this.badWindows = 0;
+        this.goodWindows++;
+        if (this.goodWindows < this.limits.raisePatience)
+            return null;
+        this.goodWindows = 0;
+        const next = Math.min(this.ceiling, this.current + this.limits.raiseStep);
+        if (next === this.current)
+            return null;
+        this.current = next;
+        return this.current;
+    }
+}

package/dist/render/scatterDeform.d.ts

@@ -0,0 +1,17 @@
+/** What the scatter vertex stage reads, after every conversion has been applied. */
+export interface ScatterDeform {
+    /** Unit wind direction, or zero when there is no wind to have a direction. */
+    readonly direction: Float32Array;
+    /** **Metres of bend, not metres per second.** A blade at the wind's own speed lies flat. */
+    bend: number;
+    gust: number;
+    time: number;
+    readonly spatialPhase: Float32Array;
+    trample: Float32Array;
+    trampleRadius: number;
+    trampleDepth: number;
+}
+/** Allocate one per binder, refilled per call: both callers are per-frame paths. */
+export declare function createScatterDeform(): ScatterDeform;
+/** Convert a gust into what the shader wants, into a target the caller owns. */
+export declare function resolveScatterDeform(windX: number, windZ: number, windGust: number, timeSeconds: number, trample: Float32Array | null, out: ScatterDeform): ScatterDeform;

package/dist/render/scatterDeform.js

@@ -0,0 +1,46 @@
+import { TRAMPLE_SLOTS } from './trample.js';
+/**
+ * How wind and footfall deform a scatter batch, decided once for both backends.
+ *
+ * **Every number here is a conversion, and a copy of one would drift.** The vertex stage is
+ * handed metres of bend rather than metres per second, a time already scaled, and a wind
+ * direction already normalised — so the same gust has to arrive at both backends through the
+ * same arithmetic or a field of grass leans differently depending on which one is drawing it.
+ * That is the 2026-08-13 rule in `AGENTS.md`: the decision is neutral, the binding is not.
+ */
+/** How far a press reaches, and how far down it pushes. */
+const TRAMPLE_RADIUS_M = 1.1;
+const TRAMPLE_DEPTH = 0.8;
+/**
+ * Zeroed presses, for a batch nothing walks through.
+ *
+ * Bound rather than skipped: a uniform array still holding the last batch's presses would
+ * flatten the *next* one, and the grit from a drift is drawn through this same path — which
+ * would have made a slide comb grass it was nowhere near.
+ */
+const EMPTY_TRAMPLE = new Float32Array(TRAMPLE_SLOTS * 4);
+/** Allocate one per binder, refilled per call: both callers are per-frame paths. */
+export function createScatterDeform() {
+    return {
+        direction: new Float32Array(2),
+        bend: 0,
+        gust: 0,
+        time: 0,
+        spatialPhase: new Float32Array([0.18, 0.13]),
+        trample: EMPTY_TRAMPLE,
+        trampleRadius: TRAMPLE_RADIUS_M,
+        trampleDepth: TRAMPLE_DEPTH,
+    };
+}
+/** Convert a gust into what the shader wants, into a target the caller owns. */
+export function resolveScatterDeform(windX, windZ, windGust, timeSeconds, trample, out) {
+    const speed = Math.hypot(windX, windZ);
+    const invSpeed = speed > 1e-5 ? 1 / speed : 0;
+    out.direction[0] = windX * invSpeed;
+    out.direction[1] = windZ * invSpeed;
+    out.bend = speed * 0.045;
+    out.gust = windGust * 0.06;
+    out.time = timeSeconds * 1.6;
+    out.trample = trample ?? EMPTY_TRAMPLE;
+    return out;
+}

package/dist/render/sceneTarget.d.ts

@@ -0,0 +1,288 @@
+import { type ColourGradeLut } from './colourGrade.ts';
+import type { Vec3 } from '../math/color.ts';
+/**
+ * An off-screen colour target for the frame, and the pass that resolves it to the canvas.
+ *
+ * The renderer drew straight to the canvas, which is the right default and is why this is
+ * opt-in: with nothing to sample a finished frame from, no screen-space effect can exist at
+ * all. A speed blur faked with a compositor filter over the canvas gets the boundary
+ * wrong in both directions: it is too strong, and it cannot leave the HUD alone. The
+ * effect belongs to the 3D scene, so the scene needs somewhere to land before it is shown.
+ *
+ * **It resolves to the canvas, always.** Two consumers depend on that and neither is
+ * optional: a frame recorder reads the canvas to build a clip, and a still is a canvas
+ * copy. Leaving the scene in a framebuffer would produce a black export while the screen
+ * looked correct, which is the worst shape a bug can have.
+ *
+ * Sized from the drawing buffer and rebuilt when that changes, so a resize, a DPR change
+ * and an export lock all land on an exactly-sized target rather than a stretched one. The
+ * depth buffer lives here too: a scene drawn into a colour attachment with the canvas's
+ * depth buffer would have no depth at all.
+ */
+export declare class SceneTarget {
+    private readonly gl;
+    /**
+     * Whether the multisampled buffers may be thrown away once blitted down.
+     *
+     * True is correct and saves a full attachment write per frame on a tiler. It is a switch
+     * because, like WebGPU's `storeOp: 'discard'`, it is invisible on an immediate-mode desktop
+     * part and therefore cannot be verified by a screenshot: see
+     * `RenderQuality.discardResolvedAttachments`.
+     */
+    private readonly discardResolved;
+    private framebuffer;
+    private texture;
+    /**
+     * Depth as a *texture* rather than a renderbuffer, so the composite pass can read it.
+     *
+     * A renderbuffer is write-only from a shader's point of view, and every screen-space
+     * effect worth having needs the depth back: motion blur reconstructs a world position
+     * from it to reproject through the previous view, and ambient occlusion is nothing but
+     * depth compared against its neighbours. Costing the same memory and being sampleable,
+     * there is no reason for it to be anything else.
+     */
+    private depth;
+    /**
+     * A copy of the frame's depth taken mid-pass, for anything that must read it while drawing.
+     *
+     * **Not `depth` itself, and the distinction is the whole reason this exists.** `depth` is the
+     * attachment the frame is testing against, and sampling a texture that is attached to the
+     * bound framebuffer is undefined in WebGL2 — it draws something plausible on this driver and
+     * something else on the next. So a volume of light, which has to know where the opaque scene
+     * is in order to stop marching at it, reads this instead.
+     *
+     * Filled by `snapshotDepth`, on demand, and only in frames that ask.
+     */
+    private depthCopy;
+    private depthCopyFramebuffer;
+    /** Whether this frame has filled it. One snapshot serves every volume in a frame. */
+    private depthCopyFilled;
+    /**
+     * The colour the frame had already drawn when something first asked for it.
+     *
+     * **A copy and never the attachment**, which is the difference `colorAttachment` documents from
+     * the other side: that one returns null while multisampling, because the frame lives in a
+     * renderbuffer until `resolve` blits into it. A blit from a multisampled source to a
+     * single-sampled destination *is* a resolve, so this answers in exactly the configuration where
+     * reading the attachment cannot.
+     *
+     * Filled by `snapshotColor`, on demand, and only in frames that ask.
+     */
+    private colorCopy;
+    private colorCopyFramebuffer;
+    /** Whether this frame has filled it. One snapshot serves every refracting draw in a frame. */
+    private colorCopyFilled;
+    /**
+     * The colour grade, as a 3D texture on unit 4, and the table it was built from.
+     *
+     * **The source is kept to compare identities, not to read.** A grade is set every frame by a
+     * consumer that has one, and re-uploading a 32-lattice table is 131 kilobytes of `texImage3D`
+     * sixty times a second for bytes that did not change. Comparing the object is what makes
+     * `setColourGrade` free to call from a frame loop — and a consumer crossfading between two
+     * grades holds two objects, which compare unequal and upload once each on the swap.
+     */
+    private gradeTexture;
+    private gradeSource;
+    private gradeSize;
+    private gradeStrength;
+    private width;
+    private height;
+    /**
+     * The multisampled pair, present only when a caller asked for samples.
+     *
+     * Two framebuffers rather than one, because a multisampled attachment cannot be sampled
+     * by a shader: the scene is drawn into `msaaFramebuffer`, blitted down into the ordinary
+     * texture, and the post chain reads that exactly as it always has. Everything downstream
+     * of the blit is unchanged, which is what keeps this a quality option rather than a
+     * second rendering path.
+     */
+    private msaaFramebuffer;
+    private msaaColor;
+    private msaaDepth;
+    /** What was actually allocated, after clamping to what the driver reports. */
+    private samples;
+    /** Whether anything actually reads the resolved depth. Nothing is copied if not. */
+    private depthWanted;
+    /** Set once if the driver refuses the depth copy, so it is attempted once and not per frame. */
+    private depthBlitRefused;
+    private readonly program;
+    private readonly uniforms;
+    private readonly vao;
+    /**
+     * Built the first time a caller asks for occlusion, and never for one that does not.
+     *
+     * Two programs and two full-frame targets is not a thing to allocate on the chance somebody
+     * turns the option on later: the option is construction-time, so a renderer that was not
+     * asked for it will never be.
+     */
+    private ao;
+    /** Built the first time a caller asks for bloom, on the same terms as the occlusion pass. */
+    private bloom;
+    /** Built on the first frame that asks for it, like `bloom` beside it. */
+    private temporal;
+    /** Whether the colour attachments hold half floats. See the constructor. */
+    private floatColor;
+    constructor(gl: WebGL2RenderingContext, requestedSamples?: number, wantsRange?: boolean, 
+    /**
+     * Whether the multisampled buffers may be thrown away once blitted down.
+     *
+     * True is correct and saves a full attachment write per frame on a tiler. It is a switch
+     * because, like WebGPU's `storeOp: 'discard'`, it is invisible on an immediate-mode desktop
+     * part and therefore cannot be verified by a screenshot: see
+     * `RenderQuality.discardResolvedAttachments`.
+     */
+    discardResolved?: boolean);
+    /** Match the target to the drawing buffer. Cheap when unchanged. */
+    private ensureSize;
+    private releaseMultisample;
+    /** Bind the off-screen target for a frame. The caller clears as it normally would. */
+    begin(width: number, height: number): void;
+    /**
+     * Point drawing back at this target, at its own size.
+     *
+     * Needed because every borrowing pass — the shadow maps, the planar reflection — hands
+     * the framebuffer back by binding `null`, which is the *canvas*, not the frame's target.
+     * Without somewhere to come back to, everything drawn after a reflection would land on
+     * the canvas and then be overwritten by the resolve of a half-empty target: a black
+     * frame from a renderer that looked correct in isolation.
+     */
+    bind(): void;
+    /**
+     * Whether this target keeps values above 1, which decides where the tone curve belongs.
+     *
+     * False on a part without `EXT_color_buffer_float`, where the scene is squashed into 0 to 1 on
+     * the way in exactly as it always was.
+     */
+    get keepsRange(): boolean;
+    /** How many samples the scene is actually being drawn with. 1 means no multisampling. */
+    get sampleCount(): number;
+    /** The frame's depth, resolved and sampleable, for screen-space effects that need it. */
+    get depthTexture(): WebGLTexture | null;
+    /**
+     * Copy the depth drawn so far, so something still drawing can read it. Returns what to bind.
+     *
+     * **Once per frame however many callers ask**, because they all want the same thing: where
+     * the opaque scene is. `begin` clears the latch.
+     *
+     * The blit is from whichever framebuffer the frame is actually rendering into — the
+     * multisampled one where there is one — and it restores that binding afterwards, because the
+     * caller is in the middle of a pass and expects to carry on drawing into it. Forgetting that
+     * is a frame that finishes into the wrong target and comes out empty.
+     *
+     * Null where the copy could not be made, and the caller must read that as "no clamp" rather
+     * than as a texture full of zeros — a depth of zero is the near plane, which would clamp every
+     * march to nothing and delete every beam in the scene.
+     */
+    /**
+     * The depth the frame is testing against, for a pass that must test against it too.
+     *
+     * **Not `snapshotDepth`, and the difference matters.** That returns a *copy*, for a pass that
+     * samples depth while the attachment is bound; this is the attachment itself, for a pass that
+     * attaches it and depth-tests against it without writing. Order-independent transparency needs
+     * the second: its two passes reject a pane behind a wall exactly where the wall is, and both
+     * must reject it in the same place or the accumulation and the revealage cover different
+     * fragments.
+     */
+    depthAttachment(): WebGLTexture | null;
+    /**
+     * The colour the frame has drawn so far, for a pass that reads the picture rather than the depth.
+     *
+     * **Null while multisampling, and that is the honest answer rather than a missing feature.** With
+     * samples above one the frame is drawn into a renderbuffer and this texture holds nothing until
+     * `resolve` blits into it — so a pass running mid-frame would read the frame before last. A
+     * caller that needs the finished picture in the middle of the frame is asking for something a
+     * multisampled attachment cannot give without a resolve of its own.
+     */
+    colorAttachment(): WebGLTexture | null;
+    /**
+     * The colour the frame has drawn so far, copied so a draw can sample it while still drawing.
+     *
+     * **A copy and never the attachment.** Sampling a texture attached to the bound framebuffer is
+     * undefined in WebGL2 — it draws something plausible on this driver and something else on the
+     * next — and `colorAttachment` returns null under multisampling anyway. A blit answers both:
+     * it detaches the read, and from a multisampled source it resolves.
+     *
+     * **Latched, and the latch is the same trap `snapshotDepth` documents.** One copy serves every
+     * refracting draw in a frame, so glass does not refract other glass — which is correct, a pane
+     * behind a pane should show the room. What it also means is that opaque geometry drawn *after*
+     * the first refracting draw is missing from what a pane shows. Draw the world, then the glass;
+     * a caller that must have the later geometry asks `afresh` and pays another blit.
+     *
+     * Null where the copy could not be made, and a caller must read that as "do not refract" rather
+     * than as a black texture — refracting against black paints every pane the colour of a hole.
+     */
+    snapshotColor(afresh?: boolean): WebGLTexture | null;
+    snapshotDepth(
+    /**
+     * Take the copy again even though one has already been taken this frame.
+     *
+     * **The latch that makes this cheap is also the trap in it.** A beam asks for the depth in
+     * the middle of the frame, so the copy holds the world *as it stood then* — and a pass that
+     * runs once every draw is in and reuses that copy marks a scene missing everything drawn
+     * after the beam. The symptom is a decal landing on a wall that is no longer the nearest
+     * thing, which reads as a depth-test bug rather than as a stale texture.
+     *
+     * So a caller at the end of the frame asks for it afresh, and pays one more blit on the
+     * frames where something had already asked. `begin` clears the latch either way.
+     */
+    afresh?: boolean): WebGLTexture | null;
+    /**
+     * Resolve the scene to the canvas, blurred by `strength`.
+     *
+     * Depth and blending are explicitly off for the pass: it is one opaque triangle over the
+     * whole viewport, and inheriting a depth test from the last scene draw would let it fail
+     * against nothing.
+     */
+    /**
+     * The colour grade this and every later frame applies, until it is set again.
+     *
+     * **Held rather than passed to `resolve`**, because a lookup table is a *texture* and every
+     * other texture this pass reads is owned here. The alternative is a ninth parameter on a call
+     * that already takes eight, carrying an object the caller would then have to keep stable
+     * anyway.
+     *
+     * `null`, or a strength at or below zero, is exactly the frame that existed before the effect
+     * did: the shader's branch is on a uniform, so no fetch happens at all.
+     */
+    setColourGrade(lut: ColourGradeLut | null, strength: number): void;
+    /**
+     * Put a table on the device, replacing whatever was there.
+     *
+     * `RGBA8` with `LINEAR` in every direction and `CLAMP_TO_EDGE` on all three axes. The filtering
+     * is the whole point — an unfiltered 32-lattice table bands, which is the one artefact a grade
+     * must never introduce — and the clamp is what makes the texel-centre coordinate safe at the
+     * ends of the range rather than wrapping black round to white.
+     */
+    private uploadGrade;
+    resolve(strength: number, reachUv: number, grade?: {
+        readonly transform: number;
+        readonly exposure: number;
+    }, motion?: {
+        readonly reprojection: Float32Array;
+        readonly strength: number;
+        readonly max: number;
+    }, ao?: {
+        readonly strength: number;
+        readonly radius: number;
+        /** The projection's x and y scales, which turn a world radius into a screen one. */
+        readonly projScale: Float32Array;
+        readonly invProjection: Float32Array;
+    }, bloom?: {
+        readonly strength: number;
+        /** In scene units, which is why this wants `keepsRange`. See `BloomPass`. */
+        readonly threshold: number;
+    }, dof?: {
+        /** Where the lens is focused, in metres. */
+        readonly distance: number;
+        /** How many metres either side of that stay sharp. */
+        readonly range: number;
+        /** How far the blur may reach, as a fraction of the frame's height. */
+        readonly strength: number;
+        /** `(m[10], m[14], m[11], m[15])` of the inverse projection. See `uDepthToView`. */
+        readonly depthToView: Float32Array;
+    }, veilColor?: Vec3, veilAlpha?: number, temporal?: {
+        readonly reprojection: Float32Array;
+        readonly blend: number;
+    }): void;
+    dispose(): void;
+}