@driftengine/core 4.8.1 → 4.8.2

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

@@ -337,6 +337,8 @@ import {
 import type { GlobalMediumOptions } from '../../globalMedium.ts';
 import type { MeshData } from '../../mesh.ts';
 import { castsDepth, glassOf } from '../../shadowCasters.ts';
+import { materialHasMaps, noteMapsWithoutUvs } from '../../mapsWithoutUvs.ts';
+import { VIEW_MODEL_DEPTH_SHARE, viewModelDepthRange } from '../../viewModel.ts';
 import { GlassCasterList, type GlassReplaySink } from '../../glassCasters.ts';
 import { GpuGlassTint } from './glassTintPass.ts';
 import {
@@ -379,7 +381,7 @@ import {
   createDepthBindGroupLayout,
   depthPipeline,
 } from './depthPass.ts';
-import { PipelineCache } from './pipelineCache.ts';
+import { PipelineCache, type LitSwitch } from './pipelineCache.ts';
 import {
   SKY_FIELDS,
   SKY_UNIFORM_SIZE,
@@ -2805,6 +2807,8 @@ export class WebGPURenderer implements RendererApi {
   private readonly uvScale = new Float32Array([1, 1]);
   /** Whether the bound material is seen from both faces. See `SurfaceMaterial.doubleSided`. */
   private materialDoubleSided = false;
+  /** Whether the bound material has a map, for the warning a mesh with no coordinates earns. */
+  private materialHasMaps = false;
 
   createSurfaceTexture(
     source: TexImageSource,
@@ -2937,6 +2941,7 @@ export class WebGPURenderer implements RendererApi {
     this.uvScale[0] = material?.uScale ?? 1;
     this.uvScale[1] = material?.vScale ?? 1;
     this.materialDoubleSided = material?.doubleSided === true;
+    this.materialHasMaps = materialHasMaps(material);
     const normal = (material?.normal ?? null) as GpuSurfaceTexture | null;
     const orm = (material?.orm ?? null) as GpuSurfaceTexture | null;
     const emissiveMap = (material?.emissive ?? null) as GpuSurfaceTexture | null;
@@ -5450,6 +5455,27 @@ export class WebGPURenderer implements RendererApi {
    */
   /** The glass the open shadow pass was offered, kept for its own passes: `glassCasters.ts`. */
   private readonly glassCasters = new GlassCasterList();
+  /** Whether a glass caster has ever been offered, which is when lit pipelines start reading it. */
+  private glassSeen = false;
+
+  /**
+   * The first glass caster switches every lit pipeline to reading glass. See
+   * `PipelineCache.litSwitches`: until a pane exists the lookups would find nothing, and they cost
+   * the lit pass on every surface whether they find anything or not.
+   */
+  private noteGlassCaster(): void {
+    if (this.glassSeen) return;
+    this.glassSeen = true;
+    this.enableLit('GLASS_SHADOWS');
+  }
+
+  /** One of the lit stage's switches on, in every cache a lit pipeline can come from. */
+  private enableLit(feature: LitSwitch): void {
+    if (this.pipelines.litSwitches[feature]) return;
+    void this.pipelines.enable(feature);
+    if (this.overlayPipelines !== this.pipelines) void this.overlayPipelines.enable(feature);
+    if (this.latePipelines !== this.pipelines) void this.latePipelines.enable(feature);
+  }
   /** One resolution every glass caster is read through, so recording one allocates nothing. */
   private readonly glassCasterScratch: ResolvedGlass = {
     transmission: 0,
@@ -5462,6 +5488,7 @@ export class WebGPURenderer implements RendererApi {
         /* Glass: kept aside for its own two passes rather than dropped. See `glassCasters.ts`. */
         if (this.quality.glassShadows !== 'off' && glassOf(material, this.glassCasterScratch)) {
           this.glassCasters.recordMesh(mesh, model, material, this.glassCasterScratch);
+          this.noteGlassCaster();
         }
         return;
       }
@@ -5517,6 +5544,7 @@ export class WebGPURenderer implements RendererApi {
       if (!this.drawingGlassDepth && !castsDepth(material)) {
         if (this.quality.glassShadows !== 'off' && glassOf(material, this.glassCasterScratch)) {
           this.glassCasters.recordInstanced(batch, data, material, this.glassCasterScratch);
+          this.noteGlassCaster();
         }
         return;
       }
@@ -5572,6 +5600,7 @@ export class WebGPURenderer implements RendererApi {
       if (!this.drawingGlassDepth && !castsDepth(material)) {
         if (this.quality.glassShadows !== 'off' && glassOf(material, this.glassCasterScratch)) {
           this.glassCasters.recordSkinned(mesh, model, palette, material, this.glassCasterScratch);
+          this.noteGlassCaster();
         }
         return;
       }
@@ -5968,6 +5997,7 @@ export class WebGPURenderer implements RendererApi {
       quality.screenEffects ? sceneColorFormat(quality.hdrScene) : surface.format,
       this.samples,
       glassShadows,
+      quality.clusteredLights,
     );
     /*
      * The canvas' own state, for the pass `ensurePass` reopens after `endFrame`.
@@ -5980,11 +6010,11 @@ export class WebGPURenderer implements RendererApi {
     this.overlayPipelines =
       this.pipelines.format === surface.format && this.samples === 1
         ? this.pipelines
-        : new PipelineCache(device, surface.format, 1, glassShadows);
+        : new PipelineCache(device, surface.format, 1, glassShadows, quality.clusteredLights);
     this.latePipelines =
       this.pipelines.format === RECON_HISTORY_FORMAT && this.samples === 1
         ? this.pipelines
-        : new PipelineCache(device, RECON_HISTORY_FORMAT, 1, glassShadows);
+        : new PipelineCache(device, RECON_HISTORY_FORMAT, 1, glassShadows, quality.clusteredLights);
     this.issueBound = this.issueCommand.bind(this);
     this.pipelineTargets =
       this.overlayPipelines === this.pipelines
@@ -6288,7 +6318,10 @@ export class WebGPURenderer implements RendererApi {
       /* The albedo's effects table, or a one-texel stand-in the shader's size test reads as none.
          The albedo is the group's key, so its table needs no key of its own. */
       if (name === 'uSurfaceEffects') {
-        return { view: this.albedo?.effectsView ?? blankView, sampler: blankSampler };
+        const effects = this.albedo?.effectsView ?? null;
+        /* The first table bound is when the lit pipelines start reading one. See `litSwitches`. */
+        if (effects !== null) this.enableLit('SURFACE_EFFECTS');
+        return { view: effects ?? blankView, sampler: blankSampler };
       }
       /*
        * The room, once a bake has filled it. Unbaked reads as the blank cube: nothing to mirror.
@@ -7752,6 +7785,7 @@ export class WebGPURenderer implements RendererApi {
     i[at('uLightingEnabled')] = 1;
     i[at('uFogEnabled')] = 1;
     i[at('uAlbedoEnabled')] = 0;
+    this.materialHasMaps = false;
 
     /*
      * **The camera medium, which this pass did not upload until 2026-08-29.**
@@ -8284,6 +8318,7 @@ export class WebGPURenderer implements RendererApi {
      * where it happened to pass, write motion for a surface no pixel of the frame belongs to.
      */
     if (this.tracksMotionNow()) this.recordDrawMotion(mesh, model, previousModel);
+    noteMapsWithoutUvs(mesh, mesh.hasUvs, this.materialHasMaps);
     this.submitMesh(mesh, model, tint, 1, false, { depthLayer });
   }
 
@@ -8389,6 +8424,7 @@ export class WebGPURenderer implements RendererApi {
       return;
     }
 
+    noteMapsWithoutUvs(mesh, mesh.hasUvs, this.materialHasMaps);
     /* The tint travels in the options here, where `drawMesh` takes it positionally — see
        `TranslucentMeshOptions.tint` for why, and for the fade it was added for. */
     this.submitMesh(
@@ -12598,6 +12634,7 @@ export class WebGPURenderer implements RendererApi {
     command.instances = 1;
     command.indirect = null;
     recordNode(this.arena, VERB_DRAW, reads, writes, at, 0);
+    if (this.framePresented) this.queueOverlayFlush();
     return command;
   }
 
@@ -12613,11 +12650,7 @@ export class WebGPURenderer implements RendererApi {
     if (verb === VERB_PASS) {
       const definition = passAt(this.passes, nodeState(this.arena, at));
       if (definition === undefined) return;
-      this.passContext.pass = pass;
-      /* The frame's grade, so a contributed pass can obey the 2026-08-17 rule. See `PassContext`. */
-      this.passContext.outputTransform = this.gradeCode();
-      this.passContext.outputExposure = this.gradeExposure();
-      definition.draw(this.passContext as PassContext);
+      definition.draw(this.fillPassContext(pass));
       return;
     }
     if (verb !== VERB_DRAW) return;
@@ -12704,6 +12737,16 @@ export class WebGPURenderer implements RendererApi {
   }
 
   private openPass(): GPURenderPassEncoder | null {
+    const was = this.pass;
+    const pass = this.openAnyPass();
+    /* A pass opened while a view model is drawn starts with the whole depth range: squeeze it. */
+    if (this.viewModelActive && pass !== null && pass !== was && !this.reflectionPassActive) {
+      this.squeezeViewport(pass);
+    }
+    return pass;
+  }
+
+  private openAnyPass(): GPURenderPassEncoder | null {
     /* While the replay is running this is the only pass there is. See `oitEncoder`. */
     if (this.oitEncoder !== null) return this.oitEncoder;
     /*
@@ -12797,19 +12840,31 @@ export class WebGPURenderer implements RendererApi {
     });
     this.overlayActive = true;
 
-    /*
-     * **Submitted on a microtask, which runs before the browser presents.** There is no second
-     * `endFrame` to hang this on — a consumer thinks the frame is over — and presentation happens
-     * when the task ends, after the microtask checkpoint. Anything that needs the pixels sooner
-     * flushes synchronously; `copyRegionTo` is the one that does.
-     */
-    if (!this.overlayFlushQueued) {
-      this.overlayFlushQueued = true;
-      queueMicrotask(() => this.flushOverlay());
-    }
+    this.queueOverlayFlush();
     return this.pass;
   }
 
+  /**
+   * Submit what is drawn after the present on a microtask, which runs before the browser presents.
+   *
+   * There is no second `endFrame` to hang this on — a consumer thinks the frame is over — and
+   * presentation happens when the task ends, after the microtask checkpoint. Anything that needs
+   * the pixels sooner flushes synchronously; `copyRegionTo` is the one that does.
+   *
+   * **Queued wherever such work begins: where the overlay pass opens, and where a verb records.**
+   * With the graph on a verb records rather than opening a pass, and until 4.8.2 only an opening
+   * queued this, so `fillPanel` and a contributed pass drawn after `endFrame` waited for the next
+   * `beginFrame` — whose replay drew onto a canvas texture already presented and destroyed.
+   */
+  private queueOverlayFlush(): void {
+    if (this.overlayFlushQueued) return;
+    this.overlayFlushQueued = true;
+    queueMicrotask(this.flushOverlayBound);
+  }
+
+  /** `flushOverlay` bound once, so queueing it each frame allocates nothing. */
+  private readonly flushOverlayBound = (): void => this.flushOverlay();
+
   /**
    * The cache whose pipelines match the pass this draw will land in.
    *
@@ -12873,6 +12928,8 @@ export class WebGPURenderer implements RendererApi {
   }
 
   endFrame(): void {
+    /* A view model left open would squeeze every pass after the world, the composite included. */
+    if (this.viewModelActive) this.endViewModel();
     this.inFrame = false;
     if (this.surface.lost || this.encoder === null) return;
     /*
@@ -13341,14 +13398,40 @@ export class WebGPURenderer implements RendererApi {
     outputTransform: number;
     outputExposure: number;
     jitter: Float32Array;
+    format: GPUTextureFormat;
+    depthFormat: GPUTextureFormat;
+    samples: number;
   } = {
     backend: 'webgpu',
     pass: null,
     outputTransform: 0,
     outputExposure: 1,
     jitter: this.passJitter,
+    format: 'rgba8unorm',
+    depthFormat: DEPTH_FORMAT,
+    samples: 1,
   };
 
+  /**
+   * Fill the context a contributed pass draws with, for the pass it is about to draw into.
+   *
+   * **The attachments as well as the encoder**: a pass drawn after `endFrame` lands on the canvas
+   * at one sample where the frame's own is the scene target at the scene's samples, and a pipeline
+   * built for the one is refused by the other. The cache a mesh drawn here would use is the answer,
+   * so the two cannot disagree.
+   */
+  private fillPassContext(pass: GPURenderPassEncoder): PassContext {
+    const target = this.targetPipelines();
+    const context = this.passContext;
+    context.pass = pass;
+    /* The frame's grade, so a contributed pass can obey the 2026-08-17 rule. See `PassContext`. */
+    context.outputTransform = this.gradeCode();
+    context.outputExposure = this.gradeExposure();
+    context.format = target.format;
+    context.samples = target.sampleCount;
+    return context as PassContext;
+  }
+
   /**
    * Let something outside this file draw into the frame. See `Renderer.registerPass`.
    *
@@ -13502,11 +13585,7 @@ export class WebGPURenderer implements RendererApi {
     if (!this.quality.frameGraph) {
       const pass = this.openPass();
       if (pass === null) return;
-      this.passContext.pass = pass;
-      /* The frame's grade, so a contributed pass can obey the 2026-08-17 rule. See `PassContext`. */
-      this.passContext.outputTransform = this.gradeCode();
-      this.passContext.outputExposure = this.gradeExposure();
-      definition.draw(this.passContext as PassContext);
+      definition.draw(this.fillPassContext(pass));
       return;
     }
     recordNode(
@@ -13517,6 +13596,7 @@ export class WebGPURenderer implements RendererApi {
       handle,
       0,
     );
+    if (this.framePresented) this.queueOverlayFlush();
   }
 
   /** Let go of a pass. A handle kept past this draws nothing; see `PassHandle`. */
@@ -13728,7 +13808,10 @@ export class WebGPURenderer implements RendererApi {
    * **The clear is a drawn quad rather than a clear**, because WebGPU clears whole attachments
    * and cannot confine one to a scissor. See `insetPass.ts`.
    *
-   * Returns the drawing-buffer height of the inset, as the other backend does.
+   * Returns the **aspect** of the inset, width over height in the pixels its viewport got, as the
+   * other backend does — for `camera.updateMatrices`. With no pass to draw into, a lost device,
+   * it is the aspect of the box asked for: there are no pixels to measure, and a zero would be a
+   * projection of infinities in the caller's camera.
    */
   beginInset(rect: InsetRect, clearColor: Vec3 | null): number {
     /*
@@ -13738,7 +13821,8 @@ export class WebGPURenderer implements RendererApi {
      */
     if (this.quality.frameGraph) this.flushGraph();
     const pass = this.openPass();
-    if (this.surface.lost || pass === null) return 0;
+    if (this.surface.lost || pass === null)
+      return Math.max(rect.width, 1) / Math.max(rect.height, 1);
     const canvas = this.surface.context.canvas as HTMLCanvasElement;
     const cssWidth = Math.max(canvas.clientWidth, 1);
     const cssHeight = Math.max(canvas.clientHeight, 1);
@@ -13843,6 +13927,43 @@ export class WebGPURenderer implements RendererApi {
     return w / h;
   }
 
+  /**
+   * Draw what follows as a **view model**, in the nearest sliver of depth, until `endViewModel`.
+   *
+   * The twin of the WebGL2 method, which carries the reasons. Here the squeeze is the viewport's
+   * depth bounds, which are pass state applied when a draw is issued, so both ends flush the graph
+   * as an inset's do, and a pass opened in between is given the bounds again in `openPass`.
+   */
+  beginViewModel(share = VIEW_MODEL_DEPTH_SHARE): void {
+    if (this.quality.frameGraph) this.flushGraph();
+    viewModelDepthRange(this.reversedDepth, share, this.viewModelRange);
+    this.viewModelActive = true;
+    const pass = this.openPass();
+    if (this.surface.lost || pass === null) return;
+    this.squeezeViewport(pass);
+  }
+
+  /** Give the whole depth range back. Safe to call without a matching `beginViewModel`. */
+  endViewModel(): void {
+    if (!this.viewModelActive) return;
+    if (this.quality.frameGraph) this.flushGraph();
+    this.viewModelActive = false;
+    const pass = this.pass;
+    if (this.surface.lost || pass === null) return;
+    const [width, height] = this.passSize();
+    pass.setViewport(0, 0, width, height, 0, 1);
+  }
+
+  /** The view model's depth bounds on the whole of the pass. */
+  private squeezeViewport(pass: GPURenderPassEncoder): void {
+    const [width, height] = this.passSize();
+    pass.setViewport(0, 0, width, height, this.viewModelRange[0], this.viewModelRange[1]);
+  }
+
+  /** Whether a view model is being drawn: `openPass` re-applies it, `endFrame` closes it. */
+  private viewModelActive = false;
+  private readonly viewModelRange: [number, number] = [0, 1];
+
   /** Give the whole canvas back. Safe to call without a matching `beginInset`. */
   endInset(): void {
     /*
@@ -15030,6 +15151,8 @@ export class WebGPURenderer implements RendererApi {
     this.iesRows = this.iesAtlas.height;
     this.iesPlanes = this.iesAtlas.planes;
     this.cookieTiles = this.cookieImages.length;
+    /* The first profile or cookie is when the lit pipelines start reading them. See `litSwitches`. */
+    if (this.iesRows > 1 || this.cookieTiles > 0) this.enableLit('LIGHT_FIXTURES');
     return this.fixtureView;
   }
 
@@ -15125,6 +15248,8 @@ export class WebGPURenderer implements RendererApi {
     );
     this.driftIndex = index;
     this.driftAtlas = atlas;
+    /* The first volume is when the lit pipelines start reading one. See `litSwitches`. */
+    this.enableLit('DRIFT_LIGHT');
     this.driftIndexView = index.createView({ dimension: '3d' });
     this.driftAtlasView = atlas.createView({ dimension: '3d' });
     this.bakeLightField = {

package/src/render/mapsWithoutUvs.ts

@@ -0,0 +1,43 @@
+/**
+ * Saying, once a mesh, that a material's maps cannot be read on it.
+ *
+ * **A mesh with no texture coordinates reads one constant coordinate**, so every map bound to it
+ * samples a single texel: an emissive map makes nothing glow, a normal map tilts nothing, and the
+ * frame is identical pixel for pixel with and without the material's images. Found when an example's
+ * burning logs never glowed — `MeshBuilder` writes no coordinates unless `build({ planarUvs: true })`
+ * asks — and nothing said why. One decision for both backends, each calling it from its draw.
+ *
+ * Once per mesh, held weakly: a mesh drawn every frame is said once, and a disposed one is
+ * forgotten. **What it gives up** is a material shared between a textured mesh and an untextured one
+ * on purpose, which is said once for the untextured one and is then quiet.
+ */
+import type { SurfaceMaterial } from './surfaceTexture.ts';
+
+const told = new WeakSet<object>();
+
+/**
+ * Whether a material binds a map that is a picture: albedo, normal or emissive.
+ *
+ * **Not ORM**, because a one-colour ORM map is how a draw sets a constant roughness and metalness,
+ * and read at one texel it is exactly that constant — the materials example draws its spheres so.
+ * The three counted here are pictures nobody binds to be read at one point.
+ */
+export function materialHasMaps(material: SurfaceMaterial<unknown> | null): boolean {
+  if (material === null) return false;
+  return (
+    (material.albedo ?? null) !== null ||
+    (material.normal ?? null) !== null ||
+    (material.emissive ?? null) !== null
+  );
+}
+
+/** Warn the first time `mesh`, which has no coordinates, is drawn with a picture map bound. */
+export function noteMapsWithoutUvs(mesh: object, hasUvs: boolean, materialHasMaps: boolean): void {
+  if (hasUvs || !materialHasMaps || told.has(mesh)) return;
+  told.add(mesh);
+  console.warn(
+    '[driftengine] a mesh with no texture coordinates is drawn with an albedo, normal or emissive ' +
+      'map, which it cannot read: every map samples one texel. Give the mesh `uvs` — ' +
+      '`MeshBuilder.build({ planarUvs: true })` writes them — or draw it without the maps.',
+  );
+}

package/src/render/mesh.ts

@@ -136,6 +136,8 @@ export class Mesh {
   readonly bounds: Bounds = createBounds();
   /** Whether this mesh carries a rig, which decides which flat program draws it. */
   readonly isSkinned: boolean;
+  /** Whether it has texture coordinates, without which a material's maps read one texel. */
+  readonly hasUvs: boolean;
 
   /**
    * This mesh's morph deltas, or null for geometry that does not deform.
@@ -190,6 +192,7 @@ export class Mesh {
   constructor(gl: WebGL2RenderingContext, data: MeshData, dynamic = false, spread = false) {
     validateMeshData(data);
     this.spread = spread;
+    this.hasUvs = data.uvs !== undefined;
     boundsOfPositions(data.positions, this.bounds);
     this.positionFloats = data.positions.length;
     const vao = gl.createVertexArray();

package/src/render/particlePool.ts

@@ -117,6 +117,15 @@ export class ParticlePool {
    * together.
    */
   private readonly seedOf: Float32Array;
+  /**
+   * Where each slot's particle sits in the drawn streams, or -1 where it sits nowhere.
+   *
+   * **What lets `emit` draw a particle the frame it is born.** The streams are compacted, so a
+   * slot's entry is wherever `update` last put it; an emit into a slot that has one overwrites
+   * that entry, and an emit into one that has none appends. Without it a new particle waited for
+   * the next `update` to be drawn at all.
+   */
+  private readonly drawnAt: Int32Array;
   private next = 0;
 
   constructor(private readonly options: ParticlePoolOptions) {
@@ -138,6 +147,7 @@ export class ParticlePool {
     this.spin = new Float32Array(capacity);
     this.scale = new Float32Array(capacity).fill(1);
     this.seedOf = new Float32Array(capacity);
+    this.drawnAt = new Int32Array(capacity).fill(-1);
   }
 
   /** How many particles are alive. */
@@ -184,6 +194,18 @@ export class ParticlePool {
     this.spin[i] = (hash - Math.floor(hash)) * Math.PI * 2;
     this.scale[i] = sizeScale;
     this.seedOf[i] = seed;
+    /*
+     * Drawn now, at birth, rather than at the next `update`: into the entry this slot already
+     * has when it is taking over a particle that was drawn, and onto the end otherwise.
+     */
+    const held = this.drawnAt[i] as number;
+    const at = held >= 0 ? held : this.particles.count;
+    this.writeDrawn(i, at, 0, x, y, z, vx, vy, vz);
+    if (held < 0) {
+      this.drawnAt[i] = at;
+      this.instances.count = at + 1;
+      this.particles.count = at + 1;
+    }
   }
 
   /**
@@ -198,11 +220,15 @@ export class ParticlePool {
     let count = 0;
     for (let i = 0; i < this.age.length; i++) {
       const age = this.age[i] as number;
-      if (age === Infinity) continue;
+      if (age === Infinity) {
+        this.drawnAt[i] = -1;
+        continue;
+      }
       const life = this.life[i] as number;
       const next = age + dt;
       if (next >= life) {
         this.age[i] = Infinity;
+        this.drawnAt[i] = -1;
         continue;
       }
       this.age[i] = next;
@@ -222,68 +248,89 @@ export class ParticlePool {
       this.y[i] = py;
       this.z[i] = pz;
 
-      const t = next / life;
-      const size = (o.sizeStart + (o.sizeEnd - o.sizeStart) * t) * (this.scale[i] as number);
-      const r =
-        (o.colorStart[0] as number) + ((o.colorEnd[0] as number) - (o.colorStart[0] as number)) * t;
-      const g =
-        (o.colorStart[1] as number) + ((o.colorEnd[1] as number) - (o.colorStart[1] as number)) * t;
-      const b =
-        (o.colorStart[2] as number) + ((o.colorEnd[2] as number) - (o.colorStart[2] as number)) * t;
-      /*
-       * Colour carries the fade rather than an alpha channel: the instanced
-       * path multiplies a tint into the base mesh and has no per-instance
-       * opacity, and for an additive puff darkening to nothing *is* fading out.
-       * It also means the effect needs no blend-state change.
-       */
-      const fade = 1 - t * t;
-      writeInstance(
-        this.instances,
-        count,
-        px,
-        py,
-        pz,
-        size,
-        this.spin[i] as number,
-        r * fade,
-        g * fade,
-        b * fade,
-        0,
-        0,
-        0,
-      );
-      /*
-       * The same particle for a material that has a real opacity channel. Colour
-       * is written *unfaded* here, because dimming it is the scatter path's
-       * workaround and doing both would fade twice — a puff that vanished at half
-       * its life while still occluding what was behind it.
-       */
-      const p = this.particles;
-      const alphaStart = o.alphaStart ?? 1;
-      const alphaEnd = o.alphaEnd ?? 0;
-      p.positions[count * 3] = px;
-      p.positions[count * 3 + 1] = py;
-      p.positions[count * 3 + 2] = pz;
-      p.sizes[count] = size;
-      p.spins[count] = this.spin[i] as number;
-      p.colors[count * 3] = r;
-      p.colors[count * 3 + 1] = g;
-      p.colors[count * 3 + 2] = b;
-      p.alphas[count] = alphaStart + (alphaEnd - alphaStart) * t;
-      p.ages[count] = t;
-      p.seeds[count] = this.seedOf[i] as number;
-      p.velocities[count * 3] = vx;
-      p.velocities[count * 3 + 1] = vy;
-      p.velocities[count * 3 + 2] = vz;
+      this.drawnAt[i] = count;
+      this.writeDrawn(i, count, next / life, px, py, pz, vx, vy, vz);
       count++;
     }
     this.instances.count = count;
     this.particles.count = count;
   }
 
+  /**
+   * One particle's entry in both drawn streams, at `t` of its life: what `update` writes for every
+   * live particle and `emit` for a new one, so the two cannot disagree about what a particle looks
+   * like.
+   */
+  private writeDrawn(
+    i: number,
+    count: number,
+    t: number,
+    px: number,
+    py: number,
+    pz: number,
+    vx: number,
+    vy: number,
+    vz: number,
+  ): void {
+    const o = this.options;
+    const size = (o.sizeStart + (o.sizeEnd - o.sizeStart) * t) * (this.scale[i] as number);
+    const r =
+      (o.colorStart[0] as number) + ((o.colorEnd[0] as number) - (o.colorStart[0] as number)) * t;
+    const g =
+      (o.colorStart[1] as number) + ((o.colorEnd[1] as number) - (o.colorStart[1] as number)) * t;
+    const b =
+      (o.colorStart[2] as number) + ((o.colorEnd[2] as number) - (o.colorStart[2] as number)) * t;
+    /*
+     * Colour carries the fade rather than an alpha channel: the instanced
+     * path multiplies a tint into the base mesh and has no per-instance
+     * opacity, and for an additive puff darkening to nothing *is* fading out.
+     * It also means the effect needs no blend-state change.
+     */
+    const fade = 1 - t * t;
+    writeInstance(
+      this.instances,
+      count,
+      px,
+      py,
+      pz,
+      size,
+      this.spin[i] as number,
+      r * fade,
+      g * fade,
+      b * fade,
+      0,
+      0,
+      0,
+    );
+    /*
+     * The same particle for a material that has a real opacity channel. Colour
+     * is written *unfaded* here, because dimming it is the scatter path's
+     * workaround and doing both would fade twice — a puff that vanished at half
+     * its life while still occluding what was behind it.
+     */
+    const p = this.particles;
+    const alphaStart = o.alphaStart ?? 1;
+    const alphaEnd = o.alphaEnd ?? 0;
+    p.positions[count * 3] = px;
+    p.positions[count * 3 + 1] = py;
+    p.positions[count * 3 + 2] = pz;
+    p.sizes[count] = size;
+    p.spins[count] = this.spin[i] as number;
+    p.colors[count * 3] = r;
+    p.colors[count * 3 + 1] = g;
+    p.colors[count * 3 + 2] = b;
+    p.alphas[count] = alphaStart + (alphaEnd - alphaStart) * t;
+    p.ages[count] = t;
+    p.seeds[count] = this.seedOf[i] as number;
+    p.velocities[count * 3] = vx;
+    p.velocities[count * 3 + 1] = vy;
+    p.velocities[count * 3 + 2] = vz;
+  }
+
   /** Drop everything, for a respawn or a scene change. */
   clear(): void {
     this.age.fill(Infinity);
+    this.drawnAt.fill(-1);
     this.instances.count = 0;
     this.particles.count = 0;
     this.next = 0;

package/src/render/pass.ts

@@ -125,6 +125,18 @@ export type PassContext = {
       readonly pass: GPURenderPassEncoder;
       /** The frame's jitter, the same array `PrepareContext.jitter` held. */
       readonly jitter: Float32Array;
+      /**
+       * The colour format, depth format and sample count of the pass this draw lands in, which a
+       * pipeline set on it must match exactly.
+       *
+       * **Not always the device's.** `PassDevice` says what the frame is; a pass drawn after
+       * `endFrame` lands on the canvas, at the canvas's format and one sample, where the frame is
+       * the scene target at the scene's samples. A pass that is drawn in both places keeps a
+       * pipeline for each and chooses here; one built only from the device is refused by the other.
+       */
+      readonly format: GPUTextureFormat;
+      readonly depthFormat: GPUTextureFormat;
+      readonly samples: number;
     }
 );
 

package/src/render/renderQuality.ts

@@ -194,12 +194,13 @@ export interface RenderQuality {
    * existed: a pane casts nothing at all.
    *
    * Nothing is allocated until a glass caster first reaches a shadow, so a scene with no glass pays
-   * no memory and no pass whatever this says. **The lit shader is the exception**: `'full'` and
-   * `'half'` compile the glass lookup into it, and a lookup that finds no glass and returns at its
-   * first line still costs the lit pass its registers — measured on the courtyard at night, 0.27 ms
-   * at 720p on WebGPU, 0.42 ms on WebGL2 and 1.2 ms at 4K. `'off'` compiles none of it, so a world
-   * that never casts through glass is that much faster for saying so. What would make `'full'` wrong
-   * is a phone budget with a lot of glass; that is what `'half'` is for. See `glassShadow.ts`.
+   * no memory and no pass whatever this says. **Nor any shader, since 4.8.2**: the lit shader is
+   * built without the glass lookup and rebuilt with it when the first glass caster reaches a shadow.
+   * A lookup that finds no glass still cost the lit pass its registers — measured on the courtyard at
+   * night, 0.27 ms at 720p on WebGPU, 0.42 ms on WebGL2 and 1.2 ms at 4K — and from 4.5.0 to 4.8.1
+   * every scene paid it, glass or none: about 30% of the lit shader's instructions, which on a phone
+   * was the lit pass. `'off'` never rebuilds. What would make `'full'` wrong is a phone budget with a
+   * lot of glass; that is what `'half'` is for. See `glassShadow.ts`.
    */
   readonly glassShadows: GlassShadows;
   /** Horizontal world-space reach over which a directional shadow dissolves. */