@driftengine/core 3.61.0

package/src/render/shadowMap.ts

@@ -0,0 +1,89 @@
+/**
+ * Single-cascade directional shadow map: one depth texture, one extra draw of
+ * the static world per update.
+ *
+ * Filtering belongs to the receiving material shader, so the depth target can
+ * stay a single-sample texture shared by every mesh pass.
+ *
+ * Note this is a depth *render target*, not an art texture: AGENTS.md's
+ * "zero textures" rule is about the art direction (no image assets in the
+ * payload), and nothing here adds a byte to it.
+ */
+import { DEFAULT_RENDER_QUALITY } from './renderQuality.ts';
+
+export class ShadowMap {
+  readonly size: number;
+  readonly texture: WebGLTexture;
+
+  private readonly framebuffer: WebGLFramebuffer;
+
+  constructor(gl: WebGL2RenderingContext, size = DEFAULT_RENDER_QUALITY.directionalShadowMapSize) {
+    this.size = size;
+
+    const texture = gl.createTexture();
+    if (texture === null) throw new Error('ShadowMap: createTexture failed');
+    this.texture = texture;
+
+    gl.bindTexture(gl.TEXTURE_2D, texture);
+    gl.texStorage2D(gl.TEXTURE_2D, 1, gl.DEPTH_COMPONENT24, size, size);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+    // Clamp so anything outside the light frustum samples the border and is
+    // treated as lit, rather than wrapping into a spurious shadow.
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+
+    const framebuffer = gl.createFramebuffer();
+    if (framebuffer === null) throw new Error('ShadowMap: createFramebuffer failed');
+    this.framebuffer = framebuffer;
+
+    gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
+    gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.TEXTURE_2D, texture, 0);
+    // Depth-only: without this WebGL expects a colour attachment.
+    gl.drawBuffers([gl.NONE]);
+    gl.readBuffer(gl.NONE);
+
+    const status = gl.checkFramebufferStatus(gl.FRAMEBUFFER);
+    if (status !== gl.FRAMEBUFFER_COMPLETE) {
+      /*
+       * A lost context reports every attachment unusable, and that is not a
+       * misconfiguration the caller can fix — see planarReflection.ts. Init still throws,
+       * because the context cannot be lost before it exists.
+       */
+      if (gl.isContextLost()) return;
+      throw new Error(`ShadowMap: framebuffer incomplete (0x${status.toString(16)})`);
+    }
+
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    gl.bindTexture(gl.TEXTURE_2D, null);
+  }
+
+  /** Bind as the render target and clear. Caller then draws the casters. */
+  begin(gl: WebGL2RenderingContext): void {
+    gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
+    gl.viewport(0, 0, this.size, this.size);
+    gl.clear(gl.DEPTH_BUFFER_BIT);
+    /*
+     * Store the face nearest the sun. Culling front faces stores the far side
+     * and moves a box or limb through its own thickness, which is exactly the
+     * detached-shadow failure. A small slope-aware raster offset separates the
+     * stored caster from its receiver without moving the receiver differently
+     * on each face; receiver-plane compensation handles the PCF taps.
+     */
+    gl.enable(gl.CULL_FACE);
+    gl.cullFace(gl.BACK);
+    gl.enable(gl.POLYGON_OFFSET_FILL);
+    gl.polygonOffset(1.1, 4);
+  }
+
+  end(gl: WebGL2RenderingContext): void {
+    gl.disable(gl.POLYGON_OFFSET_FILL);
+    gl.cullFace(gl.BACK);
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+  }
+
+  dispose(gl: WebGL2RenderingContext): void {
+    gl.deleteFramebuffer(this.framebuffer);
+    gl.deleteTexture(this.texture);
+  }
+}

package/src/render/shotPlacement.ts

@@ -0,0 +1,266 @@
+import { clamp } from '../math/scalar.ts';
+
+/**
+ * Where a shot puts the camera, and what it frames.
+ *
+ * Pure: a shot plus a subject pose plus how far into the shot it is, in and a
+ * placement out. No state, no smoothing, no collision — those belong to the rig
+ * (`cinematicCamera.ts`), and keeping them apart is what lets the rig evaluate
+ * the *same* shot at two poses in a frame, which is how it learns the speed its
+ * target is travelling at instead of trailing behind it.
+ *
+ * Game-agnostic, like the rig: a shot is a placement rule and a subject.
+ * Nothing here knows what a character is.
+ */
+export type ShotKind = 'chase' | 'lowWide' | 'orbit' | 'flyby' | 'overhead' | 'lookAt';
+
+export interface ShotParams {
+  readonly kind: ShotKind;
+  /** How far the camera sits from its subject, in metres. */
+  readonly distance: number;
+  /** How high above it. */
+  readonly height: number;
+  readonly fovDeg: number;
+  /** Radians per second, for `orbit`. */
+  readonly orbitRate?: number;
+  /**
+   * How long this shot is going to hold, in seconds, when the caller knows.
+   *
+   * Only motion *within* a shot needs it, and only to know where the end is so
+   * it can arrive there rather than being cut off mid-travel. An `orbit` given a
+   * hold eases across the whole of it; one without eases in and then keeps its
+   * rate, because inventing a duration would be worse than not having one.
+   */
+  readonly holdSec?: number;
+  /**
+   * A fixed world point. `lookAt` frames it; `flyby` uses it as the station to
+   * shoot from. Ignored by the others.
+   */
+  readonly anchor?: readonly [number, number, number];
+}
+
+/**
+ * How far a `lookAt` shot's aim may sit from its subject, as a share of the shot's own
+ * camera distance.
+ *
+ * A *share of the gap* was the first attempt and it is wrong for the case that matters:
+ * a subject thirty metres past its anchor, with even a modest share left behind, pulls the
+ * aim further back than the camera stands — so the shot looks the wrong way down its own
+ * axis and the subject is behind the lens. Clamping the offset in metres instead cannot do
+ * that, because it is measured against the distance the camera is placed at.
+ *
+ * At half, the aim is never more than half the camera's distance from the subject, which
+ * keeps them near the middle of frame at any separation. While the two are closer than
+ * that the aim lands on the anchor exactly, which is the composition the shot exists for.
+ */
+const LOOK_AT_ANCHOR_PULL = 0.5;
+
+/** Where the subject is and which way it faces. Caller-owned and mutated in place. */
+export interface SubjectPose {
+  x: number;
+  y: number;
+  z: number;
+  yaw: number;
+}
+
+/** The answer: caller-owned, written in place, never allocated per frame. */
+export interface ShotPlacement {
+  /** Where the shot wants the camera, before smoothing and before collision. */
+  wantX: number;
+  wantY: number;
+  wantZ: number;
+  /** What it wants in the middle of frame. */
+  lookX: number;
+  lookY: number;
+  lookZ: number;
+  fovDeg: number;
+}
+
+export function createShotPlacement(): ShotPlacement {
+  return { wantX: 0, wantY: 0, wantZ: 0, lookX: 0, lookY: 0, lookZ: 0, fovDeg: 70 };
+}
+
+/**
+ * How long an orbit with no stated hold spends getting up to speed.
+ *
+ * Long enough to read as a camera being pushed rather than switched on, short
+ * enough that a two-second shot still travels. A stated hold is always better —
+ * it gets an ease at *both* ends — and the director supplies one.
+ */
+const ORBIT_EASE_SEC = 1.2;
+
+/**
+ * The station a `flyby` shoots from, when the shot did not name one.
+ *
+ * Split out because the station is captured once, on the cut, and then held: a
+ * flyby that follows is a chase cam, and the whole point is a camera the world
+ * moves past.
+ */
+export function flybyStation(
+  shot: ShotParams,
+  pose: SubjectPose,
+  out: [number, number, number],
+): void {
+  const anchor = shot.anchor;
+  if (anchor !== undefined) {
+    out[0] = anchor[0] ?? 0;
+    out[1] = anchor[1] ?? 0;
+    out[2] = anchor[2] ?? 0;
+    return;
+  }
+  const distance = shotParam(shot.distance, 6, 0.5, 400);
+  const height = shotParam(shot.height, 2, -50, 200);
+  out[0] = pose.x + Math.cos(pose.yaw) * distance;
+  out[1] = pose.y + height;
+  out[2] = pose.z + Math.sin(pose.yaw) * distance;
+}
+
+/**
+ * Place `shot` for a subject at `pose`, `ageSec` into the shot.
+ *
+ * `station` is only read by `flyby`; pass the rig's held station.
+ */
+export function placeShot(
+  shot: ShotParams,
+  pose: SubjectPose,
+  ageSec: number,
+  station: readonly number[],
+  out: ShotPlacement,
+): void {
+  const distance = shotParam(shot.distance, 6, 0.5, 400);
+  const height = shotParam(shot.height, 2, -50, 200);
+  const { x, y, z, yaw } = pose;
+
+  out.fovDeg = shotParam(shot.fovDeg, 70, 20, 140);
+  out.wantX = x;
+  out.wantY = y + height;
+  out.wantZ = z;
+  out.lookX = x;
+  out.lookY = y;
+  out.lookZ = z;
+
+  switch (shot.kind) {
+    case 'chase': {
+      // Behind the character's own heading, so the shot reads as following.
+      out.wantX = x - Math.sin(yaw) * distance;
+      out.wantZ = z + Math.cos(yaw) * distance;
+      break;
+    }
+    case 'lowWide': {
+      // Across the line of travel and near the ground, so the character crosses
+      // frame instead of receding — the shot that sells a gap.
+      out.wantX = x + Math.cos(yaw) * distance;
+      out.wantZ = z + Math.sin(yaw) * distance;
+      break;
+    }
+    case 'orbit': {
+      const rate = shotParam(shot.orbitRate, 0.6, -3, 3);
+      const angle = yaw + sweptAngle(rate, ageSec, shot.holdSec);
+      out.wantX = x - Math.sin(angle) * distance;
+      out.wantZ = z + Math.cos(angle) * distance;
+      break;
+    }
+    case 'overhead': {
+      out.wantX = x - Math.sin(yaw) * distance * 0.4;
+      out.wantZ = z + Math.cos(yaw) * distance * 0.4;
+      break;
+    }
+    case 'flyby': {
+      out.wantX = station[0] ?? 0;
+      out.wantY = station[1] ?? 0;
+      out.wantZ = station[2] ?? 0;
+      break;
+    }
+    case 'lookAt': {
+      /*
+       * Frames a fixed point *and* keeps the subject, handing the frame from one to the
+       * other as they separate.
+       *
+       * The fixed point is the reason this shot kind exists — a grapple shot holds on the
+       * ring while the character flies at it, and aiming at the character instead loses the thing
+       * the moment is about. But it aimed at the anchor and *nothing else*, and an anchor is
+       * a place the character arrives at and then leaves. Once they had swung through it they
+       * were simply out of shot, for as long as the cut lasted — reported from a replay
+       * as framing that loses the subject entirely, because the camera stops following
+       * them in that phase.
+       *
+       * So the aim is a point on the line between them, pulled toward the anchor by a
+       * bounded number of metres. While the two are close the aim *is* the anchor, which is
+       * the composition the shot was written for; once the character has flown past, the aim
+       * stays with them and the ring slides out toward the edge of frame rather than the
+       * character leaving it. Nothing needs to know which phase it is in — the geometry says.
+       */
+      const anchor = shot.anchor;
+      if (anchor !== undefined) {
+        const ax = anchor[0] ?? 0;
+        const ay = anchor[1] ?? 0;
+        const az = anchor[2] ?? 0;
+        const gap = Math.hypot(x - ax, y - ay, z - az);
+        /*
+         * Aim from the *subject* toward the anchor, by at most half the camera's distance.
+         * Nearer than that and the aim is the anchor itself; further and the anchor slides
+         * out toward the edge of frame while the subject stays in the middle of it.
+         */
+        const pull = Math.min(gap, distance * LOOK_AT_ANCHOR_PULL);
+        const k = gap > 1e-6 ? pull / gap : 0;
+        out.lookX = x + (ax - x) * k;
+        out.lookY = y + (ay - y) * k;
+        out.lookZ = z + (az - z) * k;
+      }
+      out.wantX = x - Math.sin(yaw) * distance;
+      out.wantZ = z + Math.cos(yaw) * distance;
+      break;
+    }
+  }
+}
+
+/**
+ * How far an orbit has swept by `ageSec` — eased, not `age x rate`.
+ *
+ * The linear version was reported, exactly, as looking *straight*: measured at a
+ * dead constant 3.82 m/s from the twentieth frame of the shot to the last one,
+ * still at full speed at the instant the shot was cut away from. A dolly on
+ * rails. Every other shot kind travelled exactly 0.000 m over two seconds with a
+ * still character, so this was the only self-motion in the file and the only place
+ * the complaint could come from.
+ *
+ * The **arc is preserved**: `rate x hold` is what a hold sweeps either way, since
+ * where an orbit starts and finishes is a composition decision and the ease is
+ * only about how it gets there. It peaks half again as fast in the middle, which
+ * is the cost of standing still at both ends.
+ */
+function sweptAngle(rate: number, ageSec: number, holdSec: number | undefined): number {
+  const hold = holdSec !== undefined && Number.isFinite(holdSec) && holdSec > 0 ? holdSec : 0;
+  if (hold > 0) {
+    const t = clamp(ageSec / hold, 0, 1);
+    return rate * hold * t * t * (3 - 2 * t);
+  }
+
+  /*
+   * No hold to aim at, so ease in and then keep the rate. This is the integral of
+   * `smoothstep(age / EASE)` — which is why the straight part is offset by half
+   * the ramp rather than starting from zero, and why the two halves meet with the
+   * same speed as well as the same position.
+   */
+  if (ageSec >= ORBIT_EASE_SEC) return rate * (ageSec - ORBIT_EASE_SEC * 0.5);
+  const u = ageSec / ORBIT_EASE_SEC;
+  return rate * ORBIT_EASE_SEC * (u * u * u - 0.5 * u * u * u * u);
+}
+
+/**
+ * Clamp a shot parameter into something a camera can use.
+ *
+ * Shots are produced by a director working from measured data — a run that
+ * lasted no time, an anchor at the origin — and a NaN reaching a view matrix
+ * blanks the entire frame without raising anything, which is the worst way for a
+ * bad number to fail.
+ */
+export function shotParam(
+  value: number | undefined,
+  fallback: number,
+  min: number,
+  max: number,
+): number {
+  if (value === undefined || !Number.isFinite(value)) return fallback;
+  return clamp(value, min, max);
+}

package/src/render/skinPalette.ts

@@ -0,0 +1,157 @@
+/**
+ * The joint palette's shape: how wide its texture is, how many joints fit, and which unit it takes.
+ *
+ * **Backend-neutral by the 2026-08-13 rule.** Both backends upload a palette and both need the
+ * same three answers, so the decision lives here and only the binding is per-backend. A helper
+ * that took a `WebGL2RenderingContext` would be a decision the other backend could not reach, and
+ * two implementations of one rule drift.
+ *
+ * **The palette is a texture and not a `uniform mat4[]`, and the rule that would have barred one
+ * does not reach here.** The 2026-08-07 rule governs implicit derivatives in non-uniform control
+ * flow — a *fragment*-stage hazard. A vertex stage computes no derivatives, so `texelFetch` there
+ * is unconditional and that rule has nothing to say about it.
+ *
+ * What a uniform array would have cost is the reason: `MAX_VERTEX_UNIFORM_VECTORS` is 256 on the
+ * WebGL2 floor and `FLAT_VERT` already spends fifteen, so four vectors a matrix caps a rig at
+ * **sixty joints** — under a humanoid with fingers, and on exactly the mid-range hardware the
+ * engine hard-gates 60 fps on.
+ *
+ * What the texture costs is an upload per skinned draw where an array would be a uniform write.
+ * What would make it wrong is a profile showing that upload is the limit at a realistic character
+ * count; the fix is then one texture holding every character's palette with a per-draw row offset,
+ * which is a follow-on rather than a starting point.
+ *
+ * **A palette belongs to a draw, and what it takes to honour that differs per backend.** WebGL2
+ * uploads with `texSubImage2D`, a command in the same stream as the draws around it, so one texture
+ * rewritten between two draws separates them by construction. WebGPU's `queue.writeTexture` is
+ * ordered on the queue timeline and the frame's encoder is submitted after every upload in it, so
+ * the same one texture hands *every* skinned draw of the frame the last palette written — and since
+ * a rig carries its placement in its palette, that is every character standing where the last one
+ * drawn stands. That backend therefore binds a ring of palettes, one slot per palette a frame sets:
+ * `backend/webgpu/skinPaletteRing.ts`. The decision here is one; only the binder differs, per the
+ * 2026-08-13 rule.
+ */
+
+/**
+ * The palette's texture unit, from the lit pass's own budget.
+ *
+ * Re-exported rather than declared, because a unit number written twice is a collision waiting to
+ * happen and `lightBudget.ts` is where every other unit in this pass is decided. It carries the
+ * reason it is not 0.
+ */
+export { SKIN_PALETTE_TEXTURE_UNIT } from './lightBudget.ts';
+
+/** Four `rgba32float` texels hold one column-major 4x4. */
+const TEXELS_PER_JOINT = 4;
+
+/**
+ * The most joints one palette can hold.
+ *
+ * WebGL2 guarantees `MAX_TEXTURE_SIZE` of 2048 and promises nothing above it, so a single-row
+ * palette holds 2048 / 4 matrices. A humanoid rig is sixty to ninety joints, so this is not a
+ * limit anybody meets by accident — but it is stated, refused at construction and named in the
+ * error, because a limit a consumer discovers is a defect and a limit they read is a
+ * specification.
+ *
+ * What it costs is that a crowd cannot share one palette. What would make it wrong is a rig above
+ * it, and the fix is wrapping onto more rows — which costs one division in the vertex stage and is
+ * why it is not the starting point.
+ */
+export const MAX_JOINTS = 512;
+
+/** How wide the palette texture is for a rig of this many joints. */
+export function paletteTextureWidth(jointCount: number): number {
+  if (!Number.isInteger(jointCount) || jointCount < 1) {
+    throw new Error(`skin palette: a rig needs at least one joint, got ${jointCount}`);
+  }
+  if (jointCount > MAX_JOINTS) {
+    throw new Error(
+      `skin palette: ${jointCount} joints exceeds the ${MAX_JOINTS} a single-row palette holds. ` +
+        `WebGL2 guarantees a texture width of 2048 and four texels carry one matrix, so this is ` +
+        `the floor rather than this machine's limit.`,
+    );
+  }
+  return jointCount * TEXELS_PER_JOINT;
+}
+
+/**
+ * Refuse a palette that is not whole matrices, naming the length.
+ *
+ * A caller error with exactly one correct outcome, so it throws rather than warns — and it throws
+ * where the palette is handed over rather than where a shader reads a partial matrix and draws a
+ * rig folded in on itself.
+ */
+export function validateSkinPalette(palette: Float32Array): void {
+  if (palette.length % 16 !== 0) {
+    throw new Error(
+      `skin palette: ${palette.length} floats is not a whole number of 4x4 matrices (16 each)`,
+    );
+  }
+  const joints = palette.length / 16;
+  if (joints < 1 || joints > MAX_JOINTS) {
+    throw new Error(
+      `skin palette: ${joints} joints, which is outside 1 to ${MAX_JOINTS}. See MAX_JOINTS.`,
+    );
+  }
+}
+
+/* --- Morph targets, on the same mechanism --- */
+
+/**
+ * The most morph targets one mesh can carry.
+ *
+ * Bounded by the weight array in the vertex uniform block rather than by the delta texture, which
+ * is why it is small: eight `vec4`-aligned floats is 128 bytes of a block that has fifteen vectors
+ * in it already. Eight is what glTF's own tooling emits and what every exporter defaults to.
+ *
+ * What it costs is a rig wanting nine expressions. What would make it wrong is one, and the fix is
+ * a second weight texture rather than a wider block — the block is per draw and the texture is not.
+ */
+export const MAX_MORPH_TARGETS = 8;
+
+/**
+ * Where one target's delta for one vertex sits in the delta texture.
+ *
+ * Interleaved by vertex rather than by target — every target of a vertex is adjacent — because the
+ * shader reads all of them for one vertex and nothing reads one target across many vertices. That
+ * is one cache line instead of `targetCount` of them.
+ */
+export function morphTexelIndex(vertex: number, target: number, targetCount: number): number {
+  return vertex * targetCount + target;
+}
+
+/** Refuse a weight array that cannot drive the targets a mesh carries, naming both counts. */
+export function validateMorph(weights: Float32Array, targetCount: number): void {
+  if (targetCount < 1 || targetCount > MAX_MORPH_TARGETS) {
+    throw new Error(
+      `morph targets: ${targetCount} is outside 1 to ${MAX_MORPH_TARGETS}. See MAX_MORPH_TARGETS.`,
+    );
+  }
+  if (weights.length < targetCount) {
+    throw new Error(
+      `morph targets: ${weights.length} weights for ${targetCount} targets. Every target needs ` +
+        `one, or the ones past the end read as zero and that target silently never applies.`,
+    );
+  }
+}
+
+/** How wide the delta texture is for a mesh of this many vertices and targets. */
+export function morphTextureWidth(vertexCount: number, targetCount: number): number {
+  const texels = vertexCount * targetCount;
+  if (texels < 1) throw new Error('morph targets: a mesh needs at least one vertex and one target');
+  /*
+   * One row while it fits, then as many rows as it takes. WebGL2 guarantees a texture width of
+   * 2048 and nothing more, and a mesh times its targets passes that at 256 vertices with eight
+   * targets — which is a small mesh, so unlike the palette this is the ordinary case rather than
+   * the edge one.
+   */
+  return Math.min(texels, MORPH_TEXTURE_WIDTH);
+}
+
+/** Rows the delta texture needs, given the width above. */
+export function morphTextureRows(vertexCount: number, targetCount: number): number {
+  return Math.ceil((vertexCount * targetCount) / MORPH_TEXTURE_WIDTH);
+}
+
+/** WebGL2's guaranteed `MAX_TEXTURE_SIZE`, which is the only width that is safe everywhere. */
+const MORPH_TEXTURE_WIDTH = 2048;