@woosh/meep-engine 3.18.0 → 3.20.0

package/src/engine/graphics3/GPUParticleEmitterSystem.js

@@ -1,310 +1,809 @@
-import { assert } from "../../core/assert.js";
-import { FramePhase } from "../../shade/renderer/extension/FramePhase.js";
-import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
-import { GPUTextureContext } from "../../shade/renderer/texture/GPUTextureContext.js";
-import { System } from "../ecs/System.js";
-import { GameAssetType } from "../asset/GameAssetType.js";
-import { ImageRGBADataLoader } from "../asset/loaders/image/ImageRGBADataLoader.js";
-import { TextureAtlas } from "../graphics/texture/atlas/TextureAtlas.js";
-import { Sampler2D } from "../graphics/texture/sampler/Sampler2D.js";
-import { sampler2d_ensure_uint8_RGBA } from "../graphics/texture/sampler/sampler2d_ensure_uint8_RGBA.js";
-
-/**
- * @typedef {object} ParticleAtlasTexture
- * @property {number} references Number of emitters using this URL.
- * @property {import("../graphics/texture/atlas/AtlasPatch.js").AtlasPatch|null} patch Null while loading or after failure.
- */
-
-/**
- * @typedef {object} ParticleAtlasEntry
- * @property {string|null} url Last observed emitter texture URL.
- * @property {ParticleAtlasTexture|null} texture Shared image record, or null for an untextured emitter.
- * @property {number} seen Last membership sweep that visited this emitter.
- */
-
-/**
- * Asset and atlas ownership for Shade's GPU particle emitters in one scene.
- *
- * This ECS system observes the scene's ParticleEmitter nodes, so it needs no additional component
- * or duplicate transform. Add/remove nodes through the scene as usual. One system owns the sprite
- * atlas for that scene; the legacy ParticleEmitterSystem continues to serve CPU particle effects.
- *
- * Images load through the supplied AssetManager and share a patch by URL. TextureAtlas already
- * handles packing, growth and repacking with MaxRectanglesPacker. A FrameStart extension publishes
- * the pixels and every current patch before the renderer records particle simulation and drawing.
- * Pending/failed images sample transparent; emitters without an image sample white.
- */
-export class GPUParticleEmitterSystem extends System {
-    /**
-     * CPU atlas, exposed for inspection. Owned by this system.
-     * @type {TextureAtlas}
-     */
-    atlas = new TextureAtlas(64);
-
-    /** @type {import("./GraphicsEngine.js").GraphicsEngine} */
-    #graphics;
-    /** @type {import("../../shade/renderer/scene/Scene.js").Scene} */
-    #scene;
-    /** @type {import("../asset/AssetManager.js").AssetManager} */
-    #assets;
-    /** @type {Map<import("../../shade/renderer/particles/runtime/ParticleEmitter.js").ParticleEmitter, ParticleAtlasEntry>} */
-    #entries = new Map();
-    /** @type {Map<string, ParticleAtlasTexture>} */
-    #textures = new Map();
-    /** @type {number} */
-    #sweep = 0;
-    /** @type {number} */
-    #membership_version = -1;
-    /** @type {import("../graphics/texture/atlas/AtlasPatch.js").AtlasPatch} */
-    #white;
-    /** @type {import("../graphics/texture/atlas/AtlasPatch.js").AtlasPatch} */
-    #transparent;
-    /** @type {GPUParticleAtlasExtension|null} */
-    #extension = null;
-    /** @type {GPUTextureContext|null} */
-    #texture = null;
-    /** @type {GPUTextureView|null} */
-    #view = null;
-    /** @type {GPUDevice|null} */
-    #device = null;
-    /** @type {number} */
-    #uploaded_version = -1;
-    /** @type {import("../../shade/renderer/particles/GPUParticleSystem.js").GPUParticleSystem|null} */
-    #particles = null;
-    /** @type {GPUTextureView|null} */
-    #previous_atlas = null;
-    /** @type {Float32Array} */
-    #region = new Float32Array(4);
-
-    /**
-     * @param {import("./GraphicsEngine.js").GraphicsEngine} graphics
-     * @param {import("../../shade/renderer/scene/Scene.js").Scene} scene scene whose particle atlas this system owns
-     * @param {import("../asset/AssetManager.js").AssetManager} assets
-     */
-    constructor(graphics, scene, assets) {
-        super();
-        assert.defined(graphics, "graphics");
-        assert.equal(scene.isScene, true, "scene.isScene !== true");
-        assert.defined(assets, "assets");
-        this.#graphics = graphics;
-        this.#scene = scene;
-        this.#assets = assets;
-        this.#create_defaults();
-    }
-
-    /**
-     * @param {import("../ecs/EntityManager.js").EntityManager} entityManager
-     * @returns {Promise<void>}
-     */
-    async startup(entityManager) {
-        this.entityManager = entityManager;
-        if (!this.#assets.hasLoaderForType(GameAssetType.Image)) {
-            await this.#assets.registerLoader(GameAssetType.Image, new ImageRGBADataLoader());
-        }
-        this.#extension = new GPUParticleAtlasExtension(this);
-        this.#graphics.add_extension(this.#extension);
-    }
-
-    /** @returns {Promise<void>} */
-    async shutdown() {
-        if (this.#extension !== null) {
-            this.#graphics.remove_extension(this.#extension);
-            this.#extension = null;
-        }
-        this.#detach();
-        this.#texture?.destroy();
-        this.#texture = null;
-        this.#view = null;
-        this.#device = null;
-        this.#uploaded_version = -1;
-        this.#entries.clear();
-        this.#membership_version = -1;
-        // An in-flight load checks its record's identity here before adding a patch.
-        this.#textures.clear();
-        this.atlas.reset();
-        this.#create_defaults();
-    }
-
-    /** @returns {void} */
-    #create_defaults() {
-        const white = Sampler2D.uint8(4, 1, 1);
-        white.data.fill(255);
-        this.#white = this.atlas.add(white);
-        this.#transparent = this.atlas.add(Sampler2D.uint8(4, 1, 1));
-    }
-
-    /** @returns {void} */
-    update() {
-        this.#sync_membership();
-        for (const [emitter, entry] of this.#entries) {
-            if (entry.url !== emitter.texture) {
-                this.#release(entry.url);
-                entry.url = emitter.texture;
-                entry.texture = entry.url === null ? null : this.#acquire(entry.url);
-            }
-        }
-        this.atlas.update();
-    }
-
-    /** @returns {void} */
-    #sync_membership() {
-        const instances = this.#scene.instances;
-        if (instances.version === this.#membership_version) { return; }
-        const sweep = ++this.#sweep;
-        for (const emitter of instances.nodes) {
-            if (emitter.isParticleEmitter !== true) { continue; }
-            let entry = this.#entries.get(emitter);
-            if (entry === undefined) {
-                entry = { url: null, texture: null, seen: sweep };
-                this.#entries.set(emitter, entry);
-            }
-            entry.seen = sweep;
-        }
-        for (const [emitter, entry] of this.#entries) {
-            if (entry.seen !== sweep) {
-                this.#release(entry.url);
-                this.#entries.delete(emitter);
-            }
-        }
-        this.#membership_version = instances.version;
-    }
-
-    /**
-     * @param {string} url
-     * @returns {ParticleAtlasTexture}
-     */
-    #acquire(url) {
-        let texture = this.#textures.get(url);
-        if (texture !== undefined) {
-            texture.references++;
-            return texture;
-        }
-        texture = { references: 1, patch: null };
-        this.#textures.set(url, texture);
-        this.#assets.promise(url, GameAssetType.Image).then(asset => {
-            // Removed, changed URL, or shut down while loading: the completion owns nothing now.
-            if (this.#textures.get(url) !== texture) { return; }
-            texture.patch = this.atlas.add(sampler2d_ensure_uint8_RGBA(asset.create()));
-        }).catch(error => {
-            if (this.#textures.get(url) === texture) {
-                console.warn(`GPU particle texture '${url}' could not be loaded`, error);
-            }
-        });
-        return texture;
-    }
-
-    /**
-     * @param {string|null} url
-     * @returns {void}
-     */
-    #release(url) {
-        if (url === null) { return; }
-        const texture = this.#textures.get(url);
-        if (--texture.references !== 0) { return; }
-        this.#textures.delete(url);
-        if (texture.patch !== null) { this.atlas.remove(texture.patch); }
-    }
-
-    /** Publish atlas data at FrameStart, after scene rows exist and before particle passes record.
-     * @param {import("../../shade/renderer/extension/FrameContext.js").FrameContext} frame
-     * @returns {void}
-     */
-    prepare(frame) {
-        if (frame.view.scene.scene !== this.#scene) { return; }
-        this.update();
-        const renderer = this.#graphics.renderer;
-        renderer.feature_particles_enabled = true;
-        const particles = renderer.particles(frame.view.scene);
-        if (particles !== this.#particles) {
-            this.#detach();
-            this.#particles = particles;
-            this.#previous_atlas = particles.atlas;
-        }
-        particles.sync_membership();
-        this.#upload(renderer.graphics.device);
-        particles.atlas = this.#view;
-
-        for (const [emitter, entry] of this.#entries) {
-            if (particles.registry.context(emitter) === undefined) { continue; }
-            const patch = entry.texture === null ? this.#white : entry.texture.patch ?? this.#transparent;
-            const uv = patch.uv;
-            const region = this.#region;
-            if (patch === this.#white || patch === this.#transparent) {
-                // Sample the texel centre everywhere, avoiding interpolation into the gutter.
-                region[0] = uv.position.x + uv.size.x * 0.5;
-                region[1] = uv.position.y + uv.size.y * 0.5;
-                region[2] = 0;
-                region[3] = 0;
-            } else {
-                region[0] = uv.position.x;
-                region[1] = uv.position.y;
-                region[2] = uv.size.x;
-                region[3] = uv.size.y;
-            }
-            // Re-read every patch after packing: growth also changes UVs of unchanged images.
-            particles.registry.set_atlas_region(emitter, region);
-        }
-    }
-
-    /**
-     * @param {GPUDevice} device
-     * @returns {void}
-     */
-    #upload(device) {
-        const source = this.atlas.sampler;
-        if (this.#device !== device || this.#texture === null) {
-            this.#texture?.destroy();
-            this.#device = device;
-            this.#texture = new GPUTextureContext(device);
-            const descriptor = this.#texture.descriptor;
-            descriptor.label = "particles/sprite atlas";
-            descriptor.format = "rgba8unorm";
-            descriptor.usage = GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST;
-            this.#uploaded_version = -1;
-        }
-        const texture = this.#texture;
-        if (texture.width !== source.width || texture.height !== source.height) {
-            texture.resize(source.width, source.height);
-            this.#uploaded_version = -1;
-        }
-        if (this.#uploaded_version !== source.version) {
-            device.queue.writeTexture({ texture: texture.gpu_texture }, source.data,
-                { bytesPerRow: source.width * 4 }, [source.width, source.height]);
-            texture.incrementVersion();
-            this.#uploaded_version = source.version;
-        }
-        this.#view = texture.obtainView();
-    }
-
-    /** @returns {void} */
-    #detach() {
-        if (this.#particles !== null && this.#particles.atlas === this.#view) {
-            this.#particles.atlas = this.#previous_atlas;
-            for (const emitter of this.#particles.emitters) {
-                this.#particles.registry.set_atlas_region(emitter, [0, 0, 1, 1]);
-            }
-        }
-        this.#particles = null;
-        this.#previous_atlas = null;
-    }
-}
-
-class GPUParticleAtlasExtension extends RenderExtension {
-    /** @type {string} */
-    name = "gpu particle atlas";
-    /** @type {FramePhase} */
-    phase = FramePhase.FrameStart;
-    /** @type {GPUParticleEmitterSystem} */
-    #system;
-
-    /** @param {GPUParticleEmitterSystem} system */
-    constructor(system) {
-        super();
-        this.#system = system;
-    }
-    /**
-     * @param {import("../../shade/renderer/extension/FrameContext.js").FrameContext} frame
-     * @returns {void}
-     */
-    record(frame) { this.#system.prepare(frame); }
-}
+import { assert } from "../../core/assert.js";
+import { warn_limited } from "../../shade/util/warn_limited.js";
+import { FramePhase } from "../../shade/renderer/extension/FramePhase.js";
+import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
+import { ParticleEmitter } from "../../shade/renderer/particles/runtime/ParticleEmitter.js";
+import { GPUTextureContext } from "../../shade/renderer/texture/GPUTextureContext.js";
+import { System } from "../ecs/System.js";
+import Name from "../ecs/name/Name.js";
+import { Transform64 } from "../ecs/transform/Transform64.js";
+import { TRANSFORM64_EVENT_CHANGE } from "../ecs/transform/TRANSFORM64_EVENT_CHANGE.js";
+import { GameAssetType } from "../asset/GameAssetType.js";
+import { ImageRGBADataLoader } from "../asset/loaders/image/ImageRGBADataLoader.js";
+import { ParticleEffect } from "../graphics/ecs/particles/ParticleEffect.js";
+import { TextureAtlas } from "../graphics/texture/atlas/TextureAtlas.js";
+import { Sampler2D } from "../graphics/texture/sampler/Sampler2D.js";
+import { sampler2d_ensure_uint8_RGBA } from "../graphics/texture/sampler/sampler2d_ensure_uint8_RGBA.js";
+
+/**
+ * Bursts {@link GPUParticleEmitterSystem#burst} will hold before it starts dropping them. Reached
+ * only when frames have stopped arriving — see the call site.
+ *
+ * @type {number}
+ */
+const BURST_QUEUE_LIMIT = 256;
+
+/**
+ * @typedef {object} ParticleAtlasTexture
+ * @property {number} references Number of entities using this URL.
+ * @property {import("../graphics/texture/atlas/AtlasPatch.js").AtlasPatch|null} patch Null while loading or after failure.
+ */
+
+/**
+ * @typedef {object} ParticleEmitterEntry
+ * @property {number} entity
+ * @property {ParticleEffect} effect the entity's component — what to emit
+ * @property {Transform64} transform the entity's transform — where to emit it
+ * @property {ParticleEmitter|null} node the scene node, once the effect has a program to run
+ * @property {function():void} on_transform_changed
+ * @property {string|null} url last observed {@link ParticleEffect#texture}
+ * @property {ParticleAtlasTexture|null} texture shared image record, or null for an untextured effect
+ */
+
+/**
+ * Draws the game's GPU particle effects: one emitter per entity carrying
+ * {@link ../graphics/ecs/particles/ParticleEffect.js ParticleEffect} and
+ * {@link ../ecs/transform/Transform64.js Transform64}.
+ *
+ * ```js
+ * entityManager.addSystem(new GPUParticleEmitterSystem(graphics, scene, assetManager));
+ *
+ * new Entity()
+ *     .add(new Transform64())
+ *     .add(ParticleEffect.from({ ...create_particle_effect({ layout, init, update }), spawn_rate: 400 }))
+ *     .build(dataset);
+ * ```
+ *
+ * **The entity is the emitter.** The component says what it emits and the transform says where, the
+ * same division every other placed thing in this engine uses — a `Decal`, an `SGMesh`, a `Light`.
+ * Which means an emitter is spawned, moved, parented, attached to a bone, saved and destroyed by
+ * exactly the machinery that does those things for everything else, and a particle effect stops
+ * being a special case that needs its own scene-graph call.
+ *
+ * ## What this system does with the pair
+ *
+ * It builds a {@link ParticleEmitter} scene node per entity and owns it: the node is added to
+ * {@link scene} when the component has a compiled effect, follows the entity's transform, carries
+ * whatever the component currently says, and leaves the scene when the entity does. The node is not
+ * hidden — {@link node_of} hands it out — but it is not the interface either: write to the
+ * component and the next frame carries it.
+ *
+ * Changes are found by **comparison** rather than announced. Once a frame each entity's
+ * fields are compared against what was last written to its node, and the node is marked dirty only
+ * where they differ; `EmitterRegistry` then restages exactly the rows that moved. A component nobody
+ * touched costs a run of integer comparisons and no upload, so there is no change signal to fire and
+ * none to forget. What that buys is that gameplay can write `effect.spawn_rate = 0` anywhere,
+ * including from code that has never heard of this system.
+ *
+ * ## It owns the scene's sprite atlas
+ *
+ * Every {@link ParticleEffect#texture} is loaded through the supplied `AssetManager` and packed into
+ * one {@link TextureAtlas} shared by the scene, one patch per distinct URL however many entities
+ * name it, reference-counted so the last entity to let go is what unpacks it. A `FrameStart`
+ * extension publishes the pixels and every current patch region before the renderer records the
+ * particle passes — every repack moves UVs that nothing else changed, so the regions are rewritten
+ * whole rather than when a URL changes. Pending and failed images sample a transparent texel;
+ * effects with no image sample a white one.
+ *
+ * An emitter node in this scene that this system did not build — one added to the `Scene` directly —
+ * gets the white texel. The atlas is the scene's and that emitter has nothing in it, so the
+ * alternative is not "its own texture" but a UV rectangle from somebody else's image.
+ *
+ * ## What it is not
+ *
+ * It does not simulate anything and does not record a particle pass. `GPUParticleSystem` does both,
+ * inside the renderer, driven from the emitter table these rows are in — see
+ * `shade/renderer/particles/DESIGN.md`. This system's whole contribution is membership, placement,
+ * the fields, and the sprite sheet.
+ *
+ * It also does not retire the CPU `ParticleEmitterSystem`, which serves the `particular` effects the
+ * game still ships. The two coexist and share nothing.
+ */
+export class GPUParticleEmitterSystem extends System {
+    dependencies = [ParticleEffect, Transform64];
+
+    /**
+     * CPU atlas, exposed for inspection. Owned by this system.
+     * @type {TextureAtlas}
+     */
+    atlas = new TextureAtlas(64);
+
+    /** @type {import("./GraphicsEngine.js").GraphicsEngine} */
+    #graphics;
+    /** @type {import("../../shade/renderer/scene/Scene.js").Scene} */
+    #scene;
+    /** @type {import("../asset/AssetManager.js").AssetManager} */
+    #assets;
+    /** @type {Map<number, ParticleEmitterEntry>} */
+    #entries = new Map();
+    /**
+     * The same entries by the node they own, so that the emitters this system did not build can be
+     * told apart from the ones it did without a linear search per emitter per frame.
+     * @type {Map<ParticleEmitter, ParticleEmitterEntry>}
+     */
+    #by_node = new Map();
+    /** @type {Map<string, ParticleAtlasTexture>} */
+    #textures = new Map();
+    /**
+     * Bursts asked for through {@link burst} and not yet handed to the particle system. Flat pairs
+     * of `entity, count`, drained every frame.
+     * @type {number[]}
+     */
+    #bursts = [];
+    /** @type {import("../graphics/texture/atlas/AtlasPatch.js").AtlasPatch} */
+    #white;
+    /** @type {import("../graphics/texture/atlas/AtlasPatch.js").AtlasPatch} */
+    #transparent;
+    /** @type {GPUParticleAtlasExtension|null} */
+    #extension = null;
+    /** @type {GPUTextureContext|null} */
+    #texture = null;
+    /** @type {GPUTextureView|null} */
+    #view = null;
+    /** @type {GPUDevice|null} */
+    #device = null;
+    /** @type {number} */
+    #uploaded_version = -1;
+    /** @type {import("../../shade/renderer/particles/GPUParticleSystem.js").GPUParticleSystem|null} */
+    #particles = null;
+    /** @type {GPUTextureView|null} */
+    #previous_atlas = null;
+    /** @type {Float32Array} */
+    #region = new Float32Array(4);
+
+    /**
+     * @param {import("./GraphicsEngine.js").GraphicsEngine} graphics
+     * @param {import("../../shade/renderer/scene/Scene.js").Scene} scene scene the emitters are put
+     *        in, and whose particle atlas this system owns
+     * @param {import("../asset/AssetManager.js").AssetManager} assets
+     */
+    constructor(graphics, scene, assets) {
+        super();
+
+        assert.defined(graphics, "graphics");
+        assert.equal(scene.isScene, true, "scene.isScene !== true");
+        assert.defined(assets, "assets");
+
+        this.#graphics = graphics;
+        this.#scene = scene;
+        this.#assets = assets;
+
+        this.#create_defaults();
+    }
+
+    /**
+     * The scene the emitters are put in. Received rather than created: meshes and lights come from
+     * systems of their own, and all of them have to be writing into one scene for any of it to be
+     * visible together.
+     *
+     * @returns {import("../../shade/renderer/scene/Scene.js").Scene}
+     */
+    get scene() {
+        return this.#scene;
+    }
+
+    /**
+     * The emitter nodes this system currently has in the scene, in no particular order. Read-only —
+     * they follow the entities.
+     *
+     * @returns {ParticleEmitter[]}
+     */
+    get emitters() {
+        return Array.from(this.#by_node.keys());
+    }
+
+    /**
+     * The scene node built for an entity.
+     *
+     * Handed out for the things an entity reference cannot express — parenting something to the
+     * emitter, reading the world matrix the hierarchy pass composed — and for nothing routine: the
+     * component is how an effect is changed, and a node written to behind the component's back is
+     * overwritten by the next comparison.
+     *
+     * @param {number} entity
+     * @returns {ParticleEmitter|null} `null` for an entity this system has not linked, or one whose
+     * component has no compiled effect yet
+     */
+    node_of(entity) {
+        const entry = this.#entries.get(entity);
+
+        if (entry === undefined) {
+            return null;
+        }
+
+        return entry.node;
+    }
+
+    /**
+     * Ask an entity's emitter for `count` particles on top of its rate, on the next frame.
+     *
+     * The one-shot half of the API, and the only thing here the CPU asks for rather than describes:
+     * an impact, a footfall, a muzzle flash. It goes through the same GPU path as continuous
+     * emission — the tick pass folds the burst into the emitter's accumulator, and the pool budget
+     * and the culling apply — so it is a request rather than a guarantee, and an entity whose
+     * emitter is not live by the time the frame starts is silently skipped.
+     *
+     * @param {number} entity
+     * @param {number} count
+     */
+    burst(entity, count) {
+        assert.isNonNegativeInteger(count, "count");
+
+        if (count === 0) {
+            return;
+        }
+
+        if (this.#bursts.length >= BURST_QUEUE_LIMIT * 2) {
+            /*
+             The queue is drained by a frame, so it only grows without bound when frames have stopped
+             arriving — a scene nobody draws, or a device that never came up — and gameplay carries on
+             asking. Dropping is right either way: nothing is going to spawn these, and a burst is a
+             request about the moment it was made.
+
+             The text is the key `warn_limited` counts on, so it carries no entity: one message per
+             limit, not one per caller that happens to be unlucky.
+            */
+            warn_limited(
+                `GPUParticleEmitterSystem: ${BURST_QUEUE_LIMIT} bursts are queued and no frame has `
+                + "drained them; dropping the rest"
+            );
+
+            return;
+        }
+
+        this.#bursts.push(entity, count);
+    }
+
+    /**
+     * @param {import("../ecs/EntityManager.js").EntityManager} entityManager
+     * @returns {Promise<void>}
+     */
+    async startup(entityManager) {
+        this.entityManager = entityManager;
+
+        if (!this.#assets.hasLoaderForType(GameAssetType.Image)) {
+            await this.#assets.registerLoader(GameAssetType.Image, new ImageRGBADataLoader());
+        }
+
+        this.#extension = new GPUParticleAtlasExtension(this);
+
+        this.#graphics.add_extension(this.#extension);
+    }
+
+    /** @returns {Promise<void>} */
+    async shutdown() {
+        if (this.#extension !== null) {
+            this.#graphics.remove_extension(this.#extension);
+            this.#extension = null;
+        }
+
+        for (const entity of Array.from(this.#entries.keys())) {
+            this.#drop(entity);
+        }
+
+        this.#detach();
+
+        this.#texture?.destroy();
+        this.#texture = null;
+        this.#view = null;
+        this.#device = null;
+        this.#uploaded_version = -1;
+        this.#bursts.length = 0;
+
+        // An in-flight load checks its record's identity here before adding a patch.
+        this.#textures.clear();
+
+        this.atlas.reset();
+        this.#create_defaults();
+    }
+
+    /**
+     * @param {ParticleEffect} effect
+     * @param {Transform64} transform
+     * @param {number} entity
+     */
+    link(effect, transform, entity) {
+        /** @type {ParticleEmitterEntry} */
+        const entry = {
+            entity,
+            effect,
+            transform,
+            node: null,
+            on_transform_changed: null,
+            url: null,
+            texture: null
+        };
+
+        this.#entries.set(entity, entry);
+
+        /*
+         The emitter is placed the moment its transform moves rather than on a poll. A Transform64
+         has no signals of its own, so the announcement comes from the dataset: whoever wrote the
+         transform sends TRANSFORM64_EVENT_CHANGE and this wakes on it. Coarser than watching
+         position, rotation and scale separately — a scale write wakes a placement that reads the
+         whole transform anyway — and that is the trade the type makes everywhere.
+        */
+        entry.on_transform_changed = () => this.#place(entry);
+
+        this.entityManager.dataset.addEntityEventListener(
+            entity, TRANSFORM64_EVENT_CHANGE, entry.on_transform_changed
+        );
+
+        // Everything else — building the node, acquiring the texture — is what a frame does anyway,
+        // and doing it here as well would be a second copy of it that has to stay in step.
+        this.#sync(entry);
+    }
+
+    /**
+     * @param {ParticleEffect} effect
+     * @param {Transform64} transform
+     * @param {number} entity
+     */
+    unlink(effect, transform, entity) {
+        this.#drop(entity);
+    }
+
+    /**
+     * Bring every emitter in line with its entity: build nodes for effects that have arrived, retire
+     * nodes for effects that have gone, copy changed fields onto the ones that stay, and follow the
+     * texture URLs.
+     *
+     * @param {number} [time_delta_seconds]
+     * @returns {void}
+     */
+    update(time_delta_seconds) {
+        for (const entry of this.#entries.values()) {
+            this.#sync(entry);
+        }
+
+        this.atlas.update();
+    }
+
+    /**
+     * Publish the atlas at FrameStart — after the scene context has established transform rows, and
+     * before the renderer records the particle passes that read the emitter table.
+     *
+     * {@link update} is called from here as well as by the entity manager, because a frame must not
+     * depend on a simulation tick having preceded it: an editor draws on demand, and a paused game
+     * still renders. It is idempotent and costs a comparison per emitter when nothing has changed,
+     * which is what makes running it twice a frame the cheap way to be right rather than a saving
+     * worth chasing.
+     *
+     * @param {import("../../shade/renderer/extension/FrameContext.js").FrameContext} frame
+     * @returns {void}
+     */
+    prepare(frame) {
+        if (frame.view.scene.scene !== this.#scene) {
+            return;
+        }
+
+        this.update();
+
+        const renderer = this.#graphics.renderer;
+
+        /*
+         The renderer's GPU particle feature is this system's to turn on, and it is turned on every
+         frame rather than once, because a device restart builds a renderer that has never heard of
+         it. The consequence is worth stating: while this system is in the profile there is no way to
+         switch GPU particles off through the renderer, because this would switch them back on at the
+         next FrameStart. Switching them off means taking the system out — or, for one effect,
+         `ParticleEffect#emitting`.
+        */
+        renderer.feature_particles_enabled = true;
+
+        const particles = renderer.particles(frame.view.scene);
+
+        if (particles !== this.#particles) {
+            this.#detach();
+            this.#particles = particles;
+            this.#previous_atlas = particles.atlas;
+        }
+
+        particles.sync_membership();
+
+        this.#upload(renderer.graphics.device);
+
+        particles.atlas = this.#view;
+
+        this.#publish_regions(particles);
+        this.#drain_bursts(particles);
+    }
+
+    /**
+     * Point every emitter of this scene at its patch in the atlas.
+     *
+     * Every region, every frame: growth also moves the UVs of images that did not change, and there
+     * is no signal for that which an emitter could subscribe to.
+     *
+     * @param {import("../../shade/renderer/particles/GPUParticleSystem.js").GPUParticleSystem} particles
+     */
+    #publish_regions(particles) {
+        const registry = particles.registry;
+        const emitters = registry.emitters;
+        const region = this.#region;
+
+        for (let i = 0; i < emitters.length; i++) {
+            const emitter = emitters[i];
+            const entry = this.#by_node.get(emitter);
+
+            // Not ours: it has nothing in this atlas, so it gets the one patch that is true for
+            // everybody — a white texel, which draws it as a flat quad of its own colour.
+            const patch = entry === undefined || entry.texture === null
+                ? this.#white
+                : entry.texture.patch ?? this.#transparent;
+
+            const uv = patch.uv;
+
+            if (patch === this.#white || patch === this.#transparent) {
+                // Sample the texel centre everywhere, avoiding interpolation into the gutter.
+                region[0] = uv.position.x + uv.size.x * 0.5;
+                region[1] = uv.position.y + uv.size.y * 0.5;
+                region[2] = 0;
+                region[3] = 0;
+            } else {
+                region[0] = uv.position.x;
+                region[1] = uv.position.y;
+                region[2] = uv.size.x;
+                region[3] = uv.size.y;
+            }
+
+            registry.set_atlas_region(emitter, region);
+        }
+    }
+
+    /**
+     * Hand this frame's bursts to the particle system, now that membership has been swept and every
+     * emitter that can have a row has one.
+     *
+     * The queue is emptied whether or not each burst could be delivered. A burst is a request about
+     * *this* moment — a footfall, an impact — and holding one for an emitter that is not live yet
+     * would deliver it seconds late, at whatever unrelated moment the emitter finally arrived.
+     *
+     * @param {import("../../shade/renderer/particles/GPUParticleSystem.js").GPUParticleSystem} particles
+     */
+    #drain_bursts(particles) {
+        const bursts = this.#bursts;
+
+        for (let i = 0; i < bursts.length; i += 2) {
+            const entry = this.#entries.get(bursts[i]);
+
+            if (entry === undefined || entry.node === null) {
+                continue;
+            }
+
+            if (particles.registry.context(entry.node) === undefined) {
+                continue;
+            }
+
+            particles.spawn(entry.node, bursts[i + 1]);
+        }
+
+        bursts.length = 0;
+    }
+
+    /**
+     * One entity's emitter, brought in line with its component.
+     *
+     * @param {ParticleEmitterEntry} entry
+     */
+    #sync(entry) {
+        const effect = entry.effect;
+
+        /*
+         Ahead of everything the effect gates, and deliberately: an image takes a fetch and a decode
+         to arrive, and an entity that names one has said what it wants to draw with whether or not
+         its program has finished compiling. Waiting would mean a first frame of transparent
+         particles for every effect that arrives with its texture.
+        */
+        if (entry.url !== effect.texture) {
+            this.#release(entry.url);
+
+            entry.url = effect.texture;
+            entry.texture = entry.url === null ? null : this.#acquire(entry.url);
+        }
+
+        if (effect.layout === null || effect.program === null) {
+            // No effect (yet, or any more). An entity whose effect is still compiling is ordinary,
+            // and so is one whose effect was cleared — both mean "emits nothing", and the emitter
+            // leaves the scene rather than keeping the last program it happened to have.
+            this.#detach_node(entry);
+
+            return;
+        }
+
+        if (entry.node === null) {
+            const node = new ParticleEmitter();
+
+            /*
+             The row takes the entity's name when it has one, exactly as `ShadedGeometrySystem` does
+             for a primitive. Nothing draws differently for it: what it buys is that a walk over what
+             is in the scene is readable in a debugger.
+            */
+            const name = this.entityManager.dataset.getComponent(entry.entity, Name);
+
+            node.name = name === undefined || name === null
+                ? `particles/entity ${entry.entity}`
+                : name.getValue();
+
+            entry.node = node;
+
+            apply_particle_effect(node, effect);
+
+            this.#place(entry);
+
+            this.#by_node.set(node, entry);
+            this.#scene.add(node);
+        } else if (apply_particle_effect(entry.node, effect)) {
+            // The node's own change counter, which is what EmitterRegistry restages a row from.
+            entry.node.needsUpdate = true;
+        }
+    }
+
+    /**
+     * @param {ParticleEmitterEntry} entry
+     */
+    #place(entry) {
+        const node = entry.node;
+
+        if (node === null) {
+            return;
+        }
+
+        node.transform_local.copy(entry.transform);
+
+        // recomputes transform_global down the subtree, and bumps the version the scene database
+        // reads to decide what to upload
+        node.updateMatrices();
+    }
+
+    /**
+     * Take an entity's emitter back out of the scene, leaving the entry linked.
+     *
+     * @param {ParticleEmitterEntry} entry
+     */
+    #detach_node(entry) {
+        const node = entry.node;
+
+        if (node === null) {
+            return;
+        }
+
+        this.#scene.remove(node);
+        this.#by_node.delete(node);
+
+        entry.node = null;
+    }
+
+    /**
+     * @param {number} entity
+     */
+    #drop(entity) {
+        const entry = this.#entries.get(entity);
+
+        if (entry === undefined) {
+            return;
+        }
+
+        if (entry.on_transform_changed !== null) {
+            this.entityManager.dataset.removeEntityEventListener(
+                entity, TRANSFORM64_EVENT_CHANGE, entry.on_transform_changed
+            );
+
+            entry.on_transform_changed = null;
+        }
+
+        this.#detach_node(entry);
+        this.#release(entry.url);
+
+        entry.url = null;
+        entry.texture = null;
+
+        this.#entries.delete(entity);
+    }
+
+    /** @returns {void} */
+    #create_defaults() {
+        const white = Sampler2D.uint8(4, 1, 1);
+
+        white.data.fill(255);
+
+        this.#white = this.atlas.add(white);
+        this.#transparent = this.atlas.add(Sampler2D.uint8(4, 1, 1));
+    }
+
+    /**
+     * @param {string} url
+     * @returns {ParticleAtlasTexture}
+     */
+    #acquire(url) {
+        let texture = this.#textures.get(url);
+
+        if (texture !== undefined) {
+            texture.references++;
+
+            return texture;
+        }
+
+        texture = { references: 1, patch: null };
+
+        this.#textures.set(url, texture);
+
+        this.#assets.promise(url, GameAssetType.Image).then(asset => {
+            // Removed, changed URL, or shut down while loading: the completion owns nothing now.
+            if (this.#textures.get(url) !== texture) {
+                return;
+            }
+
+            texture.patch = this.atlas.add(sampler2d_ensure_uint8_RGBA(asset.create()));
+        }).catch(error => {
+            if (this.#textures.get(url) === texture) {
+                console.warn(`GPU particle texture '${url}' could not be loaded`, error);
+            }
+        });
+
+        return texture;
+    }
+
+    /**
+     * @param {string|null} url
+     * @returns {void}
+     */
+    #release(url) {
+        if (url === null) {
+            return;
+        }
+
+        const texture = this.#textures.get(url);
+
+        if (texture === undefined || --texture.references !== 0) {
+            return;
+        }
+
+        this.#textures.delete(url);
+
+        if (texture.patch !== null) {
+            this.atlas.remove(texture.patch);
+        }
+    }
+
+    /**
+     * @param {GPUDevice} device
+     * @returns {void}
+     */
+    #upload(device) {
+        const source = this.atlas.sampler;
+
+        if (this.#device !== device || this.#texture === null) {
+            this.#texture?.destroy();
+
+            this.#device = device;
+            this.#texture = new GPUTextureContext(device);
+
+            const descriptor = this.#texture.descriptor;
+
+            descriptor.label = "particles/sprite atlas";
+            descriptor.format = "rgba8unorm";
+            descriptor.usage = GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST;
+
+            this.#uploaded_version = -1;
+        }
+
+        const texture = this.#texture;
+
+        if (texture.width !== source.width || texture.height !== source.height) {
+            texture.resize(source.width, source.height);
+
+            this.#uploaded_version = -1;
+        }
+
+        if (this.#uploaded_version !== source.version) {
+            device.queue.writeTexture({ texture: texture.gpu_texture }, source.data,
+                { bytesPerRow: source.width * 4 }, [source.width, source.height]);
+
+            texture.incrementVersion();
+
+            this.#uploaded_version = source.version;
+        }
+
+        this.#view = texture.obtainView();
+    }
+
+    /** @returns {void} */
+    #detach() {
+        if (this.#particles !== null && this.#particles.atlas === this.#view) {
+            this.#particles.atlas = this.#previous_atlas;
+
+            for (const emitter of this.#particles.emitters) {
+                this.#particles.registry.set_atlas_region(emitter, [0, 0, 1, 1]);
+            }
+        }
+
+        this.#particles = null;
+        this.#previous_atlas = null;
+    }
+}
+
+/**
+ * Copy a component onto the scene node built for it, reporting whether anything actually moved.
+ *
+ * Comparing while assigning rather than in a pass of its own is what makes change detection cost
+ * nothing extra: the fields have to be read to be written, and the only addition is an `||` per
+ * field. What it answers is whether the emitter's GPU row has to be restaged, and restaging one that
+ * has not changed is an upload per emitter per frame.
+ *
+ * `spawn_rate` comes from {@link ParticleEffect#effective_spawn_rate}, so an effect switched off
+ * with `emitting = false` reaches the GPU as a rate of zero and keeps its authored rate to come back
+ * to. Layout and program are shared by reference, never copied — two entities of one effect belong
+ * on one program id in the heap.
+ *
+ * @param {ParticleEmitter} node
+ * @param {ParticleEffect} effect
+ * @returns {boolean} whether the node differs from what it held before
+ */
+export function apply_particle_effect(node, effect) {
+    let changed = false;
+
+    changed = assign(node, "layout", effect.layout) || changed;
+    changed = assign(node, "program", effect.program) || changed;
+    changed = assign(node, "texture", effect.texture) || changed;
+    changed = assign(node, "seed", effect.seed) || changed;
+    changed = assign(node, "spawn_rate", effect.effective_spawn_rate) || changed;
+    changed = assign(node, "prewarm", effect.prewarm) || changed;
+    changed = assign(node, "flags", effect.flags) || changed;
+    changed = assign(node, "render_position", effect.render_position) || changed;
+    changed = assign(node, "render_size", effect.render_size) || changed;
+    changed = assign(node, "render_color", effect.render_color) || changed;
+    changed = assign(node, "render_rotation", effect.render_rotation) || changed;
+    changed = assign(node, "render_frame", effect.render_frame) || changed;
+    changed = assign(node, "render_velocity", effect.render_velocity) || changed;
+
+    const flipbook = node.flipbook;
+
+    if (flipbook[0] !== effect.flipbook[0] || flipbook[1] !== effect.flipbook[1]) {
+        flipbook.set(effect.flipbook);
+
+        changed = true;
+    }
+
+    return changed;
+}
+
+/**
+ * @param {object} target
+ * @param {string} field
+ * @param {*} value
+ * @returns {boolean} whether the field held something else
+ */
+function assign(target, field, value) {
+    if (target[field] === value) {
+        return false;
+    }
+
+    target[field] = value;
+
+    return true;
+}
+
+class GPUParticleAtlasExtension extends RenderExtension {
+    /** @type {string} */
+    name = "gpu particle atlas";
+    /** @type {FramePhase} */
+    phase = FramePhase.FrameStart;
+    /** @type {GPUParticleEmitterSystem} */
+    #system;
+
+    /** @param {GPUParticleEmitterSystem} system */
+    constructor(system) {
+        super();
+
+        this.#system = system;
+    }
+
+    /**
+     * @param {import("../../shade/renderer/extension/FrameContext.js").FrameContext} frame
+     * @returns {void}
+     */
+    record(frame) {
+        this.#system.prepare(frame);
+    }
+}