@driftengine/core 3.61.0

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

@@ -0,0 +1,163 @@
+import { DEPTH_COMPARE } from '../../depthConvention.ts';
+import {
+  FLOCK_BINDINGS,
+  FLOCK_FRAG_WGSL,
+  FLOCK_VERT_WGSL,
+} from '../../shaders/generated/flock.wgsl.ts';
+import { buildFlockGeometry } from '../../flockGeometry.ts';
+import type { UniformFields } from './scatterPass.ts';
+import { DEPTH_FORMAT } from './flatPass.ts';
+import type { PipelineCache } from './pipelineCache.ts';
+import { shaderModule } from './shaderModules.ts';
+
+/**
+ * The flock pass: ambient sky life, two triangles a bird, every path in the vertex shader.
+ *
+ * **The one effect in this backend that is neither blended nor additive.** A bird is opaque and
+ * writes depth like any other surface, which is what lets one pass in front of another. Nothing
+ * is culled: they are flat cards seen from both sides as they bank.
+ */
+
+export const FLOCK_VERT_FIELDS: UniformFields = FLOCK_BINDINGS.FLOCK_VERT.fields;
+export const FLOCK_VERT_SIZE = FLOCK_BINDINGS.FLOCK_VERT.uniformSize;
+export const FLOCK_FRAG_FIELDS: UniformFields = FLOCK_BINDINGS.FLOCK_FRAG.fields;
+export const FLOCK_FRAG_SIZE = FLOCK_BINDINGS.FLOCK_FRAG.uniformSize;
+
+const VERT_BINDING = FLOCK_BINDINGS.FLOCK_VERT.uniforms;
+const FRAG_BINDING = FLOCK_BINDINGS.FLOCK_FRAG.uniforms;
+
+const VISIBILITY_VERTEX = 0x1;
+const VISIBILITY_FRAGMENT = 0x2;
+const USAGE_VERTEX = 0x0020 | 0x0008;
+
+/** A flock on the device, behind the surface's opaque handle. */
+export interface GpuFlock {
+  readonly corners: GPUBuffer;
+  readonly wings: GPUBuffer;
+  readonly indices: GPUBuffer;
+  readonly vertexCount: number;
+  dispose(): void;
+}
+
+export function createGpuFlock(device: GPUDevice, count: number): GpuFlock {
+  const geometry = buildFlockGeometry(count);
+  const upload = (data: Float32Array, label: string): GPUBuffer => {
+    const buffer = device.createBuffer({
+      label,
+      size: Math.max(4, data.byteLength),
+      usage: USAGE_VERTEX,
+    });
+    device.queue.writeBuffer(buffer, 0, data);
+    return buffer;
+  };
+  const corners = upload(geometry.corners, 'flock.corners');
+  const wings = upload(geometry.wings, 'flock.wings');
+  const indices = upload(geometry.indices, 'flock.indices');
+
+  return {
+    corners,
+    wings,
+    indices,
+    vertexCount: geometry.vertexCount,
+    dispose(): void {
+      corners.destroy();
+      wings.destroy();
+      indices.destroy();
+    },
+  };
+}
+
+/** `aCorner`, `aWing`, `aIndex` — one buffer each, as `FlockRenderer` holds them. */
+export function flockVertexLayouts(): GPUVertexBufferLayout[] {
+  return [
+    {
+      arrayStride: 8,
+      attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x2' as GPUVertexFormat }],
+    },
+    {
+      arrayStride: 4,
+      attributes: [{ shaderLocation: 1, offset: 0, format: 'float32' as GPUVertexFormat }],
+    },
+    {
+      arrayStride: 4,
+      attributes: [{ shaderLocation: 2, offset: 0, format: 'float32' as GPUVertexFormat }],
+    },
+  ];
+}
+
+export function createFlockBindGroupLayout(device: GPUDevice): GPUBindGroupLayout {
+  return device.createBindGroupLayout({
+    label: 'flock.layout',
+    entries: [
+      /*
+       * **Addressed by a dynamic offset, so a frame can draw more than one batch.**
+       *
+       * With one buffer rewritten between draws, every batch reads whatever was written last:
+       * `queue.write*` calls are ordered on the queue timeline and the encoder is submitted after
+       * every one of them. The picture is each batch wearing the last one's colour, width, time
+       * and placement. That is the hazard `UniformRing` exists for, recorded in `AGENTS.md` on
+       * 2026-08-27, and this pass was one of four still carrying it — invisible for as long as
+       * nothing drew two, which is exactly how water kept it for eight releases.
+       *
+       * WebGL2 needs none of this: it sets uniforms and draws in one stream.
+       */
+      {
+        binding: VERT_BINDING,
+        visibility: VISIBILITY_VERTEX,
+        buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: FLOCK_VERT_SIZE },
+      },
+      {
+        binding: FRAG_BINDING,
+        visibility: VISIBILITY_FRAGMENT,
+        buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: FLOCK_FRAG_SIZE },
+      },
+    ],
+  });
+}
+
+export function createFlockBindGroup(
+  device: GPUDevice,
+  layout: GPUBindGroupLayout,
+  vertices: GPUBuffer,
+  fragments: GPUBuffer,
+): GPUBindGroup {
+  return device.createBindGroup({
+    label: 'flock.bindGroup',
+    layout,
+    entries: [
+      { binding: VERT_BINDING, resource: { buffer: vertices, size: FLOCK_VERT_SIZE } },
+      { binding: FRAG_BINDING, resource: { buffer: fragments, size: FLOCK_FRAG_SIZE } },
+    ],
+  });
+}
+
+/**
+ * The pipeline.
+ *
+ * `less` and depth written, matching the flat pass: a bird is geometry in the world rather than
+ * an effect over it, and a flock that did not write depth would show every bird through every
+ * other one.
+ */
+export function flockPipeline(
+  cache: PipelineCache,
+  device: GPUDevice,
+  layout: GPUBindGroupLayout,
+): GPURenderPipeline {
+  return cache.get('flock', () => ({
+    label: 'flock',
+    layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+    vertex: {
+      module: shaderModule(device, { label: 'flock.vert', code: FLOCK_VERT_WGSL }),
+      entryPoint: 'main',
+      buffers: flockVertexLayouts(),
+    },
+    fragment: {
+      module: shaderModule(device, { label: 'flock.frag', code: FLOCK_FRAG_WGSL }),
+      entryPoint: 'main',
+      targets: [{ format: cache.format }],
+    },
+    primitive: { topology: 'triangle-list', cullMode: 'none' },
+    multisample: { count: cache.sampleCount },
+    depthStencil: { format: DEPTH_FORMAT, depthWriteEnabled: true, depthCompare: DEPTH_COMPARE },
+  }));
+}

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

@@ -0,0 +1,255 @@
+/**
+ * What a WebGPU frame cost, from the GPU rather than from a clock.
+ *
+ * **This backend shipped without one, and that is why a phone was slow for a release without
+ * anybody being able to say by how much.** `WebGpuRenderer.gpuTimer` was a stub reporting
+ * `available: false` and `null` forever, so every GPU figure this project has ever quoted came
+ * from WebGL2 — the backend phones do not use. The consumer's own rule is that a
+ * GPU verdict needs `gpuSamples > 0`, which on the shipping backend could never be satisfied,
+ * so the frame meter, the FPS report and the diagnostics bundle all had a hole exactly where
+ * the answer was.
+ *
+ * **Nothing here is new API.** It implements `FrameTimer`, the same interface `GpuTimer`
+ * implements over `EXT_disjoint_timer_query_webgl2`, so the game that already calls
+ * `beginFrame`, `begin('rest')`, `end`, `endFrame` and `poll` starts getting numbers without
+ * one line changing over there.
+ *
+ * **The one shape difference, and it is forced by the API.** WebGL2 brackets an arbitrary run
+ * of commands with `TIME_ELAPSED_EXT`. WebGPU cannot: a timestamp is written at the start and
+ * the end of a *render pass*, declared on the pass descriptor. So the bracket becomes an
+ * attribution rather than a measurement — `begin(slot)` records which slot is open,
+ * `writesFor` hands the next query pair to each pass the renderer opens and remembers where it
+ * belonged, and the readback sums the pass deltas per slot. A pass drawn without calling
+ * `writesFor` is GPU time the total silently omits, which is the one way to get a wrong number
+ * out of this rather than no number.
+ *
+ * **Never blocks.** A frame resolves its queries into a staging buffer and asks for the
+ * mapping; the answer lands a frame or two later and is reported then. A timer that waited for
+ * its own frame would be a stall, which is the one thing a profiler must not add.
+ */
+import type { FrameTimer } from '../timer.ts';
+import { GPU_SLOTS, type GpuSample, type GpuSlot } from '../../gpuTimer.ts';
+
+/**
+ * Passes one frame may time.
+ *
+ * The heaviest frame measured on this engine is twenty — the game's courtyard, with three shadow
+ * layers, six cubemap faces, two mirrors and the occlusion chain. Thirty-two leaves room for a
+ * scene heavier than any that exists without allocating a query set nobody fills.
+ */
+const MAX_TIMED_PASSES = 32;
+const QUERIES_PER_PASS = 2;
+const BYTES_PER_QUERY = 8;
+const NS_PER_MS = 1e6;
+
+/** Resolved frames waiting for `poll`. Past this a frame is skipped rather than queued. */
+const POOL_DEPTH = 4;
+
+/*
+ * Numeric rather than `GPUBufferUsage.*`, matching the rest of this directory. Those globals
+ * do not exist under vitest, and a timer that cannot be constructed in a test is a timer whose
+ * arithmetic nobody checks.
+ */
+const USAGE_QUERY_RESOLVE = 0x0200;
+const USAGE_COPY_SRC = 0x0004;
+const USAGE_COPY_DST = 0x0008;
+const USAGE_MAP_READ = 0x0001;
+const MAP_MODE_READ = 0x0001;
+
+/** Slot to index, so a frame's attribution is a `Uint8Array` and costs no allocation. */
+const SLOT_INDEX: Readonly<Record<GpuSlot, number>> = { shadows: 0, reflection: 1, rest: 2 };
+
+export class GpuTimestamps implements FrameTimer {
+  /** False where the adapter withheld `timestamp-query`, which is a normal state. */
+  readonly available: boolean;
+
+  private readonly querySet: GPUQuerySet | null = null;
+  private readonly resolveBuffer: GPUBuffer | null = null;
+  private readonly readBuffer: GPUBuffer | null = null;
+  private readonly sampleEvery: number;
+
+  /** Which slot each timed pass of the frame being recorded belongs to. */
+  private readonly passSlots = new Uint8Array(MAX_TIMED_PASSES);
+  /** The same, for the frame whose readback is in flight; the recorder reuses the other. */
+  private readonly inFlightSlots = new Uint8Array(MAX_TIMED_PASSES);
+  private passCount = 0;
+  private inFlightCount = 0;
+
+  private openSlot: GpuSlot | null = null;
+  private frame = 0;
+  private measuring = false;
+  /** Whether this frame's queries have already been copied out; a second copy is a no-op. */
+  private resolved = false;
+  private readbackBusy = false;
+
+  private readonly pending: GpuSample[] = [];
+  private lastSample: GpuSample | null = null;
+
+  get sampling(): boolean {
+    return this.measuring;
+  }
+
+  constructor(device: GPUDevice, enabled = false, sampleEvery = 8) {
+    this.sampleEvery = Math.max(1, Math.floor(sampleEvery));
+    /*
+     * Both halves, and `enabled` is the one that matters. A timer costs two queries a pass and
+     * attaches a block to every pass descriptor in the frame, so an implementation that
+     * disagrees about any of it invalidates the command buffer and the frame draws nothing.
+     * That risk belongs to whoever asked to measure, never to every consumer by default.
+     */
+    this.available = enabled && (device.features?.has('timestamp-query') ?? false);
+    if (!this.available) return;
+
+    const count = MAX_TIMED_PASSES * QUERIES_PER_PASS;
+    const bytes = count * BYTES_PER_QUERY;
+    this.querySet = device.createQuerySet({ label: 'gpu.timestamps', type: 'timestamp', count });
+    /*
+     * Two buffers, because one cannot be both. `QUERY_RESOLVE` is where the driver writes and
+     * `MAP_READ` is what this side may look at, and the flags are mutually exclusive.
+     */
+    this.resolveBuffer = device.createBuffer({
+      label: 'gpu.timestamps.resolve',
+      size: bytes,
+      usage: USAGE_QUERY_RESOLVE | USAGE_COPY_SRC,
+    });
+    this.readBuffer = device.createBuffer({
+      label: 'gpu.timestamps.read',
+      size: bytes,
+      usage: USAGE_COPY_DST | USAGE_MAP_READ,
+    });
+  }
+
+  /**
+   * Whether this frame is measured. Called once per frame, before any `begin`.
+   *
+   * Declines while a readback is still in flight, and that is not politeness: the read buffer
+   * belongs to the driver until the mapping lands, and copying into a mapped buffer is a
+   * validation error rather than a slow frame.
+   */
+  beginFrame(): boolean {
+    if (this.querySet === null) return false;
+    const measured = this.frame % this.sampleEvery === 0;
+    this.frame++;
+    this.measuring = measured && !this.readbackBusy && this.pending.length < POOL_DEPTH;
+    if (this.measuring) {
+      this.passCount = 0;
+      this.resolved = false;
+      this.openSlot = null;
+    }
+    return this.measuring;
+  }
+
+  /** Open a bracket. Every pass opened until `end` is attributed to this slot. */
+  begin(slot: GpuSlot): void {
+    if (!this.measuring || this.openSlot !== null) return;
+    this.openSlot = slot;
+  }
+
+  end(): void {
+    this.openSlot = null;
+  }
+
+  /**
+   * The query pair for the pass about to be opened, or undefined where there is nothing to
+   * measure with.
+   *
+   * Undefined is a legal value for `timestampWrites`, so a caller passes this straight into
+   * the descriptor without branching, and an unmeasured frame costs one property write.
+   */
+  writesFor(): GPURenderPassTimestampWrites | undefined {
+    if (!this.measuring || this.resolved || this.querySet === null) return undefined;
+    if (this.passCount >= MAX_TIMED_PASSES) return undefined;
+    const index = this.passCount;
+    this.passSlots[index] = SLOT_INDEX[this.openSlot ?? 'rest'];
+    this.passCount++;
+    return {
+      querySet: this.querySet,
+      beginningOfPassWriteIndex: index * QUERIES_PER_PASS,
+      endOfPassWriteIndex: index * QUERIES_PER_PASS + 1,
+    };
+  }
+
+  /**
+   * Copy the frame's queries out, on the frame's own encoder, before it is submitted.
+   *
+   * The renderer calls this rather than `endFrame`, because by the time the consumer ends the
+   * frame the encoder it would have to ride on has already been finished and submitted.
+   */
+  resolve(encoder: GPUCommandEncoder): void {
+    if (!this.measuring || this.resolved || this.readbackBusy) return;
+    if (this.querySet === null || this.resolveBuffer === null || this.readBuffer === null) return;
+    if (this.passCount === 0) return;
+    const count = this.passCount * QUERIES_PER_PASS;
+    encoder.resolveQuerySet(this.querySet, 0, count, this.resolveBuffer, 0);
+    encoder.copyBufferToBuffer(this.resolveBuffer, 0, this.readBuffer, 0, count * BYTES_PER_QUERY);
+    this.resolved = true;
+  }
+
+  /** Close the frame and ask for the mapping. Nothing waits for it. */
+  endFrame(): void {
+    if (!this.measuring) return;
+    this.measuring = false;
+    this.openSlot = null;
+    if (!this.resolved || this.readbackBusy) return;
+
+    this.inFlightSlots.set(this.passSlots);
+    this.inFlightCount = this.passCount;
+    this.readbackBusy = true;
+    this.readBack();
+  }
+
+  private readBack(): void {
+    const buffer = this.readBuffer;
+    if (buffer === null) return;
+    void buffer.mapAsync(MAP_MODE_READ).then(
+      () => {
+        const stamps = new BigUint64Array(buffer.getMappedRange());
+        const parts = { shadows: 0, reflection: 0, rest: 0 };
+        for (let i = 0; i < this.inFlightCount; i++) {
+          const started = stamps[i * QUERIES_PER_PASS] ?? 0n;
+          const finished = stamps[i * QUERIES_PER_PASS + 1] ?? 0n;
+          /*
+           * A pair the driver never wrote reads as two zeros, and a disjoint one can read
+           * backwards. Both mean "no measurement", and neither is worth reporting as a
+           * confident 0.0 — see `FrameTimer` on why an invented zero is the worst answer here.
+           */
+          if (finished <= started) continue;
+          const slot = GPU_SLOTS[this.inFlightSlots[i] ?? 2] ?? 'rest';
+          parts[slot] += Number(finished - started) / NS_PER_MS;
+        }
+        buffer.unmap();
+        this.lastSample = parts;
+        if (this.pending.length < POOL_DEPTH) this.pending.push(parts);
+        this.readbackBusy = false;
+      },
+      () => {
+        /* A lost device or a cancelled mapping is not a reason to stop drawing. */
+        this.readbackBusy = false;
+      },
+    );
+  }
+
+  /** The oldest finished sample, or null. Never blocks. */
+  poll(): GpuSample | null {
+    return this.pending.shift() ?? null;
+  }
+
+  /**
+   * The whole of the last resolved frame in milliseconds, or null where nothing measured.
+   *
+   * Summed because the three brackets partition the frame rather than overlapping, which is
+   * the same arithmetic `GpuTimer.lastFrameMs` does over the same three names.
+   */
+  lastFrameMs(): number | null {
+    if (this.lastSample === null) return null;
+    return this.lastSample.shadows + this.lastSample.reflection + this.lastSample.rest;
+  }
+
+  dispose(): void {
+    this.querySet?.destroy();
+    this.resolveBuffer?.destroy();
+    this.readBuffer?.destroy();
+    this.pending.length = 0;
+    this.lastSample = null;
+  }
+}

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

@@ -0,0 +1,123 @@
+import type { PipelineCache } from './pipelineCache.ts';
+import { DEPTH_FORMAT } from './flatPass.ts';
+import { shaderModule } from './shaderModules.ts';
+
+/**
+ * Clearing a *rectangle* of the frame, which WebGPU has no operation for.
+ *
+ * `beginInset` on WebGL2 is `gl.scissor` plus `gl.clear`, and the scissor confines the clear.
+ * WebGPU clears at `loadOp`, which applies to the whole attachment and cannot be confined —
+ * reopening the pass to clear would throw away the frame outside the inset, and clearing only
+ * depth that way would silently un-occlude everything a scene draws *after* `endInset`.
+ *
+ * So the rect is drawn rather than cleared: one quad at the far plane, depth always written,
+ * colour written or masked off depending on whether the caller asked for a colour.
+ *
+ * **Its own shader, and it is allowed to be.** This is not generated from GLSL and has no
+ * WebGL2 counterpart to stay honest against — the counterpart is `gl.clear`. The mip blit in
+ * `surfaceTexturePass.ts` is here for the same reason.
+ */
+const INSET_WGSL = `
+struct Rect {
+  color: vec4<f32>,
+}
+@group(0) @binding(0) var<uniform> rect: Rect;
+
+@vertex
+fn vertexMain(@builtin(vertex_index) index: u32) -> @builtin(position) vec4<f32> {
+  /*
+   * The whole of the current viewport, which is the inset, because \`beginInset\` has already
+   * set it.
+   *
+   * **It used to place the quad from the rect's own CSS pixels and that is one transform too
+   * many.** Clip space is relative to the viewport in force, not to the canvas, so a quad
+   * describing "this box within the canvas" was mapped into the box a second time: it came out
+   * small and pushed toward a corner, leaving most of the inset uncleared. What a caller then
+   * saw was whatever had been in the frame there, or nothing at all where the frame was
+   * transparent — reported from the game as a hole where a portrait should be. The content
+   * inside the inset was always correct, which is what made it look like a missing draw rather
+   * than a misplaced one.
+   */
+  var corner = array<vec2<f32>, 6>(
+    vec2<f32>(0.0, 0.0), vec2<f32>(1.0, 0.0), vec2<f32>(1.0, 1.0),
+    vec2<f32>(0.0, 0.0), vec2<f32>(1.0, 1.0), vec2<f32>(0.0, 1.0),
+  );
+  let ndc = corner[index] * 2.0 - vec2<f32>(1.0, 1.0);
+  // z = 1: the far plane, which is what a depth clear writes.
+  return vec4<f32>(ndc, 1.0, 1.0);
+}
+
+@fragment
+fn fragmentMain() -> @location(0) vec4<f32> {
+  return rect.color;
+}
+`;
+
+/**
+ * `color` (4), and nothing else.
+ *
+ * The rect's bounds and the canvas size were in here to place the quad and are not needed to
+ * cover a viewport that is already the rect. Kept out rather than left unread: an unused uniform
+ * is a field somebody later writes and expects to matter.
+ */
+export const INSET_UNIFORM_SIZE = 16;
+
+export function createInsetBindGroupLayout(device: GPUDevice): GPUBindGroupLayout {
+  return device.createBindGroupLayout({
+    label: 'inset.layout',
+    entries: [
+      {
+        binding: 0,
+        visibility: 0x1 | 0x2,
+        buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: INSET_UNIFORM_SIZE },
+      },
+    ],
+  });
+}
+
+export function createInsetBindGroup(
+  device: GPUDevice,
+  layout: GPUBindGroupLayout,
+  uniforms: GPUBuffer,
+): GPUBindGroup {
+  return device.createBindGroup({
+    label: 'inset.bindGroup',
+    layout,
+    entries: [{ binding: 0, resource: { buffer: uniforms, size: INSET_UNIFORM_SIZE } }],
+  });
+}
+
+/**
+ * The clearing quad.
+ *
+ * `writeColor` off is the depth-only case — `beginInset(rect, null)`, where the frame behind
+ * survives so what is drawn next sits over the scene rather than over a rectangle of flat
+ * colour. `depthCompare: 'always'` because a clear does not ask permission.
+ */
+export function insetPipeline(
+  cache: PipelineCache,
+  device: GPUDevice,
+  layout: GPUBindGroupLayout,
+  writeColor: boolean,
+): GPURenderPipeline {
+  return cache.get(`inset|${writeColor ? 'color' : 'depth'}`, () => {
+    const module = shaderModule(device, { label: 'inset', code: INSET_WGSL });
+    return {
+      label: `inset|${writeColor ? 'color' : 'depth'}`,
+      layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+      vertex: { module, entryPoint: 'vertexMain' },
+      fragment: {
+        module,
+        entryPoint: 'fragmentMain',
+        targets: [{ format: cache.format, writeMask: writeColor ? 0xf : 0 }],
+      },
+      primitive: { topology: 'triangle-list' as const, cullMode: 'none' as const },
+      multisample: { count: cache.sampleCount },
+      depthStencil: {
+        format: DEPTH_FORMAT,
+        depthWriteEnabled: true,
+        depthCompare: 'always' as const,
+      },
+    };
+  });
+}

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

@@ -0,0 +1,55 @@
+import { INSTANCE_FLOATS, INSTANCE_STRIDE, packInstances } from '../../instances.ts';
+import type { MeshInstances } from '../../instances.ts';
+import type { GpuMesh } from './buffers.ts';
+
+/** VERTEX | COPY_DST, spelled the way every other pass here spells it. */
+const USAGE_VERTEX = 0x0020 | 0x0008;
+
+/**
+ * One mesh's per-instance buffer on the device.
+ *
+ * **Attached to a mesh rather than owning one.** The geometry an instanced draw repeats is
+ * usually the expensive kind — a loaded model rather than a blade of grass — so this holds a
+ * reference to the mesh a consumer already uploaded and adds only the placement.
+ *
+ * The staging array is allocated here and rewritten in place, which is what keeps a frame that
+ * re-uploads a moving batch allocation-free.
+ */
+export class GpuInstancedBatch {
+  readonly buffer: GPUBuffer;
+  readonly mesh: GpuMesh;
+  readonly capacity: number;
+  private readonly staging: Float32Array;
+
+  constructor(device: GPUDevice, mesh: GpuMesh, capacity: number, label: string) {
+    this.mesh = mesh;
+    this.capacity = capacity;
+    this.staging = new Float32Array(capacity * INSTANCE_FLOATS);
+    this.buffer = device.createBuffer({
+      /*
+       * Labelled, and it is not decoration: a WebGPU validation failure arrives at `submit`
+       * naming the resource it was about, and an unlabelled buffer names nothing.
+       */
+      label,
+      size: capacity * INSTANCE_STRIDE,
+      usage: USAGE_VERTEX,
+    });
+  }
+
+  /**
+   * Pack and push `data.count` instances, in one write.
+   *
+   * Only the live prefix, for the reason `uploadScatter` gives: the rest is not drawn and
+   * uploading it would be per-frame waste with nothing reading it.
+   */
+  upload(queue: GPUQueue, data: MeshInstances): void {
+    const count = Math.min(data.count, this.capacity);
+    if (count === 0) return;
+    packInstances(data, this.staging);
+    queue.writeBuffer(this.buffer, 0, this.staging, 0, count * INSTANCE_FLOATS);
+  }
+
+  dispose(): void {
+    this.buffer.destroy();
+  }
+}