@driftengine/core 4.6.0 → 4.7.0

package/CHANGELOG.json

@@ -1,4 +1,41 @@
 [
+  {
+    "version": "4.7.0",
+    "date": "2026-10-01",
+    "entries": [
+      {
+        "kind": "added",
+        "short": "Blender files bake directly: .blend from 2.79 to 5.x, compressed or not, with meshes, normals, materials, lights, cameras, shape keys and animation, and through your Blender where needed.",
+        "text": "**A `.blend` file is read directly, with nothing installed.** `readModel` and `npm run bake` take Blender's own format from 2.79 to 5.x, plain, gzip or zstd, because the reader learns every struct from the file's `DNA1` catalogue rather than from a list of Blender releases. It reads meshes in all three layouts Blender has stored them in (the legacy structs, 3.5's named attributes and 5.0's attribute storage), their normals by Blender's own rule — sharp edges and faces, auto smooth, custom split normals — with UVs, colour attributes and shape keys; Principled materials wired the way the glTF importer wires them, with their packed pictures; point, spot and sun lights, blackbody colour included; cameras; parents, collection instances and render visibility; and keyed object animation, layered actions and NLA strips included. It builds the same glTF the rest of the pipeline reads, so a `.blend` and a `.glb` reach the baker as the same thing, and the fixtures in `scripts/fixtures/blend/` hold it to what Blender's own exporter writes for the same file. **What only Blender can evaluate is refused by name** — a rig, a constraint, a modifier past the smoothing ones — as `BlendNeedsBlender`, never as half a scene; the baker then drives the user's own Blender through its bundled glTF exporter, `--via-blender` asks for that outright and `--direct` refuses it, and every import says which route it took."
+      },
+      {
+        "kind": "added",
+        "short": "materialChangesPerFrame: a scene that changes material more than 1,024 times a frame on WebGPU can now ask for a larger ring instead of losing the draws past it.",
+        "text": "**How many material changes a WebGPU frame holds is a quality option, `materialChangesPerFrame`.** A frame spends a slot of a uniform ring each time it changes material and skips every draw past the last slot, which is geometry missing rather than geometry drawn wrong — and 1,024 was a constant. A bought city of eleven hundred materials spends about nine hundred on a street, and a planar mirror of that street spends as many again, so its reflection came and went as the camera turned. The default stays 1,024; a scene that measures past it asks for more at construction and pays seven to thirteen kilobytes a slot, and `frameBudget`'s materials line reports the ceiling it got. WebGL2 keeps no ring and reads the option without effect."
+      },
+      {
+        "kind": "fixed",
+        "short": "The PNG reader in core's scripts reads palettes, one- to four-bit greys, sixteen-bit images and tRNS transparency, so a bake no longer drops those pictures and draws their surfaces white.",
+        "text": "**`@driftengine/core/scripts/png.mjs` reads every non-interlaced PNG.** It refused palettes (colour type 3), greys below eight bits and sixteen-bit images, and the baker and the native host read model pictures through it: measured on one bought city, 219 of its 2,447 pictures, every material wearing one baked with no colour map and drew white. Rows are now un-filtered as packed bytes and then widened to eight-bit samples — a palette to RGB, or RGBA where it carries `tRNS`; a grey or RGB `tRNS` key to an alpha of nought at that value; sixteen bits to the high byte; a grey below eight bits scaled to the full byte. An eight-bit image with no key still takes the path that copies nothing, so a screenshot decodes as it did. Interlacing is still refused by name."
+      },
+      {
+        "kind": "fixed",
+        "short": "A glTF material with no metallic texture and no metallicFactor is a full metal, as the specification says, and now reflects like one instead of reading as matte.",
+        "text": "**An untextured glTF metal that states no `metallicFactor` mirrors.** The specification's default for the factor is 1, and the reader took the material's reflectivity from the factor alone with a default of 0, so every such material — an exporter writes none when the value is the default — drew as a matte surface. The reflectivity of a material with no base colour texture now follows its metallic value, defaulted as the specification defaults it; a textured or vertex-coloured one is unchanged."
+      }
+    ]
+  },
+ {
+  "version": "4.6.1",
+  "date": "2026-10-01",
+  "entries": [
+   {
+    "kind": "fixed",
+    "short": "A mesh with no triangles is skipped by every pass instead of drawn as nothing, so a game's console no longer fills with WebGPU warnings about empty draws.",
+    "text": "**A mesh with no triangles draws nothing, in every pass, on both backends.** A game's world can hold an empty mesh, for a level with none of that kind of geometry, and every pass it reached issued a draw of zero indices: WebGPU answers each with a warning, five on one game's first screen (the frame, its reflection, the sun's static and peeled maps and a lamp's shadow faces), and WebGL2 counted draws that drew nothing. `GpuMesh.indexCount` and `Mesh.indexCount` carry the rule, and every place a mesh enters a pass skips an empty one beside its other checks: meshes, translucent meshes, instanced batches, light volumes, shadow casters, glass depth and the motion pass. A game that already skipped its empty meshes itself can keep doing so."
+   }
+  ]
+ },
  {
   "version": "4.6.0",
   "date": "2026-10-01",

package/README.md

@@ -2,7 +2,7 @@
 
 The runtime everything needs: renderer, loop, camera, input, geometry. Collision and dynamics live in [`@driftengine/physics`](../physics/README.md), which this package depends on and re-exports whole, so reaching for them through this barrel works as it always did.
 
-**Cost: 698.9 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`, which fails if it drifts more than
+**Cost: 699.0 KB gzipped, importing `createRenderer`.** Measured by `scripts/size-gate.test.mjs`, which fails if it drifts more than
 3% — the number is a fact about the build rather than a claim in a document.
 
 Part of [DriftEngine](../../README.md). See [`docs/ARCHITECTURE.md`](../../docs/ARCHITECTURE.md)

package/dist/render/backend/budget.d.ts

@@ -47,6 +47,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;
 }
 /**
  * Every ceiling a backend imposes, counted for the frame just drawn.

package/dist/render/backend/budget.js

@@ -30,6 +30,9 @@ class Line {
         this.ceiling = ceiling;
         this.budget = budget;
     }
+    limit(ceiling) {
+        this.ceiling = ceiling;
+    }
     /** One more of this thing was asked for, whether or not it will fit. */
     ask() {
         this.used += 1;

package/dist/render/backend/webgl2/renderer.js

@@ -2844,7 +2844,8 @@ export class WebGL2Renderer {
         if (this.contextLost)
             return;
         const mesh = batch.mesh;
-        if (!mesh.complete)
+        /* 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)
@@ -6215,8 +6216,9 @@ export class WebGL2Renderer {
     _previousModel = null) {
         if (this.contextLost)
             return;
-        /* Geometry that has not all arrived is not drawn. See `Mesh.complete`. */
-        if (!mesh.complete)
+        /* 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.
@@ -6406,8 +6408,9 @@ export class WebGL2Renderer {
     drawTranslucentMesh(mesh, model, opacity, options = {}) {
         if (this.contextLost)
             return;
-        /* Geometry that has not all arrived is not drawn. See `Mesh.complete`. */
-        if (!mesh.complete)
+        /* 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;
@@ -6803,8 +6806,9 @@ export class WebGL2Renderer {
     drawLightVolume(mesh, model, camera, strength, length, spread, options = {}) {
         if (this.contextLost)
             return;
-        /* Geometry that has not all arrived is not drawn. See `Mesh.complete`. */
-        if (!mesh.complete)
+        /* 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/dist/render/backend/webgpu/buffers.d.ts

@@ -68,6 +68,13 @@ export interface GpuMesh {
         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/dist/render/backend/webgpu/motionPass.js

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

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

@@ -242,6 +242,35 @@ export declare class WebGPURenderer implements RendererApi {
      */
     private readonly budget;
     private readonly drawBudget;
+    /**
+     * 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;
     /**
      * Native bind groups built this frame, which is the one cost a consumer could not see.
@@ -2277,7 +2306,7 @@ export declare 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.

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

@@ -139,7 +139,9 @@ import { LightField } from '../../driftLight/lightField.js';
 import { WorldLightField } from '../../driftLight/worldLightField.js';
 import { createDriftLightUniforms, resolveDriftLight } from '../../driftLight/uniforms.js';
 /**
- * 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
@@ -194,36 +196,6 @@ const MAX_OVERLAYS = 64;
  * and passes nobody has written yet; the cost is sixteen kilobytes.
  */
 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.
  *
@@ -992,8 +964,37 @@ export class WebGPURenderer {
      * geometry come first.
      */
     budget = new FrameBudget();
-    drawBudget = this.budget.line('draws', MAX_DRAWS_PER_FRAME);
-    materialBudget = this.budget.line('materials', MAX_MATERIALS_PER_FRAME);
+    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.
+     */
+    materialBudget = this.budget.line('materials', null);
     /**
      * Native bind groups built this frame, which is the one cost a consumer could not see.
      *
@@ -1004,7 +1005,7 @@ export class WebGPURenderer {
      * in draw order, precisely because the frame reported draws and material changes and never this.
      */
     bindGroupBudget = this.budget.line('bind groups', null);
-    shadowDrawBudget = this.budget.line('shadow draws', MAX_DRAWS_PER_FRAME);
+    shadowDrawBudget = this.budget.line('shadow draws', null);
     scatterDepthBudget = this.budget.line('scatter shadow draws', MAX_SCATTER_DEPTH_DRAWS);
     waterBudget = this.budget.line('water bodies', MAX_WATER_BODIES_PER_FRAME);
     lightVolumeBudget = this.budget.line('light volumes', MAX_LIGHT_VOLUMES_PER_FRAME);
@@ -1982,7 +1983,7 @@ export class WebGPURenderer {
         if (!this.canDraw())
             return;
         const geometry = mesh;
-        if (geometry.vertexBuffers === undefined)
+        if (geometry.vertexBuffers === undefined || geometry.indexCount === 0)
             return;
         const vertexSlot = this.filmVerts.allocate();
         const fragmentSlot = this.filmFrags.allocate();
@@ -3465,8 +3466,9 @@ export class WebGPURenderer {
             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)
+           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. */
@@ -4426,7 +4428,7 @@ export class WebGPURenderer {
             if (cutout !== null && cutoutGroup !== null)
                 this.writeCutout(slot, cutout, DEPTH_CUTOUT_VERT_FIELDS);
             const geometry = mesh;
-            if (geometry.vertexBuffers === undefined)
+            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. */
@@ -4455,7 +4457,7 @@ export class WebGPURenderer {
                 return;
             const gpuBatch = batch;
             const geometry = gpuBatch.mesh;
-            if (geometry.vertexBuffers === undefined)
+            if (geometry.vertexBuffers === undefined || geometry.indexCount === 0)
                 return;
             const count = Math.min(data.count, gpuBatch.capacity);
             if (count === 0)
@@ -4510,7 +4512,7 @@ export class WebGPURenderer {
             this.shadowDraws.writeFloats(slot, DEPTH_VERT_FIELDS.uModel.offset, model);
             this.writeShadowWind(slot);
             const geometry = mesh;
-            if (geometry.vertexBuffers === undefined)
+            if (geometry.vertexBuffers === undefined || geometry.indexCount === 0)
                 return;
             pass.setPipeline(depthPipeline(this.pipelines, this.surface.device, this.shadowSkinnedLayout, `depth-skinned|${this.depthCullMode}|${geometry.key ?? ''}`, this.presentOf(geometry), this.depthCullMode, true));
             pass.setBindGroup(0, this.shadowSkinnedGroup(view, paletteSlot), [slot]);
@@ -4532,7 +4534,7 @@ export class WebGPURenderer {
             if (pass === null || data.count === 0)
                 return;
             const geometry = scatter;
-            if (geometry.vertexBuffers === undefined)
+            if (geometry.vertexBuffers === undefined || geometry.indexCount === 0)
                 return;
             const v = this.scatterDepthFloats;
             const at = (name) => (SCATTER_DEPTH_FIELDS[name]?.offset ?? -4) / 4;
@@ -4781,6 +4783,9 @@ export class WebGPURenderer {
             }
             : 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 =
@@ -4878,7 +4883,7 @@ export class WebGPURenderer {
         this.skinnedBindGroupLayout = createFlatBindGroupLayout(device, this.variant, true);
         this.morphedBindGroupLayout = createFlatBindGroupLayout(device, this.variant, false, true);
         this.bothBindGroupLayout = createFlatBindGroupLayout(device, this.variant, true, true);
-        this.perDraw = new UniformRing(device, FLAT_VERT_SIZE, MAX_DRAWS_PER_FRAME, USAGE_UNIFORM_DST, 'flat.vertRing', this.drawBudget);
+        this.perDraw = new UniformRing(device, FLAT_VERT_SIZE, quality.drawsPerFrame, USAGE_UNIFORM_DST, 'flat.vertRing', this.drawBudget);
         this.perFrameStaging = new ArrayBuffer(this.fragment.uniformSize);
         this.perFrameFloats = new Float32Array(this.perFrameStaging);
         this.perFrameInts = new Int32Array(this.perFrameStaging);
@@ -4895,7 +4900,7 @@ export class WebGPURenderer {
          * A slot per *material change* rather than per draw: `drawMesh` reuses the open slot until
          * something dirties it, so a scene drawing a hundred meshes of one material spends one.
          */
-        this.perFrame = new UniformRing(device, this.fragment.uniformSize, MAX_MATERIALS_PER_FRAME, USAGE_UNIFORM_DST, 'flat.fragRing', this.materialBudget);
+        this.perFrame = new UniformRing(device, this.fragment.uniformSize, this.quality.materialChangesPerFrame, USAGE_UNIFORM_DST, 'flat.fragRing', this.materialBudget);
         /*
          * A one-pixel stand-in for the albedo binding. `uAlbedoEnabled` is zero for untextured
          * geometry, which is nearly all of it, so the shader never samples this — but WebGPU
@@ -5487,7 +5492,7 @@ export class WebGPURenderer {
         this.shadowCutoutLayout = createDepthBindGroupLayout(device, false, true);
         this.shadowDraws = new UniformRing(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, USAGE_UNIFORM_DST, 'shadow.drawRing', this.shadowDrawBudget);
+        Math.max(DEPTH_VERT_SIZE, DEPTH_CUTOUT_VERT_SIZE), quality.drawsPerFrame, USAGE_UNIFORM_DST, 'shadow.drawRing', this.shadowDrawBudget);
         const depthPassUniforms = device.createBuffer({
             label: 'depth.passUniforms',
             size: DEPTH_FRAG_SIZE,
@@ -6638,7 +6643,7 @@ export class WebGPURenderer {
         if (slot === null) {
             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.`);
+                console.warn(`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;
         }
@@ -6823,14 +6828,15 @@ export class WebGPURenderer {
     submitMesh(mesh, model, tint, opacity, blend, options = {}) {
         if (!this.canDraw() || this.viewProj === null)
             return;
-        /* Geometry that has not all arrived is not drawn. See `GpuMesh.complete`. */
-        if (!mesh.complete)
+        /* 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`);
+                console.warn(`WebGPU: more than ${this.quality.drawsPerFrame} draws in a frame; the rest are skipped`);
             }
             return;
         }
@@ -6973,7 +6979,7 @@ export class WebGPURenderer {
         /*
          * 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
@@ -7212,7 +7218,8 @@ export class WebGPURenderer {
         if (!this.canDraw() || this.viewProj === null)
             return;
         const mesh = batch.mesh;
-        if (!mesh.complete)
+        /* 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)
@@ -7229,7 +7236,7 @@ export class WebGPURenderer {
         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`);
+                console.warn(`WebGPU: more than ${this.quality.drawsPerFrame} draws in a frame; the rest are skipped`);
             }
             return;
         }
@@ -7573,7 +7580,7 @@ export class WebGPURenderer {
      * *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.
@@ -7803,7 +7810,7 @@ export class WebGPURenderer {
             if (pass === null || tint === null)
                 return;
             const geometry = mesh;
-            if (geometry.vertexBuffers === undefined)
+            if (geometry.vertexBuffers === undefined || geometry.indexCount === 0)
                 return;
             const cutout = cutoutOf(material);
             const albedo = cutout === null ? null : cutout.albedo;
@@ -7834,7 +7841,7 @@ export class WebGPURenderer {
                 return;
             const gpuBatch = batch;
             const geometry = gpuBatch.mesh;
-            if (geometry.vertexBuffers === undefined)
+            if (geometry.vertexBuffers === undefined || geometry.indexCount === 0)
                 return;
             const count = Math.min(data.count, gpuBatch.capacity);
             if (count === 0)
@@ -7867,7 +7874,7 @@ export class WebGPURenderer {
             if (pass === null || tint === null)
                 return;
             const geometry = mesh;
-            if (geometry.vertexBuffers === undefined)
+            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);

package/dist/render/mesh.d.ts

@@ -19,7 +19,12 @@ export declare class Mesh {
     private readonly deformable;
     /** How many floats the position buffer holds, so an update of the wrong size is refused. */
     private readonly positionFloats;
-    /** 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

package/dist/render/mesh.js

@@ -88,7 +88,12 @@ export class Mesh {
     deformable = null;
     /** How many floats the position buffer holds, so an update of the wrong size is refused. */
     positionFloats;
-    /** 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.
+     */
     indexCount;
     /**
      * The constant values this mesh's *absent* attributes are shaded with, re-applied on

package/dist/render/renderQuality.d.ts

@@ -88,6 +88,37 @@ export interface RenderQuality {
      * halved frame rate rather than a slightly slower one.
      */
     readonly maxDrawingBufferPixels: number;
+    /**
+     * How many times a frame may change material, on a backend that keeps a slot for each.
+     *
+     * **WebGPU spends a slot of a uniform ring per material change and skips every draw past it**,
+     * because a buffer rewritten between two draws would hand both of them its last contents. So
+     * this is a ceiling on what a frame can show, not a performance hint: a scene that needs more
+     * loses whatever it asks for last — measured on a bought city of 1,139 materials, whose street
+     * spends some nine hundred and whose river's planar mirror spends the rest twice over.
+     *
+     * **What it costs is memory, paid at construction**: a slot is the fragment block twice over,
+     * staging and buffer, so 7 to 13 KB depending on the permutation built — 1,024 is 7 to 13 MB
+     * and 2,048 twice that. Hence a default that suits most scenes and an option for the one that
+     * measures past it, rather than a number every consumer pays for. WebGL2 writes each uniform
+     * into the command stream and keeps no ring, so there it is read and does nothing, and its
+     * budget line reports no ceiling. What would make it wrong is a scene that switches material
+     * every draw, which no ring answers: many copies of one mesh want one instanced draw.
+     */
+    readonly materialChangesPerFrame: number;
+    /**
+     * How many draws a frame may make, on a backend that keeps a uniform slot for each — the main
+     * pass and the shadow passes each hold this many.
+     *
+     * **The same shape as `materialChangesPerFrame` and the same failure**: WebGPU skips every draw
+     * past the ring. A frame that draws two hundred pays for two hundred whatever this says, so
+     * raising it costs no bandwidth; it costs memory at construction, 1,540 bytes a slot — 6 MB at
+     * the default 4,096. A city whose street spends three and a half thousand and whose river
+     * mirrors that street spends more than the default, and a scene in the ordinary band of two to
+     * ten thousand draws can meet it. WebGL2 keeps no ring and reads this without effect. What would
+     * make it wrong is a frame that approaches it on the CPU first, which four thousand draws can.
+     */
+    readonly drawsPerFrame: number;
     readonly directionalShadows: boolean;
     readonly pointShadows: boolean;
     /**
@@ -810,6 +841,10 @@ export interface RenderQuality {
 /** Callers override only the levers selected by a future settings profile. */
 export type RenderQualityOptions = Partial<RenderQuality>;
 export declare const MAX_SHADOW_FILTER_TAPS = 12;
+/** The most material changes a frame may be built to hold. See `materialChangesPerFrame`. */
+export declare const MAX_MATERIAL_CHANGES_PER_FRAME = 8192;
+/** The most draws a frame may be built to hold. See `drawsPerFrame`. */
+export declare const MAX_DRAWS_PER_FRAME = 65536;
 export declare const MAX_WATER_REFLECTION_FILTER_TAPS = 9;
 export declare const POINT_SHADOW_FADE_START = 0.35;
 export declare const DIRECTIONAL_SHADOW_FADE_START = 0.65;

package/dist/render/renderQuality.js

@@ -4,6 +4,10 @@ import { MAX_GLOBAL_MEDIUM_STEPS } from './globalMedium.js';
 import { MAX_POINT_LIGHTS } from './lightBudget.js';
 import { PREFILTER_SAMPLE_COUNTS } from './prefilterEnvMap.js';
 export const MAX_SHADOW_FILTER_TAPS = 12;
+/** The most material changes a frame may be built to hold. See `materialChangesPerFrame`. */
+export const MAX_MATERIAL_CHANGES_PER_FRAME = 8192;
+/** The most draws a frame may be built to hold. See `drawsPerFrame`. */
+export const MAX_DRAWS_PER_FRAME = 65536;
 export const MAX_WATER_REFLECTION_FILTER_TAPS = 9;
 export const POINT_SHADOW_FADE_START = 0.35;
 export const DIRECTIONAL_SHADOW_FADE_START = 0.65;
@@ -46,6 +50,8 @@ export const DEFAULT_RENDER_QUALITY = Object.freeze({
      * if it is above where people actually are. Consumers wanting the pixels set it to 0.
      */
     maxDrawingBufferPixels: 12_000_000,
+    materialChangesPerFrame: 1024,
+    drawsPerFrame: 4096,
     directionalShadows: true,
     pointShadows: true,
     /* The engine's own budgets, which the renderer lowers per device when it has to. */
@@ -194,6 +200,8 @@ export function resolveRenderQuality(options = {}) {
         pointLightFalloff: options.pointLightFalloff ?? DEFAULT_RENDER_QUALITY.pointLightFalloff,
         maxDevicePixelRatio: options.maxDevicePixelRatio ?? DEFAULT_RENDER_QUALITY.maxDevicePixelRatio,
         maxDrawingBufferPixels: options.maxDrawingBufferPixels ?? DEFAULT_RENDER_QUALITY.maxDrawingBufferPixels,
+        materialChangesPerFrame: options.materialChangesPerFrame ?? DEFAULT_RENDER_QUALITY.materialChangesPerFrame,
+        drawsPerFrame: options.drawsPerFrame ?? DEFAULT_RENDER_QUALITY.drawsPerFrame,
         directionalShadows: options.directionalShadows ?? DEFAULT_RENDER_QUALITY.directionalShadows,
         pointShadows: options.pointShadows ?? DEFAULT_RENDER_QUALITY.pointShadows,
         /* Whole slots, at least one, never above what the shader is written for: these two are
@@ -260,6 +268,17 @@ export function resolveRenderQuality(options = {}) {
     // Zero is legal and means uncapped, so this is the non-negative check rather than
     // the positive one.
     nonNegative('maxDrawingBufferPixels', quality.maxDrawingBufferPixels);
+    positiveInteger('materialChangesPerFrame', quality.materialChangesPerFrame);
+    if (quality.materialChangesPerFrame > MAX_MATERIAL_CHANGES_PER_FRAME) {
+        throw new Error(`materialChangesPerFrame is ${quality.materialChangesPerFrame}, and at most ` +
+            `${MAX_MATERIAL_CHANGES_PER_FRAME} are kept: past that the ring is a hundred megabytes, ` +
+            'and a frame changing material that often wants its draws batched instead.');
+    }
+    positiveInteger('drawsPerFrame', quality.drawsPerFrame);
+    if (quality.drawsPerFrame > MAX_DRAWS_PER_FRAME) {
+        throw new Error(`drawsPerFrame is ${quality.drawsPerFrame}, and at most ${MAX_DRAWS_PER_FRAME} are kept: ` +
+            'past that the rings are a hundred megabytes, and a frame drawing that often wants instancing.');
+    }
     positiveInteger('directionalShadowMapSize', quality.directionalShadowMapSize);
     positiveInteger('pointShadowFaceSize', quality.pointShadowFaceSize);
     positiveInteger('shadowFilterTaps', quality.shadowFilterTaps);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/core",
-  "version": "4.6.0",
+  "version": "4.7.0",
   "description": "DriftEngine reusable browser 3D runtime",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,8 +29,8 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@driftengine/drft": "4.6.0",
-    "@driftengine/physics": "4.6.0",
+    "@driftengine/drft": "4.7.0",
+    "@driftengine/physics": "4.7.0",
     "gl-matrix": "^3.4.3"
   },
   "author": "Drift Technologies",
@@ -63,8 +63,8 @@
     "prepack": "node ../../scripts/build.mjs @driftengine/core"
   },
   "devDependencies": {
-    "@driftengine/nav": "4.6.0",
-    "@driftengine/network": "4.6.0",
-    "@driftengine/texture": "4.6.0"
+    "@driftengine/nav": "4.7.0",
+    "@driftengine/network": "4.7.0",
+    "@driftengine/texture": "4.7.0"
   }
 }

package/scripts/png.d.mts

@@ -1,4 +1,4 @@
-/** What a decoded PNG is: row-major 8-bit samples, three or four to a pixel. */
+/** What a decoded PNG is: row-major 8-bit samples, one to four to a pixel. */
 export interface DecodedPng {
   readonly width: number;
   readonly height: number;