@driftengine/core 4.13.1 → 4.13.3

package/src/render/backend/webgl2/renderer.ts

@@ -117,6 +117,15 @@ import {
   packSurfaceLayers,
 } from '../../surfaceLayers.ts';
 import type { SurfaceLayers } from '../../surfaceLayers.ts';
+import {
+  DETAIL_FLOATS,
+  detailOf,
+  detailRefusal,
+  detailRefusalWarning,
+  packSurfaceDetail,
+  type DetailRefusal,
+  type SurfaceDetail,
+} from '../../surfaceDetail.ts';
 import { LOOK_FLOATS, asksLayerLooks, packLayerLooks } from '../../surfaceLayerLooks.ts';
 import type { SurfaceProjection } from '../../surfaceProjection.ts';
 import { FILM_FRAG, FILM_VERT } from '../../shaders/film.ts';
@@ -377,6 +386,13 @@ import type { SurfaceTextureHandle } from '../api.ts';
 import { materialHasMaps, noteMapsWithoutUvs } from '../../mapsWithoutUvs.ts';
 import { VIEW_MODEL_DEPTH_SHARE, viewModelDepthRange } from '../../viewModel.ts';
 import { noLitSwitches, type LitSwitch } from '../../shaders/flat/glassTint.ts';
+import {
+  poseBounds,
+  validatePointSkin,
+  validatePose,
+  type PointSkinData,
+} from '../../pointSkin.ts';
+import { GlPointSkin, createPointSkinPose, type PointSkinPose } from './pointSkinFeedback.ts';
 
 /**
  * How many frames `firstFrameSettled` will ask before it stops asking.
@@ -1794,6 +1810,13 @@ export class WebGL2Renderer implements RendererApi {
   /** Whether it has room for the layers' looks beside them, and whether the refusal was said. */
   private looksRoom: boolean | null = null;
   private warnedLooksRoom = false;
+  /** `uDetail`, the material's tiled detail packed by `packSurfaceDetail`. */
+  private readonly detailFloats = new Float32Array(DETAIL_FLOATS);
+  /** Whether the lit stage has room for detail on this part, asked once. See `detailOfMaterial`. */
+  private detailRoom: boolean | null = null;
+  private warnedDetailRoom = false;
+  /** The refusals already said, each once. */
+  private readonly warnedDetail = new Set<DetailRefusal>();
   private warnedLayersModelMap = false;
   private warnedLayersTriplanar = false;
   private warnedOverlayRoom = false;
@@ -3624,7 +3647,13 @@ export class WebGL2Renderer implements RendererApi {
      */
     const drawn = withLightmapUvs(data);
     this.warmVariants(drawn);
-    return new Mesh(this.gl, drawn, options.dynamic === true);
+    return new Mesh(
+      this.gl,
+      drawn,
+      options.dynamic === true,
+      false,
+      options.dynamicColors === true,
+    );
   }
 
   /**
@@ -3639,7 +3668,12 @@ export class WebGL2Renderer implements RendererApi {
   createMeshIncremental(data: MeshData, options: MeshOptions = {}): IncrementalMesh {
     const drawn = withLightmapUvs(data);
     this.warmVariants(drawn);
-    const { mesh, upload } = createMeshIncremental(this.gl, drawn, options.dynamic === true);
+    const { mesh, upload } = createMeshIncremental(
+      this.gl,
+      drawn,
+      options.dynamic === true,
+      options.dynamicColors === true,
+    );
     return {
       mesh,
       upload: {
@@ -3692,6 +3726,49 @@ export class WebGL2Renderer implements RendererApi {
     mesh.update(this.gl, positions, normals);
   }
 
+  /** The program and feedback object every point skin poses with, made at the first one. */
+  private pointSkinPose: PointSkinPose | null = null;
+
+  /**
+   * A dynamic mesh posed on the device from weighted points in its joints' spaces, by transform
+   * feedback. Refused in words on a mesh that is not dynamic, whose buffers are not hinted for a
+   * rewrite every frame.
+   */
+  createPointSkin(mesh: Mesh, data: PointSkinData): GlPointSkin {
+    if (mesh.streams === null) {
+      throw new Error(
+        'a point skin poses a mesh created with { dynamic: true }, whose positions and normals ' +
+          'are rewritten every frame. Say so at `createMesh`.',
+      );
+    }
+    validatePointSkin(data, mesh.vertexCount);
+    this.pointSkinPose ??= createPointSkinPose(this.gl);
+    return new GlPointSkin(this.gl, mesh, data);
+  }
+
+  /**
+   * Pose a skin now: `matrices` holds each joint's transform into the mesh's model space, sixteen
+   * floats, column-major. A command in the stream, so the draws after it read this pose.
+   */
+  posePointSkin(skin: GlPointSkin, matrices: Float32Array): void {
+    validatePose(matrices, skin.reach);
+    if (this.contextLost || this.pointSkinPose === null) return;
+    poseBounds(matrices, skin.reach, skin.mesh.bounds);
+    skin.pose(this.gl, this.pointSkinPose, matrices);
+  }
+
+  disposePointSkin(skin: GlPointSkin): void {
+    skin.dispose(this.gl);
+  }
+
+  /**
+   * Rewrite a mesh's colours, on a mesh made `dynamicColors`. The VAO is left alone for the reason
+   * `updateMesh` gives: the buffer is the same buffer.
+   */
+  updateMeshColors(mesh: Mesh, colors: Float32Array): void {
+    mesh.updateColors(this.gl, colors);
+  }
+
   /**
    * Compile the skinned flat program, once, on the first rigged mesh.
    *
@@ -4401,10 +4478,16 @@ export class WebGL2Renderer implements RendererApi {
     const modelMap = material?.modelMap ?? null;
     /* A layered material's mask, where it is a map, goes where a model's would: surfaceLayers.ts. */
     const layers = this.layersOf(material);
-    const boundMap = modelMap ?? layerMaskMap(layers);
+    const taken = modelMap ?? layerMaskMap(layers);
+    /* And its detail's array, where nothing else is read there: surfaceDetail.ts. */
+    const detail = this.detailOfMaterial(material, taken);
+    const boundMap = taken ?? detail?.maps ?? null;
     gl.activeTexture(gl.TEXTURE0 + MODEL_MAP_TEXTURE_UNIT);
     gl.bindTexture(gl.TEXTURE_2D_ARRAY, this.emptyTexture2DArray);
     if (boundMap !== null) boundMap.bind(gl, MODEL_MAP_TEXTURE_UNIT);
+    packSurfaceDetail(detail, (material?.orm ?? null) !== null, this.detailFloats);
+    if (detail !== null) this.askLit('SURFACE_DETAIL');
+    gl.uniform4fv(u['uDetail'] ?? null, this.detailFloats);
     packSurfaceLayers(layers, this.layerFloats);
     if (layers !== null) this.askLit('LAYERED');
     gl.uniform4fv(u['uLayers'] ?? null, this.layerFloats);
@@ -4710,6 +4793,37 @@ export class WebGL2Renderer implements RendererApi {
    * as they are, said once — which on a material sharing its arrays reads the wrong textures, so
    * the sentence names the way out.
    */
+  /**
+   * A material's detail, or null where it is refused: its slot holds another array, it is placed by
+   * the world, or the lit stage has no room for its thirty-three vectors. Each said once.
+   */
+  private detailOfMaterial(
+    material: SurfaceMaterial | null,
+    taken: SurfaceTexture | null,
+  ): SurfaceDetail<SurfaceTexture> | null {
+    const detail = detailOf(material) as SurfaceDetail<SurfaceTexture> | null;
+    if (detail === null) return null;
+    const refusal = detailRefusal(detail, taken, (material?.projection ?? null) !== null);
+    if (refusal !== null) {
+      if (!this.warnedDetail.has(refusal)) {
+        this.warnedDetail.add(refusal);
+        console.warn(detailRefusalWarning(refusal));
+      }
+      return null;
+    }
+    this.detailRoom ??= this.switchFits('SURFACE_DETAIL');
+    if (this.detailRoom) return detail;
+    if (!this.warnedDetailRoom) {
+      this.warnedDetailRoom = true;
+      console.warn(
+        "Renderer: a material's detail is refused on this device. It takes thirty-three fragment " +
+          'uniform vectors the lit shader does not have, so the material is drawn without it. A ' +
+          'lower `maxLights` makes the room, or WebGPU has it.',
+      );
+    }
+    return null;
+  }
+
   private looksFit(layers: SurfaceLayers<SurfaceTexture> | null): boolean {
     if (!asksLayerLooks(layers)) return false;
     this.looksRoom ??= this.switchFits('LAYER_LOOKS', 'LAYERED');
@@ -7060,6 +7174,7 @@ export class WebGL2Renderer implements RendererApi {
       movingSun: asIf.MOVING_SUN ?? this.litOn.MOVING_SUN,
       layered: asIf.LAYERED ?? this.litOn.LAYERED,
       layerLooks: asIf.LAYER_LOOKS ?? this.litOn.LAYER_LOOKS,
+      surfaceDetail: asIf.SURFACE_DETAIL ?? this.litOn.SURFACE_DETAIL,
       maxLights: budget.maxLights,
       maxAreaLights: budget.maxAreaLights,
     });
@@ -9226,9 +9341,10 @@ export class WebGL2Renderer implements RendererApi {
     this.projection.fill(0);
     /* Nor light through from behind. See `SurfaceMaterial.diffuseTransmission`. */
     resolveTransmission(null, this.transmission);
-    /* Nor layers: one layer until a material asks for more. */
+    /* Nor layers: one layer until a material asks for more. Nor detail. */
     this.layerFloats.fill(0);
     this.lookFloats.fill(0);
+    this.detailFloats.fill(0);
     this.overlayMaps = null;
     this.overlayTexture = null;
     /* Nor an ambient of its own: the frame's, until a draw asks. See `setAmbientSH`. */
@@ -9404,6 +9520,7 @@ export class WebGL2Renderer implements RendererApi {
     gl.uniform4fv(u['uWorldUv'] ?? null, this.projection);
     gl.uniform4fv(u['uLayers'] ?? null, this.layerFloats);
     gl.uniform4fv(u['uLayerLooks'] ?? null, this.lookFloats);
+    gl.uniform4fv(u['uDetail'] ?? null, this.detailFloats);
     /* Neither refracting nor glass, which is every draw that does not say otherwise. See
        `bindSeeThrough` for the four numbers in the one vector. */
     gl.uniform4f(u['uSeeThrough'] ?? null, 0, 0, 0, 0);

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

@@ -39,6 +39,7 @@ const USAGE = {
   INDEX: 0x0010,
   VERTEX: 0x0020,
   UNIFORM: 0x0040,
+  STORAGE: 0x0080,
 } as const;
 
 /**
@@ -276,6 +277,14 @@ export interface GpuMesh {
         staged?: StagedRewrite | null,
       ) => void)
     | null;
+  /**
+   * Rewrite this mesh's colours, three floats a vertex.
+   *
+   * Absent unless the mesh was created `dynamicColors`, whose colours are a buffer of their own at
+   * the end of `vertexBuffers` (`vertexPacking.ts`), so this is one `writeBuffer` and nothing else
+   * moves: not the positions, not the bounds, and no motion, since a colour does not move.
+   */
+  readonly updateColors: ((device: GPUDevice, colors: Float32Array) => void) | null;
   /**
    * A dynamic mesh's motion state, which the renderer owns: a buffer for last frame's positions and
    * one the new positions are staged in, each made the first time a reconstructing renderer
@@ -328,8 +337,13 @@ export interface IncrementalGpuMesh {
  * two paths cannot write different bytes. The one that spreads the work is the one with the
  * interesting decisions in it; read that.
  */
-export function createGpuMesh(device: GPUDevice, data: MeshData, dynamic = false): GpuMesh {
-  const { mesh, upload } = createGpuMeshIncremental(device, data, dynamic);
+export function createGpuMesh(
+  device: GPUDevice,
+  data: MeshData,
+  dynamic = false,
+  dynamicColors = false,
+): GpuMesh {
+  const { mesh, upload } = createGpuMeshIncremental(device, data, dynamic, dynamicColors);
   while (upload.next().done !== true);
   return mesh;
 }
@@ -363,6 +377,7 @@ export function createGpuMeshIncremental(
   device: GPUDevice,
   data: MeshData,
   dynamic = false,
+  dynamicColors = false,
 ): IncrementalGpuMesh {
   /*
    * The other backend's refusal, and the premise of the interleave below: every attribute holds
@@ -373,11 +388,11 @@ export function createGpuMeshIncremental(
   const vertexCount = data.positions.length / 3;
   const layered = data.layers !== undefined;
   /* How each attribute travels, which the pipeline key says too: `vertexPacking.ts`. */
-  const packing = vertexPackingOf(data, dynamic);
+  const packing = vertexPackingOf(data, dynamic, dynamicColors);
 
   /* Interleaved: one stride holding every attribute the mesh actually supplied — less a dynamic
-     mesh's positions and normals, which are buffers of their own, and any attribute every vertex
-     shares, which is a constant. */
+     mesh's positions and normals and a `dynamicColors` mesh's colours, which are buffers of their
+     own, and any attribute every vertex shares, which is a constant. */
   const fields: Field[] = [];
   let stride = 0;
   for (const declared of VERTEX_LAYOUT) {
@@ -385,7 +400,7 @@ export function createGpuMeshIncremental(
     if (dynamic && isStreamed(declared)) continue;
     const attribute = laidOut(declared, layered);
     const how = packingFor(packing, attribute.name);
-    if (how === 'constant') continue;
+    if (how === 'constant' || how === 'stream') continue;
     const format = packedFormat(attribute.format, how);
     fields.push({ attribute, packing: how, format, offset: stride });
     stride += formatBytes(format);
@@ -466,22 +481,32 @@ export function createGpuMeshIncremental(
     usage: USAGE.INDEX | USAGE.COPY_DST,
   });
 
-  /* A dynamic mesh's two moving streams: copied from as well as written, for last frame's positions. */
+  /* A dynamic mesh's two moving streams: copied from as well as written, for last frame's positions,
+     and written by a point skin's pose on the device (`pointSkin.ts`). */
   const streamBytes = align4(vertexCount * 12);
   const streams = dynamic
     ? {
         positions: device.createBuffer({
           label: 'mesh.positions',
           size: streamBytes,
-          usage: USAGE.VERTEX | USAGE.COPY_DST | USAGE.COPY_SRC,
+          usage: USAGE.VERTEX | USAGE.COPY_DST | USAGE.COPY_SRC | USAGE.STORAGE,
         }),
         normals: device.createBuffer({
           label: 'mesh.normals',
           size: streamBytes,
-          usage: USAGE.VERTEX | USAGE.COPY_DST,
+          usage: USAGE.VERTEX | USAGE.COPY_DST | USAGE.STORAGE,
         }),
       }
     : null;
+  /* And a `dynamicColors` mesh's colours, which only the caller's rewrites ever change. */
+  const colorStream =
+    packing.colors === 'stream'
+      ? device.createBuffer({
+          label: 'mesh.colors',
+          size: streamBytes,
+          usage: USAGE.VERTEX | USAGE.COPY_DST,
+        })
+      : null;
 
   /*
    * The chunks, in whole vertices and whole indices: a step never writes half of either, so the
@@ -489,7 +514,9 @@ export function createGpuMeshIncremental(
    */
   const verticesPerStep = Math.max(
     1,
-    Math.floor(UPLOAD_BYTES_PER_STEP / (stride + (dynamic ? 24 : 0))),
+    Math.floor(
+      UPLOAD_BYTES_PER_STEP / (stride + (dynamic ? 24 : 0) + (colorStream === null ? 0 : 12)),
+    ),
   );
   /* Whole four-byte words a step, which is all a queue writes: two sixteen-bit indices to one. */
   const indexWidth = indices.BYTES_PER_ELEMENT;
@@ -505,13 +532,15 @@ export function createGpuMeshIncremental(
    * gives every closure in a scope one context — so a getter returning a boolean held the whole
    * `MeshData` and the interleaved rows for as long as the mesh lived. The voxel sandbox's forward
    * path held 2,058 MB of ArrayBuffers at radius 32 against the second pipeline's 368.
-   * `meshRetention.test.ts` holds it: a mesh keeps its buffers, and a dynamic one its rows.
+   * `meshRetention.test.ts` holds it: a mesh keeps its buffers and none of its source, a dynamic
+   * one included.
    */
   const progress = { uploaded: false };
   const mesh = gpuMeshOf({
     vertices,
     constants,
     streams,
+    colorStream,
     indexBuffer,
     indexFormat: indices instanceof Uint16Array ? 'uint16' : 'uint32',
     stride: streams === null ? stride : 12,
@@ -538,6 +567,7 @@ export function createGpuMeshIncremental(
       streams === null
         ? null
         : streamUpdate(streams.positions, streams.normals, streamBytes, bounds, vertexCount),
+    updateColors: colorStream === null ? null : colorUpdate(colorStream, vertexCount),
   });
 
   const job: UploadJob = {
@@ -547,6 +577,7 @@ export function createGpuMeshIncremental(
     device,
     fields,
     streams,
+    colorStream,
     vertices,
     indexBuffer,
     vertexCount,
@@ -588,6 +619,7 @@ interface UploadJob {
   readonly device: GPUDevice;
   readonly fields: readonly Field[];
   readonly streams: { readonly positions: GPUBuffer; readonly normals: GPUBuffer } | null;
+  readonly colorStream: GPUBuffer | null;
   readonly vertices: GPUBuffer;
   readonly indexBuffer: GPUBuffer;
   readonly vertexCount: number;
@@ -662,6 +694,9 @@ function* uploadSteps(job: UploadJob): Generator<void, void, void> {
       device.queue.writeBuffer(job.streams.positions, from * 12, data.positions, from * 3, count);
       device.queue.writeBuffer(job.streams.normals, from * 12, data.normals, from * 3, count);
     }
+    if (job.colorStream !== null) {
+      device.queue.writeBuffer(job.colorStream, from * 12, data.colors, from * 3, (to - from) * 3);
+    }
     taken += 1;
     if (taken < job.totalSteps) yield;
   }
@@ -759,6 +794,7 @@ function gpuMeshOf(parts: {
   readonly vertices: GPUBuffer;
   readonly constants: GPUBuffer;
   readonly streams: { readonly positions: GPUBuffer; readonly normals: GPUBuffer } | null;
+  readonly colorStream: GPUBuffer | null;
   readonly indexBuffer: GPUBuffer;
   readonly indexFormat: GPUIndexFormat;
   readonly stride: number;
@@ -774,17 +810,21 @@ function gpuMeshOf(parts: {
   readonly hasChannel: boolean;
   readonly morph: MorphTexture | null;
   readonly update: GpuMesh['update'];
+  readonly updateColors: GpuMesh['updateColors'];
 }): GpuMesh {
   const motion =
     parts.update === null
       ? null
       : { previous: null as GPUBuffer | null, staging: null as GPUBuffer | null, changed: -1 };
-  const { vertices, constants, streams, indexBuffer, progress } = parts;
+  const { vertices, constants, streams, colorStream, indexBuffer, progress } = parts;
+  const vertexBuffers =
+    streams === null
+      ? [vertices, constants]
+      : [streams.positions, streams.normals, vertices, constants];
+  /* Last, behind the constants, where `vertexBufferLayouts` puts it: no other slot moves. */
+  if (colorStream !== null) vertexBuffers.push(colorStream);
   return {
-    vertexBuffers:
-      streams === null
-        ? [vertices, constants]
-        : [streams.positions, streams.normals, vertices, constants],
+    vertexBuffers,
     vertexStride: parts.stride,
     skinOffsets: parts.skinOffsets,
     indexBuffer,
@@ -802,12 +842,14 @@ function gpuMeshOf(parts: {
     hasChannel: parts.hasChannel,
     morph: parts.morph,
     update: parts.update,
+    updateColors: parts.updateColors,
     motion,
     dispose(): void {
       motion?.previous?.destroy();
       motion?.staging?.destroy();
       streams?.positions.destroy();
       streams?.normals.destroy();
+      colorStream?.destroy();
       vertices.destroy();
       constants.destroy();
       indexBuffer.destroy();
@@ -866,6 +908,26 @@ function streamUpdate(
   };
 }
 
+/**
+ * A `dynamicColors` mesh's `updateColors`: the caller's colours, written as they came into the
+ * buffer they have to themselves.
+ */
+function colorUpdate(
+  colorBuffer: GPUBuffer,
+  vertexCount: number,
+): NonNullable<GpuMesh['updateColors']> {
+  return (target: GPUDevice, colors: Float32Array): void => {
+    if (colors.length !== vertexCount * 3) {
+      throw new Error(
+        `this mesh has ${vertexCount} vertices and the colours have ${colors.length / 3}. ` +
+          "A mesh's vertex count is fixed at creation: the index buffer, the pipeline and " +
+          'every other attribute are sized against it.',
+      );
+    }
+    target.queue.writeBuffer(colorBuffer, 0, colors);
+  };
+}
+
 /**
  * The buffer layouts a pipeline is built with, matching what `createGpuMesh` uploaded.
  *
@@ -919,6 +981,8 @@ export function vertexBufferLayouts(
   /* A dynamic mesh's positions and normals: buffers of their own, ahead of the rest. */
   const dynamic = present['dynamic'] === true;
   const layouts: GPUVertexBufferLayout[] = [];
+  /* Attributes a caller rewrites, each a buffer of its own behind the constants: `vertexPacking.ts`. */
+  const trailing: GPUVertexBufferLayout[] = [];
   VERTEX_LAYOUT.forEach((declared, index) => {
     const attribute = laidOut(declared, layered);
     if (dynamic && isStreamed(attribute)) {
@@ -945,6 +1009,15 @@ export function vertexBufferLayouts(
      */
     /* One value every vertex shares sits with the absent ones: `vertexPacking.ts`. */
     const packing = packingIn(present, String(attribute.name));
+    if (packing === 'stream') {
+      trailing.push({
+        arrayStride: attribute.components * 4,
+        attributes: [
+          { shaderLocation: attribute.shaderLocation, offset: 0, format: attribute.format },
+        ],
+      });
+      return;
+    }
     const supplied =
       (!attribute.optional || present[String(attribute.name)] === true) && packing !== 'constant';
     if (instanced && INSTANCE_LOCATIONS.has(attribute.shaderLocation)) {
@@ -987,6 +1060,7 @@ export function vertexBufferLayouts(
    * need a different layout from one that does not.
    */
   layouts.push({ arrayStride: 0, attributes: constants });
+  for (const layout of trailing) layouts.push(layout);
   /*
    * The four matrix columns and the tint — the five the flat shader's INSTANCED variant declares
    * and exactly the five left once the base mesh has spent eleven of WebGL2's guaranteed sixteen.

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

@@ -105,8 +105,8 @@ export class GpuClothParticles {
   private latest = 0;
   /** The frame each texture was last written for, so a motion knows whether the other is last frame's. */
   private readonly written = [-1, -1];
-  private paired: GpuClothBinding | null = null;
-  private pairedViews: ClothViews[] = [];
+  /** Each binding's views with these particles, one for each texture: see `viewsWith`. */
+  private readonly paired = new WeakMap<GpuClothBinding, readonly [ClothViews, ClothViews]>();
 
   constructor(device: GPUDevice, count: number, storage = false) {
     this.count = count;
@@ -178,17 +178,20 @@ export class GpuClothParticles {
 
   /**
    * The three views a draw of `binding` with these particles binds, kept so a cached bind group
-   * compares equal frame after frame. Two objects, one for each texture that is current.
+   * compares equal frame after frame. Two objects, one for each texture that is current, made the
+   * first time a binding is drawn with these particles and kept **for every binding**: several
+   * meshes follow one cloth, each with a binding of its own, and keeping only the last made two
+   * objects a draw as they took turns.
    */
   viewsWith(binding: GpuClothBinding): ClothViews {
-    if (this.paired !== binding) {
-      this.paired = binding;
-      this.pairedViews = [0, 1].map((k) => ({
-        binding: binding.bindingView,
-        particles: this.views[k] as GPUTextureView,
-        rest: binding.restView,
-      }));
+    let pair = this.paired.get(binding);
+    if (pair === undefined) {
+      pair = [
+        { binding: binding.bindingView, particles: this.views[0], rest: binding.restView },
+        { binding: binding.bindingView, particles: this.views[1], rest: binding.restView },
+      ];
+      this.paired.set(binding, pair);
     }
-    return this.pairedViews[this.latest] as ClothViews;
+    return pair[this.latest === 0 ? 0 : 1];
   }
 }

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

@@ -12,9 +12,9 @@
  */
 
 /**
- * WebGPU's guaranteed `maxVertexBuffers`, so no verb can outgrow it. The most any binds is five — a
- * dynamic mesh's positions, normals, rows and constants, and an instanced batch's placements — and
- * this said three, then four, while text and bolts already bound four.
+ * WebGPU's guaranteed `maxVertexBuffers`, so no verb can outgrow it. The most any binds is six — a
+ * dynamic mesh's positions, normals, rows, constants and rewritten colours, and an instanced
+ * batch's placements — and this said three, then four, while text and bolts already bound four.
  */
 const VERTEX_BUFFER_SLOTS = 8;
 

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

@@ -338,6 +338,7 @@ export class GpuClothSet {
     u[base + 32] = garment.range.colliderBase;
     u[base + 33] = garment.range.colliders;
     u[base + 34] = garment.particles.width;
+    f[base + 35] = 1 / (1 + p.pull * h * h);
     f[base + 36] = exactExp(p.damping * h);
     f[base + 37] = exactExp(p.drag * h);
     f[base + 38] = p.maxDistanceScale;

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

@@ -0,0 +1,74 @@
+/**
+ * A few bind groups kept under one key, each found again by the four resources it was built with,
+ * compared by identity.
+ *
+ * **Why more than one.** A skinned draw's group was kept one a palette slot and material and made
+ * again whenever a resource in it differed from the last draw's. A garment's particles live in two
+ * textures that take turns, a step each, so a draw following cloth found the other texture every
+ * frame; and several meshes following one cloth bind one particle texture each with a binding of
+ * its own, so they replaced each other's group draw by draw. Reported at twenty-four groups made a
+ * frame for two characters, and none with cloth off. A shelf keeps each combination it has seen,
+ * so a steady garment's draws bind the groups of two frames ago and make none.
+ *
+ * **What it gives up** is a bound: `SHELF_CAPACITY` groups a key, replaced oldest first. Eight
+ * meshes following cloth under one palette slot and material fit, two groups each; a ninth makes
+ * groups again every frame, as every draw did before, and nothing worse. What would make it wrong
+ * is a draw whose resources change every frame for another reason, which a shelf cannot help and
+ * which would cycle it.
+ */
+
+/** Groups a shelf keeps before it replaces the oldest. See the module comment for the count. */
+export const SHELF_CAPACITY = 16;
+
+/** One key's groups and what each was built with, four identities a group, flat. */
+export class GroupShelf {
+  private readonly groups: (GPUBindGroup | null)[] = new Array<GPUBindGroup | null>(
+    SHELF_CAPACITY,
+  ).fill(null);
+  private readonly made: (object | null)[] = new Array<object | null>(SHELF_CAPACITY * 4).fill(
+    null,
+  );
+  /** Where the next group goes: the oldest, once the shelf is full. */
+  private next = 0;
+
+  /** The group built with exactly these four, or null. */
+  find(
+    a: object | null,
+    b: object | null,
+    c: object | null,
+    d: object | null,
+  ): GPUBindGroup | null {
+    for (let slot = 0; slot < SHELF_CAPACITY; slot++) {
+      const group = this.groups[slot] ?? null;
+      if (group === null) return null;
+      const at = slot * 4;
+      if (
+        this.made[at] === a &&
+        this.made[at + 1] === b &&
+        this.made[at + 2] === c &&
+        this.made[at + 3] === d
+      ) {
+        return group;
+      }
+    }
+    return null;
+  }
+
+  /** Keep `group` as the one built with these four. */
+  keep(
+    group: GPUBindGroup,
+    a: object | null,
+    b: object | null,
+    c: object | null,
+    d: object | null,
+  ): void {
+    const slot = this.next;
+    this.groups[slot] = group;
+    const at = slot * 4;
+    this.made[at] = a;
+    this.made[at + 1] = b;
+    this.made[at + 2] = c;
+    this.made[at + 3] = d;
+    this.next = (slot + 1) % SHELF_CAPACITY;
+  }
+}