@driftengine/core 3.61.0

package/src/render/rendererHarness.ts

@@ -0,0 +1,214 @@
+/**
+ * A WebGL2 context that answers everything, for tests that need a renderer and not a GPU.
+ *
+ * **Not a `.test.ts` file, and that is the point.** Vitest registers a test when the file
+ * declaring it is imported, so a second test file importing this from beside its own tests would
+ * re-run every test in that file as well — five today, and more with each one added. Split out so
+ * that importing the harness costs nothing but the harness.
+ *
+ * **Until this existed, nothing in this repository had ever constructed the WebGL2 `Renderer` in a
+ * test**, which is why every claim about that backend was settled by a capture — expensive, slow,
+ * and blind to anything the published scenes do not do. There is a `renderer.test.ts` beside that
+ * backend now, and what it pins is the shape a capture is worst at: a frame-wide decision taken
+ * from the profile, where the wrong answer still draws a plausible picture. The `Proxy` is the
+ * same trick `sceneTarget.test.ts` uses one level down: anything not named below is a recorded
+ * no-op returning a fresh object, so a constructor that touches several hundred entry points runs
+ * to completion and a test can assert the one thing it is about.
+ */
+import { countUniformVectors } from './uniformVectorBudget.ts';
+
+export function recordingGl(
+  options: {
+    /**
+     * Extensions this context answers with an object rather than with `null`.
+     *
+     * **Opt-in, and the default of none is the honest one for most tests**: the shipped default
+     * answers `null` to everything, which is the weakest part this engine claims to run on and is
+     * what a test that does not care should be written against. A test that *is* about the branch
+     * an extension opens has to name it here, or the code under test refuses one step earlier and
+     * the test passes for the wrong reason — `EXT_color_buffer_float` is the worked example: with
+     * it absent, `OitPass` declines for the float colour buffer and every order-independent
+     * profile looks alike whatever its sample count.
+     */
+    readonly extensions?: readonly string[];
+    /**
+     * What this context reports for `MAX_FRAGMENT_UNIFORM_VECTORS`. 1024 by default.
+     *
+     * Named because it is a limit the renderer now *sizes a shader against* rather than merely
+     * compares: 256 is an Adreno 740 and 224 is what WebGL2 guarantees, and both are numbers at
+     * which the lit shader has to be built smaller than the engine's own budget.
+     */
+    readonly fragmentUniformVectors?: number;
+    /**
+     * The ceiling this fake driver actually enforces at link time, if it is not the one it admits.
+     *
+     * **For the gap between what a device reports and what it does.** `planLightBudget` counts an
+     * upper bound over the source, so the interesting failure is the other one: a program the
+     * arithmetic passed that the driver still refuses. Setting this below
+     * `fragmentUniformVectors` is that device, and it is what the renderer's retry is for.
+     * `Infinity` by default, so a link only ever fails where a test asked for it.
+     */
+    readonly refuseLinkAbove?: number;
+  } = {},
+) {
+  const extensions = new Set(options.extensions ?? []);
+  const reportedVectors = options.fragmentUniformVectors ?? 1024;
+  const enforcedVectors = options.refuseLinkAbove ?? Number.POSITIVE_INFINITY;
+  /** Fragment sources by shader handle, so a refusal can be decided from what was compiled. */
+  const fragmentSources = new WeakMap<object, string>();
+  /** Each program's fragment source, gathered at `attachShader`. */
+  const programFragments = new WeakMap<object, string>();
+  const calls: { name: string; args: unknown[] }[] = [];
+  const constants: Record<string, number> = {
+    ACTIVE_UNIFORMS: 0x8b86,
+    ACTIVE_ATTRIBUTES: 0x8b89,
+    COMPILE_STATUS: 0x8b81,
+    LINK_STATUS: 0x8b82,
+    FRAMEBUFFER_COMPLETE: 0x8cd5,
+    NO_ERROR: 0,
+    MAX_SAMPLES: 0x8d57,
+    MAX_TEXTURE_SIZE: 0x0d33,
+    MAX_TEXTURE_IMAGE_UNITS: 0x8872,
+    MAX_VERTEX_UNIFORM_VECTORS: 0x8dfb,
+    MAX_FRAGMENT_UNIFORM_VECTORS: 0x8dfd,
+    /*
+     * Enums a test needs to compare against, rather than merely to pass through.
+     *
+     * The `Proxy` below answers an unnamed property with a **fresh function**, so
+     * `gl.TEXTURE_2D_ARRAY` read twice is two different values and `toContain(gl.TEXTURE_2D)` can
+     * never match anything a call recorded. Anything a test asserts on has to be named here; a
+     * constant only ever passed along does not.
+     */
+    TEXTURE_2D: 0x0de1,
+    TEXTURE_2D_ARRAY: 0x8c1a,
+    DEPTH_COMPONENT24: 0x81a6,
+    DEPTH_ATTACHMENT: 0x8d00,
+    FRAMEBUFFER: 0x8d40,
+    NONE: 0,
+    ALWAYS: 0x0207,
+    LESS: 0x0201,
+    TEXTURE_MIN_FILTER: 0x2801,
+    TEXTURE_MAG_FILTER: 0x2800,
+    TEXTURE_WRAP_S: 0x2802,
+    TEXTURE_WRAP_T: 0x2803,
+    NEAREST: 0x2600,
+    CLAMP_TO_EDGE: 0x812f,
+    /* The blend factors, so a test can tell an additive stroke from a covering one. */
+    SRC_ALPHA: 0x0302,
+    ONE: 1,
+    ONE_MINUS_SRC_ALPHA: 0x0303,
+    TRIANGLES: 0x0004,
+    TEXTURE0: 0x84c0,
+    DEPTH_BUFFER_BIT: 0x00000100,
+    DEPTH_TEST: 0x0b71,
+    CULL_FACE: 0x0b44,
+    /* Named so a pass-owned attachment's two colour formats and its two attachment points can be
+       compared rather than merely passed along. See `passTarget.test.ts`. */
+    COLOR_ATTACHMENT0: 0x8ce0,
+    RGBA8: 0x8058,
+    RGBA16F: 0x881a,
+    RGBA: 0x1908,
+    UNSIGNED_BYTE: 0x1401,
+    HALF_FLOAT: 0x140b,
+    DEPTH_COMPONENT: 0x1902,
+    UNSIGNED_INT: 0x1405,
+    LINEAR: 0x2601,
+    COLOR_BUFFER_BIT: 0x00004000,
+    /* Named so a test can tell a mesh that declared itself deforming from one that did not. */
+    ARRAY_BUFFER: 0x8892,
+    STATIC_DRAW: 0x88e4,
+    DYNAMIC_DRAW: 0x88e8,
+  };
+  const answers: Record<string, (...a: unknown[]) => unknown> = {
+    getParameter: (pname: unknown) => {
+      if (pname === constants.MAX_TEXTURE_SIZE) return 4096;
+      if (pname === constants.MAX_TEXTURE_IMAGE_UNITS) return 16;
+      if (pname === constants.MAX_SAMPLES) return 4;
+      if (pname === constants.MAX_FRAGMENT_UNIFORM_VECTORS) return reportedVectors;
+      if (pname === constants.MAX_VERTEX_UNIFORM_VECTORS) return 1024;
+      /* Generous by default: every remaining limit is a ceiling something is checked against,
+         and a small answer is read as a device that cannot do the thing. */
+      return 4096;
+    },
+    getExtension: (name: unknown) => (extensions.has(String(name)) ? {} : null),
+    getShaderParameter: () => true,
+    /*
+     * A shader remembers its own source, and a program remembers its fragment one, so a link can
+     * be refused for the reason a real driver refuses it rather than by a flag. Both are no-ops
+     * for every test that does not set a ceiling.
+     */
+    createShader: (type: unknown) => ({ type }),
+    shaderSource: (shader: unknown, source: unknown) => {
+      if (typeof shader === 'object' && shader !== null && typeof source === 'string') {
+        fragmentSources.set(shader, source);
+      }
+    },
+    attachShader: (program: unknown, shader: unknown) => {
+      if (typeof program !== 'object' || program === null) return;
+      if (typeof shader !== 'object' || shader === null) return;
+      const source = fragmentSources.get(shader);
+      /* The fragment stage is the one with a `void main` and no attributes; `#version` is on both,
+         so the discriminator is the qualifier only a fragment stage declares. */
+      if (source !== undefined && source.includes('precision highp float;')) {
+        programFragments.set(program, source);
+      }
+    },
+    /* Linked yes; zero active uniforms and attributes, which ends every reflection loop at once
+       and is why this harness does not have to know a single uniform name. */
+    getProgramParameter: (program: unknown, pname: unknown) => {
+      if (pname === constants.ACTIVE_UNIFORMS || pname === constants.ACTIVE_ATTRIBUTES) return 0;
+      if (pname !== constants.LINK_STATUS) return true;
+      if (!Number.isFinite(enforcedVectors)) return true;
+      if (typeof program !== 'object' || program === null) return true;
+      const source = programFragments.get(program);
+      return source === undefined || countUniformVectors(source) <= enforcedVectors;
+    },
+    getActiveUniform: () => ({ name: '', size: 1, type: 0 }),
+    getActiveAttrib: () => ({ name: '', size: 1, type: 0 }),
+    getUniformLocation: () => ({}),
+    getAttribLocation: () => -1,
+    checkFramebufferStatus: () => constants.FRAMEBUFFER_COMPLETE,
+    getError: () => constants.NO_ERROR,
+    getShaderInfoLog: () => '',
+    /* ANGLE's own words for this refusal, so a test asserting on the message is asserting on the
+       sentence a consumer actually pastes into a report. */
+    getProgramInfoLog: () =>
+      Number.isFinite(enforcedVectors)
+        ? `FRAGMENT shader uniforms count exceeds MAX_FRAGMENT_UNIFORM_VECTORS(${enforcedVectors})`
+        : '',
+    isContextLost: () => false,
+  };
+
+  const gl = new Proxy(
+    {},
+    {
+      get(_target, prop: string) {
+        if (prop in constants) return constants[prop];
+        if (prop in answers) {
+          return (...args: unknown[]) => {
+            calls.push({ name: prop, args });
+            return answers[prop]?.(...args);
+          };
+        }
+        /* An unnamed call: recorded, and answered with a fresh object so a handle is a handle. */
+        return (...args: unknown[]) => {
+          calls.push({ name: prop, args });
+          return {};
+        };
+      },
+    },
+  ) as unknown as WebGL2RenderingContext;
+
+  const canvas = {
+    width: 640,
+    height: 480,
+    clientWidth: 640,
+    clientHeight: 480,
+    getContext: () => gl,
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    getBoundingClientRect: () => ({ left: 0, top: 0, width: 640, height: 480 }),
+  } as unknown as HTMLCanvasElement;
+
+  return { gl, canvas, calls };
+}

package/src/render/resolutionGovernor.ts

@@ -0,0 +1,189 @@
+/**
+ * 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.ts';
+export interface GovernorLimits {
+  /**
+   * The frame time a frame is allowed, in milliseconds. Longer than this is a *long* frame.
+   *
+   * 40 rather than 16.67, and that gap is the tolerance. This is not a governor for
+   * squeezing a machine from 55 fps to 60: it exists for the parts that render at 4 to 9
+   * fps, and a trigger anywhere near the vsync interval would spend its life reacting to
+   * jitter on machines that are entirely fine. It is `LONG_FRAME_MS` from the consuming
+   * game's own frame health, deliberately, because that number has already been tuned
+   * against real false positives.
+   */
+  readonly budgetMs: number;
+  /**
+   * Share of a window's frames that must be long before the window counts as bad.
+   *
+   * **This is the guard that makes a busy high-end machine safe.** One hitch in sixty
+   * frames is a 1.7% share and decides nothing; a garbage collection, a shader compile, a
+   * texture upload or another application grabbing the GPU all look like that. Half the
+   * window being long is not a hitch, it is the machine.
+   */
+  readonly badShare: number;
+  /** Never go below this. A soft picture beats a slideshow. */
+  readonly minScale: number;
+  /** Frames per decision. One slow frame is noise; a window of them is evidence. */
+  readonly windowFrames: number;
+  /**
+   * Consecutive bad windows before the scale actually moves.
+   *
+   * The second half of the tolerance, and the same reasoning `SLOW_WINDOWS` carries in the
+   * game: one bad window is a level load, a world build, a tab that just came back. Two in
+   * a row is a machine, because none of those things happen twice in a row.
+   */
+  readonly badWindows: number;
+  /** How far to drop in one decision. */
+  readonly dropStep: number;
+  /** How far to raise in one decision. Deliberately smaller than `dropStep`. */
+  readonly raiseStep: number;
+  /** Consecutive clean windows required before raising at all. */
+  readonly raisePatience: number;
+}
+
+/**
+ * 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: GovernorLimits = {
+  budgetMs: 40,
+  badShare: 0.5,
+  minScale: 0.5,
+  windowFrames: 60,
+  badWindows: 2,
+  dropStep: 0.25,
+  raiseStep: 0.125,
+  raisePatience: 4,
+};
+
+export class ResolutionGovernor {
+  private readonly limits: GovernorLimits;
+  private ceiling: number;
+  private current: number;
+  private frames = 0;
+  private longFrames = 0;
+  private badWindows = 0;
+  private goodWindows = 0;
+
+  constructor(ceiling: number, limits: Partial<GovernorLimits> = {}) {
+    this.limits = withDefaults(DEFAULT_GOVERNOR_LIMITS, limits);
+    this.ceiling = ceiling;
+    this.current = ceiling;
+  }
+
+  get scale(): number {
+    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: number): void {
+    this.ceiling = ceiling;
+    if (this.current > ceiling) this.current = ceiling;
+  }
+
+  /** Start the window again, leaving the scale where it is. */
+  reset(): void {
+    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: number, playable: boolean): number | null {
+    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/src/render/scatterDeform.ts

@@ -0,0 +1,72 @@
+import { TRAMPLE_SLOTS } from './trample.ts';
+
+/**
+ * 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);
+
+/** 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 function createScatterDeform(): ScatterDeform {
+  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: number,
+  windZ: number,
+  windGust: number,
+  timeSeconds: number,
+  trample: Float32Array | null,
+  out: ScatterDeform,
+): ScatterDeform {
+  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;
+}