@driftengine/core 4.6.1 → 4.7.0

package/CHANGELOG.json

@@ -1,4 +1,30 @@
 [
+  {
+    "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",

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/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);
@@ -4782,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 =
@@ -4879,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);
@@ -4896,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
@@ -5488,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,
@@ -6639,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;
         }
@@ -6832,7 +6836,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;
         }
@@ -6975,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
@@ -7232,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;
         }
@@ -7576,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.

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.1",
+  "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.1",
-    "@driftengine/physics": "4.6.1",
+    "@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.1",
-    "@driftengine/network": "4.6.1",
-    "@driftengine/texture": "4.6.1"
+    "@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;

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/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,
@@ -5909,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 =
@@ -6014,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,
@@ -6038,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,
@@ -6773,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,
@@ -8208,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;
@@ -8432,7 +8435,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;
@@ -8598,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
@@ -8888,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;
@@ -9272,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.

package/src/render/renderQuality.ts

@@ -97,6 +97,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;
   /**
@@ -821,6 +852,10 @@ export interface RenderQuality {
 export type RenderQualityOptions = Partial<RenderQuality>;
 
 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;
@@ -864,6 +899,8 @@ export const DEFAULT_RENDER_QUALITY: Readonly<RenderQuality> = 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. */
@@ -1015,6 +1052,9 @@ export function resolveRenderQuality(options: RenderQualityOptions = {}): Readon
     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
@@ -1132,6 +1172,21 @@ export function resolveRenderQuality(options: RenderQualityOptions = {}): Readon
   // 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);