@woosh/meep-engine 3.53.0 → 3.54.0

package/src/engine/graphics3/GPUParticleEmitterSystem.js

@@ -1,808 +1,749 @@
-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 { row_of_entity } from "../../shade/renderer/scene/rows/GPUSceneRows.js";
-import { GameAssetType } from "../asset/GameAssetType.js";
-import { ImageRGBADataLoader } from "../asset/loaders/image/ImageRGBADataLoader.js";
-import { ParticleEffect } from "../graphics/ecs/particles/ParticleEffect.js";
-import { DecalAtlas } from "./decal/DecalAtlas.js";
-import { DecalAtlasFill } from "./decal/DecalAtlasFill.js";
-import { TextureFilterType } from "../../shade/renderer/texture/TextureFilterType.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} emitter the emitter, once the effect has a program to run
- * @property {import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext|null} context
- * the scene context the emitter is registered with, at the entity's row; null until a frame has
- * registered it, or after a device restart took that context away
- * @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} per entity and owns it: the emitter is registered with the
- * scene's particle system at the entity's row when the component has a compiled effect, so it
- * stands where the entity stands, carries whatever the component currently says, and is retired
- * when the entity goes. The emitter is not hidden — {@link emitter_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 emitter, and the emitter 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 in this scene that this system did not build — one registered with the particle
- * system 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.
- */
-export class GPUParticleEmitterSystem extends System {
-    dependencies = [ParticleEffect, Transform64];
-
-    /**
-     * CPU atlas, exposed for inspection. Owned by this system.
-     * @type {TextureAtlas}
-     */
-    atlas = new DecalAtlas(DecalAtlasFill.EdgeExtend, 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 emitter 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_emitter = 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 emitters this system currently holds, in no particular order. Read-only — they follow
-     * the entities.
-     *
-     * @returns {ParticleEmitter[]}
-     */
-    get emitters() {
-        return Array.from(this.#by_emitter.keys());
-    }
-
-    /**
-     * The emitter built for an entity.
-     *
-     * Handed out for what an entity reference cannot express — asking the particle system about
-     * it — and for nothing routine: the component is how an effect is changed, and an emitter
-     * 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
-     */
-    emitter_of(entity) {
-        const entry = this.#entries.get(entity);
-
-        if (entry === undefined) {
-            return null;
-        }
-
-        return entry.emitter;
-    }
-
-    /**
-     * 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;
-
-        // the scene's rows are this dataset's entities; the first system to place one says so
-        const dataset = entityManager.dataset;
-        const scene = this.#scene;
-
-        assert.ok(
-            scene.dataset === null || scene.dataset === undefined || scene.dataset === dataset,
-            'the scene is bound to another dataset'
-        );
-
-        scene.dataset = dataset;
-
-        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,
-            emitter: null,
-            context: 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 emitter, 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);
-
-        // Registered now when there is a context to register with, so an entity spawned mid-level
-        // stands where it should from its first frame.
-        this.#register_all();
-    }
-
-    /**
-     * @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 emitters for effects that have arrived,
-     * retire emitters 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);
-        }
-
-        /*
-         Registered here as well as at FrameStart, so an emitter whose effect arrived during a
-         simulation tick has its row written by the next frame's build rather than the one after:
-         a frame builds the scene context before FrameStart runs, so a row acquired at FrameStart
-         is not written until the frame after.
-        */
-        this.#register_all();
-
-        this.atlas.update();
-    }
-
-    /**
-     * The particle system a scene context's frames run, or null while there is no renderer.
-     *
-     * @param {import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} context
-     * @returns {import("../../shade/renderer/particles/GPUParticleSystem.js").GPUParticleSystem|null}
-     */
-    #particles_of(context) {
-        const renderer = this.#graphics.renderer;
-
-        if (renderer === null || renderer === undefined) {
-            return null;
-        }
-
-        return renderer.particles(context);
-    }
-
-    /**
-     * {@link #register} against whatever context and particle system the scene has right now, if
-     * it has any.
-     */
-    #register_all() {
-        const context = this.#graphics.scene_context(this.#scene);
-
-        if (context === null) {
-            return;
-        }
-
-        const particles = this.#particles_of(context);
-
-        if (particles !== null) {
-            this.#register(particles, context);
-        }
-    }
-
-    /**
-     * 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;
-        }
-
-        this.#register(particles, frame.view.scene);
-
-        this.#upload(renderer.graphics);
-
-        particles.atlas = this.#view;
-
-        this.#publish_regions(particles);
-        this.#drain_bursts(particles);
-    }
-
-    /**
-     * Register every emitter not yet registered with this context, at its entity's row.
-     *
-     * From {@link update} and {@link prepare} rather than at link, because a row needs a scene
-     * context and the context needs a device, and neither is a system's to wait for: a level loads
-     * before the device is up, and a device restart replaces the context under every entry. An
-     * entry registered with a context that is no longer this one is registered again with the one
-     * that is. Idempotent, and a comparison per entry when nothing has changed.
-     *
-     * @param {import("../../shade/renderer/particles/GPUParticleSystem.js").GPUParticleSystem} particles
-     * @param {import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} scene_context
-     */
-    #register(particles, scene_context) {
-        const rows = scene_context.rows;
-
-        for (const entry of this.#entries.values()) {
-            if (entry.emitter === null || entry.context === scene_context) {
-                continue;
-            }
-
-            rows.acquire(entry.entity);
-
-            particles.add_emitter(entry.emitter, row_of_entity(entry.entity));
-
-            entry.context = scene_context;
-        }
-    }
-
-    /**
-     * 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_emitter.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.emitter === null) {
-                continue;
-            }
-
-            if (particles.registry.context(entry.emitter) === undefined) {
-                continue;
-            }
-
-            particles.spawn(entry.emitter, 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
-            // is retired rather than keeping the last program it happened to have.
-            this.#detach_emitter(entry);
-
-            return;
-        }
-
-        if (entry.emitter === null) {
-            const emitter = new ParticleEmitter();
-
-            /*
-             The emitter 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
-             the registry is readable in a debugger.
-            */
-            const name = this.entityManager.dataset.getComponent(entry.entity, Name);
-
-            emitter.name = name === undefined || name === null
-                ? `particles/entity ${entry.entity}`
-                : name.getValue();
-
-            entry.emitter = emitter;
-
-            apply_particle_effect(emitter, effect);
-
-            // registered at the entity's row by the next frame — see #register
-            this.#by_emitter.set(emitter, entry);
-        } else if (apply_particle_effect(entry.emitter, effect)) {
-            // The emitter's own change counter, which is what EmitterRegistry restages a row from.
-            entry.emitter.needsUpdate = true;
-        }
-    }
-
-    /**
-     * The entity moved: its row is rewritten from its transform by the context that holds it.
-     *
-     * @param {ParticleEmitterEntry} entry
-     */
-    #place(entry) {
-        const context = entry.context;
-
-        if (context === null || context !== this.#graphics.scene_context(this.#scene)) {
-            return;
-        }
-
-        context.rows.mark_world(entry.entity);
-    }
-
-    /**
-     * Retire an entity's emitter and let go of its row, leaving the entry linked.
-     *
-     * @param {ParticleEmitterEntry} entry
-     */
-    #detach_emitter(entry) {
-        const emitter = entry.emitter;
-
-        if (emitter === null) {
-            return;
-        }
-
-        const context = entry.context;
-
-        // A context that has been replaced took its rows and its particle system with it; only the
-        // one that is running is handed anything back.
-        if (context !== null && context === this.#graphics.scene_context(this.#scene)) {
-            const particles = this.#particles_of(context);
-
-            if (particles !== null && particles.registry.context(emitter) !== undefined) {
-                particles.remove_emitter(emitter);
-            }
-
-            context.rows.release(entry.entity);
-        }
-
-        entry.context = null;
-
-        this.#by_emitter.delete(emitter);
-
-        entry.emitter = 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_emitter(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}
-     */
+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 { row_of_entity } from "../../shade/renderer/scene/rows/GPUSceneRows.js";
+import { GameAssetType } from "../asset/GameAssetType.js";
+import { ImageRGBADataLoader } from "../asset/loaders/image/ImageRGBADataLoader.js";
+import { ParticleEffect } from "../graphics/ecs/particles/ParticleEffect.js";
+import { ManagedAtlas } from "../graphics/texture/atlas/ManagedTextureAtlas.js";
+import { SpriteAtlas } from "../graphics/texture/atlas/SpriteAtlas.js";
+import { SpriteAtlasFill } from "../graphics/texture/atlas/SpriteAtlasFill.js";
+import { TextureFilterType } from "../../shade/renderer/texture/TextureFilterType.js";
+import { Sampler2D } from "../graphics/texture/sampler/Sampler2D.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} 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} emitter the emitter, once the effect has a program to run
+ * @property {import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext|null} context
+ * the scene context the emitter is registered with, at the entity's row; null until a frame has
+ * registered it, or after a device restart took that context away
+ * @property {function():void} on_transform_changed
+ * @property {string|null} url last observed {@link ParticleEffect#texture}
+ * @property {import("../graphics/texture/atlas/ManagedTextureAtlas.js").ManagedAtlasReference|null} texture shared image reference, 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} per entity and owns it: the emitter is registered with the
+ * scene's particle system at the entity's row when the component has a compiled effect, so it
+ * stands where the entity stands, carries whatever the component currently says, and is retired
+ * when the entity goes. The emitter is not hidden — {@link emitter_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 emitter, and the emitter 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 SpriteAtlas} shared by the scene, one patch per distinct URL however many entities
+ * name it, reference-counted through {@link ManagedAtlas} so unreferenced sprites remain in the
+ * atlas graveyard and are only reaped when incoming sprites need the space. 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 in this scene that this system did not build — one registered with the particle
+ * system 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.
+ */
+export class GPUParticleEmitterSystem extends System {
+    dependencies = [ParticleEffect, Transform64];
+
+    /**
+     * CPU atlas, exposed for inspection. Owned by this system.
+     * @type {SpriteAtlas}
+     */
+    atlas = new SpriteAtlas(SpriteAtlasFill.EdgeExtend, 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 emitter 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_emitter = new Map();
+    /** @type {ManagedAtlas} */
+    #managed_atlas;
+    /**
+     * 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.#managed_atlas = new ManagedAtlas({
+            assetManager: this.#assets,
+            atlas: this.atlas
+        });
+
+        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 emitters this system currently holds, in no particular order. Read-only — they follow
+     * the entities.
+     *
+     * @returns {ParticleEmitter[]}
+     */
+    get emitters() {
+        return Array.from(this.#by_emitter.keys());
+    }
+
+    /**
+     * The emitter built for an entity.
+     *
+     * Handed out for what an entity reference cannot express — asking the particle system about
+     * it — and for nothing routine: the component is how an effect is changed, and an emitter
+     * 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
+     */
+    emitter_of(entity) {
+        const entry = this.#entries.get(entity);
+
+        if (entry === undefined) {
+            return null;
+        }
+
+        return entry.emitter;
+    }
+
+    /**
+     * 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;
+
+        // the scene's rows are this dataset's entities; the first system to place one says so
+        const dataset = entityManager.dataset;
+        const scene = this.#scene;
+
+        assert.ok(
+            scene.dataset === null || scene.dataset === undefined || scene.dataset === dataset,
+            'the scene is bound to another dataset'
+        );
+
+        scene.dataset = dataset;
+
+        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;
+
+        this.#managed_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,
+            emitter: null,
+            context: 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 emitter, 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);
+
+        // Registered now when there is a context to register with, so an entity spawned mid-level
+        // stands where it should from its first frame.
+        this.#register_all();
+    }
+
+    /**
+     * @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 emitters for effects that have arrived,
+     * retire emitters 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);
+        }
+
+        /*
+         Registered here as well as at FrameStart, so an emitter whose effect arrived during a
+         simulation tick has its row written by the next frame's build rather than the one after:
+         a frame builds the scene context before FrameStart runs, so a row acquired at FrameStart
+         is not written until the frame after.
+        */
+        this.#register_all();
+
+        this.#managed_atlas.update();
+    }
+
+    /**
+     * The particle system a scene context's frames run, or null while there is no renderer.
+     *
+     * @param {import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} context
+     * @returns {import("../../shade/renderer/particles/GPUParticleSystem.js").GPUParticleSystem|null}
+     */
+    #particles_of(context) {
+        const renderer = this.#graphics.renderer;
+
+        if (renderer === null || renderer === undefined) {
+            return null;
+        }
+
+        return renderer.particles(context);
+    }
+
+    /**
+     * {@link #register} against whatever context and particle system the scene has right now, if
+     * it has any.
+     */
+    #register_all() {
+        const context = this.#graphics.scene_context(this.#scene);
+
+        if (context === null) {
+            return;
+        }
+
+        const particles = this.#particles_of(context);
+
+        if (particles !== null) {
+            this.#register(particles, context);
+        }
+    }
+
+    /**
+     * 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;
+        }
+
+        this.#register(particles, frame.view.scene);
+
+        this.#upload(renderer.graphics);
+
+        particles.atlas = this.#view;
+
+        this.#publish_regions(particles);
+        this.#drain_bursts(particles);
+    }
+
+    /**
+     * Register every emitter not yet registered with this context, at its entity's row.
+     *
+     * From {@link update} and {@link prepare} rather than at link, because a row needs a scene
+     * context and the context needs a device, and neither is a system's to wait for: a level loads
+     * before the device is up, and a device restart replaces the context under every entry. An
+     * entry registered with a context that is no longer this one is registered again with the one
+     * that is. Idempotent, and a comparison per entry when nothing has changed.
+     *
+     * @param {import("../../shade/renderer/particles/GPUParticleSystem.js").GPUParticleSystem} particles
+     * @param {import("../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} scene_context
+     */
+    #register(particles, scene_context) {
+        const rows = scene_context.rows;
+
+        for (const entry of this.#entries.values()) {
+            if (entry.emitter === null || entry.context === scene_context) {
+                continue;
+            }
+
+            rows.acquire(entry.entity);
+
+            particles.add_emitter(entry.emitter, row_of_entity(entry.entity));
+
+            entry.context = scene_context;
+        }
+    }
+
+    /**
+     * 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_emitter.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.getValue() ?? 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.emitter === null) {
+                continue;
+            }
+
+            if (particles.registry.context(entry.emitter) === undefined) {
+                continue;
+            }
+
+            particles.spawn(entry.emitter, 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) {
+            entry.texture?.release();
+
+            entry.url = effect.texture;
+            entry.texture = entry.url === null ? null : this.#managed_atlas.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
+            // is retired rather than keeping the last program it happened to have.
+            this.#detach_emitter(entry);
+
+            return;
+        }
+
+        if (entry.emitter === null) {
+            const emitter = new ParticleEmitter();
+
+            /*
+             The emitter 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
+             the registry is readable in a debugger.
+            */
+            const name = this.entityManager.dataset.getComponent(entry.entity, Name);
+
+            emitter.name = name === undefined || name === null
+                ? `particles/entity ${entry.entity}`
+                : name.getValue();
+
+            entry.emitter = emitter;
+
+            apply_particle_effect(emitter, effect);
+
+            // registered at the entity's row by the next frame — see #register
+            this.#by_emitter.set(emitter, entry);
+        } else if (apply_particle_effect(entry.emitter, effect)) {
+            // The emitter's own change counter, which is what EmitterRegistry restages a row from.
+            entry.emitter.needsUpdate = true;
+        }
+    }
+
+    /**
+     * The entity moved: its row is rewritten from its transform by the context that holds it.
+     *
+     * @param {ParticleEmitterEntry} entry
+     */
+    #place(entry) {
+        const context = entry.context;
+
+        if (context === null || context !== this.#graphics.scene_context(this.#scene)) {
+            return;
+        }
+
+        context.rows.mark_world(entry.entity);
+    }
+
+    /**
+     * Retire an entity's emitter and let go of its row, leaving the entry linked.
+     *
+     * @param {ParticleEmitterEntry} entry
+     */
+    #detach_emitter(entry) {
+        const emitter = entry.emitter;
+
+        if (emitter === null) {
+            return;
+        }
+
+        const context = entry.context;
+
+        // A context that has been replaced took its rows and its particle system with it; only the
+        // one that is running is handed anything back.
+        if (context !== null && context === this.#graphics.scene_context(this.#scene)) {
+            const particles = this.#particles_of(context);
+
+            if (particles !== null && particles.registry.context(emitter) !== undefined) {
+                particles.remove_emitter(emitter);
+            }
+
+            context.rows.release(entry.entity);
+        }
+
+        entry.context = null;
+
+        this.#by_emitter.delete(emitter);
+
+        entry.emitter = 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_emitter(entry);
+        entry.texture?.release();
+
+        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 {import("../../shade/renderer/GPUDeviceContext.js").GPUDeviceContext} graphics
+     * @returns {void}
+     */
     #upload(graphics) {
-        const device = graphics.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";
+        const device = graphics.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
-                | GPUTextureUsage.RENDER_ATTACHMENT;
-
-            this.#uploaded_version = -1;
-        }
-
-        const texture = this.#texture;
-
-        if (texture.width !== source.width || texture.height !== source.height) {
+                | GPUTextureUsage.RENDER_ATTACHMENT;
+
+            this.#uploaded_version = -1;
+        }
+
+        const texture = this.#texture;
+
+        if (texture.width !== source.width || texture.height !== source.height) {
             texture.descriptor.mipLevelCount = 1 + Math.floor(Math.log2(Math.max(source.width, 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.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]);
+
             if (texture.descriptor.mipLevelCount > 1) {
                 graphics.textures.mipmaps.generateMipmap(
                     texture.gpu_texture,
@@ -811,153 +752,153 @@ export class GPUParticleEmitterSystem extends System {
                 );
             }
 
-            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 emitter 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.
- *
- * Every field is compared by name, and that is load-bearing rather than style. Through a shared
- * `assign(target, field, value)` the one `target[field]` access saw all thirteen names, went
- * megamorphic, and read numbers back boxed, while the call boxed the value it was handed: 228 B and
- * ~120 ns per emitter per call, against nothing and ~9 ns written out like this
- * (`GPUParticleEmitterSystem.allocation.spec.js`). This runs for every live emitter twice a frame.
- *
- * @param {ParticleEmitter} emitter
- * @param {ParticleEffect} effect
- * @returns {boolean} whether the emitter differs from what it held before
- */
-export function apply_particle_effect(emitter, effect) {
-    let changed = false;
-
-    if (emitter.layout !== effect.layout) {
-        emitter.layout = effect.layout;
-        changed = true;
-    }
-
-    if (emitter.program !== effect.program) {
-        emitter.program = effect.program;
-        changed = true;
-    }
-
-    if (emitter.texture !== effect.texture) {
-        emitter.texture = effect.texture;
-        changed = true;
-    }
-
-    if (emitter.seed !== effect.seed) {
-        emitter.seed = effect.seed;
-        changed = true;
-    }
-
-    const spawn_rate = effect.effective_spawn_rate;
-
-    if (emitter.spawn_rate !== spawn_rate) {
-        emitter.spawn_rate = spawn_rate;
-        changed = true;
-    }
-
-    if (emitter.prewarm !== effect.prewarm) {
-        emitter.prewarm = effect.prewarm;
-        changed = true;
-    }
-
-    if (emitter.flags !== effect.flags) {
-        emitter.flags = effect.flags;
-        changed = true;
-    }
-
-    if (emitter.render_position !== effect.render_position) {
-        emitter.render_position = effect.render_position;
-        changed = true;
-    }
-
-    if (emitter.render_size !== effect.render_size) {
-        emitter.render_size = effect.render_size;
-        changed = true;
-    }
-
-    if (emitter.render_color !== effect.render_color) {
-        emitter.render_color = effect.render_color;
-        changed = true;
-    }
-
-    if (emitter.render_orientation !== effect.render_orientation) {
-        emitter.render_orientation = effect.render_orientation;
-        changed = true;
-    }
-
-    if (emitter.render_frame !== effect.render_frame) {
-        emitter.render_frame = effect.render_frame;
-        changed = true;
-    }
-
-    if (emitter.render_velocity !== effect.render_velocity) {
-        emitter.render_velocity = effect.render_velocity;
-        changed = true;
-    }
-
-    const flipbook = emitter.flipbook;
-
-    if (flipbook[0] !== effect.flipbook[0] || flipbook[1] !== effect.flipbook[1]) {
-        flipbook.set(effect.flipbook);
-
-        changed = true;
-    }
-
-    return changed;
-}
-
-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);
-    }
-}
+            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 emitter 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.
+ *
+ * Every field is compared by name, and that is load-bearing rather than style. Through a shared
+ * `assign(target, field, value)` the one `target[field]` access saw all thirteen names, went
+ * megamorphic, and read numbers back boxed, while the call boxed the value it was handed: 228 B and
+ * ~120 ns per emitter per call, against nothing and ~9 ns written out like this
+ * (`GPUParticleEmitterSystem.allocation.spec.js`). This runs for every live emitter twice a frame.
+ *
+ * @param {ParticleEmitter} emitter
+ * @param {ParticleEffect} effect
+ * @returns {boolean} whether the emitter differs from what it held before
+ */
+export function apply_particle_effect(emitter, effect) {
+    let changed = false;
+
+    if (emitter.layout !== effect.layout) {
+        emitter.layout = effect.layout;
+        changed = true;
+    }
+
+    if (emitter.program !== effect.program) {
+        emitter.program = effect.program;
+        changed = true;
+    }
+
+    if (emitter.texture !== effect.texture) {
+        emitter.texture = effect.texture;
+        changed = true;
+    }
+
+    if (emitter.seed !== effect.seed) {
+        emitter.seed = effect.seed;
+        changed = true;
+    }
+
+    const spawn_rate = effect.effective_spawn_rate;
+
+    if (emitter.spawn_rate !== spawn_rate) {
+        emitter.spawn_rate = spawn_rate;
+        changed = true;
+    }
+
+    if (emitter.prewarm !== effect.prewarm) {
+        emitter.prewarm = effect.prewarm;
+        changed = true;
+    }
+
+    if (emitter.flags !== effect.flags) {
+        emitter.flags = effect.flags;
+        changed = true;
+    }
+
+    if (emitter.render_position !== effect.render_position) {
+        emitter.render_position = effect.render_position;
+        changed = true;
+    }
+
+    if (emitter.render_size !== effect.render_size) {
+        emitter.render_size = effect.render_size;
+        changed = true;
+    }
+
+    if (emitter.render_color !== effect.render_color) {
+        emitter.render_color = effect.render_color;
+        changed = true;
+    }
+
+    if (emitter.render_orientation !== effect.render_orientation) {
+        emitter.render_orientation = effect.render_orientation;
+        changed = true;
+    }
+
+    if (emitter.render_frame !== effect.render_frame) {
+        emitter.render_frame = effect.render_frame;
+        changed = true;
+    }
+
+    if (emitter.render_velocity !== effect.render_velocity) {
+        emitter.render_velocity = effect.render_velocity;
+        changed = true;
+    }
+
+    const flipbook = emitter.flipbook;
+
+    if (flipbook[0] !== effect.flipbook[0] || flipbook[1] !== effect.flipbook[1]) {
+        flipbook.set(effect.flipbook);
+
+        changed = true;
+    }
+
+    return changed;
+}
+
+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);
+    }
+}