@driftengine/core 4.13.1 → 4.13.3

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

@@ -0,0 +1,115 @@
+/**
+ * A point skin on WebGPU: its points, joints and normals in storage buffers made once, and a pose
+ * recorded as one compute dispatch into the dynamic mesh's own position and normal buffers. What a
+ * point skin is, and why it poses into a mesh rather than in a vertex stage, is `pointSkin.ts`.
+ *
+ * **Each skin owns its joints buffer**, so two skins posed in one frame read their own: a write to
+ * one buffer between two dispatches would hand both the last, the per-draw rule `AGENTS.md` keeps
+ * for every resource a later write in the frame overwrites. A skin posed twice in a frame draws its
+ * last pose everywhere, as a mesh rewritten twice with `updateMesh` does.
+ */
+import { reachOf, type PointSkinData, type PointSkinReach } from '../../pointSkin.ts';
+import type { GpuMesh } from './buffers.ts';
+import { POINT_SKIN_WGSL, POINT_SKIN_WORKGROUP } from './shaders/pointSkin.wgsl.ts';
+
+const STORAGE = 0x0080;
+const UNIFORM = 0x0040;
+const COPY_DST = 0x0008;
+
+/** The pipeline every skin on a device poses with, made at the first skin. */
+export function createPointSkinPipeline(device: GPUDevice): GPUComputePipeline {
+  return device.createComputePipeline({
+    label: 'pointSkin.pose',
+    layout: 'auto',
+    compute: {
+      module: device.createShaderModule({ label: 'pointSkin.pose', code: POINT_SKIN_WGSL }),
+      entryPoint: 'posePoints',
+    },
+  });
+}
+
+export class GpuPointSkin {
+  readonly mesh: GpuMesh;
+  readonly reach: PointSkinReach;
+  private readonly count: number;
+  private readonly pipeline: GPUComputePipeline;
+  private readonly joints: GPUBuffer;
+  private readonly buffers: readonly GPUBuffer[];
+  private readonly group: GPUBindGroup;
+
+  constructor(device: GPUDevice, pipeline: GPUComputePipeline, mesh: GpuMesh, data: PointSkinData) {
+    this.mesh = mesh;
+    this.pipeline = pipeline;
+    this.reach = reachOf(data);
+    const count = data.weights.length / 4;
+    this.count = count;
+
+    /* Each influence a vec4: its point, and its weight in w. */
+    const points = new Float32Array(count * 16);
+    for (let i = 0; i < count * 4; i++) {
+      points.set(data.points.subarray(i * 3, i * 3 + 3), i * 4);
+      points[i * 4 + 3] = data.weights[i] as number;
+    }
+    const named = Uint32Array.from(data.joints);
+    const normals = new Float32Array(count * 4);
+    for (let v = 0; v < count; v++) normals.set(data.normals.subarray(v * 3, v * 3 + 3), v * 4);
+    const params = new Uint32Array([count, 0, 0, 0]);
+
+    const made = (
+      label: string,
+      contents: Float32Array | Uint32Array,
+      usage: number,
+    ): GPUBuffer => {
+      const buffer = device.createBuffer({
+        label,
+        size: Math.max(16, contents.byteLength),
+        usage: usage | COPY_DST,
+      });
+      device.queue.writeBuffer(buffer, 0, contents);
+      return buffer;
+    };
+    this.joints = device.createBuffer({
+      label: 'pointSkin.joints',
+      size: Math.max(1, this.reach.joints) * 64,
+      usage: STORAGE | COPY_DST,
+    });
+    const buffers = [
+      made('pointSkin.params', params, UNIFORM),
+      made('pointSkin.points', points, STORAGE),
+      made('pointSkin.named', named, STORAGE),
+      made('pointSkin.normals', normals, STORAGE),
+    ];
+    this.buffers = buffers;
+    const [positionsOut, normalsOut] = mesh.vertexBuffers as [GPUBuffer, GPUBuffer];
+    this.group = device.createBindGroup({
+      label: 'pointSkin.pose',
+      layout: pipeline.getBindGroupLayout(0),
+      entries: [
+        { binding: 0, resource: { buffer: buffers[0] as GPUBuffer } },
+        { binding: 1, resource: { buffer: this.joints } },
+        { binding: 2, resource: { buffer: buffers[1] as GPUBuffer } },
+        { binding: 3, resource: { buffer: buffers[2] as GPUBuffer } },
+        { binding: 4, resource: { buffer: buffers[3] as GPUBuffer } },
+        { binding: 5, resource: { buffer: positionsOut } },
+        { binding: 6, resource: { buffer: normalsOut } },
+      ],
+    });
+  }
+
+  /** Write the pose's joints and record the dispatch that poses every vertex into `encoder`. */
+  pose(device: GPUDevice, encoder: GPUCommandEncoder, matrices: Float32Array): void {
+    if (this.reach.joints > 0) {
+      device.queue.writeBuffer(this.joints, 0, matrices, 0, this.reach.joints * 16);
+    }
+    const pass = encoder.beginComputePass({ label: 'pointSkin.pose' });
+    pass.setPipeline(this.pipeline);
+    pass.setBindGroup(0, this.group);
+    pass.dispatchWorkgroups(Math.ceil(this.count / POINT_SKIN_WORKGROUP));
+    pass.end();
+  }
+
+  dispose(): void {
+    this.joints.destroy();
+    for (const buffer of this.buffers) buffer.destroy();
+  }
+}

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

@@ -181,6 +181,14 @@ import { GpuSceneCaptureTarget } from './sceneCaptureTarget.ts';
 import { sceneCaptureTexels } from '../../sceneCapture.ts';
 import { gpuCompressedFormats } from './compressedUpload.ts';
 import { GpuClothBinding, GpuClothParticles, clothStandIn } from './clothTextures.ts';
+import { GroupShelf } from './groupShelf.ts';
+import { GpuPointSkin, createPointSkinPipeline } from './pointSkinPass.ts';
+import {
+  poseBounds,
+  validatePointSkin,
+  validatePose,
+  type PointSkinData,
+} from '../../pointSkin.ts';
 import type { ClothViews } from './clothTextures.ts';
 import type { ComputeHost } from './computeHost.ts';
 import {
@@ -208,6 +216,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 {
   frameReflectionsRefused,
@@ -1476,15 +1493,6 @@ interface SunTintTarget {
   readonly mips: readonly [SnapshotMips, SnapshotMips];
 }
 
-/** A skinned or morphed flat group, and what it was built with, compared by identity. */
-interface SkinnedTwin {
-  readonly group: GPUBindGroup;
-  readonly palette: GPUTextureView | null;
-  readonly deltas: GPUTextureView | null;
-  readonly cloth: GPUTextureView | null;
-  readonly clothBinding: GPUTextureView | null;
-}
-
 export class WebGPURenderer implements RendererApi {
   /**
    * Real timestamp queries, where the adapter offers them.
@@ -1602,9 +1610,11 @@ export class WebGPURenderer implements RendererApi {
    * thirty-odd sections, each its own material, built one a section a frame — about ninety a frame
    * for two characters, reported by a consumer. A slot's map holds one entry a material its rigs
    * are drawn in, and is emptied wherever the unskinned groups are, whose identities it is keyed
-   * by.
+   * by. **And by what each group was built with, on a shelf a material** (`groupShelf.ts`): a
+   * garment's particles take turns between two textures and several meshes may follow one cloth,
+   * so one group a material was made again draw after draw.
    */
-  private readonly skinnedGroups: (Map<GPUBindGroup, SkinnedTwin> | undefined)[] = [];
+  private readonly skinnedGroups: (Map<GPUBindGroup, GroupShelf> | undefined)[] = [];
   /** The cloth the next skinned draws are placed by, or null. See `setCloth`. */
   private cloth: { binding: GpuClothBinding; particles: GpuClothParticles } | null = null;
   private clothStandCache: { texture: GPUTexture; views: ClothViews } | null = null;
@@ -3037,6 +3047,10 @@ export class WebGPURenderer implements RendererApi {
    */
   private readonly transmission = new Float32Array([-1, -1, -1, 0]);
   private warnedLayersModelMap = false;
+  /** `uDetail`, the material's tiled detail packed by `packSurfaceDetail`. */
+  private readonly detailFloats = new Float32Array(DETAIL_FLOATS);
+  /** The detail refusals already said, each once. See `detailOfMaterial`. */
+  private readonly warnedDetail = new Set<DetailRefusal>();
   private warnedLayersTriplanar = false;
   /** Its numbers, `uModelParams`, packed by `packModel`. */
   private readonly modelParams = new Float32Array(MODEL_PARAM_FLOATS);
@@ -3515,7 +3529,10 @@ export class WebGPURenderer implements RendererApi {
     const ownModelMap = (material?.modelMap ?? null) as GpuSurfaceTexture | 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 modelMap = ownModelMap ?? layerMaskMap(layers);
+    const taken = ownModelMap ?? layerMaskMap(layers);
+    /* And its detail's array, where nothing else is read there: surfaceDetail.ts. */
+    const detail = this.detailOfMaterial(material, taken);
+    const modelMap = taken ?? detail?.maps ?? null;
     this.materialModel = material?.model ?? null;
     const reflectivity = material?.reflectivity;
     const environmentGain = material?.environmentGain;
@@ -3608,6 +3625,10 @@ export class WebGPURenderer implements RendererApi {
       packLayerLooks(layers, this.lookFloats);
       f.set(this.lookFloats, this.materialField('uLayerLooks'));
       if (asksLayerLooks(layers)) this.enableLit('LAYER_LOOKS');
+      /* And its tiled detail, the first time a material lays any: detail.ts. */
+      packSurfaceDetail(detail, orm !== null, this.detailFloats);
+      f.set(this.detailFloats, this.materialField('uDetail'));
+      if (detail !== null) this.enableLit('SURFACE_DETAIL');
       f.set(this.modelParams, this.materialField('uModelParams'));
     });
     /*
@@ -6157,17 +6178,14 @@ export class WebGPURenderer implements RendererApi {
   /** The same layout plus the joint palette. See `createDepthBindGroupLayout`. */
   private readonly shadowSkinnedLayout: GPUBindGroupLayout;
   /**
-   * The skinned shadow bind groups, one per palette slot, cached against what can invalidate them.
+   * The skinned shadow bind groups, a shelf per palette slot, each found by what it was built with.
    *
    * The same argument `flatBindGroupFor` makes, and per slot for the same reason: the group it was
    * built beside, and the palette view, which now differs between two characters casting into one
-   * bake. Comparing object identity makes a missed invalidation impossible rather than unlikely.
+   * bake, and the cloth's particles and binding, which take turns. Comparing object identity makes
+   * a missed invalidation impossible rather than unlikely. See `groupShelf.ts`.
    */
-  private readonly shadowSkinnedGroups: (GPUBindGroup | null)[] = [];
-  private readonly shadowSkinnedGroupsBeside: (GPUBindGroup | null)[] = [];
-  private readonly shadowSkinnedGroupsPalette: (GPUTextureView | null)[] = [];
-  private readonly shadowSkinnedGroupsCloth: (GPUTextureView | null)[] = [];
-  private readonly shadowSkinnedGroupsClothBinding: (GPUTextureView | null)[] = [];
+  private readonly shadowSkinnedShelves: (GroupShelf | undefined)[] = [];
   /** Held from construction so the skinned group can be rebuilt without them being threaded. */
   private shadowBlankView: GPUTextureView | null = null;
   private shadowBlankSampler: GPUSampler | null = null;
@@ -6343,30 +6361,26 @@ export class WebGPURenderer implements RendererApi {
    */
   private shadowSkinnedGroup(palette: GPUTextureView, at: number, cloth: ClothViews): GPUBindGroup {
     const beside = this.shadowBindGroup;
-    if (
-      (this.shadowSkinnedGroups[at] ?? null) === null ||
-      this.shadowSkinnedGroupsBeside[at] !== beside ||
-      this.shadowSkinnedGroupsPalette[at] !== palette ||
-      this.shadowSkinnedGroupsCloth[at] !== cloth.particles ||
-      this.shadowSkinnedGroupsClothBinding[at] !== cloth.binding
-    ) {
-      this.shadowSkinnedGroups[at] = createDepthBindGroup(
-        this.surface.device,
-        this.shadowSkinnedLayout,
-        this.shadowDraws.buffer,
-        this.shadowPassUniforms as GPUBuffer,
-        this.shadowBlankView as GPUTextureView,
-        this.shadowBlankSampler as GPUSampler,
-        palette,
-        null,
-        cloth,
-      );
-      this.shadowSkinnedGroupsBeside[at] = beside;
-      this.shadowSkinnedGroupsPalette[at] = palette;
-      this.shadowSkinnedGroupsCloth[at] = cloth.particles;
-      this.shadowSkinnedGroupsClothBinding[at] = cloth.binding;
+    let shelf = this.shadowSkinnedShelves[at];
+    if (shelf === undefined) {
+      shelf = new GroupShelf();
+      this.shadowSkinnedShelves[at] = shelf;
     }
-    return this.shadowSkinnedGroups[at] as GPUBindGroup;
+    const kept = shelf.find(beside, palette, cloth.particles, cloth.binding);
+    if (kept !== null) return kept;
+    const group = createDepthBindGroup(
+      this.surface.device,
+      this.shadowSkinnedLayout,
+      this.shadowDraws.buffer,
+      this.shadowPassUniforms as GPUBuffer,
+      this.shadowBlankView as GPUTextureView,
+      this.shadowBlankSampler as GPUSampler,
+      palette,
+      null,
+      cloth,
+    );
+    shelf.keep(group, beside, palette, cloth.particles, cloth.binding);
+    return group;
   }
 
   private scatterDepthGroup(): GPUBindGroup {
@@ -6401,6 +6415,25 @@ export class WebGPURenderer implements RendererApi {
    * A material's layers where they can be drawn: none asked, or a model's map in the mask's place,
    * said once, leave one layer.
    */
+  /**
+   * A material's detail, or null where it is refused: its slot holds another array, or it is placed
+   * by the world. Each said once. This backend has room for its vectors wherever it runs.
+   */
+  private detailOfMaterial(
+    material: SurfaceMaterial<GpuSurfaceTexture> | null,
+    taken: GpuSurfaceTexture | null,
+  ): SurfaceDetail<GpuSurfaceTexture> | null {
+    const detail = detailOf(material);
+    if (detail === null) return null;
+    const refusal = detailRefusal(detail, taken, (material?.projection ?? null) !== null);
+    if (refusal === null) return detail;
+    if (!this.warnedDetail.has(refusal)) {
+      this.warnedDetail.add(refusal);
+      console.warn(detailRefusalWarning(refusal));
+    }
+    return null;
+  }
+
   private layersOf(
     material: SurfaceMaterial<GpuSurfaceTexture> | null,
   ): SurfaceLayers<GpuSurfaceTexture> | null {
@@ -8621,7 +8654,7 @@ export class WebGPURenderer implements RendererApi {
    * neither the pipeline set nor the key depends on whether the geometry lands in one call or
    * over six frames.
    */
-  private warmFlatPipelines(data: MeshData, dynamic: boolean): string {
+  private warmFlatPipelines(data: MeshData, dynamic: boolean, dynamicColors = false): string {
     /*
      * **Every optional attribute, not the two that come to mind.** `present` decides where
      * each attribute sits in the interleaved buffer, and `createGpuMesh` decides the same
@@ -8658,9 +8691,10 @@ export class WebGPURenderer implements RendererApi {
     }
     /*
      * And how each attribute travels (`vertexPacking.ts`): a field read as sixteen bits rather than
-     * thirty-two, or not interleaved at all, moves every field after it, so the key says so.
+     * thirty-two, or not interleaved at all, moves every field after it, so the key says so. A
+     * `dynamicColors` mesh's colours are one of those, as `:colors~stream`.
      */
-    const packing = vertexPackingOf(data, dynamic);
+    const packing = vertexPackingOf(data, dynamic, dynamicColors);
     markPacking(present, packing);
     key += packingKey(packing);
     const fullKey = `${this.variant}|${key}`;
@@ -8777,8 +8811,10 @@ export class WebGPURenderer implements RendererApi {
   createMesh(given: MeshData, options: MeshOptions = {}): GpuMesh {
     /* The streams it is drawn with, before anything records which it has. See `withLightmapUvs`. */
     const data = withLightmapUvs(given);
-    const fullKey = this.warmFlatPipelines(data, options.dynamic === true);
-    return this.keyed(createGpuMesh(this.surface.device, data, options.dynamic === true), fullKey);
+    const dynamic = options.dynamic === true;
+    const dynamicColors = options.dynamicColors === true;
+    const fullKey = this.warmFlatPipelines(data, dynamic, dynamicColors);
+    return this.keyed(createGpuMesh(this.surface.device, data, dynamic, dynamicColors), fullKey);
   }
 
   /**
@@ -8792,11 +8828,14 @@ export class WebGPURenderer implements RendererApi {
    */
   createMeshIncremental(given: MeshData, options: MeshOptions = {}): IncrementalMeshHandle {
     const data = withLightmapUvs(given);
-    const fullKey = this.warmFlatPipelines(data, options.dynamic === true);
+    const dynamic = options.dynamic === true;
+    const dynamicColors = options.dynamicColors === true;
+    const fullKey = this.warmFlatPipelines(data, dynamic, dynamicColors);
     const { mesh, upload } = createGpuMeshIncremental(
       this.surface.device,
       data,
-      options.dynamic === true,
+      dynamic,
+      dynamicColors,
     );
     const surface = this.surface;
     return {
@@ -8897,6 +8936,81 @@ export class WebGPURenderer implements RendererApi {
     mesh.update(this.surface.device, positions, normals, staged);
   }
 
+  /** The pipeline every point skin poses with, made at the first one. See `pointSkinPass.ts`. */
+  private pointSkinPipeline: GPUComputePipeline | null = null;
+
+  /**
+   * A dynamic mesh posed on the device from weighted points in its joints' spaces. Refused in words
+   * on a mesh that is not dynamic, whose positions share one buffer with the rest of each vertex.
+   */
+  createPointSkin(mesh: GpuMesh, data: PointSkinData): GpuPointSkin {
+    if (mesh.update === null) {
+      throw new Error(
+        'a point skin poses a mesh created with { dynamic: true }, whose positions and normals ' +
+          'have buffers of their own for the pose to write. Say so at `createMesh`.',
+      );
+    }
+    validatePointSkin(data, mesh.vertexCount);
+    const device = this.surface.device;
+    this.pointSkinPipeline ??= createPointSkinPipeline(device);
+    return new GpuPointSkin(device, this.pointSkinPipeline, mesh, data);
+  }
+
+  /**
+   * Pose a skin: `matrices` holds each joint's transform into the mesh's model space, sixteen floats,
+   * column-major. Recorded into the encoder the frame's next submit leads with, behind a copy of
+   * last frame's positions where a reconstruction keeps them, as `updateMesh` records its rewrite.
+   */
+  posePointSkin(skin: GpuPointSkin, matrices: Float32Array): void {
+    validatePose(matrices, skin.reach);
+    if (this.surface.lost) return;
+    const mesh = skin.mesh;
+    poseBounds(matrices, skin.reach, mesh.bounds);
+    const encoder = this.rewriteCopies();
+    const motion = mesh.motion;
+    if (motion !== null && this.reconstructionWanted) {
+      const frame = frameOfChange(this.moverFrame, this.inFrame);
+      if (keepsPrevious(motion.changed, frame)) {
+        const size = mesh.vertexBuffers[0]?.size ?? 0;
+        motion.previous ??= this.surface.device.createBuffer({
+          label: 'recon.dynamicPrevious',
+          size,
+          usage: 0x0020 | 0x0008, // VERTEX | COPY_DST
+        });
+        encoder.copyBufferToBuffer(mesh.vertexBuffers[0] as GPUBuffer, 0, motion.previous, 0, size);
+      }
+      motion.changed = frame;
+    }
+    skin.pose(this.surface.device, encoder, matrices);
+  }
+
+  /**
+   * **The pending rewrites go first**, since a pose recorded into them reads the skin's buffers and
+   * a destroyed buffer in a submit loses the whole command buffer. Nothing else reads them, so once
+   * the rewrites are submitted, which only moves them earlier, the buffers can go at once.
+   */
+  disposePointSkin(skin: GpuPointSkin): void {
+    if (this.pendingRewrites !== null && !this.surface.lost) this.submit([]);
+    skin.dispose();
+  }
+
+  /**
+   * Rewrite a mesh's colours. Refused in words on a mesh that did not ask for `dynamicColors`,
+   * whose colours are interleaved with the rest of a vertex or are one value with no buffer at all.
+   * See `GpuMesh.updateColors`.
+   */
+  updateMeshColors(mesh: GpuMesh, colors: Float32Array): void {
+    if (mesh.updateColors === null) {
+      throw new Error(
+        'this mesh was not created with { dynamicColors: true }, so its colours are packed with ' +
+          'the rest of each vertex, or are one value with no buffer at all, and cannot be ' +
+          'rewritten. Say so at `createMesh`: the flag gives the colours a buffer of their own.',
+      );
+    }
+    if (this.surface.lost) return;
+    mesh.updateColors(this.surface.device, colors);
+  }
+
   /**
    * Settle everything the frame shares: the camera, the lights and the fog.
    *
@@ -9035,6 +9149,8 @@ export class WebGPURenderer implements RendererApi {
     /* Nor layers: one layer until a material asks for more. */
     f.fill(0, at('uLayers'), at('uLayers') + LAYER_FLOATS);
     f.fill(0, at('uLayerLooks'), at('uLayerLooks') + LOOK_FLOATS);
+    /* Nor detail. */
+    f.fill(0, at('uDetail'), at('uDetail') + DETAIL_FLOATS);
     f[at('uCutout')] = 0;
     f[at('uCutout') + 1] = 0;
     this.cutoutResolveStaged = 'hard';
@@ -12391,40 +12507,33 @@ export class WebGPURenderer implements RendererApi {
       byMaterial = new Map();
       this.skinnedGroups[at] = byMaterial;
     }
-    let twin = byMaterial.get(base);
-    if (
-      twin === undefined ||
-      twin.palette !== palette ||
-      twin.deltas !== deltas ||
-      twin.cloth !== (cloth?.particles ?? null) ||
-      twin.clothBinding !== (cloth?.binding ?? null)
-    ) {
-      /* Built from the live material, with the overlay's atlas where `base` is its twin. */
-      this.overlayBinding = base !== this.bindGroup;
-      const group = createFlatBindGroup(
-        this.surface.device,
-        this.flatLayoutFor(skinned, morphed),
-        this.variant,
-        this.perDraw.buffer,
-        this.passRing.buffer,
-        this.materialStore.buffer,
-        this.viewRing.buffer,
-        this.flatTextures,
-        palette,
-        deltas,
-        cloth,
-      );
-      this.overlayBinding = false;
-      twin = {
-        group,
-        palette,
-        deltas,
-        cloth: cloth?.particles ?? null,
-        clothBinding: cloth?.binding ?? null,
-      };
-      byMaterial.set(base, twin);
-    }
-    return twin.group;
+    let shelf = byMaterial.get(base);
+    if (shelf === undefined) {
+      shelf = new GroupShelf();
+      byMaterial.set(base, shelf);
+    }
+    const particles = cloth?.particles ?? null;
+    const binding = cloth?.binding ?? null;
+    const kept = shelf.find(palette, deltas, particles, binding);
+    if (kept !== null) return kept;
+    /* Built from the live material, with the overlay's atlas where `base` is its twin. */
+    this.overlayBinding = base !== this.bindGroup;
+    const group = createFlatBindGroup(
+      this.surface.device,
+      this.flatLayoutFor(skinned, morphed),
+      this.variant,
+      this.perDraw.buffer,
+      this.passRing.buffer,
+      this.materialStore.buffer,
+      this.viewRing.buffer,
+      this.flatTextures,
+      palette,
+      deltas,
+      cloth,
+    );
+    this.overlayBinding = false;
+    shelf.keep(group, palette, deltas, particles, binding);
+    return group;
   }
 
   /** The layout matching a pair of vertex flags. A pipeline and its bind group must agree. */

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

@@ -88,7 +88,8 @@ struct Pace {
   colliderBase: u32,
   colliders: u32,
   width: u32,
-  pad0: u32,
+  /* The share of its offset from its skinned position a particle keeps a substep: the pull's. */
+  pullKeep: f32,
   keep: f32,
   dragKeep: f32,
   maxDistanceScale: f32,
@@ -428,7 +429,7 @@ fn pushOut(p: vec3<f32>, centre: vec3<f32>, radius: f32) -> vec3<f32> {
   return centre + d * (radius / sqrt(d2));
 }
 
-/* applyMaxDistance, applyStops (back, then front) and applyColliders, in that order. */
+/* applyPull, applyMaxDistance, applyStops (back, then front) and applyColliders, in that order. */
 @compute @workgroup_size(64)
 fn clothLimit(@builtin(global_invocation_id) id: vec3<u32>) {
   let i = id.x;
@@ -444,6 +445,10 @@ fn clothLimit(@builtin(global_invocation_id) id: vec3<u32>) {
   let at = stateAt(POSITION, i);
   var p = load(at);
   let t = skinnedAt(i, g);
+  /* Only where there is a pull, as on the CPU: t + (p - t) is not p in floats. */
+  if (paces[g].pullKeep < 1.0) {
+    p = t + (p - t) * paces[g].pullKeep;
+  }
   /* A max distance below zero is none: the CPU's Infinity, which a device may not be handed. */
   let maxDistance = statics[n + i];
   if ((limits & 1u) != 0u && maxDistance >= 0.0) {

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

@@ -0,0 +1,58 @@
+/**
+ * A point skin posed on the device, in WGSL, hand-authored under the compute exception `AGENTS.md`
+ * records (2026-08-24): a compute shader has no WebGL2 twin to generate from, and `npm run wgsl`
+ * neither writes nor polices this file. WebGL2 poses the same skin by transform feedback, in
+ * `backend/webgl2/pointSkinFeedback.ts`, by the same arithmetic in the same order.
+ *
+ * One invocation a vertex: its position the sum of each weighted point moved by its joint, an
+ * influence of weight 0 skipped, and its normal the first joint's turn of the normal it was given,
+ * made unit length where it has any. Written into the mesh's own position and normal buffers, three
+ * floats a vertex, which every pass then draws as it draws any dynamic mesh.
+ */
+export const POINT_SKIN_WORKGROUP = 64;
+
+export const POINT_SKIN_WGSL = /* wgsl */ `
+struct Params {
+  count: u32,
+  pad0: u32,
+  pad1: u32,
+  pad2: u32,
+}
+
+@group(0) @binding(0) var<uniform> params: Params;
+@group(0) @binding(1) var<storage, read> joints: array<mat4x4<f32>>;
+@group(0) @binding(2) var<storage, read> points: array<vec4<f32>>;
+@group(0) @binding(3) var<storage, read> named: array<vec4<u32>>;
+@group(0) @binding(4) var<storage, read> normals: array<vec4<f32>>;
+@group(0) @binding(5) var<storage, read_write> posedPositions: array<f32>;
+@group(0) @binding(6) var<storage, read_write> posedNormals: array<f32>;
+
+@compute @workgroup_size(${POINT_SKIN_WORKGROUP})
+fn posePoints(@builtin(global_invocation_id) id: vec3<u32>) {
+  let v = id.x;
+  if (v >= params.count) {
+    return;
+  }
+  let j = named[v];
+  var p = vec3<f32>(0.0, 0.0, 0.0);
+  for (var k = 0u; k < 4u; k = k + 1u) {
+    let q = points[v * 4u + k];
+    if (q.w != 0.0) {
+      p = p + q.w * (joints[j[k]] * vec4<f32>(q.xyz, 1.0)).xyz;
+    }
+  }
+  let m = joints[j.x];
+  let raw = mat3x3<f32>(m[0].xyz, m[1].xyz, m[2].xyz) * normals[v].xyz;
+  let l = length(raw);
+  var n = raw;
+  if (l > 0.0) {
+    n = raw / l;
+  }
+  posedPositions[v * 3u] = p.x;
+  posedPositions[v * 3u + 1u] = p.y;
+  posedPositions[v * 3u + 2u] = p.z;
+  posedNormals[v * 3u] = n.x;
+  posedNormals[v * 3u + 1u] = n.y;
+  posedNormals[v * 3u + 2u] = n.z;
+}
+`;

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

@@ -17,7 +17,7 @@ import {
  */
 
 /** The ways an attribute can travel other than as floats, as the key words name them. */
-const PACKINGS = ['snorm16', 'unorm16', 'constant'] as const;
+const PACKINGS = ['snorm16', 'unorm16', 'constant', 'stream'] as const;
 
 /** The pipeline key's word for one attribute's packing. Not a prefix of any other word. */
 function word(name: string, packing: AttributePacking): string {

package/src/render/lightBudget.ts

@@ -287,6 +287,13 @@ export const BONE_PLACES_TEXTURE_UNIT = PARTICLE_DEPTH_UNIT + 1;
 export const BONE_TURNS_TEXTURE_UNIT = BONE_PLACES_TEXTURE_UNIT + 1;
 export const INSTANCE_CLOCKS_TEXTURE_UNIT = BONE_TURNS_TEXTURE_UNIT + 1;
 
+/**
+ * A point skin's joints (`pointSkin.ts`), read by the transform-feedback program that poses it. Past
+ * every unit a draw binds, so a pose taken between two draws leaves nothing a draw expects to find.
+ * Twenty-nine.
+ */
+export const POINT_SKIN_TEXTURE_UNIT = INSTANCE_CLOCKS_TEXTURE_UNIT + 1;
+
 /**
  * A cookie's tile, in texels a side.
  *