@driftengine/core 3.61.0

package/src/render/backend/webgpu/shaders/clusterBin.wgsl.ts

@@ -0,0 +1,219 @@
+import {
+  CLUSTER_COUNT,
+  CLUSTER_TEXELS,
+  CLUSTER_X,
+  CLUSTER_Y,
+  CLUSTER_Z,
+  LIGHT_REGION_TEXELS,
+  LIGHT_TEXELS,
+  MAX_LIGHTS_PER_CLUSTER,
+  TABLE_WIDTH,
+} from '../../../clusteredLights.ts';
+
+/**
+ * The froxel binner, in WGSL, hand-authored.
+ *
+ * **`npm run wgsl` does not produce this file and `npm run wgsl:check` does not police it.** That
+ * is an exception to the standing rule that GLSL is the source of truth, it is written down in
+ * `AGENTS.md` under the 2026-08-12 rule, and the argument is in
+ * the compute-seam design. In one line: the rule exists so
+ * no shader is maintained twice and so a generator defect can only reach the backend that has a
+ * fallback, and a compute shader has no twin and no fallback — generating it would invert the very
+ * property the rule protects.
+ *
+ * **Every layout constant is interpolated from `clusteredLights.ts` rather than written here.**
+ * Two files agreeing about a stride by both containing the number 8 is the shape of defect this
+ * whole feature is gated against; there is one definition and this reads it.
+ *
+ * **It must produce the same bytes as `buildLightClusters`.** Where the two could have differed
+ * they were made to agree deliberately: lights are visited in increasing index so a cluster's list
+ * is sorted without sorting, unused slots are written as zero on both sides, and the overflow rule
+ * is the same eviction of the farthest from the cluster centre followed by the same ascending
+ * sort. `scripts/cluster-check.mjs` is what holds that, and the 2026-08-17 rule about two
+ * implementations of one decision is why it exists at all.
+ */
+export const CLUSTER_BIN_WGSL = `
+const CLUSTER_X: u32 = ${CLUSTER_X}u;
+const CLUSTER_Y: u32 = ${CLUSTER_Y}u;
+const CLUSTER_Z: u32 = ${CLUSTER_Z}u;
+const CLUSTER_COUNT: u32 = ${CLUSTER_COUNT}u;
+const CLUSTER_TEXELS: u32 = ${CLUSTER_TEXELS}u;
+const MAX_LIGHTS_PER_CLUSTER: u32 = ${MAX_LIGHTS_PER_CLUSTER}u;
+const LIGHT_TEXELS: u32 = ${LIGHT_TEXELS}u;
+const LIGHT_REGION_TEXELS: u32 = ${LIGHT_REGION_TEXELS}u;
+const TABLE_WIDTH: u32 = ${TABLE_WIDTH}u;
+
+struct Params {
+  view: mat4x4<f32>,
+  /** near, far, tan(fovY/2), aspect. */
+  frustum: vec4<f32>,
+  lightCount: u32,
+  pad0: u32,
+  pad1: u32,
+  pad2: u32,
+}
+
+@group(0) @binding(0) var<uniform> params: Params;
+/** Three vec4s a light, in exactly the record order \`buildLightClusters\` writes. */
+@group(0) @binding(1) var<storage, read> lights: array<vec4<f32>>;
+/**
+ * Write-only, which is all core WGSL offers and all the fixed-slot layout needs.
+ *
+ * A read-modify-write list would need a storage buffer and an atomic counter, and it is the reason
+ * a cluster owns a fixed run rather than appending into a shared one.
+ */
+@group(0) @binding(2) var table: texture_storage_2d<rgba32uint, write>;
+
+/** A flat texel index to its place in the table. TABLE_WIDTH divides both regions exactly. */
+fn texelAt(texel: u32) -> vec2<i32> {
+  return vec2<i32>(i32(texel % TABLE_WIDTH), i32(texel / TABLE_WIDTH));
+}
+
+fn sliceNearDepth(slice: f32) -> f32 {
+  return params.frustum.x * pow(params.frustum.y / params.frustum.x, slice / f32(CLUSTER_Z));
+}
+
+/** Squared distance from a point to an axis-aligned box, zero inside it. */
+fn distanceSqToBounds(p: vec3<f32>, lo: vec3<f32>, hi: vec3<f32>) -> f32 {
+  let d = max(max(lo - p, p - hi), vec3<f32>(0.0));
+  return dot(d, d);
+}
+
+/** A light's view-space centre, with depth positive along the view direction. */
+fn viewOf(light: u32) -> vec3<f32> {
+  let world = lights[light * LIGHT_TEXELS];
+  let v = params.view * vec4<f32>(world.xyz, 1.0);
+  return vec3<f32>(v.x, v.y, -v.z);
+}
+
+/**
+ * Squared distance from a light's view-space centre to a point.
+ *
+ * **Squared, matching \`centreDistanceSq\` in \`clusteredLights.ts\` rather than taking a root.** The
+ * ranking is identical either way, and a square root is one more operation for the two
+ * implementations to round differently.
+ */
+fn centreDistanceSq(light: u32, centre: vec3<f32>) -> f32 {
+  let d = viewOf(light) - centre;
+  return dot(d, d);
+}
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
+  let id = gid.x;
+
+  /*
+   * The light records, written by the first invocations that have one.
+   *
+   * **Two jobs in one kernel, and it is deliberate.** The records have to reach the same texture
+   * the clusters do, because the lit pass reads both through one texture unit; writing them from
+   * the CPU instead would mean a partial texture upload racing a dispatch over the same resource.
+   * There are always more clusters than lights, so every record has an invocation.
+   */
+  if (id < params.lightCount) {
+    let record = id * LIGHT_TEXELS;
+    for (var t: u32 = 0u; t < LIGHT_TEXELS; t = t + 1u) {
+      textureStore(table, texelAt(record + t), bitcast<vec4<u32>>(lights[record + t]));
+    }
+  }
+
+  if (id >= CLUSTER_COUNT) {
+    return;
+  }
+
+  let k = id / (CLUSTER_X * CLUSTER_Y);
+  let j = (id - k * CLUSTER_X * CLUSTER_Y) / CLUSTER_X;
+  let i = id - k * CLUSTER_X * CLUSTER_Y - j * CLUSTER_X;
+
+  /* The AABB of the froxel's eight corners, exactly as \`clusterViewBounds\` derives it. */
+  let zNear = sliceNearDepth(f32(k));
+  let zFar = sliceNearDepth(f32(k + 1u));
+  let xLo = -1.0 + 2.0 * f32(i) / f32(CLUSTER_X);
+  let xHi = -1.0 + 2.0 * f32(i + 1u) / f32(CLUSTER_X);
+  let yLo = -1.0 + 2.0 * f32(j) / f32(CLUSTER_Y);
+  let yHi = -1.0 + 2.0 * f32(j + 1u) / f32(CLUSTER_Y);
+  let halfHNear = zNear * params.frustum.z;
+  let halfHFar = zFar * params.frustum.z;
+  let halfWNear = halfHNear * params.frustum.w;
+  let halfWFar = halfHFar * params.frustum.w;
+
+  let lo = vec3<f32>(
+    min(min(xLo * halfWNear, xLo * halfWFar), min(xHi * halfWNear, xHi * halfWFar)),
+    min(min(yLo * halfHNear, yLo * halfHFar), min(yHi * halfHNear, yHi * halfHFar)),
+    zNear,
+  );
+  let hi = vec3<f32>(
+    max(max(xLo * halfWNear, xLo * halfWFar), max(xHi * halfWNear, xHi * halfWFar)),
+    max(max(yLo * halfHNear, yLo * halfHFar), max(yHi * halfHNear, yHi * halfHFar)),
+    zFar,
+  );
+  let centre = (lo + hi) * 0.5;
+
+  var indices: array<u32, MAX_LIGHTS_PER_CLUSTER>;
+  for (var n: u32 = 0u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {
+    indices[n] = 0u;
+  }
+  var count: u32 = 0u;
+
+  /* Increasing light index, which is what makes the list sorted without a sort. */
+  for (var light: u32 = 0u; light < params.lightCount; light = light + 1u) {
+    let radius = lights[light * LIGHT_TEXELS].w;
+    let v = viewOf(light);
+    if (v.z + radius <= 0.0) {
+      continue;
+    }
+    if (distanceSqToBounds(v, lo, hi) > radius * radius) {
+      continue;
+    }
+
+    if (count < MAX_LIGHTS_PER_CLUSTER) {
+      indices[count] = light;
+      count = count + 1u;
+      continue;
+    }
+
+    /*
+     * Full. Drop the farthest from the cluster's centre if this one is nearer.
+     *
+     * **The only float comparison that decides anything here**, and the reason the *order* is an
+     * integer: a float rank cannot be relied on to agree between this and the JavaScript binner,
+     * so it is confined to membership, where the conformance script forgives a light sitting
+     * within epsilon of a boundary.
+     */
+    var worstSlot: i32 = -1;
+    var worst = centreDistanceSq(light, centre);
+    for (var n: u32 = 0u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {
+      let d = centreDistanceSq(indices[n], centre);
+      if (d > worst) {
+        worst = d;
+        worstSlot = i32(n);
+      }
+    }
+    if (worstSlot < 0) {
+      continue;
+    }
+    indices[u32(worstSlot)] = light;
+
+    /* Insertion sort over at most 28 integers, so the bytes stay ascending after a replacement. */
+    for (var n: u32 = 1u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {
+      let value = indices[n];
+      var m: i32 = i32(n) - 1;
+      while (m >= 0 && indices[u32(m)] > value) {
+        indices[u32(m) + 1u] = indices[u32(m)];
+        m = m - 1;
+      }
+      indices[u32(m + 1)] = value;
+    }
+  }
+
+  let base = LIGHT_REGION_TEXELS + id * CLUSTER_TEXELS;
+  textureStore(table, texelAt(base), vec4<u32>(count, 0u, 0u, 0u));
+  for (var t: u32 = 0u; t < CLUSTER_TEXELS - 1u; t = t + 1u) {
+    textureStore(
+      table,
+      texelAt(base + 1u + t),
+      vec4<u32>(indices[t * 4u], indices[t * 4u + 1u], indices[t * 4u + 2u], indices[t * 4u + 3u]),
+    );
+  }
+}
+`;

package/src/render/backend/webgpu/skinPaletteRing.ts

@@ -0,0 +1,105 @@
+import { SkinPaletteTexture } from './skinPaletteTexture.ts';
+
+/**
+ * How many palettes one frame may set before the ring is full.
+ *
+ * The arithmetic rather than a round number: a character's palette is uploaded once per *pass*
+ * that draws it, and a full profile draws the same character five times — the main pass, a planar
+ * reflection, and the static, peel and dynamic shadow layers. So this is twenty-five characters at
+ * once, which is a crowd rather than a cast.
+ *
+ * **What it costs is nothing until it is used.** A slot allocates its texture on the first frame
+ * that reaches it and keeps it, so a scene with two characters holds two: a 24-joint rig is 96
+ * texels of `rgba32float`, which is 1.5 KB, and a 96-joint humanoid is 6 KB.
+ *
+ * **What would make it wrong** is a genuine crowd — a stadium, a swarm of rigged birds — and the
+ * fix is then the one `skinPalette.ts` names: one texture holding every palette with a per-draw
+ * row offset, which spends a uniform and a shader change to stop spending textures.
+ */
+export const MAX_SKIN_PALETTES = 128;
+
+/**
+ * Every joint palette a frame sets, each in its own texture, reused frame after frame.
+ *
+ * **This exists for the reason `UniformRing` exists, and the fact is the same one.**
+ * `queue.writeTexture` does not interleave with draw commands: writes are ordered on the queue
+ * timeline and the frame's encoder is submitted *after* all of them, so two palettes uploaded into
+ * one texture between two draws give **both** draws the last palette written. Not the first, not a
+ * blend — the last, for every skinned draw in the frame.
+ *
+ * What that looks like is not a skinning bug. Every character in the frame stands in the pose, and
+ * at the position, of whichever was drawn last, because a rig carries its placement in its palette
+ * rather than in `uModel`. Measured in the product: a game drawing a ghost of an earlier run and
+ * then the live character drew the ghost with the *character's* palette, so a translucent second body sat
+ * exactly on top of the player and read as a transparency fault.
+ *
+ * **The other backend needs none of this and that is not an asymmetry of decision.** WebGL2's
+ * `texSubImage2D` is a command in the same stream as the draws around it, so an upload between two
+ * draws separates them there by construction. The decision — a palette belongs to a draw — is one;
+ * only what it takes to honour it differs, which is what `skinPalette.ts` says a binder is for.
+ *
+ * **A slot is written at most once per frame**, since every `setSkinPalette` takes a fresh one.
+ * That is what makes the reallocation inside `SkinPaletteTexture` safe: a joint count can only
+ * change a slot's texture between frames, never while a recorded draw is still pointing at it.
+ */
+export class SkinPaletteRing {
+  private readonly slots: SkinPaletteTexture[] = [];
+  private used = 0;
+  private warnedFull = false;
+
+  /** How many slots this frame has taken. */
+  get count(): number {
+    return this.used;
+  }
+
+  /**
+   * Start a frame: every slot is free again.
+   *
+   * **Called where the frame's encoder is replaced and not a line earlier.** A slot may only be
+   * re-let once the draws pointing at it have been submitted, which is exactly what `beginFrame`
+   * has just done — including for anything drawn after the previous `endFrame`.
+   */
+  reset(): void {
+    this.used = 0;
+  }
+
+  /**
+   * Upload a palette into a slot of its own and return that slot, or null when the ring is full.
+   *
+   * **Null rather than reusing a slot**, because reusing one is the defect this class is named
+   * after: the caller's character would silently take another character's pose. A caller that runs
+   * out declines the draw and says so once.
+   */
+  take(device: GPUDevice, palette: Float32Array): number | null {
+    if (this.used >= MAX_SKIN_PALETTES) {
+      if (!this.warnedFull) {
+        this.warnedFull = true;
+        console.warn(
+          `WebGPU: more than ${MAX_SKIN_PALETTES} skin palettes in one frame; the rest of the ` +
+            'skinned draws are declined this frame rather than drawn in another rig’s pose. ' +
+            'See MAX_SKIN_PALETTES.',
+        );
+      }
+      return null;
+    }
+    const at = this.used++;
+    let slot = this.slots[at];
+    if (slot === undefined) {
+      slot = new SkinPaletteTexture();
+      this.slots[at] = slot;
+    }
+    slot.update(device, palette);
+    return at;
+  }
+
+  /** The view a draw binds for a slot, or null for a slot nothing has uploaded into. */
+  view(slot: number): GPUTextureView | null {
+    return this.slots[slot]?.view() ?? null;
+  }
+
+  dispose(): void {
+    for (const slot of this.slots) slot.dispose();
+    this.slots.length = 0;
+    this.used = 0;
+  }
+}

package/src/render/backend/webgpu/skinPaletteTexture.ts

@@ -0,0 +1,79 @@
+import { paletteTextureWidth, validateSkinPalette } from '../../skinPalette.ts';
+
+/**
+ * The joint palette as a one-row `rgba32float` texture, on WebGPU.
+ *
+ * The twin of the WebGL2 module of this name, and deliberately symmetric with it: one decision in
+ * `skinPalette.ts`, two thin binders, per the 2026-08-13 rule.
+ *
+ * **`rgba32float` is `unfilterable-float` to a bind group layout**, which costs nothing because
+ * the shader reads it with `textureLoad` — an integer coordinate and no sampler at all. A layout
+ * declaring it filterable would fail validation at pipeline creation, which is the loud failure
+ * rather than the quiet one.
+ */
+/*
+ * Spelled out rather than read from the global `GPUTextureUsage`, which is not in the TypeScript
+ * lib this package compiles against — `clusterBinner.ts` does the same and for the same reason.
+ */
+const TEXTURE_USAGE = {
+  COPY_DST: 0x02,
+  TEXTURE_BINDING: 0x04,
+} as const;
+
+export class SkinPaletteTexture {
+  private texture: GPUTexture | null = null;
+  private joints = 0;
+  /**
+   * The view, cached rather than created per call.
+   *
+   * `createView` allocates, and a bind group is rebuilt against this per draw — so a fresh view
+   * each time is both an allocation in the frame loop and a value that never compares equal,
+   * which would defeat any cache keyed on it. Invalidated only when the texture is replaced.
+   */
+  private cachedView: GPUTextureView | null = null;
+
+  /** Upload a palette, reallocating only when the joint count changes. */
+  update(device: GPUDevice, palette: Float32Array): void {
+    validateSkinPalette(palette);
+    const joints = palette.length / 16;
+    const width = paletteTextureWidth(joints);
+
+    if (this.texture === null || this.joints !== joints) {
+      this.texture?.destroy();
+      this.cachedView = null;
+      this.texture = device.createTexture({
+        /* Labelled, because `createGpuSurface`'s uncaptured-error lines are only legible when
+           every resource carries one. See the 2026-08-14 rule. */
+        label: `skin.palette:${joints}`,
+        size: { width, height: 1 },
+        format: 'rgba32float',
+        usage: TEXTURE_USAGE.TEXTURE_BINDING | TEXTURE_USAGE.COPY_DST,
+      });
+      this.joints = joints;
+    }
+
+    device.queue.writeTexture(
+      { texture: this.texture },
+      palette,
+      { bytesPerRow: width * 16 },
+      { width, height: 1 },
+    );
+  }
+
+  view(): GPUTextureView | null {
+    if (this.texture === null) return null;
+    if (this.cachedView === null) this.cachedView = this.texture.createView();
+    return this.cachedView;
+  }
+
+  get ready(): boolean {
+    return this.texture !== null;
+  }
+
+  dispose(): void {
+    this.texture?.destroy();
+    this.texture = null;
+    this.cachedView = null;
+    this.joints = 0;
+  }
+}

package/src/render/backend/webgpu/skyPass.ts

@@ -0,0 +1,85 @@
+import { DEPTH_COMPARE_EQUAL } from '../../depthConvention.ts';
+import { SKY_BINDINGS, SKY_FRAG_WGSL, SKY_VERT_WGSL } from '../../shaders/generated/sky.wgsl.ts';
+import { DEPTH_FORMAT } from './flatPass.ts';
+import type { PipelineCache } from './pipelineCache.ts';
+import { shaderModule } from './shaderModules.ts';
+
+/**
+ * The sky: one triangle covering the screen, with the world reconstructed per fragment.
+ *
+ * **No vertex buffers at all.** The vertex shader builds its three corners from
+ * `gl_VertexIndex` — `gl_VertexID` in the GLSL, which the transform renames — so there is
+ * nothing to upload and nothing to bind. That makes this the simplest pass in the engine to
+ * port and a good second one after `flat`.
+ */
+
+export const SKY_FIELDS = SKY_BINDINGS.SKY_FRAG.fields;
+export const SKY_UNIFORM_SIZE = SKY_BINDINGS.SKY_FRAG.uniformSize;
+
+const SKY_BINDING = SKY_BINDINGS.SKY_FRAG.uniforms;
+const VISIBILITY_FRAGMENT = 0x2;
+
+export function createSkyBindGroupLayout(device: GPUDevice): GPUBindGroupLayout {
+  return device.createBindGroupLayout({
+    label: 'sky.bindGroupLayout',
+    entries: [
+      {
+        binding: SKY_BINDING,
+        visibility: VISIBILITY_FRAGMENT,
+        buffer: { type: 'uniform', minBindingSize: SKY_UNIFORM_SIZE },
+      },
+    ],
+  });
+}
+
+export function createSkyBindGroup(
+  device: GPUDevice,
+  layout: GPUBindGroupLayout,
+  uniforms: GPUBuffer,
+): GPUBindGroup {
+  return device.createBindGroup({
+    label: 'sky.bindGroup',
+    layout,
+    entries: [{ binding: SKY_BINDING, resource: { buffer: uniforms, size: SKY_UNIFORM_SIZE } }],
+  });
+}
+
+/**
+ * The sky pipeline.
+ *
+ * **Depth is tested but not written**, which is what `gl.depthMask(false)` does on the
+ * WebGL2 path. The sky sits at the far plane, so writing its depth would push every later
+ * pass behind it; not testing at all would paint it over geometry already drawn.
+ */
+export function skyPipeline(
+  cache: PipelineCache,
+  device: GPUDevice,
+  layout: GPUBindGroupLayout,
+): GPURenderPipeline {
+  return cache.get('sky', () => ({
+    label: 'sky',
+    layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+    vertex: {
+      module: shaderModule(device, { label: 'sky.vert', code: SKY_VERT_WGSL }),
+      entryPoint: 'main',
+      buffers: [],
+    },
+    fragment: {
+      module: shaderModule(device, { label: 'sky.frag', code: SKY_FRAG_WGSL }),
+      entryPoint: 'main',
+      targets: [{ format: cache.format }],
+    },
+    primitive: { topology: 'triangle-list' },
+    multisample: { count: cache.sampleCount },
+    depthStencil: {
+      format: DEPTH_FORMAT,
+      depthWriteEnabled: false,
+      /*
+       * `less-equal` rather than `less`: the triangle is emitted at exactly the far plane,
+       * and a cleared depth buffer holds exactly that value, so `less` would reject every
+       * fragment and the sky would never appear.
+       */
+      depthCompare: DEPTH_COMPARE_EQUAL,
+    },
+  }));
+}