@driftengine/core 4.13.1 → 4.13.3

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

@@ -162,6 +162,14 @@ export interface GpuMesh {
      * layout, keyed by `:dynamic`, and two more buffers bound per draw of such a mesh.
      */
     readonly update: ((device: GPUDevice, positions: Float32Array, normals?: Float32Array, 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
@@ -211,7 +219,7 @@ 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 declare function createGpuMesh(device: GPUDevice, data: MeshData, dynamic?: boolean): GpuMesh;
+export declare function createGpuMesh(device: GPUDevice, data: MeshData, dynamic?: boolean, dynamicColors?: boolean): GpuMesh;
 /**
  * Upload a mesh over as many frames as the caller gives it.
  *
@@ -237,7 +245,7 @@ export declare function createGpuMesh(device: GPUDevice, data: MeshData, dynamic
  * streamer places and culls a region from them before a byte of it has landed, so a handle whose
  * bounds were not yet known would not be usable at once, which is the whole promise here.
  */
-export declare function createGpuMeshIncremental(device: GPUDevice, data: MeshData, dynamic?: boolean): IncrementalGpuMesh;
+export declare function createGpuMeshIncremental(device: GPUDevice, data: MeshData, dynamic?: boolean, dynamicColors?: boolean): IncrementalGpuMesh;
 export declare function vertexBufferLayouts(present: Readonly<Record<string, boolean>>, 
 /**
  * Whether a third buffer carries one placement and colour per instance.

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

@@ -28,6 +28,7 @@ const USAGE = {
     INDEX: 0x0010,
     VERTEX: 0x0020,
     UNIFORM: 0x0040,
+    STORAGE: 0x0080,
 };
 /**
  * Bytes reserved per absent attribute in the constants buffer.
@@ -123,8 +124,8 @@ function laidOut(attribute, layered) {
  * 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, data, dynamic = false) {
-    const { mesh, upload } = createGpuMeshIncremental(device, data, dynamic);
+export function createGpuMesh(device, data, dynamic = false, dynamicColors = false) {
+    const { mesh, upload } = createGpuMeshIncremental(device, data, dynamic, dynamicColors);
     while (upload.next().done !== true)
         ;
     return mesh;
@@ -154,7 +155,7 @@ export function createGpuMesh(device, data, dynamic = false) {
  * streamer places and culls a region from them before a byte of it has landed, so a handle whose
  * bounds were not yet known would not be usable at once, which is the whole promise here.
  */
-export function createGpuMeshIncremental(device, data, dynamic = false) {
+export function createGpuMeshIncremental(device, data, dynamic = false, dynamicColors = false) {
     /*
      * The other backend's refusal, and the premise of the interleave below: every attribute holds
      * exactly a vertex's worth for every vertex, so nothing reads past the end of its array.
@@ -164,10 +165,10 @@ export function createGpuMeshIncremental(device, data, dynamic = false) {
     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 = [];
     let stride = 0;
     for (const declared of VERTEX_LAYOUT) {
@@ -177,7 +178,7 @@ export function createGpuMeshIncremental(device, data, dynamic = false) {
             continue;
         const attribute = laidOut(declared, layered);
         const how = packingFor(packing, attribute.name);
-        if (how === 'constant')
+        if (how === 'constant' || how === 'stream')
             continue;
         const format = packedFormat(attribute.format, how);
         fields.push({ attribute, packing: how, format, offset: stride });
@@ -255,27 +256,36 @@ export function createGpuMeshIncremental(device, data, dynamic = false) {
         size: align4(indices.byteLength),
         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
      * buffer never holds a torn one even for the frame between two steps.
      */
-    const verticesPerStep = Math.max(1, Math.floor(UPLOAD_BYTES_PER_STEP / (stride + (dynamic ? 24 : 0))));
+    const verticesPerStep = Math.max(1, 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;
     const indicesPerStep = Math.max(1, Math.floor(UPLOAD_BYTES_PER_STEP / 4)) * (4 / indexWidth);
@@ -288,13 +298,15 @@ export function createGpuMeshIncremental(device, data, dynamic = false) {
      * 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,
@@ -314,6 +326,7 @@ export function createGpuMeshIncremental(device, data, dynamic = false) {
         update: streams === null
             ? null
             : streamUpdate(streams.positions, streams.normals, streamBytes, bounds, vertexCount),
+        updateColors: colorStream === null ? null : colorUpdate(colorStream, vertexCount),
     });
     const job = {
         data,
@@ -322,6 +335,7 @@ export function createGpuMeshIncremental(device, data, dynamic = false) {
         device,
         fields,
         streams,
+        colorStream,
         vertices,
         indexBuffer,
         vertexCount,
@@ -368,6 +382,9 @@ function* uploadSteps(job) {
             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;
@@ -461,11 +478,15 @@ function gpuMeshOf(parts) {
     const motion = parts.update === null
         ? null
         : { previous: null, staging: 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,
@@ -483,12 +504,14 @@ function gpuMeshOf(parts) {
         hasChannel: parts.hasChannel,
         morph: parts.morph,
         update: parts.update,
+        updateColors: parts.updateColors,
         motion,
         dispose() {
             motion?.previous?.destroy();
             motion?.staging?.destroy();
             streams?.positions.destroy();
             streams?.normals.destroy();
+            colorStream?.destroy();
             vertices.destroy();
             constants.destroy();
             indexBuffer.destroy();
@@ -534,6 +557,20 @@ function streamUpdate(positionsBuffer, normalsBuffer, streamBytes, bounds, verte
             target.queue.writeBuffer(normalsBuffer, 0, normals);
     };
 }
+/**
+ * A `dynamicColors` mesh's `updateColors`: the caller's colours, written as they came into the
+ * buffer they have to themselves.
+ */
+function colorUpdate(colorBuffer, vertexCount) {
+    return (target, colors) => {
+        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.
  *
@@ -580,6 +617,8 @@ instanced = false) {
     /* A dynamic mesh's positions and normals: buffers of their own, ahead of the rest. */
     const dynamic = present['dynamic'] === true;
     const layouts = [];
+    /* Attributes a caller rewrites, each a buffer of its own behind the constants: `vertexPacking.ts`. */
+    const trailing = [];
     VERTEX_LAYOUT.forEach((declared, index) => {
         const attribute = laidOut(declared, layered);
         if (dynamic && isStreamed(attribute)) {
@@ -606,6 +645,15 @@ instanced = false) {
          */
         /* 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)) {
             /*
@@ -644,6 +692,8 @@ instanced = false) {
      * 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/dist/render/backend/webgpu/clothTextures.d.ts

@@ -38,8 +38,8 @@ export declare class GpuClothParticles {
     private latest;
     /** The frame each texture was last written for, so a motion knows whether the other is last frame's. */
     private readonly written;
-    private paired;
-    private pairedViews;
+    /** Each binding's views with these particles, one for each texture: see `viewsWith`. */
+    private readonly paired;
     constructor(device: GPUDevice, count: number, storage?: boolean);
     /** This frame's particles. */
     get current(): GPUTextureView;
@@ -62,7 +62,10 @@ export declare class GpuClothParticles {
     update(device: GPUDevice, positions: Float32Array, frame: number): void;
     /**
      * 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;
 }

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

@@ -72,8 +72,8 @@ export class GpuClothParticles {
     latest = 0;
     /** The frame each texture was last written for, so a motion knows whether the other is last frame's. */
     written = [-1, -1];
-    paired = null;
-    pairedViews = [];
+    /** Each binding's views with these particles, one for each texture: see `viewsWith`. */
+    paired = new WeakMap();
     constructor(device, count, storage = false) {
         this.count = count;
         const size = clothTextureSize(count);
@@ -129,17 +129,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) {
-        if (this.paired !== binding) {
-            this.paired = binding;
-            this.pairedViews = [0, 1].map((k) => ({
-                binding: binding.bindingView,
-                particles: this.views[k],
-                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];
+        return pair[this.latest === 0 ? 0 : 1];
     }
 }

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

@@ -11,9 +11,9 @@
  * edits rather than twenty-three implementations.
  */
 /**
- * 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;
 function emptyCommand() {

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

@@ -278,6 +278,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/dist/render/backend/webgpu/groupShelf.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 declare const SHELF_CAPACITY = 16;
+/** One key's groups and what each was built with, four identities a group, flat. */
+export declare class GroupShelf {
+    private readonly groups;
+    private readonly made;
+    /** Where the next group goes: the oldest, once the shelf is full. */
+    private next;
+    /** The group built with exactly these four, or null. */
+    find(a: object | null, b: object | null, c: object | null, d: object | null): GPUBindGroup | 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;
+}

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

@@ -0,0 +1,54 @@
+/**
+ * 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 {
+    groups = new Array(SHELF_CAPACITY).fill(null);
+    made = new Array(SHELF_CAPACITY * 4).fill(null);
+    /** Where the next group goes: the oldest, once the shelf is full. */
+    next = 0;
+    /** The group built with exactly these four, or null. */
+    find(a, b, c, d) {
+        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, a, b, c, d) {
+        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;
+    }
+}

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

@@ -0,0 +1,27 @@
+/**
+ * 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 { type PointSkinData, type PointSkinReach } from '../../pointSkin.ts';
+import type { GpuMesh } from './buffers.ts';
+/** The pipeline every skin on a device poses with, made at the first skin. */
+export declare function createPointSkinPipeline(device: GPUDevice): GPUComputePipeline;
+export declare class GpuPointSkin {
+    readonly mesh: GpuMesh;
+    readonly reach: PointSkinReach;
+    private readonly count;
+    private readonly pipeline;
+    private readonly joints;
+    private readonly buffers;
+    private readonly group;
+    constructor(device: GPUDevice, pipeline: GPUComputePipeline, mesh: GpuMesh, data: PointSkinData);
+    /** Write the pose's joints and record the dispatch that poses every vertex into `encoder`. */
+    pose(device: GPUDevice, encoder: GPUCommandEncoder, matrices: Float32Array): void;
+    dispose(): void;
+}

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

@@ -0,0 +1,104 @@
+/**
+ * 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 } from '../../pointSkin.js';
+import { POINT_SKIN_WGSL, POINT_SKIN_WORKGROUP } from './shaders/pointSkin.wgsl.js';
+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) {
+    return device.createComputePipeline({
+        label: 'pointSkin.pose',
+        layout: 'auto',
+        compute: {
+            module: device.createShaderModule({ label: 'pointSkin.pose', code: POINT_SKIN_WGSL }),
+            entryPoint: 'posePoints',
+        },
+    });
+}
+export class GpuPointSkin {
+    mesh;
+    reach;
+    count;
+    pipeline;
+    joints;
+    buffers;
+    group;
+    constructor(device, pipeline, mesh, data) {
+        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];
+        }
+        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, contents, usage) => {
+            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;
+        this.group = device.createBindGroup({
+            label: 'pointSkin.pose',
+            layout: pipeline.getBindGroupLayout(0),
+            entries: [
+                { binding: 0, resource: { buffer: buffers[0] } },
+                { binding: 1, resource: { buffer: this.joints } },
+                { binding: 2, resource: { buffer: buffers[1] } },
+                { binding: 3, resource: { buffer: buffers[2] } },
+                { binding: 4, resource: { buffer: buffers[3] } },
+                { 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, encoder, matrices) {
+        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() {
+        this.joints.destroy();
+        for (const buffer of this.buffers)
+            buffer.destroy();
+    }
+}

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

@@ -22,6 +22,8 @@ import { GpuText } from './textPass.ts';
 import type { TextStyle } from '../../textLayout.ts';
 import { GpuSurfaceTexture } from './surfaceTexturePass.ts';
 import { GpuClothBinding, GpuClothParticles } from './clothTextures.ts';
+import { GpuPointSkin } from './pointSkinPass.ts';
+import { type PointSkinData } from '../../pointSkin.ts';
 import type { ComputeHost } from './computeHost.ts';
 import { type SurfaceOverlay } from '../../surfaceOverlay.ts';
 import type { ClothBindingData } from '../../clothBindingData.ts';
@@ -1206,6 +1208,10 @@ export declare class WebGPURenderer implements RendererApi {
      */
     private readonly transmission;
     private warnedLayersModelMap;
+    /** `uDetail`, the material's tiled detail packed by `packSurfaceDetail`. */
+    private readonly detailFloats;
+    /** The detail refusals already said, each once. See `detailOfMaterial`. */
+    private readonly warnedDetail;
     private warnedLayersTriplanar;
     /** Its numbers, `uModelParams`, packed by `packModel`. */
     private readonly modelParams;
@@ -1951,17 +1957,14 @@ export declare class WebGPURenderer implements RendererApi {
     /** The same layout plus the joint palette. See `createDepthBindGroupLayout`. */
     private readonly shadowSkinnedLayout;
     /**
-     * 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;
-    private readonly shadowSkinnedGroupsBeside;
-    private readonly shadowSkinnedGroupsPalette;
-    private readonly shadowSkinnedGroupsCloth;
-    private readonly shadowSkinnedGroupsClothBinding;
+    private readonly shadowSkinnedShelves;
     /** Held from construction so the skinned group can be rebuilt without them being threaded. */
     private shadowBlankView;
     private shadowBlankSampler;
@@ -2113,6 +2116,11 @@ export declare 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;
     private layersOf;
     /** Says once that a layered material's triplanar projection is laid on the horizontal plane. */
     private warnLayersTriplanar;
@@ -2384,6 +2392,31 @@ export declare class WebGPURenderer implements RendererApi {
      * creation. See `GpuMesh.update`.
      */
     updateMesh(mesh: GpuMesh, positions: Float32Array, normals?: Float32Array): void;
+    /** The pipeline every point skin poses with, made at the first one. See `pointSkinPass.ts`. */
+    private pointSkinPipeline;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * **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;
+    /**
+     * 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;
     /**
      * Settle everything the frame shares: the camera, the lights and the fog.
      *