@driftengine/core 4.6.0 → 4.7.0

package/scripts/png.mjs

@@ -2,10 +2,11 @@
  * Enough of a PNG reader to compare two frames, with no dependency.
  *
  * A screenshot arrives as 8-bit RGBA, filter method 0, not interlaced, which is what every
- * browser produces. A bought model's maps also arrive as 8-bit grey, grey with alpha and RGB, and
- * the baker and the native host read those through here too. Anything else — a palette, sixteen
- * bits, interlacing — is refused by name rather than guessed at, because a reader that quietly
- * mis-decodes produces pixel differences that look like a rendering change.
+ * browser produces, and is read on a path that copies nothing. A bought model's maps arrive as
+ * every other non-interlaced kind — grey, grey with alpha, RGB and RGBA at eight or sixteen bits,
+ * palettes and greys at one to eight — and the baker and the native host read those through here
+ * too, widened to 8-bit samples. Interlacing is refused by name rather than guessed at, because a
+ * reader that quietly mis-decodes produces pixel differences that look like a rendering change.
  *
  * `zlib` is Node's own, so this costs nothing to have.
  */
@@ -14,14 +15,28 @@ import { readFileSync } from 'node:fs';
 
 const SIGNATURE = 0x89504e47;
 
-/** `{ width, height, channels, pixels }`, pixels being row-major 8-bit samples. */
+/** Samples a pixel, by colour type. */
+const SAMPLES = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 };
+/** The bit depths the specification allows for each colour type. */
+const DEPTHS = { 0: [1, 2, 4, 8, 16], 2: [8, 16], 3: [1, 2, 4, 8], 4: [8, 16], 6: [8, 16] };
+
+/**
+ * `{ width, height, channels, pixels }`, pixels being row-major 8-bit samples.
+ *
+ * A palette widens to RGB, or to RGBA where it carries `tRNS`; a grey or RGB image with a `tRNS`
+ * key gains an alpha channel, nought at that one value; sixteen bits keep the high byte; a grey
+ * below eight bits is scaled to the full byte, so one bit is 0 or 255.
+ */
 export function decodePng(bytes) {
   if (bytes.length < 8 || bytes.readUInt32BE(0) !== SIGNATURE) throw new Error('not a PNG');
 
   let at = 8;
   let width = 0;
   let height = 0;
-  let channels = 0;
+  let depth = 0;
+  let colorType = 0;
+  let palette = null;
+  let transparency = null;
   const parts = [];
 
   while (at + 8 <= bytes.length) {
@@ -31,20 +46,22 @@ export function decodePng(bytes) {
     if (type === 'IHDR') {
       width = body.readUInt32BE(0);
       height = body.readUInt32BE(4);
-      const depth = body[8];
-      const colorType = body[9];
+      depth = body[8];
+      colorType = body[9];
       const interlace = body[12];
-      if (depth !== 8) throw new Error(`bit depth ${depth}, only 8 is handled`);
       if (interlace !== 0) throw new Error('interlaced PNG, not handled');
-      /*
-       * Grey, grey with alpha, RGB and RGBA — every 8-bit type but a palette. A bought model's
-       * single-channel maps are greyscale, and refusing them left a baker's texture cap unable to
-       * shrink a third of one scene's maps. A palette needs `PLTE` read, and nothing has asked.
-       */
-      channels = { 0: 1, 4: 2, 2: 3, 6: 4 }[colorType] ?? 0;
-      if (channels === 0) {
-        throw new Error(`colour type ${colorType}, only 0, 2, 4 and 6 are handled`);
+      if (SAMPLES[colorType] === undefined) {
+        throw new Error(`colour type ${colorType}, which is not a PNG colour type`);
       }
+      if (!DEPTHS[colorType].includes(depth)) {
+        throw new Error(
+          `bit depth ${depth} for colour type ${colorType}, which PNG does not allow`,
+        );
+      }
+    } else if (type === 'PLTE') {
+      palette = body;
+    } else if (type === 'tRNS') {
+      transparency = body;
     } else if (type === 'IDAT') {
       parts.push(body);
     } else if (type === 'IEND') {
@@ -54,15 +71,21 @@ export function decodePng(bytes) {
     at += 12 + length;
   }
   if (width === 0 || height === 0) throw new Error('no IHDR');
+  if (colorType === 3 && palette === null) throw new Error('a palette PNG with no PLTE');
 
+  const samples = SAMPLES[colorType];
+  const bits = samples * depth;
+  /* What a filter steps back by: a whole pixel, or one byte where a pixel is smaller than one. */
+  const step = Math.max(1, bits >> 3);
+  const stride = (width * bits + 7) >> 3;
   const raw = inflateSync(Buffer.concat(parts));
-  const stride = width * channels;
-  const pixels = Buffer.alloc(stride * height);
+  const scan = Buffer.alloc(stride * height);
 
   /*
    * Un-filtering, which is the whole of the format that is not zlib. Each row states one of five
-   * predictors and the residual against it; `a` is the sample one pixel left, `b` the one above,
-   * `c` the one above and left, and all three are zero outside the image rather than wrapped.
+   * predictors and the residual against it; `a` is the byte one pixel left, `b` the one above,
+   * `c` the one above and left, and all three are zero outside the image rather than wrapped. It
+   * runs on the packed bytes, before a sub-byte pixel is unpacked, which is what the format says.
    */
   for (let y = 0; y < height; y++) {
     const filter = raw[y * (stride + 1)];
@@ -70,9 +93,9 @@ export function decodePng(bytes) {
     const to = y * stride;
     for (let i = 0; i < stride; i++) {
       const value = raw[from + i];
-      const a = i >= channels ? pixels[to + i - channels] : 0;
-      const b = y > 0 ? pixels[to - stride + i] : 0;
-      const c = i >= channels && y > 0 ? pixels[to - stride + i - channels] : 0;
+      const a = i >= step ? scan[to + i - step] : 0;
+      const b = y > 0 ? scan[to - stride + i] : 0;
+      const c = i >= step && y > 0 ? scan[to - stride + i - step] : 0;
       let restored;
       if (filter === 0) restored = value;
       else if (filter === 1) restored = value + a;
@@ -80,10 +103,61 @@ export function decodePng(bytes) {
       else if (filter === 3) restored = value + ((a + b) >> 1);
       else if (filter === 4) restored = value + paeth(a, b, c);
       else throw new Error(`row ${y} states filter ${filter}, which is not a PNG filter`);
-      pixels[to + i] = restored & 0xff;
+      scan[to + i] = restored & 0xff;
     }
   }
 
+  /* Eight bits of grey, grey and alpha, RGB or RGBA with no key: the scan is the pixels. */
+  if (depth === 8 && colorType !== 3 && transparency === null) {
+    return { width, height, channels: samples, pixels: scan };
+  }
+  return widen(scan, width, height, depth, colorType, stride, palette, transparency);
+}
+
+/** A sample at its own precision: pixel `x`, sample `s` of row `y`. */
+function sampleAt(scan, stride, depth, samples, y, x, s) {
+  const index = x * samples + s;
+  if (depth === 16) return scan.readUInt16BE(y * stride + index * 2);
+  if (depth === 8) return scan[y * stride + index];
+  const bit = index * depth;
+  return (scan[y * stride + (bit >> 3)] >> (8 - depth - (bit & 7))) & ((1 << depth) - 1);
+}
+
+/** Everything the 8-bit path does not take, widened to 8-bit samples. */
+function widen(scan, width, height, depth, colorType, stride, palette, transparency) {
+  const samples = SAMPLES[colorType];
+  const paletted = colorType === 3;
+  /* A key in tRNS is one sample value a channel, at the image's own depth. */
+  const keyed = !paletted && transparency !== null && (colorType === 0 || colorType === 2);
+  const channels = paletted ? (transparency === null ? 3 : 4) : samples + (keyed ? 1 : 0);
+  const key = keyed
+    ? [0, 1, 2].slice(0, samples).map((s) => transparency.readUInt16BE(s * 2))
+    : null;
+  const to8 =
+    depth === 16 ? (v) => v >> 8 : depth === 8 ? (v) => v : (v) => (v * 255) / ((1 << depth) - 1);
+  const entries = paletted ? palette.length / 3 : 0;
+  const pixels = Buffer.alloc(width * height * channels);
+  let out = 0;
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      if (paletted) {
+        const index = sampleAt(scan, stride, depth, 1, y, x, 0);
+        if (index >= entries) throw new Error(`palette index ${index} past a PLTE of ${entries}`);
+        pixels[out++] = palette[index * 3];
+        pixels[out++] = palette[index * 3 + 1];
+        pixels[out++] = palette[index * 3 + 2];
+        if (channels === 4) pixels[out++] = index < transparency.length ? transparency[index] : 255;
+        continue;
+      }
+      let matches = key !== null;
+      for (let s = 0; s < samples; s++) {
+        const value = sampleAt(scan, stride, depth, samples, y, x, s);
+        if (key !== null && value !== key[s]) matches = false;
+        pixels[out++] = to8(value);
+      }
+      if (keyed) pixels[out++] = matches ? 0 : 255;
+    }
+  }
   return { width, height, channels, pixels };
 }
 

package/src/render/backend/budget.ts

@@ -49,6 +49,12 @@ export interface BudgetCounter extends BudgetLine {
   ask(): void;
   /** One of them was refused, and the frame is marked. */
   drop(): void;
+  /**
+   * The ceiling, where it is a construction-time option and not known when the line is declared.
+   * Called at construction, once; a line keeps the place it was declared in, which is the order a
+   * report reads in.
+   */
+  limit(ceiling: number): void;
 }
 
 class Line implements BudgetCounter {
@@ -57,10 +63,14 @@ class Line implements BudgetCounter {
 
   constructor(
     readonly name: string,
-    readonly ceiling: number | null,
+    public ceiling: number | null,
     private readonly budget: FrameBudget,
   ) {}
 
+  limit(ceiling: number): void {
+    this.ceiling = ceiling;
+  }
+
   /** One more of this thing was asked for, whether or not it will fit. */
   ask(): void {
     this.used += 1;

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

@@ -3794,7 +3794,8 @@ export class WebGL2Renderer implements RendererApi {
   ): void {
     if (this.contextLost) return;
     const mesh = batch.mesh;
-    if (!mesh.complete) return;
+    /* Nor a batch of a mesh with nothing in it: see `Mesh.indexCount`. */
+    if (!mesh.complete || mesh.indexCount === 0) return;
     const count = Math.min(data.count, batch.capacity);
     if (count === 0) return;
     /* A culling batch's camera draw: the whole batch against the view and the occluders first,
@@ -7698,8 +7699,9 @@ export class WebGL2Renderer implements RendererApi {
     _previousModel: ReadonlyMat4 | Mover | null = null,
   ): void {
     if (this.contextLost) return;
-    /* Geometry that has not all arrived is not drawn. See `Mesh.complete`. */
-    if (!mesh.complete) return;
+    /* Geometry that has not all arrived is not drawn, nor a mesh with none. See `Mesh.complete`
+       and `Mesh.indexCount`. */
+    if (!mesh.complete || mesh.indexCount === 0) return;
 
     /*
      * Skipped where the flag asks and the bounds say so.
@@ -7885,8 +7887,9 @@ export class WebGL2Renderer implements RendererApi {
     options: TranslucentMeshOptions = {},
   ): void {
     if (this.contextLost) return;
-    /* Geometry that has not all arrived is not drawn. See `Mesh.complete`. */
-    if (!mesh.complete) return;
+    /* Geometry that has not all arrived is not drawn, nor a mesh with none. See `Mesh.complete`
+       and `Mesh.indexCount`. */
+    if (!mesh.complete || mesh.indexCount === 0) return;
 
     if (opacity <= 0) return;
 
@@ -8312,8 +8315,9 @@ export class WebGL2Renderer implements RendererApi {
     options: LightVolumeDrawOptions = {},
   ): void {
     if (this.contextLost) return;
-    /* Geometry that has not all arrived is not drawn. See `Mesh.complete`. */
-    if (!mesh.complete) return;
+    /* Geometry that has not all arrived is not drawn, nor a mesh with none. See `Mesh.complete`
+       and `Mesh.indexCount`. */
+    if (!mesh.complete || mesh.indexCount === 0) return;
     const shown =
       options.medium === undefined
         ? strength

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

@@ -154,6 +154,13 @@ export interface GpuMesh {
    */
   readonly skinOffsets: { readonly joints: number; readonly weights: number } | null;
   readonly indexBuffer: GPUBuffer;
+  /**
+   * How many indices the mesh draws. **Zero is a mesh with nothing to draw, and no pass draws it**:
+   * a level can hold none of some kind of geometry, and a draw of zero indices does nothing but
+   * earn a warning from the device in every pass that issues it. Every place a mesh enters a pass
+   * checks this beside `complete` or its vertex buffers, and WebGL2 skips the same meshes, so the
+   * two backends count the same draws.
+   */
   readonly indexCount: number;
   /**
    * How big this mesh is, in its own space.

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

@@ -509,7 +509,8 @@ export class MotionPass {
         } else {
           pipeline = this.pipelineFor(mesh.vertexStride);
         }
-        if (pipeline === null) continue;
+        /* A mesh with nothing in it draws nothing: see `GpuMesh.indexCount`. */
+        if (pipeline === null || mesh.indexCount === 0) continue;
         if (pipeline !== bound) {
           pass.setPipeline(pipeline);
           bound = pipeline;

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

@@ -586,7 +586,9 @@ import type { WorldLightFieldOptions } from '../../driftLight/worldLightField.ts
 import { createDriftLightUniforms, resolveDriftLight } from '../../driftLight/uniforms.ts';
 
 /**
- * How many draws one frame may make before the ring is full.
+ * How many draws one frame is prepared for before anything grows: `drawsPerFrame`'s default, and
+ * the starting size of the arena and the command pool, which reallocate on demand. The two rings
+ * that cannot grow take `drawsPerFrame` itself.
  *
  * **Four thousand and ninety-six, and the number is an allocation rather than a limit.**
  * `UniformRing.flush` uploads `used * slotSize`, so a frame that draws two hundred pays for two
@@ -644,37 +646,6 @@ const MAX_OVERLAYS = 64;
  */
 const MAX_SKY_DRAWS = 64;
 
-/**
- * Distinct materials a frame may set.
- *
- * A slot is spent per *change*, not per draw, so this counts how many times a scene switches
- * material rather than how much it draws.
- *
- * **A thousand and twenty-four, and it is the expensive one of the two.** A slot is the fragment
- * block — 3,376 to 6,656 bytes depending on which of the sixteen permutations is built — paid
- * twice for staging and buffer, so **7,168 to 13,312 bytes a slot** against 1,540 for a draw.
- * Raising it from 256 costs 5.25 to 9.75 MB.
- *
- * It is worth paying for how it *fails* rather than how it performs. Past the ring
- * `materialSlotForDraw` returns null and **every draw that needed a new material is skipped** —
- * a stretch of the world simply not drawn, which has been reported from a consumer as
- * ground that appears and disappears as the camera moves. A budget that hopes to stay under a
- * ceiling is a budget that ships this the first time somebody adds a model.
- *
- * **This comment said "silently reuses the last material" until 2026-09-02, and so did the
- * warning, and neither was ever true.** The skip has been there since `9d90bf7` wrote both
- * halves in one diff. It is recorded because the wrong failure was the stated argument for
- * raising this number from 256, and because "wrong texture" and "no geometry" send a consumer
- * looking in completely different places — one at materials, the other at culling, which is
- * where the reporting game spent its weeks. `frameBudget` reports the count now, so the next
- * consumer reads a number instead of a sentence.
- *
- * **What would make it wrong** is a scene switching material every draw: a thousand material
- * changes is a thousand uniform copies, and a consumer reaching this has a batching problem no
- * ring size answers — many copies of one mesh want one material and one instanced draw.
- */
-const MAX_MATERIALS_PER_FRAME = 1024;
-
 /**
  * Whether the environment probe's permutation fits this device's per-stage binding limits.
  *
@@ -1584,8 +1555,37 @@ export class WebGPURenderer implements RendererApi {
    * geometry come first.
    */
   private readonly budget = new FrameBudget();
-  private readonly drawBudget = this.budget.line('draws', MAX_DRAWS_PER_FRAME);
-  private readonly materialBudget = this.budget.line('materials', MAX_MATERIALS_PER_FRAME);
+  private readonly drawBudget = this.budget.line('draws', null);
+  /**
+   * Distinct materials a frame may set: `materialChangesPerFrame`, 1,024 unless a consumer asks.
+   *
+   * A slot is spent per *change*, not per draw, so this counts how many times a scene switches
+   * material rather than how much it draws.
+   *
+   * **A thousand and twenty-four by default, and it is the expensive one of the two.** A slot is the fragment
+   * block — 3,376 to 6,656 bytes depending on which of the sixteen permutations is built — paid
+   * twice for staging and buffer, so **7,168 to 13,312 bytes a slot** against 1,540 for a draw.
+   * Raising it from 256 costs 5.25 to 9.75 MB.
+   *
+   * It is worth paying for how it *fails* rather than how it performs. Past the ring
+   * `materialSlotForDraw` returns null and **every draw that needed a new material is skipped** —
+   * a stretch of the world simply not drawn, which has been reported from a consumer as
+   * ground that appears and disappears as the camera moves. A budget that hopes to stay under a
+   * ceiling is a budget that ships this the first time somebody adds a model.
+   *
+   * **This comment said "silently reuses the last material" until 2026-09-02, and so did the
+   * warning, and neither was ever true.** The skip has been there since `9d90bf7` wrote both
+   * halves in one diff. It is recorded because the wrong failure was the stated argument for
+   * raising this number from 256, and because "wrong texture" and "no geometry" send a consumer
+   * looking in completely different places — one at materials, the other at culling, which is
+   * where the reporting game spent its weeks. `frameBudget` reports the count now, so the next
+   * consumer reads a number instead of a sentence.
+   *
+   * **What would make it wrong** is a scene switching material every draw: a thousand material
+   * changes is a thousand uniform copies, and a consumer reaching this has a batching problem no
+   * ring size answers — many copies of one mesh want one material and one instanced draw.
+   */
+  private readonly materialBudget = this.budget.line('materials', null);
   /**
    * Native bind groups built this frame, which is the one cost a consumer could not see.
    *
@@ -1596,7 +1596,7 @@ export class WebGPURenderer implements RendererApi {
    * in draw order, precisely because the frame reported draws and material changes and never this.
    */
   private readonly bindGroupBudget = this.budget.line('bind groups', null);
-  private readonly shadowDrawBudget = this.budget.line('shadow draws', MAX_DRAWS_PER_FRAME);
+  private readonly shadowDrawBudget = this.budget.line('shadow draws', null);
   private readonly scatterDepthBudget = this.budget.line(
     'scatter shadow draws',
     MAX_SCATTER_DEPTH_DRAWS,
@@ -2624,7 +2624,7 @@ export class WebGPURenderer implements RendererApi {
   ): void {
     if (!this.canDraw()) return;
     const geometry = mesh as GpuMesh & { key?: string };
-    if (geometry.vertexBuffers === undefined) return;
+    if (geometry.vertexBuffers === undefined || geometry.indexCount === 0) return;
     const vertexSlot = this.filmVerts.allocate();
     const fragmentSlot = this.filmFrags.allocate();
     if (vertexSlot === null || fragmentSlot === null) return;
@@ -4329,8 +4329,9 @@ export class WebGPURenderer implements RendererApi {
     if (!this.canDraw()) return;
     /* Geometry that has not all arrived is not drawn, which is the surface's contract and what
        every other mesh verb here and the other backend's volume already kept. This one drew a
-       beam from a buffer still filling, and counted it, until 2026-09-19. See `Mesh.complete`. */
-    if (!mesh.complete) return;
+       beam from a buffer still filling, and counted it, until 2026-09-19. See `Mesh.complete`. A
+       hull with no triangles draws nothing either: see `GpuMesh.indexCount`. */
+    if (!mesh.complete || mesh.indexCount === 0) return;
     /* At zero it draws nothing rather than adding black, so a caller may keep the call in. That
        now covers a clear night too: a beam with no medium to light is not drawn at all. */
     const shown =
@@ -5478,7 +5479,7 @@ export class WebGPURenderer implements RendererApi {
         this.writeCutout(slot, cutout, DEPTH_CUTOUT_VERT_FIELDS);
 
       const geometry = mesh as GpuMesh & { key?: string };
-      if (geometry.vertexBuffers === undefined) return;
+      if (geometry.vertexBuffers === undefined || geometry.indexCount === 0) return;
       const cuts = cutoutGroup !== null;
       /* A two-sided caster casts from whichever face the light sees: nothing culled. */
       const cull = material?.doubleSided === true ? 'none' : this.depthCullMode;
@@ -5517,7 +5518,7 @@ export class WebGPURenderer implements RendererApi {
       if (pass === null) return;
       const gpuBatch = batch as GpuInstancedBatch;
       const geometry = gpuBatch.mesh as GpuMesh & { key?: string };
-      if (geometry.vertexBuffers === undefined) return;
+      if (geometry.vertexBuffers === undefined || geometry.indexCount === 0) return;
       const count = Math.min(data.count, gpuBatch.capacity);
       if (count === 0) return;
       const cutout = cutoutOf(material);
@@ -5591,7 +5592,7 @@ export class WebGPURenderer implements RendererApi {
       this.writeShadowWind(slot);
 
       const geometry = mesh as GpuMesh & { key?: string };
-      if (geometry.vertexBuffers === undefined) return;
+      if (geometry.vertexBuffers === undefined || geometry.indexCount === 0) return;
       pass.setPipeline(
         depthPipeline(
           this.pipelines,
@@ -5621,7 +5622,7 @@ export class WebGPURenderer implements RendererApi {
       const pass = this.shadowPass;
       if (pass === null || data.count === 0) return;
       const geometry = scatter as GpuScatter;
-      if (geometry.vertexBuffers === undefined) return;
+      if (geometry.vertexBuffers === undefined || geometry.indexCount === 0) return;
 
       const v = this.scatterDepthFloats;
       const at = (name: string): number => (SCATTER_DEPTH_FIELDS[name]?.offset ?? -4) / 4;
@@ -5908,6 +5909,9 @@ export class WebGPURenderer implements RendererApi {
         }
       : quality;
     quality = this.quality;
+    this.materialBudget.limit(quality.materialChangesPerFrame);
+    this.drawBudget.limit(quality.drawsPerFrame);
+    this.shadowDrawBudget.limit(quality.drawsPerFrame);
     this.maxDrawingBufferPixels = quality.maxDrawingBufferPixels;
     this.exposure = quality.outputExposure;
     this.flushSchedule =
@@ -6013,7 +6017,7 @@ export class WebGPURenderer implements RendererApi {
     this.perDraw = new UniformRing(
       device,
       FLAT_VERT_SIZE,
-      MAX_DRAWS_PER_FRAME,
+      quality.drawsPerFrame,
       USAGE_UNIFORM_DST,
       'flat.vertRing',
       this.drawBudget,
@@ -6037,7 +6041,7 @@ export class WebGPURenderer implements RendererApi {
     this.perFrame = new UniformRing(
       device,
       this.fragment.uniformSize,
-      MAX_MATERIALS_PER_FRAME,
+      this.quality.materialChangesPerFrame,
       USAGE_UNIFORM_DST,
       'flat.fragRing',
       this.materialBudget,
@@ -6772,7 +6776,7 @@ export class WebGPURenderer implements RendererApi {
       device,
       /* The cutout block is the plain one and two fields more, and a slot must hold either. */
       Math.max(DEPTH_VERT_SIZE, DEPTH_CUTOUT_VERT_SIZE),
-      MAX_DRAWS_PER_FRAME,
+      quality.drawsPerFrame,
       USAGE_UNIFORM_DST,
       'shadow.drawRing',
       this.shadowDrawBudget,
@@ -8207,7 +8211,7 @@ export class WebGPURenderer implements RendererApi {
       if (!this.warnedMaterialsFull) {
         this.warnedMaterialsFull = true;
         console.warn(
-          `WebGPU: more than ${MAX_MATERIALS_PER_FRAME} material changes in a frame; the draws asking for the rest are skipped. renderer.frameBudget names the line and the count.`,
+          `WebGPU: more than ${this.quality.materialChangesPerFrame} material changes in a frame; the draws asking for the rest are skipped. renderer.frameBudget names the line and the count.`,
         );
       }
       return null;
@@ -8422,15 +8426,16 @@ export class WebGPURenderer implements RendererApi {
     options: TranslucentMeshOptions = {},
   ): void {
     if (!this.canDraw() || this.viewProj === null) return;
-    /* Geometry that has not all arrived is not drawn. See `GpuMesh.complete`. */
-    if (!mesh.complete) return;
+    /* Geometry that has not all arrived is not drawn, nor a mesh with none. See `GpuMesh.complete`
+       and `GpuMesh.indexCount`. */
+    if (!mesh.complete || mesh.indexCount === 0) return;
 
     const slot = this.perDraw.allocate();
     if (slot === null) {
       if (!this.warnedFull) {
         this.warnedFull = true;
         console.warn(
-          `WebGPU: more than ${MAX_DRAWS_PER_FRAME} draws in a frame; the rest are skipped`,
+          `WebGPU: more than ${this.quality.drawsPerFrame} draws in a frame; the rest are skipped`,
         );
       }
       return;
@@ -8596,7 +8601,7 @@ export class WebGPURenderer implements RendererApi {
     /*
      * Guards the draw call only, not the restore below.
      *
-     * `materialSlotForDraw` returns null once `MAX_MATERIALS_PER_FRAME` is exhausted, and an
+     * `materialSlotForDraw` returns null once `materialChangesPerFrame` is exhausted, and an
      * early `return` here used to skip the restore too — which left `uOpacity`,
      * `uLightingEnabled` and `uFogEnabled` dirtied in `perFrameFloats`/`perFrameInts` for the
      * rest of the frame, since that scratch block is cumulative state shared by every draw
@@ -8868,7 +8873,8 @@ export class WebGPURenderer implements RendererApi {
   ): void {
     if (!this.canDraw() || this.viewProj === null) return;
     const mesh = batch.mesh;
-    if (!mesh.complete) return;
+    /* Nor a batch of a mesh with nothing in it: see `GpuMesh.indexCount`. */
+    if (!mesh.complete || mesh.indexCount === 0) return;
     const count = Math.min(data.count, batch.capacity);
     if (count === 0) return;
     /* A culling batch's camera draw: the whole batch against the view and the occluders on the CPU,
@@ -8885,7 +8891,7 @@ export class WebGPURenderer implements RendererApi {
       if (!this.warnedFull) {
         this.warnedFull = true;
         console.warn(
-          `WebGPU: more than ${MAX_DRAWS_PER_FRAME} draws in a frame; the rest are skipped`,
+          `WebGPU: more than ${this.quality.drawsPerFrame} draws in a frame; the rest are skipped`,
         );
       }
       return;
@@ -9269,7 +9275,7 @@ export class WebGPURenderer implements RendererApi {
    * *unchanged*, so a run of entries sharing one material has no shorter spelling and the sink
    * bound once per entry. On this backend that is a cliff rather than a slope: `setMaterial`
    * dirties `materialSlot`, so a bind per entry is a **slot per draw** out of
-   * `MAX_MATERIALS_PER_FRAME` — and past the ring `materialSlotForDraw` returns null and the draw
+   * `materialChangesPerFrame` — and past the ring `materialSlotForDraw` returns null and the draw
    * is skipped, which is the world that appears and disappears that constant's own comment
    * describes. A consumer measured 82 materials a model over two to four draws each, and a
    * reflection replaying the frame shares the ring with the pass that recorded it.
@@ -9522,7 +9528,7 @@ export class WebGPURenderer implements RendererApi {
       const tint = this.glassTint;
       if (pass === null || tint === null) return;
       const geometry = mesh as GpuMesh & { key?: string };
-      if (geometry.vertexBuffers === undefined) return;
+      if (geometry.vertexBuffers === undefined || geometry.indexCount === 0) return;
       const cutout = cutoutOf(material);
       const albedo = cutout === null ? null : (cutout.albedo as unknown as GpuSurfaceTexture);
       const slot = this.shadowDraws.allocate();
@@ -9565,7 +9571,7 @@ export class WebGPURenderer implements RendererApi {
       if (pass === null || tint === null) return;
       const gpuBatch = batch as GpuInstancedBatch;
       const geometry = gpuBatch.mesh as GpuMesh & { key?: string };
-      if (geometry.vertexBuffers === undefined) return;
+      if (geometry.vertexBuffers === undefined || geometry.indexCount === 0) return;
       const count = Math.min(data.count, gpuBatch.capacity);
       if (count === 0) return;
       const cutout = cutoutOf(material);
@@ -9609,7 +9615,7 @@ export class WebGPURenderer implements RendererApi {
       const tint = this.glassTint;
       if (pass === null || tint === null) return;
       const geometry = mesh as GpuMesh & { key?: string };
-      if (geometry.vertexBuffers === undefined) return;
+      if (geometry.vertexBuffers === undefined || geometry.indexCount === 0) return;
       const paletteSlot = this.skinPalettes.take(this.surface.device, palette);
       const view = paletteSlot === null ? null : this.skinPalettes.view(paletteSlot);
       if (view === null) return;

package/src/render/mesh.ts

@@ -99,7 +99,12 @@ export class Mesh {
   private readonly deformable: { positions: WebGLBuffer; normals: WebGLBuffer } | null = null;
   /** How many floats the position buffer holds, so an update of the wrong size is refused. */
   private readonly positionFloats: number;
-  /** Indices one draw of it issues; the batch-size rule reads it (`cullsInstances`). */
+  /**
+   * Indices one draw of it issues; the batch-size rule reads it (`cullsInstances`). **At zero the
+   * mesh has nothing to draw and no verb draws it**, as on WebGPU (`GpuMesh.indexCount`): a draw of
+   * nothing is silent here but is still a call and a counted draw, and the two backends count the
+   * same frame.
+   */
   readonly indexCount: number;
   /**
    * The constant values this mesh's *absent* attributes are shaded with, re-applied on