@driftengine/core 4.8.1 → 4.8.2

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

@@ -1115,6 +1115,8 @@ export declare class WebGPURenderer implements RendererApi {
     private readonly uvScale;
     /** Whether the bound material is seen from both faces. See `SurfaceMaterial.doubleSided`. */
     private materialDoubleSided;
+    /** Whether the bound material has a map, for the warning a mesh with no coordinates earns. */
+    private materialHasMaps;
     createSurfaceTexture(source: TexImageSource, options?: SurfaceTextureOptions): GpuSurfaceTexture;
     /** Several images of one size as an array's layers. See `RendererApi.createSurfaceTextureArray`. */
     createSurfaceTextureArray(sources: readonly TexImageSource[], options?: SurfaceTextureOptions): GpuSurfaceTexture;
@@ -1834,6 +1836,16 @@ export declare class WebGPURenderer implements RendererApi {
      */
     /** The glass the open shadow pass was offered, kept for its own passes: `glassCasters.ts`. */
     private readonly glassCasters;
+    /** Whether a glass caster has ever been offered, which is when lit pipelines start reading it. */
+    private glassSeen;
+    /**
+     * 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;
+    /** One of the lit stage's switches on, in every cache a lit pipeline can come from. */
+    private enableLit;
     /** One resolution every glass caster is read through, so recording one allocates nothing. */
     private readonly glassCasterScratch;
     private readonly casterSink;
@@ -2944,6 +2956,22 @@ export declare class WebGPURenderer implements RendererApi {
      */
     private canDraw;
     private openPass;
+    private openAnyPass;
+    /**
+     * 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;
+    /** `flushOverlay` bound once, so queueing it each frame allocates nothing. */
+    private readonly flushOverlayBound;
     /**
      * The cache whose pipelines match the pass this draw will land in.
      *
@@ -3159,6 +3187,15 @@ export declare class WebGPURenderer implements RendererApi {
      * context is valid for the duration of the call for exactly this reason.
      */
     private readonly passContext;
+    /**
+     * 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;
     /**
      * Let something outside this file draw into the frame. See `Renderer.registerPass`.
      *
@@ -3313,9 +3350,27 @@ export declare 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;
+    /**
+     * 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?: number): void;
+    /** Give the whole depth range back. Safe to call without a matching `beginViewModel`. */
+    endViewModel(): void;
+    /** The view model's depth bounds on the whole of the pass. */
+    private squeezeViewport;
+    /** Whether a view model is being drawn: `openPass` re-applies it, `endFrame` closes it. */
+    private viewModelActive;
+    private readonly viewModelRange;
     /** Give the whole canvas back. Safe to call without a matching `beginInset`. */
     endInset(): void;
     /**

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

@@ -77,6 +77,8 @@ import { resolvePointLights } from '../../lightBudget.js';
 import { resolveRenderQuality } from '../../renderQuality.js';
 import { DEFAULT_GLOBAL_MEDIUM, mediumActive, mediumTargetSize, WEAK_GPU_MEDIUM_STEPS, resolveGlobalMedium, } from '../../globalMedium.js';
 import { castsDepth, glassOf } from '../../shadowCasters.js';
+import { materialHasMaps, noteMapsWithoutUvs } from '../../mapsWithoutUvs.js';
+import { VIEW_MODEL_DEPTH_SHARE, viewModelDepthRange } from '../../viewModel.js';
 import { GlassCasterList } from '../../glassCasters.js';
 import { GpuGlassTint } from './glassTintPass.js';
 import { SUN_DYNAMIC_LAYER, SUN_GLASS_MOVING_LAYER, SUN_GLASS_STATIC_LAYER, SUN_PEELED_LAYER, SUN_STATIC_LAYER, } from '../../shadowMap.js';
@@ -2131,6 +2133,8 @@ export class WebGPURenderer {
     uvScale = new Float32Array([1, 1]);
     /** Whether the bound material is seen from both faces. See `SurfaceMaterial.doubleSided`. */
     materialDoubleSided = false;
+    /** Whether the bound material has a map, for the warning a mesh with no coordinates earns. */
+    materialHasMaps = false;
     createSurfaceTexture(source, options = {}) {
         return new GpuSurfaceTexture(this.surface.device, this.pipelines, source, options);
     }
@@ -2257,6 +2261,7 @@ export class WebGPURenderer {
         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);
         const orm = (material?.orm ?? null);
         const emissiveMap = (material?.emissive ?? null);
@@ -4400,6 +4405,29 @@ export class WebGPURenderer {
      */
     /** The glass the open shadow pass was offered, kept for its own passes: `glassCasters.ts`. */
     glassCasters = new GlassCasterList();
+    /** Whether a glass caster has ever been offered, which is when lit pipelines start reading it. */
+    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.
+     */
+    noteGlassCaster() {
+        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. */
+    enableLit(feature) {
+        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. */
     glassCasterScratch = {
         transmission: 0,
@@ -4412,6 +4440,7 @@ export class WebGPURenderer {
                 /* 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;
             }
@@ -4451,6 +4480,7 @@ export class WebGPURenderer {
             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;
             }
@@ -4491,6 +4521,7 @@ export class WebGPURenderer {
             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;
             }
@@ -4833,7 +4864,7 @@ export class WebGPURenderer {
          */
         /* Off compiles none of the glass lookup into a lit pipeline: see `PipelineCache.glassShadows`. */
         const glassShadows = quality.glassShadows !== 'off';
-        this.pipelines = new PipelineCache(device, quality.screenEffects ? sceneColorFormat(quality.hdrScene) : surface.format, this.samples, glassShadows);
+        this.pipelines = new PipelineCache(device, quality.screenEffects ? sceneColorFormat(quality.hdrScene) : surface.format, this.samples, glassShadows, quality.clusteredLights);
         /*
          * The canvas' own state, for the pass `ensurePass` reopens after `endFrame`.
          *
@@ -4845,11 +4876,11 @@ export class WebGPURenderer {
         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
@@ -5123,7 +5154,11 @@ export class WebGPURenderer {
             /* 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.
@@ -6215,6 +6250,7 @@ export class WebGPURenderer {
         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.**
          *
@@ -6707,6 +6743,7 @@ export class WebGPURenderer {
          */
         if (this.tracksMotionNow())
             this.recordDrawMotion(mesh, model, previousModel);
+        noteMapsWithoutUvs(mesh, mesh.hasUvs, this.materialHasMaps);
         this.submitMesh(mesh, model, tint, 1, false, { depthLayer });
     }
     /**
@@ -6801,6 +6838,7 @@ export class WebGPURenderer {
             this.translucentQueue.record(mesh, model, opacity, options);
             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(mesh, model, options.tint ?? null, Math.min(opacity, 1), true, options);
@@ -10442,6 +10480,8 @@ export class WebGPURenderer {
         command.instances = 1;
         command.indirect = null;
         recordNode(this.arena, VERB_DRAW, reads, writes, at, 0);
+        if (this.framePresented)
+            this.queueOverlayFlush();
         return command;
     }
     /** Replay one recorded draw into an open pass. */
@@ -10457,11 +10497,7 @@ export class WebGPURenderer {
             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);
+            definition.draw(this.fillPassContext(pass));
             return;
         }
         if (verb !== VERB_DRAW)
@@ -10558,6 +10594,15 @@ export class WebGPURenderer {
         return this.framePresented;
     }
     openPass() {
+        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;
+    }
+    openAnyPass() {
         /* While the replay is running this is the only pass there is. See `oitEncoder`. */
         if (this.oitEncoder !== null)
             return this.oitEncoder;
@@ -10649,18 +10694,29 @@ export class WebGPURenderer {
                 },
         });
         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.
+     */
+    queueOverlayFlush() {
+        if (this.overlayFlushQueued)
+            return;
+        this.overlayFlushQueued = true;
+        queueMicrotask(this.flushOverlayBound);
+    }
+    /** `flushOverlay` bound once, so queueing it each frame allocates nothing. */
+    flushOverlayBound = () => this.flushOverlay();
     /**
      * The cache whose pipelines match the pass this draw will land in.
      *
@@ -10725,6 +10781,9 @@ export class WebGPURenderer {
         this.encoder = null;
     }
     endFrame() {
+        /* 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;
@@ -11148,7 +11207,29 @@ export class WebGPURenderer {
         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.
+     */
+    fillPassContext(pass) {
+        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;
+    }
     /**
      * Let something outside this file draw into the frame. See `Renderer.registerPass`.
      *
@@ -11286,14 +11367,12 @@ export class WebGPURenderer {
             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);
+            definition.draw(this.fillPassContext(pass));
             return;
         }
         recordNode(this.arena, VERB_PASS, this.passReads.get(handle) ?? 0, this.currentTarget(), handle, 0);
+        if (this.framePresented)
+            this.queueOverlayFlush();
     }
     /** Let go of a pass. A handle kept past this draws nothing; see `PassHandle`. */
     unregisterPass(handle) {
@@ -11485,7 +11564,10 @@ export class WebGPURenderer {
      * **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, clearColor) {
         /*
@@ -11497,7 +11579,7 @@ export class WebGPURenderer {
             this.flushGraph();
         const pass = this.openPass();
         if (this.surface.lost || pass === null)
-            return 0;
+            return Math.max(rect.width, 1) / Math.max(rect.height, 1);
         const canvas = this.surface.context.canvas;
         const cssWidth = Math.max(canvas.clientWidth, 1);
         const cssHeight = Math.max(canvas.clientHeight, 1);
@@ -11594,6 +11676,44 @@ export class WebGPURenderer {
          */
         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) {
+        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() {
+        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. */
+    squeezeViewport(pass) {
+        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. */
+    viewModelActive = false;
+    viewModelRange = [0, 1];
     /** Give the whole canvas back. Safe to call without a matching `beginInset`. */
     endInset() {
         /*
@@ -12663,6 +12783,9 @@ export class WebGPURenderer {
         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;
     }
     /**
@@ -12739,6 +12862,8 @@ export class WebGPURenderer {
         device.queue.writeTexture({ texture: atlas }, field.atlas, { bytesPerRow: aw * 8, rowsPerImage: ah }, [aw, ah, ad]);
         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/dist/render/mapsWithoutUvs.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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';
+/**
+ * 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 declare function materialHasMaps(material: SurfaceMaterial<unknown> | null): boolean;
+/** Warn the first time `mesh`, which has no coordinates, is drawn with a picture map bound. */
+export declare function noteMapsWithoutUvs(mesh: object, hasUvs: boolean, materialHasMaps: boolean): void;

package/dist/render/mapsWithoutUvs.js

@@ -0,0 +1,24 @@
+const told = new WeakSet();
+/**
+ * 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) {
+    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, hasUvs, materialHasMaps) {
+    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/dist/render/mesh.d.ts

@@ -56,6 +56,8 @@ export declare class Mesh {
     readonly bounds: Bounds;
     /** 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.
      *

package/dist/render/mesh.js

@@ -123,6 +123,8 @@ export class Mesh {
     bounds = createBounds();
     /** Whether this mesh carries a rig, which decides which flat program draws it. */
     isSkinned;
+    /** Whether it has texture coordinates, without which a material's maps read one texel. */
+    hasUvs;
     /**
      * This mesh's morph deltas, or null for geometry that does not deform.
      *
@@ -171,6 +173,7 @@ export class Mesh {
     constructor(gl, data, 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/dist/render/particlePool.d.ts

@@ -98,6 +98,15 @@ export declare class ParticlePool {
      * together.
      */
     private readonly seedOf;
+    /**
+     * 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;
     private next;
     constructor(options: ParticlePoolOptions);
     /** How many particles are alive. */
@@ -119,6 +128,12 @@ export declare class ParticlePool {
      * particles cost nothing but the loop iteration.
      */
     update(dt: number): void;
+    /**
+     * 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;
     /** Drop everything, for a respawn or a scene change. */
     clear(): void;
 }