@driftengine/core 4.13.1 → 4.13.2

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 {
@@ -1476,15 +1484,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 +1601,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;
@@ -6157,17 +6158,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 +6341,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 {
@@ -8621,7 +8615,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 +8652,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 +8772,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 +8789,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 +8897,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.
    *
@@ -12391,40 +12466,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.
  *

package/src/render/mesh.ts

@@ -115,6 +115,12 @@ export class Mesh {
    * this — two references, and only where a consumer asked.
    */
   private readonly deformable: { positions: WebGLBuffer; normals: WebGLBuffer } | null = null;
+  /** A dynamic mesh's position and normal buffers, for a pose written on the device; else null. */
+  get streams(): { readonly positions: WebGLBuffer; readonly normals: WebGLBuffer } | null {
+    return this.deformable;
+  }
+  /** The colour buffer, kept so `updateColors` can rewrite it. Null unless `dynamicColors`. */
+  private readonly recolourable: WebGLBuffer | null = null;
   /** How many floats the position buffer holds, so an update of the wrong size is refused. */
   private readonly positionFloats: number;
   /**
@@ -222,8 +228,15 @@ export class Mesh {
    * and the default is the fast path: filling a buffer with `bufferData` in one call skips the
    * zero-fill that `bufferData(size)` then `bufferSubData` pays for, and every mesh in the
    * engine that does not need to be spread should keep skipping it.
+   * @param dynamicColors Colours as floats in a buffer kept for `updateColors`.
    */
-  constructor(gl: WebGL2RenderingContext, data: MeshData, dynamic = false, spread = false) {
+  constructor(
+    gl: WebGL2RenderingContext,
+    data: MeshData,
+    dynamic = false,
+    spread = false,
+    dynamicColors = false,
+  ) {
     validateMeshData(data);
     this.spread = spread;
     this.hasUvs = data.uvs !== undefined;
@@ -243,11 +256,15 @@ export class Mesh {
      */
     const usage = dynamic ? gl.DYNAMIC_DRAW : gl.STATIC_DRAW;
     /* How each attribute travels: sixteen-bit fixed point, or one value as a constant. */
-    const packing = vertexPackingOf(data, dynamic);
+    const packing = vertexPackingOf(data, dynamic, dynamicColors);
     const positions = this.attachAttribute(gl, ATTR_POSITION, data.positions, 3, usage);
     const normals = this.attachAttribute(gl, ATTR_NORMAL, data.normals, 3, usage, packing.normals);
     if (dynamic) this.deformable = { positions, normals };
-    this.attachShared(gl, ATTR_COLOR, data.colors, 3, packing.colors);
+    if (packing.colors === 'stream') {
+      this.recolourable = this.attachAttribute(gl, ATTR_COLOR, data.colors, 3, gl.DYNAMIC_DRAW);
+    } else {
+      this.attachShared(gl, ATTR_COLOR, data.colors, 3, packing.colors);
+    }
     this.attachShared(gl, ATTR_EMISSIVE, data.emissive, 1, packing.emissive);
     /*
      * Absent means "not shiny", supplied as a constant rather than as a buffer of
@@ -463,9 +480,9 @@ export class Mesh {
   /**
    * Rewrite this mesh's positions, and its normals where the caller has them.
    *
-   * **Only the two attributes that move.** Colour, emissive and the rest describe what a surface
-   * *is* and do not change because it bent; rewriting them would be uploading unchanged bytes
-   * every frame. A caller with genuinely changing colour wants a second mesh or a tint.
+   * **Only the two attributes that move.** Emissive and the rest describe what a surface *is* and
+   * do not change because it bent; rewriting them would be uploading unchanged bytes every frame.
+   * A caller whose colours change has `updateColors`, on a mesh made `dynamicColors`.
    *
    * **The bounds are recomputed**, because everything that decides whether this is on screen
    * starts from them — a cloth that blew sideways out of its original box would be culled while
@@ -495,6 +512,30 @@ export class Mesh {
     }
   }
 
+  /**
+   * Rewrite this mesh's colours, three floats a vertex, into the buffer they have to themselves.
+   *
+   * Nothing else moves, the bounds included: a colour does not change where a vertex is.
+   */
+  updateColors(gl: WebGL2RenderingContext, colors: Float32Array): void {
+    if (this.recolourable === null) {
+      throw new Error(
+        'this mesh was not created with { dynamicColors: true }, so its colours are packed 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 (colors.length !== this.positionFloats) {
+      throw new Error(
+        `this mesh has ${this.positionFloats / 3} 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.',
+      );
+    }
+    gl.bindBuffer(gl.ARRAY_BUFFER, this.recolourable);
+    gl.bufferSubData(gl.ARRAY_BUFFER, 0, colors);
+  }
+
   /**
    * One attribute's buffer, as floats or in its sixteen-bit fixed point (`vertexPacking.ts`), which
    * WebGL2 reads back through a normalised `SHORT` or `UNSIGNED_SHORT`: three lanes wide where
@@ -638,8 +679,9 @@ export function createMeshIncremental(
   gl: WebGL2RenderingContext,
   data: MeshData,
   dynamic = false,
+  dynamicColors = false,
 ): IncrementalMesh {
-  const mesh = new Mesh(gl, data, dynamic, true);
+  const mesh = new Mesh(gl, data, dynamic, true, dynamicColors);
   return { mesh, upload: mesh.uploads(gl) };
 }