@driftengine/core 4.8.4 → 4.8.6

package/dist/render/backend/webgpu/shaders/clusterBin.wgsl.d.ts

@@ -20,4 +20,4 @@
  * 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 declare const CLUSTER_BIN_WGSL = "\nconst CLUSTER_X: u32 = 16u;\nconst CLUSTER_Y: u32 = 9u;\nconst CLUSTER_Z: u32 = 24u;\nconst CLUSTER_COUNT: u32 = 3456u;\nconst CLUSTER_TEXELS: u32 = 20u;\nconst MAX_LIGHTS_PER_CLUSTER: u32 = 76u;\nconst LIGHT_TEXELS: u32 = 5u;\nconst LIGHT_REGION_TEXELS: u32 = 1600u;\nconst TABLE_WIDTH: u32 = 320u;\n\nstruct Params {\n  view: mat4x4<f32>,\n  /** near, far, tan(fovY/2), aspect. */\n  frustum: vec4<f32>,\n  lightCount: u32,\n  pad0: u32,\n  pad1: u32,\n  pad2: u32,\n}\n\n@group(0) @binding(0) var<uniform> params: Params;\n/**\n * The records as `writeLightRecord` lays them out, as bits. **`u32`, not `f32`**, because one\n * slot holds two halves, and a zero weight read as a float would be a subnormal a GPU is free to\n * flush on the way through; read as bits, the copy into the table cannot change them.\n */\n@group(0) @binding(1) var<storage, read> lights: array<vec4<u32>>;\n/**\n * Write-only, which is all core WGSL offers and all the fixed-slot layout needs.\n *\n * A read-modify-write list would need a storage buffer and an atomic counter, and it is the reason\n * a cluster owns a fixed run rather than appending into a shared one.\n */\n@group(0) @binding(2) var table: texture_storage_2d<rgba32uint, write>;\n\n/** A flat texel index to its place in the table. TABLE_WIDTH divides both regions exactly. */\nfn texelAt(texel: u32) -> vec2<i32> {\n  return vec2<i32>(i32(texel % TABLE_WIDTH), i32(texel / TABLE_WIDTH));\n}\n\nfn sliceNearDepth(slice: f32) -> f32 {\n  return params.frustum.x * pow(params.frustum.y / params.frustum.x, slice / f32(CLUSTER_Z));\n}\n\n/** Squared distance from a point to an axis-aligned box, zero inside it. */\nfn distanceSqToBounds(p: vec3<f32>, lo: vec3<f32>, hi: vec3<f32>) -> f32 {\n  let d = max(max(lo - p, p - hi), vec3<f32>(0.0));\n  return dot(d, d);\n}\n\n/** A light's view-space centre, with depth positive along the view direction. */\nfn viewOf(light: u32) -> vec3<f32> {\n  let world = bitcast<vec4<f32>>(lights[light * LIGHT_TEXELS]);\n  let v = params.view * vec4<f32>(world.xyz, 1.0);\n  return vec3<f32>(v.x, v.y, -v.z);\n}\n\n/**\n * Squared distance from a light's view-space centre to a point.\n *\n * **Squared, matching `centreDistanceSq` in `clusteredLights.ts` rather than taking a root.** The\n * ranking is identical either way, and a square root is one more operation for the two\n * implementations to round differently.\n */\nfn centreDistanceSq(light: u32, centre: vec3<f32>) -> f32 {\n  let d = viewOf(light) - centre;\n  return dot(d, d);\n}\n\n@compute @workgroup_size(64)\nfn main(@builtin(global_invocation_id) gid: vec3<u32>) {\n  let id = gid.x;\n\n  /*\n   * The light records, written by the first invocations that have one.\n   *\n   * **Two jobs in one kernel, and it is deliberate.** The records have to reach the same texture\n   * the clusters do, because the lit pass reads both through one texture unit; writing them from\n   * the CPU instead would mean a partial texture upload racing a dispatch over the same resource.\n   * There are always more clusters than lights, so every record has an invocation.\n   */\n  if (id < params.lightCount) {\n    let record = id * LIGHT_TEXELS;\n    for (var t: u32 = 0u; t < LIGHT_TEXELS; t = t + 1u) {\n      textureStore(table, texelAt(record + t), lights[record + t]);\n    }\n  }\n\n  if (id >= CLUSTER_COUNT) {\n    return;\n  }\n\n  let k = id / (CLUSTER_X * CLUSTER_Y);\n  let j = (id - k * CLUSTER_X * CLUSTER_Y) / CLUSTER_X;\n  let i = id - k * CLUSTER_X * CLUSTER_Y - j * CLUSTER_X;\n\n  /* The AABB of the froxel's eight corners, exactly as `clusterViewBounds` derives it. */\n  let zNear = sliceNearDepth(f32(k));\n  let zFar = sliceNearDepth(f32(k + 1u));\n  let xLo = -1.0 + 2.0 * f32(i) / f32(CLUSTER_X);\n  let xHi = -1.0 + 2.0 * f32(i + 1u) / f32(CLUSTER_X);\n  let yLo = -1.0 + 2.0 * f32(j) / f32(CLUSTER_Y);\n  let yHi = -1.0 + 2.0 * f32(j + 1u) / f32(CLUSTER_Y);\n  let halfHNear = zNear * params.frustum.z;\n  let halfHFar = zFar * params.frustum.z;\n  let halfWNear = halfHNear * params.frustum.w;\n  let halfWFar = halfHFar * params.frustum.w;\n\n  let lo = vec3<f32>(\n    min(min(xLo * halfWNear, xLo * halfWFar), min(xHi * halfWNear, xHi * halfWFar)),\n    min(min(yLo * halfHNear, yLo * halfHFar), min(yHi * halfHNear, yHi * halfHFar)),\n    zNear,\n  );\n  let hi = vec3<f32>(\n    max(max(xLo * halfWNear, xLo * halfWFar), max(xHi * halfWNear, xHi * halfWFar)),\n    max(max(yLo * halfHNear, yLo * halfHFar), max(yHi * halfHNear, yHi * halfHFar)),\n    zFar,\n  );\n  let centre = (lo + hi) * 0.5;\n\n  var indices: array<u32, MAX_LIGHTS_PER_CLUSTER>;\n  for (var n: u32 = 0u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {\n    indices[n] = 0u;\n  }\n  var count: u32 = 0u;\n\n  /* Increasing light index, which is what makes the list sorted without a sort. */\n  for (var light: u32 = 0u; light < params.lightCount; light = light + 1u) {\n    let radius = bitcast<f32>(lights[light * LIGHT_TEXELS].w);\n    let v = viewOf(light);\n    if (v.z + radius <= 0.0) {\n      continue;\n    }\n    if (distanceSqToBounds(v, lo, hi) > radius * radius) {\n      continue;\n    }\n\n    if (count < MAX_LIGHTS_PER_CLUSTER) {\n      indices[count] = light;\n      count = count + 1u;\n      continue;\n    }\n\n    /*\n     * Full. Drop the farthest from the cluster's centre if this one is nearer.\n     *\n     * **The only float comparison that decides anything here**, and the reason the *order* is an\n     * integer: a float rank cannot be relied on to agree between this and the JavaScript binner,\n     * so it is confined to membership, where the conformance script forgives a light sitting\n     * within epsilon of a boundary.\n     */\n    var worstSlot: i32 = -1;\n    var worst = centreDistanceSq(light, centre);\n    for (var n: u32 = 0u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {\n      let d = centreDistanceSq(indices[n], centre);\n      if (d > worst) {\n        worst = d;\n        worstSlot = i32(n);\n      }\n    }\n    if (worstSlot < 0) {\n      continue;\n    }\n    indices[u32(worstSlot)] = light;\n\n    /* Insertion sort over at most 28 integers, so the bytes stay ascending after a replacement. */\n    for (var n: u32 = 1u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {\n      let value = indices[n];\n      var m: i32 = i32(n) - 1;\n      while (m >= 0 && indices[u32(m)] > value) {\n        indices[u32(m) + 1u] = indices[u32(m)];\n        m = m - 1;\n      }\n      indices[u32(m + 1)] = value;\n    }\n  }\n\n  let base = LIGHT_REGION_TEXELS + id * CLUSTER_TEXELS;\n  textureStore(table, texelAt(base), vec4<u32>(count, 0u, 0u, 0u));\n  for (var t: u32 = 0u; t < CLUSTER_TEXELS - 1u; t = t + 1u) {\n    textureStore(\n      table,\n      texelAt(base + 1u + t),\n      vec4<u32>(indices[t * 4u], indices[t * 4u + 1u], indices[t * 4u + 2u], indices[t * 4u + 3u]),\n    );\n  }\n}\n";
+export declare const CLUSTER_BIN_WGSL = "\nconst CLUSTER_X: u32 = 16u;\nconst CLUSTER_Y: u32 = 9u;\nconst CLUSTER_Z: u32 = 24u;\nconst CLUSTER_COUNT: u32 = 3456u;\nconst CLUSTER_TEXELS: u32 = 20u;\nconst MAX_LIGHTS_PER_CLUSTER: u32 = 76u;\nconst LIGHT_TEXELS: u32 = 5u;\nconst LIGHT_REGION_TEXELS: u32 = 1600u;\nconst TABLE_WIDTH: u32 = 320u;\n\nstruct Params {\n  view: mat4x4<f32>,\n  /** near, far, tan(fovY/2), aspect. */\n  frustum: vec4<f32>,\n  lightCount: u32,\n  pad0: u32,\n  pad1: u32,\n  pad2: u32,\n}\n\n@group(0) @binding(0) var<uniform> params: Params;\n/**\n * The records as `writeLightRecord` lays them out, as bits. **`u32`, not `f32`**, because one\n * slot holds two halves, and a zero weight read as a float would be a subnormal a GPU is free to\n * flush on the way through; read as bits, the copy into the table cannot change them.\n */\n@group(0) @binding(1) var<storage, read> lights: array<vec4<u32>>;\n/**\n * Write-only, which is all core WGSL offers and all the fixed-slot layout needs.\n *\n * A read-modify-write list would need a storage buffer and an atomic counter, and it is the reason\n * a cluster owns a fixed run rather than appending into a shared one.\n */\n@group(0) @binding(2) var table: texture_storage_2d<rgba32uint, write>;\n\n/** A flat texel index to its place in the table. TABLE_WIDTH divides both regions exactly. */\nfn texelAt(texel: u32) -> vec2<i32> {\n  return vec2<i32>(i32(texel % TABLE_WIDTH), i32(texel / TABLE_WIDTH));\n}\n\nfn sliceNearDepth(slice: f32) -> f32 {\n  return params.frustum.x * pow(params.frustum.y / params.frustum.x, slice / f32(CLUSTER_Z));\n}\n\n/** Squared distance from a point to an axis-aligned box, zero inside it. */\nfn distanceSqToBounds(p: vec3<f32>, lo: vec3<f32>, hi: vec3<f32>) -> f32 {\n  let d = max(max(lo - p, p - hi), vec3<f32>(0.0));\n  return dot(d, d);\n}\n\n/** A light's view-space centre, with depth positive along the view direction. */\nfn viewOf(light: u32) -> vec3<f32> {\n  let world = bitcast<vec4<f32>>(lights[light * LIGHT_TEXELS]);\n  let v = params.view * vec4<f32>(world.xyz, 1.0);\n  return vec3<f32>(v.x, v.y, -v.z);\n}\n\n/**\n * Squared distance from a light's view-space centre to a point.\n *\n * **Squared, matching `centreDistanceSq` in `clusteredLights.ts` rather than taking a root.** The\n * ranking is identical either way, and a square root is one more operation for the two\n * implementations to round differently.\n */\nfn centreDistanceSq(light: u32, centre: vec3<f32>) -> f32 {\n  let d = viewOf(light) - centre;\n  return dot(d, d);\n}\n\n/**\n * Whether a spot's cone misses this froxel: `coneBoxGap` in `clusteredLights.ts`, the same\n * arithmetic in the same order \u2014 the froxel's bounding sphere against the infinite cone, its apex\n * included, which can keep a light the shader would not draw and never drop one it would. A light\n * with no cone carries a cosine of -2 and never reaches the test.\n */\nfn outsideCone(light: u32, apex: vec3<f32>, lo: vec3<f32>, hi: vec3<f32>) -> bool {\n  let cosOuter = bitcast<f32>(lights[light * LIGHT_TEXELS + 3u].y);\n  if (cosOuter <= -1.0) {\n    return false;\n  }\n  let world = bitcast<vec3<f32>>(lights[light * LIGHT_TEXELS + 2u].yzw);\n  let a = (params.view * vec4<f32>(world, 0.0)).xyz;\n  let axis = vec3<f32>(a.x, a.y, -a.z);\n  let len = length(axis);\n  /* The shader measures the cone against the direction as given, so a long one is a wider cone. */\n  if (len <= 1e-6 || cosOuter / len <= -1.0) {\n    return false;\n  }\n  let cosA = cosOuter / len;\n  let sinA = sqrt(max(0.0, 1.0 - cosA * cosA));\n  let unit = axis / len;\n  let extent = (hi - lo) * 0.5;\n  let toCentre = (lo + hi) * 0.5 - apex;\n  let along = dot(toCentre, unit);\n  let lengthSq = dot(toCentre, toCentre);\n  let across = sqrt(max(lengthSq - along * along, 0.0));\n  let reach = sqrt(lengthSq);\n  var distance = cosA * across - along * sinA;\n  if (along < -sinA * reach) {\n    distance = reach;\n  }\n  return distance - length(extent) > 0.0;\n}\n\n@compute @workgroup_size(64)\nfn main(@builtin(global_invocation_id) gid: vec3<u32>) {\n  let id = gid.x;\n\n  /*\n   * The light records, written by the first invocations that have one.\n   *\n   * **Two jobs in one kernel, and it is deliberate.** The records have to reach the same texture\n   * the clusters do, because the lit pass reads both through one texture unit; writing them from\n   * the CPU instead would mean a partial texture upload racing a dispatch over the same resource.\n   * There are always more clusters than lights, so every record has an invocation.\n   */\n  if (id < params.lightCount) {\n    let record = id * LIGHT_TEXELS;\n    for (var t: u32 = 0u; t < LIGHT_TEXELS; t = t + 1u) {\n      textureStore(table, texelAt(record + t), lights[record + t]);\n    }\n  }\n\n  if (id >= CLUSTER_COUNT) {\n    return;\n  }\n\n  let k = id / (CLUSTER_X * CLUSTER_Y);\n  let j = (id - k * CLUSTER_X * CLUSTER_Y) / CLUSTER_X;\n  let i = id - k * CLUSTER_X * CLUSTER_Y - j * CLUSTER_X;\n\n  /* The AABB of the froxel's eight corners, exactly as `clusterViewBounds` derives it. */\n  let zNear = sliceNearDepth(f32(k));\n  let zFar = sliceNearDepth(f32(k + 1u));\n  let xLo = -1.0 + 2.0 * f32(i) / f32(CLUSTER_X);\n  let xHi = -1.0 + 2.0 * f32(i + 1u) / f32(CLUSTER_X);\n  let yLo = -1.0 + 2.0 * f32(j) / f32(CLUSTER_Y);\n  let yHi = -1.0 + 2.0 * f32(j + 1u) / f32(CLUSTER_Y);\n  let halfHNear = zNear * params.frustum.z;\n  let halfHFar = zFar * params.frustum.z;\n  let halfWNear = halfHNear * params.frustum.w;\n  let halfWFar = halfHFar * params.frustum.w;\n\n  let lo = vec3<f32>(\n    min(min(xLo * halfWNear, xLo * halfWFar), min(xHi * halfWNear, xHi * halfWFar)),\n    min(min(yLo * halfHNear, yLo * halfHFar), min(yHi * halfHNear, yHi * halfHFar)),\n    zNear,\n  );\n  let hi = vec3<f32>(\n    max(max(xLo * halfWNear, xLo * halfWFar), max(xHi * halfWNear, xHi * halfWFar)),\n    max(max(yLo * halfHNear, yLo * halfHFar), max(yHi * halfHNear, yHi * halfHFar)),\n    zFar,\n  );\n  let centre = (lo + hi) * 0.5;\n\n  var indices: array<u32, MAX_LIGHTS_PER_CLUSTER>;\n  for (var n: u32 = 0u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {\n    indices[n] = 0u;\n  }\n  var count: u32 = 0u;\n\n  /* Increasing light index, which is what makes the list sorted without a sort. */\n  for (var light: u32 = 0u; light < params.lightCount; light = light + 1u) {\n    /* A rectangle carries its reach negated, which is how the lit pass tells it from a lamp. */\n    let signedRadius = bitcast<f32>(lights[light * LIGHT_TEXELS].w);\n    let radius = abs(signedRadius);\n    let v = viewOf(light);\n    if (v.z + radius <= 0.0) {\n      continue;\n    }\n    if (distanceSqToBounds(v, lo, hi) > radius * radius) {\n      continue;\n    }\n    if (signedRadius >= 0.0 && outsideCone(light, v, lo, hi)) {\n      continue;\n    }\n\n    if (count < MAX_LIGHTS_PER_CLUSTER) {\n      indices[count] = light;\n      count = count + 1u;\n      continue;\n    }\n\n    /*\n     * Full. Drop the farthest from the cluster's centre if this one is nearer.\n     *\n     * **The only float comparison that decides anything here**, and the reason the *order* is an\n     * integer: a float rank cannot be relied on to agree between this and the JavaScript binner,\n     * so it is confined to membership, where the conformance script forgives a light sitting\n     * within epsilon of a boundary.\n     */\n    var worstSlot: i32 = -1;\n    var worst = centreDistanceSq(light, centre);\n    for (var n: u32 = 0u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {\n      let d = centreDistanceSq(indices[n], centre);\n      if (d > worst) {\n        worst = d;\n        worstSlot = i32(n);\n      }\n    }\n    if (worstSlot < 0) {\n      continue;\n    }\n    indices[u32(worstSlot)] = light;\n\n    /* Insertion sort over at most 28 integers, so the bytes stay ascending after a replacement. */\n    for (var n: u32 = 1u; n < MAX_LIGHTS_PER_CLUSTER; n = n + 1u) {\n      let value = indices[n];\n      var m: i32 = i32(n) - 1;\n      while (m >= 0 && indices[u32(m)] > value) {\n        indices[u32(m) + 1u] = indices[u32(m)];\n        m = m - 1;\n      }\n      indices[u32(m + 1)] = value;\n    }\n  }\n\n  let base = LIGHT_REGION_TEXELS + id * CLUSTER_TEXELS;\n  textureStore(table, texelAt(base), vec4<u32>(count, 0u, 0u, 0u));\n  for (var t: u32 = 0u; t < CLUSTER_TEXELS - 1u; t = t + 1u) {\n    textureStore(\n      table,\n      texelAt(base + 1u + t),\n      vec4<u32>(indices[t * 4u], indices[t * 4u + 1u], indices[t * 4u + 2u], indices[t * 4u + 3u]),\n    );\n  }\n}\n";

package/dist/render/backend/webgpu/shaders/clusterBin.wgsl.js

@@ -91,6 +91,41 @@ fn centreDistanceSq(light: u32, centre: vec3<f32>) -> f32 {
   return dot(d, d);
 }
 
+/**
+ * Whether a spot's cone misses this froxel: \`coneBoxGap\` in \`clusteredLights.ts\`, the same
+ * arithmetic in the same order — the froxel's bounding sphere against the infinite cone, its apex
+ * included, which can keep a light the shader would not draw and never drop one it would. A light
+ * with no cone carries a cosine of -2 and never reaches the test.
+ */
+fn outsideCone(light: u32, apex: vec3<f32>, lo: vec3<f32>, hi: vec3<f32>) -> bool {
+  let cosOuter = bitcast<f32>(lights[light * LIGHT_TEXELS + 3u].y);
+  if (cosOuter <= -1.0) {
+    return false;
+  }
+  let world = bitcast<vec3<f32>>(lights[light * LIGHT_TEXELS + 2u].yzw);
+  let a = (params.view * vec4<f32>(world, 0.0)).xyz;
+  let axis = vec3<f32>(a.x, a.y, -a.z);
+  let len = length(axis);
+  /* The shader measures the cone against the direction as given, so a long one is a wider cone. */
+  if (len <= 1e-6 || cosOuter / len <= -1.0) {
+    return false;
+  }
+  let cosA = cosOuter / len;
+  let sinA = sqrt(max(0.0, 1.0 - cosA * cosA));
+  let unit = axis / len;
+  let extent = (hi - lo) * 0.5;
+  let toCentre = (lo + hi) * 0.5 - apex;
+  let along = dot(toCentre, unit);
+  let lengthSq = dot(toCentre, toCentre);
+  let across = sqrt(max(lengthSq - along * along, 0.0));
+  let reach = sqrt(lengthSq);
+  var distance = cosA * across - along * sinA;
+  if (along < -sinA * reach) {
+    distance = reach;
+  }
+  return distance - length(extent) > 0.0;
+}
+
 @compute @workgroup_size(64)
 fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
   let id = gid.x;
@@ -150,7 +185,9 @@ fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
 
   /* 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 = bitcast<f32>(lights[light * LIGHT_TEXELS].w);
+    /* A rectangle carries its reach negated, which is how the lit pass tells it from a lamp. */
+    let signedRadius = bitcast<f32>(lights[light * LIGHT_TEXELS].w);
+    let radius = abs(signedRadius);
     let v = viewOf(light);
     if (v.z + radius <= 0.0) {
       continue;
@@ -158,6 +195,9 @@ fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
     if (distanceSqToBounds(v, lo, hi) > radius * radius) {
       continue;
     }
+    if (signedRadius >= 0.0 && outsideCone(light, v, lo, hi)) {
+      continue;
+    }
 
     if (count < MAX_LIGHTS_PER_CLUSTER) {
       indices[count] = light;

package/dist/render/backend/webgpu/skinPaletteRing.d.ts

@@ -1,24 +1,3 @@
-/**
- * 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.
- *
- * **A reconstructing frame spends one more per skinned mover**: last frame's pose is uploaded into
- * a slot of its own for the motion pass. So the same budget is about twelve such characters with a
- * reflection and three shadow layers each.
- */
-export declare const MAX_SKIN_PALETTES = 128;
 /**
  * Every joint palette a frame sets, each in its own texture, reused frame after frame.
  *
@@ -39,16 +18,46 @@ export declare const MAX_SKIN_PALETTES = 128;
  * 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.
+ * **A palette set again with the same numbers is the slot it already has.** A rig is drawn in
+ * every pass of a frame — the main pass, a reflection, three shadow layers — and each one used to
+ * upload the same matrices into a slot of its own, so a crowd ran out five times sooner than it
+ * had characters. The ring now remembers the slot each array last went into and compares what it
+ * holds, so a rig posed once a frame spends one slot however many passes draw it. Identity alone
+ * would be wrong: a caller may pose every rig into one scratch array, and that array then holds a
+ * different rig at every set — the comparison is what tells the two apart.
+ *
+ * **It was capped at 128 until 4.8.6, and the cap declined draws.** A stage of three dozen idling
+ * extras beside two fighters filled it in one frame and every skinned draw past it was refused, so
+ * the consumer stood its crowd in the bind pose. The ring now holds as many palettes as a frame
+ * holds draws (`RenderQuality.drawsPerFrame`), since no frame can bind more palettes than it draws;
+ * a slot still allocates its texture only the first time a frame reaches it, so a scene with two
+ * characters holds two. **What it costs** is a texture and a cached bind group a slot, 1.5 KB for a
+ * 24-joint rig and 6 KB for a 96-joint humanoid. **What would make it wrong** is a crowd of
+ * thousands, where a texture a palette is the expensive half; the fix is then one texture holding
+ * every palette with a row offset per draw, which spends a per-draw uniform and a vertex-stage
+ * change to stop spending textures.
+ *
+ * **A slot is written at most once per frame**, since a palette that differs from what a slot
+ * holds always 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 declare class SkinPaletteRing {
+    private readonly capacity;
     private readonly slots;
+    /** What each slot was last written with, for the comparison that lets a pass reuse it. */
+    private readonly held;
+    /** The slot each palette array last went into, by identity. Weak, so a caller's array can go. */
+    private readonly lastSlot;
     private used;
+    private uploads;
     private warnedFull;
+    /** `capacity` is how many palettes one frame may hold: one per draw at most. */
+    constructor(capacity: number);
     /** How many slots this frame has taken. */
     get count(): number;
+    /** How many palettes have been written to the device since the ring was made. */
+    get uploaded(): number;
     /**
      * Start a frame: every slot is free again.
      *
@@ -62,14 +71,17 @@ export declare class SkinPaletteRing {
     /** Give back every slot taken since `mark`, once the commands reading them are submitted. */
     rewind(mark: number): void;
     /**
-     * Upload a palette into a slot of its own and return that slot, or null when the ring is full.
+     * The slot this frame holds for these numbers, uploading them into a fresh one where none does,
+     * 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.
+     * **Null rather than reusing a slot that holds something else**, because that 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;
     /** The view a draw binds for a slot, or null for a slot nothing has uploaded into. */
     view(slot: number): GPUTextureView | null;
     dispose(): void;
+    /** Whether a slot was last written with exactly these numbers. */
+    private holds;
 }

package/dist/render/backend/webgpu/skinPaletteRing.js

@@ -1,25 +1,4 @@
 import { SkinPaletteTexture } from './skinPaletteTexture.js';
-/**
- * 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.
- *
- * **A reconstructing frame spends one more per skinned mover**: last frame's pose is uploaded into
- * a slot of its own for the motion pass. So the same budget is about twelve such characters with a
- * reflection and three shadow layers each.
- */
-export const MAX_SKIN_PALETTES = 128;
 /**
  * Every joint palette a frame sets, each in its own texture, reused frame after frame.
  *
@@ -40,18 +19,52 @@ export const MAX_SKIN_PALETTES = 128;
  * 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.
+ * **A palette set again with the same numbers is the slot it already has.** A rig is drawn in
+ * every pass of a frame — the main pass, a reflection, three shadow layers — and each one used to
+ * upload the same matrices into a slot of its own, so a crowd ran out five times sooner than it
+ * had characters. The ring now remembers the slot each array last went into and compares what it
+ * holds, so a rig posed once a frame spends one slot however many passes draw it. Identity alone
+ * would be wrong: a caller may pose every rig into one scratch array, and that array then holds a
+ * different rig at every set — the comparison is what tells the two apart.
+ *
+ * **It was capped at 128 until 4.8.6, and the cap declined draws.** A stage of three dozen idling
+ * extras beside two fighters filled it in one frame and every skinned draw past it was refused, so
+ * the consumer stood its crowd in the bind pose. The ring now holds as many palettes as a frame
+ * holds draws (`RenderQuality.drawsPerFrame`), since no frame can bind more palettes than it draws;
+ * a slot still allocates its texture only the first time a frame reaches it, so a scene with two
+ * characters holds two. **What it costs** is a texture and a cached bind group a slot, 1.5 KB for a
+ * 24-joint rig and 6 KB for a 96-joint humanoid. **What would make it wrong** is a crowd of
+ * thousands, where a texture a palette is the expensive half; the fix is then one texture holding
+ * every palette with a row offset per draw, which spends a per-draw uniform and a vertex-stage
+ * change to stop spending textures.
+ *
+ * **A slot is written at most once per frame**, since a palette that differs from what a slot
+ * holds always 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 {
+    capacity;
     slots = [];
+    /** What each slot was last written with, for the comparison that lets a pass reuse it. */
+    held = [];
+    /** The slot each palette array last went into, by identity. Weak, so a caller's array can go. */
+    lastSlot = new WeakMap();
     used = 0;
+    uploads = 0;
     warnedFull = false;
+    /** `capacity` is how many palettes one frame may hold: one per draw at most. */
+    constructor(capacity) {
+        this.capacity = capacity;
+    }
     /** How many slots this frame has taken. */
     get count() {
         return this.used;
     }
+    /** How many palettes have been written to the device since the ring was made. */
+    get uploaded() {
+        return this.uploads;
+    }
     /**
      * Start a frame: every slot is free again.
      *
@@ -72,19 +85,23 @@ export class SkinPaletteRing {
             this.used = mark;
     }
     /**
-     * Upload a palette into a slot of its own and return that slot, or null when the ring is full.
+     * The slot this frame holds for these numbers, uploading them into a fresh one where none does,
+     * 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.
+     * **Null rather than reusing a slot that holds something else**, because that 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, palette) {
-        if (this.used >= MAX_SKIN_PALETTES) {
+        const known = this.lastSlot.get(palette);
+        if (known !== undefined && known < this.used && this.holds(known, palette))
+            return known;
+        if (this.used >= this.capacity) {
             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.');
+                console.warn(`WebGPU: more than ${this.capacity} distinct skin palettes in one frame, which is ` +
+                    'RenderQuality.drawsPerFrame; the rest of the skinned draws are declined this frame ' +
+                    'rather than drawn in another rig’s pose.');
             }
             return null;
         }
@@ -95,6 +112,15 @@ export class SkinPaletteRing {
             this.slots[at] = slot;
         }
         slot.update(device, palette);
+        this.uploads += 1;
+        let copy = this.held[at];
+        if (copy === undefined || copy.length !== palette.length) {
+            /* Once per slot and joint count, the way the slot's own texture is: never per frame. */
+            copy = new Float32Array(palette.length);
+            this.held[at] = copy;
+        }
+        copy.set(palette);
+        this.lastSlot.set(palette, at);
         return at;
     }
     /** The view a draw binds for a slot, or null for a slot nothing has uploaded into. */
@@ -105,6 +131,17 @@ export class SkinPaletteRing {
         for (const slot of this.slots)
             slot.dispose();
         this.slots.length = 0;
+        this.held.length = 0;
         this.used = 0;
     }
+    /** Whether a slot was last written with exactly these numbers. */
+    holds(slot, palette) {
+        const copy = this.held[slot];
+        if (copy === undefined || copy.length !== palette.length)
+            return false;
+        for (let i = 0; i < copy.length; i++)
+            if (copy[i] !== palette[i])
+                return false;
+        return true;
+    }
 }

package/dist/render/backend/webgpu/skinScatterPass.d.ts

@@ -10,14 +10,20 @@ export declare class SkinScatterPass {
     private readonly linear;
     private readonly nearest;
     private readonly commands;
+    /** The same draws again, through the pipelines that write the skin's colour alone. */
+    private readonly albedoCommands;
     /** Each profile's scatter distance per channel, in metres: four floats a profile. */
     private readonly profiles;
     private diffuse;
     private diffuseMsaa;
     private across;
+    private albedo;
+    private albedoMsaa;
     private diffuseView;
     private diffuseMsaaView;
     private acrossView;
+    private albedoView;
+    private albedoMsaaView;
     private groupAcross;
     private groupDown;
     private groupsDepth;
@@ -26,13 +32,15 @@ export declare class SkinScatterPass {
     get pending(): boolean;
     /** A command for one skin draw's diffuse half, filled by the caller. */
     take(): DrawCommand;
+    /** A command for the same draw's colour half, filled by the caller. */
+    takeAlbedo(): DrawCommand;
     /** What one profile scatters, per channel, in metres: the last material to name it says. */
     setProfile(index: number, r: number, g: number, b: number): void;
     /** The targets at the frame's size and sample count, made again only when either changes. */
     size(width: number, height: number, samples: number): void;
     /**
-     * Every kept draw's diffuse into the target, against the frame's own depth, which it reads and
-     * does not write. Called with no pass open on `encoder`.
+     * Every kept draw's diffuse into the target, and its colour into the other, against the frame's
+     * own depth, which they read and do not write. Called with no pass open on `encoder`.
      */
     drawDiffuse(encoder: GPUCommandEncoder, depth: GPUTextureView, issue: (pass: GPURenderPassEncoder, command: DrawCommand) => void, timestampWrites: GPURenderPassTimestampWrites | undefined): void;
     /**

package/dist/render/backend/webgpu/skinScatterPass.js

@@ -3,19 +3,21 @@
  * that spread them. `skinBlur.ts` is what the blur computes and why; this is where it runs.
  *
  * **What the renderer hands it.** Each skin draw, recorded into the frame with its diffuse taken
- * out, is recorded a second time here with the diffuse alone. When the frame first draws something
- * blended — or ends, if nothing is — the renderer ends its pass and calls `drawDiffuse`, which
- * replays them into a half-float target against the frame's own depth; resolves the depth; and
- * calls `spread`, which blurs across into a second target and then down, adding into the frame.
+ * out, is recorded twice more here: with the diffuse's light alone, and with its colour alone.
+ * When the frame first draws something blended — or ends, if nothing is — the renderer ends its
+ * pass and calls `drawDiffuse`, which replays them into two half-float targets against the frame's
+ * own depth; resolves the depth; and calls `spread`, which blurs the light across into a third
+ * target and then down, multiplied by the colour, adding into the frame.
  *
  * **The draws are commands, not calls**, for the reason `LatePass` keeps its own pool: the frame
  * graph's is spent at every flush, and these are replayed after the flush that ends the frame's
  * pass. Each holds the per-draw ring slot its frame half used, and those stay valid until the
  * encoder is replaced, which is after this has run.
  *
- * **What it costs**: every skin draw twice; two half-float targets the size of the frame, and a
- * third multisampled one under multisampling; a depth resolve; and two full-screen passes that
- * leave at once wherever no skin was drawn.
+ * **What it costs**: every skin draw three times — the frame's half, the light alone, and the
+ * colour alone, which the spread light is multiplied by; three half-float targets the size of the
+ * frame, and two multisampled ones under multisampling; a depth resolve; and two full-screen passes
+ * that leave at once wherever no skin was drawn.
  */
 import { SKIN_PROFILES } from '../../skinBlur.js';
 import { SKINBLUR_BINDINGS, SKIN_BLUR_FRAG_WGSL } from '../../shaders/generated/skinBlur.wgsl.js';
@@ -37,14 +39,20 @@ export class SkinScatterPass {
     linear;
     nearest;
     commands = createCommandPool(16);
+    /** The same draws again, through the pipelines that write the skin's colour alone. */
+    albedoCommands = createCommandPool(16);
     /** Each profile's scatter distance per channel, in metres: four floats a profile. */
     profiles = new Float32Array(SKIN_PROFILES * 4);
     diffuse = null;
     diffuseMsaa = null;
     across = null;
+    albedo = null;
+    albedoMsaa = null;
     diffuseView = null;
     diffuseMsaaView = null;
     acrossView = null;
+    albedoView = null;
+    albedoMsaaView = null;
     groupAcross = null;
     groupDown = null;
     groupsDepth = null;
@@ -53,6 +61,7 @@ export class SkinScatterPass {
         this.layout = createPostStageLayout(device, BINDINGS.uniforms, BINDINGS.uniformSize, [
             { binding: BINDINGS.textures.uSkin },
             { binding: BINDINGS.textures.uDepth, filterable: false },
+            { binding: BINDINGS.textures.uAlbedo },
         ]);
         this.uniforms = device.createBuffer({
             label: 'skin.blurUniforms',
@@ -80,6 +89,10 @@ export class SkinScatterPass {
     take() {
         return this.commands.commands[takeCommand(this.commands)];
     }
+    /** A command for the same draw's colour half, filled by the caller. */
+    takeAlbedo() {
+        return this.albedoCommands.commands[takeCommand(this.albedoCommands)];
+    }
     /** What one profile scatters, per channel, in metres: the last material to name it says. */
     setProfile(index, r, g, b) {
         const at = Math.min(Math.max(Math.round(index), 0), SKIN_PROFILES - 1) * 4;
@@ -106,16 +119,20 @@ export class SkinScatterPass {
         });
         this.diffuse = make('skin.diffuse', 1);
         this.across = make('skin.across', 1);
+        this.albedo = make('skin.albedo', 1);
         this.diffuseMsaa = samples > 1 ? make('skin.diffuseMsaa', samples) : null;
+        this.albedoMsaa = samples > 1 ? make('skin.albedoMsaa', samples) : null;
         this.diffuseView = this.diffuse.createView();
         this.acrossView = this.across.createView();
+        this.albedoView = this.albedo.createView();
         this.diffuseMsaaView = this.diffuseMsaa?.createView() ?? null;
+        this.albedoMsaaView = this.albedoMsaa?.createView() ?? null;
         this.groupAcross = null;
         this.groupDown = null;
     }
     /**
-     * Every kept draw's diffuse into the target, against the frame's own depth, which it reads and
-     * does not write. Called with no pass open on `encoder`.
+     * Every kept draw's diffuse into the target, and its colour into the other, against the frame's
+     * own depth, which they read and do not write. Called with no pass open on `encoder`.
      */
     drawDiffuse(encoder, depth, issue, timestampWrites) {
         const target = this.diffuseView;
@@ -139,6 +156,26 @@ export class SkinScatterPass {
             issue(pass, this.commands.commands[i]);
         }
         pass.end();
+        const colour = this.albedoView;
+        if (colour === null)
+            return;
+        const albedoPass = encoder.beginRenderPass({
+            label: 'skin.albedo',
+            colorAttachments: [
+                {
+                    view: this.albedoMsaaView ?? colour,
+                    resolveTarget: this.albedoMsaaView === null ? undefined : colour,
+                    clearValue: [0, 0, 0, 0],
+                    loadOp: 'clear',
+                    storeOp: this.albedoMsaaView === null ? 'store' : 'discard',
+                },
+            ],
+            depthStencilAttachment: { view: depth, depthLoadOp: 'load', depthStoreOp: 'store' },
+        });
+        for (let i = 0; i < this.albedoCommands.taken; i += 1) {
+            issue(albedoPass, this.albedoCommands.commands[i]);
+        }
+        albedoPass.end();
     }
     /**
      * Across into the second target, then down and added into the frame's colour — `frame` the
@@ -149,6 +186,8 @@ export class SkinScatterPass {
         const diffuse = this.diffuse;
         if (diffuse === null || this.diffuseView === null || this.acrossView === null)
             return;
+        if (this.albedoView === null)
+            return;
         if (this.groupAcross === null || this.groupDown === null || this.groupsDepth !== depth) {
             this.groupAcross = this.group('skin.blurAcross', this.diffuseView, depth);
             this.groupDown = this.group('skin.blurDown', this.acrossView, depth);
@@ -197,6 +236,7 @@ export class SkinScatterPass {
     /** Spent at the frame's start: the kept draws were this frame's. */
     reset() {
         resetPool(this.commands);
+        resetPool(this.albedoCommands);
     }
     dispose() {
         this.releaseTargets();
@@ -215,6 +255,8 @@ export class SkinScatterPass {
                 { binding: BINDINGS.textures.uSkin.sampler, resource: this.linear },
                 { binding: BINDINGS.textures.uDepth.texture, resource: depth },
                 { binding: BINDINGS.textures.uDepth.sampler, resource: this.nearest },
+                { binding: BINDINGS.textures.uAlbedo.texture, resource: this.albedoView ?? skin },
+                { binding: BINDINGS.textures.uAlbedo.sampler, resource: this.nearest },
             ],
         });
     }
@@ -236,6 +278,8 @@ export class SkinScatterPass {
                too wherever a pixel is square. */
             f[base + fields.uFocal.offset / 4] = (projection[5] * height) / 2;
             f.set(this.profiles, base + fields.uProfiles.offset / 4);
+            /* The colour is applied once, on the axis that adds into the frame. */
+            f[base + fields.uApplyAlbedo.offset / 4] = axis;
         }
         this.device.queue.writeBuffer(this.uniforms, 0, f);
     }
@@ -243,11 +287,17 @@ export class SkinScatterPass {
         this.diffuse?.destroy();
         this.diffuseMsaa?.destroy();
         this.across?.destroy();
+        this.albedo?.destroy();
+        this.albedoMsaa?.destroy();
         this.diffuse = null;
         this.diffuseMsaa = null;
         this.across = null;
+        this.albedo = null;
+        this.albedoMsaa = null;
         this.diffuseView = null;
         this.diffuseMsaaView = null;
         this.acrossView = null;
+        this.albedoView = null;
+        this.albedoMsaaView = null;
     }
 }

package/dist/render/backend/webgpu/surfaceTexturePass.d.ts

@@ -1,4 +1,5 @@
 import type { SurfaceTextureOptions } from '../../surfaceTexture.ts';
+import type { LightmapTexels } from '../../lightmap.ts';
 import type { CompressedTextureFormat, SurfaceSource } from '../../compressedSource.ts';
 import type { PipelineCache } from './pipelineCache.ts';
 /** How many levels an image of this size has, counting the one it arrives with. */
@@ -62,7 +63,7 @@ export declare class GpuSurfaceTexture {
     effectsView: GPUTextureView | null;
     /** The block format a compressed texture holds, or null for one uploaded from images. */
     private readonly blockFormat;
-    constructor(device: GPUDevice, pipelines: PipelineCache, source: SurfaceSource | readonly SurfaceSource[], options?: SurfaceTextureOptions, compressed?: readonly CompressedTextureFormat[]);
+    constructor(device: GPUDevice, pipelines: PipelineCache, source: SurfaceSource | readonly SurfaceSource[] | LightmapTexels, options?: SurfaceTextureOptions, compressed?: readonly CompressedTextureFormat[]);
     /** A view of every layer, as the shaders' `texture_2d_array` bindings read it. */
     private arrayView;
     /** The view every binding of this image holds. A new one when `update` changes the size. */

package/dist/render/backend/webgpu/surfaceTexturePass.js

@@ -1,5 +1,6 @@
 import { SURFACE_EFFECT_TEXELS, packSurfaceEffects } from '../../surfaceEffects.js';
 import { toHalfFloats } from '../../halfFloat.js';
+import { isLightmapTexels } from '../../lightmap.js';
 import { layerSize, refuseArrayUpdate, sourceSize } from '../../textureSource.js';
 import { compressedLayers, planBlocks, refuseBlockUpdate } from '../../compressedSource.js';
 import { createCompressedTexture } from './compressedUpload.js';
@@ -155,13 +156,26 @@ export class GpuSurfaceTexture {
     constructor(device, pipelines, source, options = {}, compressed = []) {
         this.device = device;
         this.pipelines = pipelines;
-        const listed = (Array.isArray(source) ? source : [source]);
+        /* A lightmap's page: half floats, uploaded as they are. See `lightmap.ts`. */
+        const baked = isLightmapTexels(source) ? source : null;
+        const listed = (baked !== null ? [] : Array.isArray(source) ? source : [source]);
         const blocks = compressedLayers(listed);
         const srgb = (options.colorSpace ?? 'linear') === 'srgb';
         /* `SRGB8_ALPHA8`'s equivalent. Decoded in the sampler, before filtering, which is the only
            place it is correct — `surfaceTexture.ts` makes the argument in full. */
-        this.format = srgb ? 'rgba8unorm-srgb' : 'rgba8unorm';
-        if (blocks !== null) {
+        this.format = baked !== null ? 'rgba16float' : srgb ? 'rgba8unorm-srgb' : 'rgba8unorm';
+        if (baked !== null) {
+            /* No chain: a page is read at its own resolution, and a level of it would blend regions. */
+            this.layers = baked.layers;
+            this.blockFormat = null;
+            this.mipmapped = false;
+            this.width = baked.width;
+            this.height = baked.height;
+            this.levels = 1;
+            this.texture = this.allocate();
+            device.queue.writeTexture({ texture: this.texture }, baked.texels, { bytesPerRow: baked.width * 8, rowsPerImage: baked.height }, { width: baked.width, height: baked.height, depthOrArrayLayers: baked.layers });
+        }
+        else if (blocks !== null) {
             /* Refused before anything is allocated; the stored chain, or level 0 alone where no chain
                was asked for. See `compressedUpload.ts`. */
             const plan = planBlocks(blocks, srgb, compressed);
@@ -216,7 +230,7 @@ export class GpuSurfaceTexture {
                 ? Math.max(1, Math.floor(options.anisotropy ?? DEFAULT_ANISOTROPY))
                 : 1,
         });
-        if (blocks === null)
+        if (blocks === null && baked === null)
             this.upload(listed);
         /* Half floats, as `renderer.ts` uploads it: filterable, so the ordinary float layout takes it,
            and read by `textureLoad` alone, so the filter never runs. */