@woosh/meep-engine 3.23.0 → 3.24.0

package/src/shade/renderer/particles/DESIGN.md

@@ -3,8 +3,8 @@
 A specialized, deeply-integrated, GPU-driven particle engine for the v2 renderer.
 Destiny-style: **one** simulation dispatch runs **all** particles of **all** emitters by
 interpreting a compact per-emitter bytecode program (a shader VM). Effects are authored as
-node graphs and lowered to that bytecode by a testable JS compiler. Emitters are scene nodes, and
-the decision to spawn is the GPU's.
+node graphs and lowered to that bytecode by a testable JS compiler. Emitters run at entities'
+rows, and the decision to spawn is the GPU's.
 
 ## Goals (from the brief)
 
@@ -18,8 +18,8 @@ the decision to spawn is the GPU's.
 - Texture lookup via atlas (region table; mirrors meep `AtlasPatch` uv offset/scale).
 - Soft-depth fade (flagged).
 - `GPUDatabase` for CPU-managed, low-churn tables (emitters).
-- Scene-node / bone attachment: an emitter **is** a `Node3D`; its world matrix is its row of the
-  scene's `transforms` table, composed by the GPU hierarchy pass.
+- Scene / bone attachment: an emitter stands at an entity with a row; its world matrix is that row
+  of the scene's `transforms` table, composed by the GPU hierarchy pass.
 - Distinct per-particle lifecycle: **no** built-in age/position — the schema + program define state.
 - Billboard drawing reuses engine shader chunks incl. lighting (forward-shaded, optional per emitter).
 - Blend modes (alpha + additive) via a **single** premultiplied blend setup.
@@ -33,7 +33,7 @@ the decision to spawn is the GPU's.
 authoring:   NodeGraph (nodes+ports)      ──compile──▶  Program (bytecode: INIT + UPDATE)
              standard node library                       │
                                                          ▼
-runtime CPU: ParticleEmitter (a Node3D) ── Scene ──▶ GPUSceneContext (transforms table)
+runtime CPU: ParticleEmitter (at an entity) ── Scene ──▶ GPUSceneContext (transforms table)
              EmitterRegistry ── GPUDatabase(emitters + emitter_state) ─┤  ProgramHeap ([header][constants][code])
              GPUParticleSystem (owns every buffer, records the frame)
                                                          ▼
@@ -222,33 +222,32 @@ disk/cone), authored curves and RGB/RGBA gradients, noise (curl), integrate, gra
 compare/select, kill-if. Curves and gradients expand into graph nodes that emit ordinary VM
 arithmetic; no animation-table binding or sampling opcode is needed.
 
-### Emitters are scene nodes
-
-`ParticleEmitter extends Node3D`. Add one to a `Scene` — on its own or under a joint — and the
-scene context's membership sweep gives it a `transforms` row like any node; the GPU hierarchy pass
-composes its `global` from its own transform and its parents' every frame, animation included.
-`GPUParticleSystem` sweeps the scene's node list when the scene's membership version moves, gives
-each emitter node a row in the emitter table pointed at its `transforms` row, and retires the row
-when the node leaves. Attaching an emitter to a bone is `joint.addChild(emitter)`; there is no
-per-frame transform copy, and an emitter under a GPU-animated joint follows it — which the old
-CPU-side copy of `transform_global` could not do, since the CPU never updates that matrix for a
-node the GPU owns.
-
-**The node knows nothing about the GPU.** A `ParticleEmitter` is a transform, an attribute
-`layout`, a compiled `program`, a `texture` URL, and the emission parameters — all of it the
-author's, all of it meaning the same thing with no device present, all of it what a saved effect is
-made of. Everything the system assigns is a `GPUParticleEmitterContext`, held by the
+### Emitters run at entities' rows
+
+A `ParticleEmitter` is placed by registration: `GPUParticleSystem#add_emitter(emitter,
+transform_row)` gives it a row in the emitter table pointed at a `transforms` row — an entity's,
+one on, held through the scene context's rows by whoever owns the entity — and `remove_emitter`
+retires the row and frees its particles. The GPU hierarchy pass composes that row's `global` from
+its pose and its parents' every frame, animation included, so an emitter registered at a joint's
+row follows the joint with nothing copied through the CPU — which a CPU-side copy of a world
+matrix could not do, since the CPU never sees the matrix of a row the GPU owns. Nothing walks the
+scene: an emitter is where its owner says it is, and per-frame upkeep is proportional to what
+changed rather than to how many emitters there are.
+
+**The emitter knows nothing about the GPU, and nothing about where.** A `ParticleEmitter` is an
+attribute `layout`, a compiled `program`, a `texture` URL, and the emission parameters — all of
+it the author's, all of it meaning the same thing with no device present, all of it what a saved
+effect is made of. Everything the system assigns is a `GPUParticleEmitterContext`, held by the
 `EmitterRegistry` against the emitter and reached through `registry.context(emitter)`: the table
-row, the generation, the program placement, the node's `transforms` row, the atlas patch. So an
-emitter cannot be saved with a row in it, cannot be given one by hand, and "is this emitter live?"
-is asked of the registry rather than read off a `-1` that anything could have written. The record
-writer is where the two meet — `write_emitter_record(record, emitter, context)`, next to the struct
-it fills.
-
-Restaging is driven by `Node3D#version`, the node's own change counter, which the renderer already
-reads to decide whether a transform needs re-uploading; the context remembers the version its row
-was staged from. An author who edits an emitter says so the way they say it for any node —
-`needsUpdate = true` — and there is no second flag to forget. A change to the context itself (a
+row, the generation, the program placement, the `transforms` row it is placed at, the atlas patch.
+So an emitter cannot be saved with a row in it, cannot be given one by hand, and "is this emitter
+live?" is asked of the registry rather than read off a `-1` that anything could have written. The
+record writer is where the two meet — `write_emitter_record(record, emitter, context)`, next to
+the struct it fills.
+
+Restaging is driven by `ParticleEmitter#version`, the emitter's own change counter; the context
+remembers the version its row was staged from. An author who edits an emitter says so with
+`needsUpdate = true`, and there is no second flag to forget. A change to the context itself (a
 `transforms` row, a repacked atlas patch) moves no version, so the context marks itself instead.
 
 ### Emitter table (`GPUDatabase`)
@@ -450,7 +449,7 @@ An emitter that sets `EMITTER_FLAG.CULL` has the box on its state row tested aga
 frustum by the tick pass, with the renderer's shared `chunk_aabb3_intersects_frustum`. The tick does
 not measure it — it reads what the bounds passes published at the end of the previous frame — so all
 that is in the spawn path is one frustum test. Because the box is where the particles are rather
-than where the node is, an effect whose particles have drifted on screen keeps spawning even when
+than where the emitter is, an effect whose particles have drifted on screen keeps spawning even when
 its emitter has not. Culled emitters spawn nothing and accrue sleep; on wake the tick adds a
 catch-up of at most `max_catchup_seconds` of rate. Live particles keep simulating while their
 emitter is culled, so its box keeps moving and keeps being published. HiZ occlusion is not
@@ -595,22 +594,25 @@ compared and hashed in (`ParticleProgram#constant_words`): `-0` and `+0` are the
 different constants, and whether a NaN's payload survives a round trip through a JS `number` is
 implementation-defined even though V8 happens to preserve it.
 
-The system builds one `ParticleEmitter` scene node per linked entity and owns it — placed from the
-entity's transform on `TRANSFORM64_EVENT_CHANGE`, added to the scene when the component has a
-compiled effect, and retired with the entity. `node_of(entity)` hands the node out for the things an
-entity reference cannot express (parenting to the emitter, reading the composed world matrix);
-`burst(entity, count)` is the entity-addressed one-shot, queued and drained after the frame's
-membership sweep so it works before the first frame has run.
+The system builds one `ParticleEmitter` per linked entity and owns it — registered with the
+scene's particle system at the entity's row (`row_of_entity`, held through the scene context's
+rows) when the component has a compiled effect and a context exists, its row marked from the
+entity's transform on `TRANSFORM64_EVENT_CHANGE`, and retired with the entity. Registration runs at
+link, at every `update` and at `FrameStart`, so an entity spawned mid-level stands where it should
+from its first frame and a device restart re-registers every entry with the context that replaced
+the old one. `emitter_of(entity)` hands the emitter out for what an entity reference cannot express
+(asking the particle system about it); `burst(entity, count)` is the entity-addressed one-shot,
+queued and drained inside the frame so it works before the first frame has run.
 
 Component 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, so a component nobody touched costs a run of integer comparisons and no upload.
-That is what lets gameplay write `effect.spawn_rate = 0` from code that has never heard of this
-system.
+fields are compared against what was last written to its emitter, and the emitter is marked dirty
+only where they differ, so a component nobody touched costs a run of integer comparisons and no
+upload. That is what lets gameplay write `effect.spawn_rate = 0` from code that has never heard of
+this system.
 
-`GPUParticleSystem` itself still finds emitters by sweeping the scene's node list, so a caller with
-no ECS — a playground, a tool — can build `ParticleEmitter` nodes and add them to a `Scene` directly.
-Such an emitter has nothing in the ECS system's atlas and is given the white texel; see below.
+A caller with no ECS — a playground, a tool — registers a `ParticleEmitter` with the scene's
+`GPUParticleSystem` directly, at a row of an entity it placed itself. Such an emitter has nothing
+in the ECS system's atlas and is given the white texel; see below.
 
 `shade/playground/particle_ecs/` is the worked example: a bonfire whose flame, smoke, embers and soot
 are four entities, alongside `ShadedGeometry` and `Light` entities in the same scene.
@@ -621,10 +623,11 @@ an image, its patch is removed. Loads completing after a URL change, removal or
 Failed images are reported and remain transparent until the URL changes or the emitter is re-added.
 Untextured emitters use a white texel; pending images use a transparent texel.
 
-At `FrameStart`, after the scene context has established transform rows, the system calls
-`GPUParticleSystem.sync_membership()`, uploads changed atlas pixels, and refreshes the patch region of
-every emitter in the scene — the ones it built get their entity's image, and any other gets the white
-texel, because the atlas is the scene's and an emitter it did not build has nothing in it.
+At `FrameStart`, after the scene context has established transform rows, the system registers
+any emitter not yet registered with the frame's context, uploads changed atlas pixels, and refreshes
+the patch region of every emitter the particle system holds — the ones it built get their entity's
+image, and any other gets the white texel, because the atlas is the scene's and an emitter it did
+not build has nothing in it.
 This occurs before particle simulation stages emitter rows. Every repack or resize therefore updates
 existing emitters too. The extension enables the renderer's GPU particle feature for its scene;
 rendering uses the existing AVBOIT path. The system owns a `GPUTextureContext` for the atlas, using
@@ -691,7 +694,7 @@ src/shade/renderer/particles/
   coherence/graph_particle_bucket.js     frame-graph wiring, around graph_prefix_scan_csdldf
   runtime/ProgramHeap.js             the one packed [header][constants][code] buffer, allocator-backed
   runtime/ProgramPlacement.js        where one program sits in it — what an emitter record carries
-  runtime/ParticleEmitter.js         one emitter — a Node3D and an effect, with no GPU in it
+  runtime/ParticleEmitter.js         one emitter — authoring data for an effect, with no GPU in it
   runtime/GPUParticleEmitterContext.js  what a registry assigns one: row, generation, placement, patch
   runtime/EmitterRegistry.js         GPUDatabase(emitters) + the live emitters + their contexts + the program heap
   runtime/create_particle_effect.js  layout + INIT/UPDATE graphs → compiled effect

package/src/shade/renderer/particles/GPUParticleSystem.d.ts

@@ -53,14 +53,14 @@
  * effects it holds and this is where that number meets the VM's; nothing about authoring a graph has
  * a register ceiling.
  *
- * ## Emitters are scene nodes
+ * ## Emitters are registered at rows
  *
- * There is no `addEmitter`. A {@link ParticleEmitter} is a {@link Node3D}: put it in the scene —
- * on its own or under a joint — and the next {@link execute} finds it in the scene's node list,
- * gives it a row in the emitter table pointed at the `transforms` row the scene context gave the
- * node, and it starts spawning. Take it out of the scene and its row is retired and its particles
- * freed. The sweep runs only when the scene's membership version moves, which is how per-frame
- * upkeep stays proportional to what changed rather than to how many emitters there are.
+ * {@link add_emitter} gives a {@link ParticleEmitter} a row in the emitter table pointed at a
+ * `transforms` row — an entity's, one on, held through the scene context's rows by whoever owns
+ * the entity — and it starts spawning on the next {@link execute}; under a joint's row it moves
+ * with the joint. {@link remove_emitter} retires the row and frees its particles. Nothing here
+ * walks the scene: an emitter is where its owner says it is, and per-frame upkeep is proportional
+ * to what changed rather than to how many emitters there are.
  *
  * ## Spawning is the GPU's decision
  *
@@ -108,7 +108,8 @@ export class GPUParticleSystem {
      */
     graphics: object;
     /**
-     * The scene whose nodes the emitters are, and whose database their world matrices come from.
+     * The scene whose rows the emitters are placed at, and whose database their world matrices
+     * come from.
      * @type {import("../scene/GPUSceneContext.js").GPUSceneContext}
      */
     scene_context: import("../scene/GPUSceneContext.js").GPUSceneContext;
@@ -202,7 +203,7 @@ export class GPUParticleSystem {
      * theirs.
      *
      * Call after the scene context has built for the frame (`GPUSceneContext#update`), so every
-     * emitter node has its `transforms` row, and after the hierarchy pass has run, so the rows'
+     * emitter's `transforms` row is uploaded, and after the hierarchy pass has run, so the rows'
      * `global` matrices are this frame's.
      *
      * **Once per frame, not once per view.** This advances the simulation by `dt` and hands out
@@ -304,16 +305,29 @@ export class GPUParticleSystem {
         emission: number;
     };
     /**
-     * Bring the emitter set in line with the scene: emitter nodes that arrived get rows, nodes that
-     * left give theirs back. Runs only when the scene's membership version has moved.
+     * Register an emitter at a `transforms` row, and if it asks, warm it up before its first frame.
      *
-     * A node the scene context has not placed yet (no `transforms` row) is left for the next frame,
-     * and the version is not recorded, so the sweep runs again until every emitter is bound.
-     * An atlas owner may call this after the scene context builds, before setting row regions.
-     * execute() calls it as well; unchanged membership costs one version comparison.
-     * @returns {void}
+     * The row is an entity's, one on (`row_of_entity`), and whoever owns the entity holds it through
+     * the scene context's rows for as long as the emitter is registered; this only records which
+     * row the emitter's particles are born at. Nothing is uploaded until the next {@link execute}.
+     *
+     * @param {import("./runtime/ParticleEmitter.js").ParticleEmitter} emitter
+     * @param {number} transform_row
+     */
+    add_emitter(emitter: import("./runtime/ParticleEmitter.js").ParticleEmitter, transform_row: number): void;
+    /**
+     * Retire an emitter's row; its particles go within a frame, carrying the row's generation.
+     *
+     * @param {import("./runtime/ParticleEmitter.js").ParticleEmitter} emitter
+     */
+    remove_emitter(emitter: import("./runtime/ParticleEmitter.js").ParticleEmitter): void;
+    /**
+     * Point a registered emitter at another row.
+     *
+     * @param {import("./runtime/ParticleEmitter.js").ParticleEmitter} emitter
+     * @param {number} transform_row
      */
-    sync_membership(): void;
+    set_transform_row(emitter: import("./runtime/ParticleEmitter.js").ParticleEmitter, transform_row: number): void;
     /**
      * Sizes of the persistent buffers, in bytes, as they stand — one entry per distinct buffer, so
      * this is the feature's reserved footprint and not a list of the names it binds them under.

package/src/shade/renderer/particles/GPUParticleSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUParticleSystem.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/GPUParticleSystem.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"GPUParticleSystem.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/particles/GPUParticleSystem.js"],"names":[],"mappings":"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"}

package/src/shade/renderer/particles/GPUParticleSystem.js

@@ -109,14 +109,14 @@ const DEFAULT_CAPACITY = 524288;
  * effects it holds and this is where that number meets the VM's; nothing about authoring a graph has
  * a register ceiling.
  *
- * ## Emitters are scene nodes
+ * ## Emitters are registered at rows
  *
- * There is no `addEmitter`. A {@link ParticleEmitter} is a {@link Node3D}: put it in the scene —
- * on its own or under a joint — and the next {@link execute} finds it in the scene's node list,
- * gives it a row in the emitter table pointed at the `transforms` row the scene context gave the
- * node, and it starts spawning. Take it out of the scene and its row is retired and its particles
- * freed. The sweep runs only when the scene's membership version moves, which is how per-frame
- * upkeep stays proportional to what changed rather than to how many emitters there are.
+ * {@link add_emitter} gives a {@link ParticleEmitter} a row in the emitter table pointed at a
+ * `transforms` row — an entity's, one on, held through the scene context's rows by whoever owns
+ * the entity — and it starts spawning on the next {@link execute}; under a joint's row it moves
+ * with the joint. {@link remove_emitter} retires the row and frees its particles. Nothing here
+ * walks the scene: an emitter is where its owner says it is, and per-frame upkeep is proportional
+ * to what changed rather than to how many emitters there are.
  *
  * ## Spawning is the GPU's decision
  *
@@ -155,7 +155,8 @@ export class GPUParticleSystem {
     graphics;
 
     /**
-     * The scene whose nodes the emitters are, and whose database their world matrices come from.
+     * The scene whose rows the emitters are placed at, and whose database their world matrices
+     * come from.
      * @type {import("../scene/GPUSceneContext.js").GPUSceneContext}
      */
     scene_context;
@@ -243,7 +244,7 @@ export class GPUParticleSystem {
     /**
      * Emitters registered since the last frame with a pre-warm to run — the input of the warm-up
      * pipeline (`warmup/`), consumed by the frame that records it. Filled where the emitter is
-     * registered ({@link sync_membership}), which is the one moment the host knows an emitter is
+     * registered ({@link add_emitter}), which is the one moment the host knows an emitter is
      * new: the GPU decides everything else about spawning, but "this one has just arrived and asks
      * to arrive warm" is a host-side fact.
      *
@@ -258,14 +259,6 @@ export class GPUParticleSystem {
      */
     #warmup_words = new Uint32Array(0);
 
-    /**
-     * Emitter node -> the sweep that last saw it in the scene.
-     * @type {Map<import("./runtime/ParticleEmitter.js").ParticleEmitter, number>}
-     */
-    #swept = new Map();
-
-    /** @type {number} */
-    #sweep = 0;
 
     /**
      * The 1x1 white texture {@link atlas} points at until a caller replaces it. Held so
@@ -274,11 +267,6 @@ export class GPUParticleSystem {
      */
     #default_atlas = null;
 
-    /**
-     * The scene membership version the emitter set was last reconciled against.
-     * @type {number}
-     */
-    #instances_version = -1;
 
     /**
      * Program assignments used to build the previous frame's coherence list.
@@ -389,7 +377,7 @@ export class GPUParticleSystem {
 
         const context = this.registry.context(emitter);
 
-        assert.defined(context, "emitter is not in the scene");
+        assert.defined(context, "emitter is not registered");
 
         const ring = this.#spawn_commands;
         const base = this.#spawn_command_count * PARTICLE_SPAWN_COMMAND_WORDS;
@@ -418,7 +406,7 @@ export class GPUParticleSystem {
      * theirs.
      *
      * Call after the scene context has built for the frame (`GPUSceneContext#update`), so every
-     * emitter node has its `transforms` row, and after the hierarchy pass has run, so the rows'
+     * emitter's `transforms` row is uploaded, and after the hierarchy pass has run, so the rows'
      * `global` matrices are this frame's.
      *
      * **Once per frame, not once per view.** This advances the simulation by `dt` and hands out
@@ -439,7 +427,6 @@ export class GPUParticleSystem {
         assert.defined(graph, "graph");
         assert.isNumber(dt, "dt");
 
-        this.sync_membership();
         this.#upload();
 
         const frame = this.#frame;
@@ -601,72 +588,51 @@ export class GPUParticleSystem {
     }
 
     /**
-     * Bring the emitter set in line with the scene: emitter nodes that arrived get rows, nodes that
-     * left give theirs back. Runs only when the scene's membership version has moved.
+     * Register an emitter at a `transforms` row, and if it asks, warm it up before its first frame.
      *
-     * A node the scene context has not placed yet (no `transforms` row) is left for the next frame,
-     * and the version is not recorded, so the sweep runs again until every emitter is bound.
-     * An atlas owner may call this after the scene context builds, before setting row regions.
-     * execute() calls it as well; unchanged membership costs one version comparison.
-     * @returns {void}
+     * The row is an entity's, one on (`row_of_entity`), and whoever owns the entity holds it through
+     * the scene context's rows for as long as the emitter is registered; this only records which
+     * row the emitter's particles are born at. Nothing is uploaded until the next {@link execute}.
+     *
+     * @param {import("./runtime/ParticleEmitter.js").ParticleEmitter} emitter
+     * @param {number} transform_row
      */
-    sync_membership() {
-        const scene = this.scene_context.scene;
-        const batch = scene.instances;
-
-        if (batch.version === this.#instances_version) {
-            return;
+    add_emitter(emitter, transform_row) {
+        assert.defined(emitter, 'emitter');
+        assert.equal(emitter.isParticleEmitter, true, 'emitter.isParticleEmitter !== true');
+        assert.isNonNegativeInteger(transform_row, 'transform_row');
+
+        this.registry.add(emitter, transform_row);
+
+        // Just arrived, and asked to arrive warm: the warm-up pipeline runs its simulation forward
+        // this frame, before it is first drawn. A reused row is a new emitter as far as this is
+        // concerned — it is the emitter that asks, not the row.
+        if (emitter.prewarm > 0) {
+            this.#warmup_queue.push(emitter);
         }
+    }
 
-        const sweep = ++this.#sweep;
-        const nodes = batch.nodes;
-        const node_count = nodes.length;
-        const mapping = this.scene_context.id_mapping;
-        const registry = this.registry;
-        const swept = this.#swept;
-
-        let complete = true;
-
-        for (let i = 0; i < node_count; i++) {
-            const node = nodes[i];
-
-            if (node.isParticleEmitter !== true) {
-                continue;
-            }
-
-            const transform_row = mapping.get(node.id);
-
-            if (transform_row === undefined) {
-                complete = false;
-                continue;
-            }
-
-            if (registry.context(node) === undefined) {
-                registry.add(node, transform_row);
-
-                // Just arrived, and asked to arrive warm: the warm-up pipeline runs its simulation
-                // forward this frame, before it is first drawn. A reused row is a new emitter as far
-                // as this is concerned — it is the emitter that asks, not the row.
-                if (node.prewarm > 0) {
-                    this.#warmup_queue.push(node);
-                }
-            } else {
-                registry.set_transform_row(node, transform_row);
-            }
+    /**
+     * Retire an emitter's row; its particles go within a frame, carrying the row's generation.
+     *
+     * @param {import("./runtime/ParticleEmitter.js").ParticleEmitter} emitter
+     */
+    remove_emitter(emitter) {
+        assert.defined(emitter, 'emitter');
 
-            swept.set(node, sweep);
-        }
+        this.registry.remove(emitter);
+    }
 
-        for (const [emitter, seen] of swept) {
-            if (seen !== sweep) {
-                registry.remove(emitter);
-                swept.delete(emitter);
-            }
-        }
+    /**
+     * Point a registered emitter at another row.
+     *
+     * @param {import("./runtime/ParticleEmitter.js").ParticleEmitter} emitter
+     * @param {number} transform_row
+     */
+    set_transform_row(emitter, transform_row) {
+        assert.isNonNegativeInteger(transform_row, 'transform_row');
 
-        if (complete) {
-            this.#instances_version = batch.version;
-        }
+        this.registry.set_transform_row(emitter, transform_row);
     }
 
     /**
@@ -1086,17 +1052,14 @@ export class GPUParticleSystem {
 
     destroy() {
         /*
-         The emitters go first, and they matter more than the buffers: they are the scene's nodes,
-         they outlive this system, and each is holding a row of the table about to be freed. A node
-         left holding one is stranded — the next system's membership sweep reads `row !== -1` as
-         "already mine", takes the moved branch rather than the arrived one, and never registers it.
-         Retiring them here puts every emitter back where it was before this system saw it.
+         The emitters go first, and they matter more than the buffers: they belong to their owners,
+         they outlive this system, and each is holding a row of the table about to be freed.
+         Retiring them here puts every emitter back where it was before this system saw it, so its
+         owner can register it with the next system.
         */
         for (const emitter of this.registry.emitters.slice()) {
             this.registry.remove(emitter);
         }
-        this.#swept.clear();
-        this.#instances_version = -1;
 
         for (const buffer of Object.values(this.buffers)) {
             if (Array.isArray(buffer)) {

package/src/shade/renderer/particles/runtime/EmitterRegistry.d.ts

@@ -12,9 +12,9 @@
  * particles of a removed emitter — which carry its generation — cannot be mistaken for the new
  * tenant's. The simulate pass kills them on sight; see {@link ../data/particle_header.js}.
  *
- * **None of that bookkeeping is on the emitter.** An emitter is a scene node and a description of
- * an effect, with nothing in it that depends on a device; the row, the generation, the program
- * placement, the node's `transforms` row and the atlas patch are a
+ * **None of that bookkeeping is on the emitter.** An emitter is a description of an effect, with
+ * nothing in it that depends on a device; the row, the generation, the program placement, the
+ * `transforms` row it is placed at and the atlas patch are a
  * {@link ./GPUParticleEmitterContext.js} this registry holds against the emitter and hands out
  * through {@link EmitterRegistry#context}. Registering an emitter creates one, removing it destroys
  * one, and an emitter with no context here is an emitter this registry does not have.
@@ -109,7 +109,7 @@ export class EmitterRegistry {
     get max_register_count(): number;
     /**
      * What this registry assigned an emitter: its table row, generation, program placement, the
-     * `transforms` row of its node and its atlas patch.
+     * `transforms` row it is placed at and its atlas patch.
      *
      * `undefined` for an emitter this registry does not hold — which is the way to ask whether one
      * is live, there being no `-1` on the emitter to read instead.
@@ -123,8 +123,9 @@ export class EmitterRegistry {
      *
      * @param {ParticleEmitter|object} config a {@link ParticleEmitter}, or a description
      *        {@link ParticleEmitter.from} accepts
-     * @param {number} [transform_row] the emitter node's row in the scene's `transforms` table, if
-     *        already known; {@link set_transform_row} sets it later otherwise
+     * @param {number} [transform_row] the row of the scene's `transforms` table the emitter is
+     *        placed at — its entity's, one on — if already known; {@link set_transform_row} sets it
+     *        later otherwise
      * @returns {ParticleEmitter}
      */
     add(config: ParticleEmitter | object, transform_row?: number): ParticleEmitter;
@@ -168,7 +169,7 @@ export class EmitterRegistry {
      */
     get(row: number): ParticleEmitter | undefined;
     /**
-     * Point an emitter's record at its node's row in the scene's `transforms` table. The row is
+     * Point an emitter's record at another row of the scene's `transforms` table. The row is
      * restaged on the next flush.
      *
      * @param {ParticleEmitter} emitter
@@ -189,10 +190,10 @@ export class EmitterRegistry {
     /**
      * Restage the table rows of every emitter whose fields have moved since the last flush.
      *
-     * "Moved" is the node's own change counter: an emitter is restaged when its
-     * {@link ../../scene/Node3D.js Node3D#version} is not the one its row was staged from, or when
-     * something in its context changed. So an author marks an edited emitter the way they mark any
-     * edited node, with `needsUpdate = true`, and there is no second flag to forget.
+     * "Moved" is the emitter's own change counter: an emitter is restaged when its
+     * {@link ./ParticleEmitter.js ParticleEmitter#version} is not the one its row was staged from,
+     * or when something in its context changed. So an author marks an edited emitter with
+     * `needsUpdate = true`, and there is no second flag to forget.
      *
      * Cheap to call every frame: an emitter that has not changed costs one integer comparison, and
      * the table coalesces repeated writes to one row within a frame anyway. Walks the context map

package/src/shade/renderer/particles/runtime/EmitterRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EmitterRegistry.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/EmitterRegistry.js"],"names":[],"mappings":"AA0BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH;IA8EI;;OAEG;IACH,+BASC;IAxFD;;OAEG;IACH,UAFU,WAAW,CAEZ;IAET;;;OAGG;IACH,UAFU,WAAW,CAEQ;IAE7B;;;OAGG;IACH,4BAFU,MAAM,CAEe;IAE/B;;;OAGG;IACH,UAFU,eAAe,EAAE,CAEb;IAEd;;;;;OAKG;IACH,QAFU,eAAe,EAAE,CAEf;IAEZ;;;;;;;;;;OAUG;IACH,8BAEC;IA8CD;;;OAGG;IACH,8EAEC;IAED;;;;OAIG;IACH,oFAEC;IAED;;OAEG;IACH,oBAEC;IAED;;;OAGG;IACH,4BAEC;IAED;;;;;OAKG;IACH,kCAEC;IAED;;;;;;;OAOG;IACH,iCAEC;IAED;;;;;;;;;OASG;IACH,iBAHW,eAAe,GACb,yBAAyB,GAAC,SAAS,CAI/C;IAED;;;;;;;;OAQG;IACH,YANW,eAAe,GAAC,MAAM,kBAEtB,MAAM,GAEJ,eAAe,CA+B3B;IAED;;;;;;;;;;;;;OAaG;IACH,gBAFW,eAAe,QA6BzB;IAED;;;;;;;;;;;;;;;OAeG;IACH,qBAHW,eAAe,WACf,OAAO,2BAA2B,EAAE,eAAe,QA0B7D;IAED;;;;;OAKG;IACH,SAHW,MAAM,GACJ,eAAe,GAAC,SAAS,CAIrC;IAED;;;;;;OAMG;IACH,2BAHW,eAAe,iBACf,MAAM,QAehB;IAED;;;;;;;;;OASG;IACH,0BAHW,eAAe,UACf,UAAU,MAAM,CAAC,QAoB3B;IAED;;;;;;;;;;;;;OAaG;IACH,cA4BC;IAED;;;;;;;;;OASG;IACH,iBAFa,WAAW,CAMvB;;CACJ;;4BA7c2B,mCAAmC;4BAYnC,kBAAkB;gCADd,sBAAsB;0CADZ,gCAAgC"}
+{"version":3,"file":"EmitterRegistry.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/EmitterRegistry.js"],"names":[],"mappings":"AA0BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH;IA8EI;;OAEG;IACH,+BASC;IAxFD;;OAEG;IACH,UAFU,WAAW,CAEZ;IAET;;;OAGG;IACH,UAFU,WAAW,CAEQ;IAE7B;;;OAGG;IACH,4BAFU,MAAM,CAEe;IAE/B;;;OAGG;IACH,UAFU,eAAe,EAAE,CAEb;IAEd;;;;;OAKG;IACH,QAFU,eAAe,EAAE,CAEf;IAEZ;;;;;;;;;;OAUG;IACH,8BAEC;IA8CD;;;OAGG;IACH,8EAEC;IAED;;;;OAIG;IACH,oFAEC;IAED;;OAEG;IACH,oBAEC;IAED;;;OAGG;IACH,4BAEC;IAED;;;;;OAKG;IACH,kCAEC;IAED;;;;;;;OAOG;IACH,iCAEC;IAED;;;;;;;;;OASG;IACH,iBAHW,eAAe,GACb,yBAAyB,GAAC,SAAS,CAI/C;IAED;;;;;;;;;OASG;IACH,YAPW,eAAe,GAAC,MAAM,kBAEtB,MAAM,GAGJ,eAAe,CA+B3B;IAED;;;;;;;;;;;;;OAaG;IACH,gBAFW,eAAe,QA6BzB;IAED;;;;;;;;;;;;;;;OAeG;IACH,qBAHW,eAAe,WACf,OAAO,2BAA2B,EAAE,eAAe,QA0B7D;IAED;;;;;OAKG;IACH,SAHW,MAAM,GACJ,eAAe,GAAC,SAAS,CAIrC;IAED;;;;;;OAMG;IACH,2BAHW,eAAe,iBACf,MAAM,QAehB;IAED;;;;;;;;;OASG;IACH,0BAHW,eAAe,UACf,UAAU,MAAM,CAAC,QAoB3B;IAED;;;;;;;;;;;;;OAaG;IACH,cA4BC;IAED;;;;;;;;;OASG;IACH,iBAFa,WAAW,CAMvB;;CACJ;;4BA9c2B,mCAAmC;4BAYnC,kBAAkB;gCADd,sBAAsB;0CADZ,gCAAgC"}

package/src/shade/renderer/particles/runtime/EmitterRegistry.js

@@ -38,9 +38,9 @@ const RECORD = create_emitter_record();
  * particles of a removed emitter — which carry its generation — cannot be mistaken for the new
  * tenant's. The simulate pass kills them on sight; see {@link ../data/particle_header.js}.
  *
- * **None of that bookkeeping is on the emitter.** An emitter is a scene node and a description of
- * an effect, with nothing in it that depends on a device; the row, the generation, the program
- * placement, the node's `transforms` row and the atlas patch are a
+ * **None of that bookkeeping is on the emitter.** An emitter is a description of an effect, with
+ * nothing in it that depends on a device; the row, the generation, the program placement, the
+ * `transforms` row it is placed at and the atlas patch are a
  * {@link ./GPUParticleEmitterContext.js} this registry holds against the emitter and hands out
  * through {@link EmitterRegistry#context}. Registering an emitter creates one, removing it destroys
  * one, and an emitter with no context here is an emitter this registry does not have.
@@ -202,7 +202,7 @@ export class EmitterRegistry {
 
     /**
      * What this registry assigned an emitter: its table row, generation, program placement, the
-     * `transforms` row of its node and its atlas patch.
+     * `transforms` row it is placed at and its atlas patch.
      *
      * `undefined` for an emitter this registry does not hold — which is the way to ask whether one
      * is live, there being no `-1` on the emitter to read instead.
@@ -219,8 +219,9 @@ export class EmitterRegistry {
      *
      * @param {ParticleEmitter|object} config a {@link ParticleEmitter}, or a description
      *        {@link ParticleEmitter.from} accepts
-     * @param {number} [transform_row] the emitter node's row in the scene's `transforms` table, if
-     *        already known; {@link set_transform_row} sets it later otherwise
+     * @param {number} [transform_row] the row of the scene's `transforms` table the emitter is
+     *        placed at — its entity's, one on — if already known; {@link set_transform_row} sets it
+     *        later otherwise
      * @returns {ParticleEmitter}
      */
     add(config, transform_row = 0) {
@@ -350,7 +351,7 @@ export class EmitterRegistry {
     }
 
     /**
-     * Point an emitter's record at its node's row in the scene's `transforms` table. The row is
+     * Point an emitter's record at another row of the scene's `transforms` table. The row is
      * restaged on the next flush.
      *
      * @param {ParticleEmitter} emitter
@@ -404,10 +405,10 @@ export class EmitterRegistry {
     /**
      * Restage the table rows of every emitter whose fields have moved since the last flush.
      *
-     * "Moved" is the node's own change counter: an emitter is restaged when its
-     * {@link ../../scene/Node3D.js Node3D#version} is not the one its row was staged from, or when
-     * something in its context changed. So an author marks an edited emitter the way they mark any
-     * edited node, with `needsUpdate = true`, and there is no second flag to forget.
+     * "Moved" is the emitter's own change counter: an emitter is restaged when its
+     * {@link ./ParticleEmitter.js ParticleEmitter#version} is not the one its row was staged from,
+     * or when something in its context changed. So an author marks an edited emitter with
+     * `needsUpdate = true`, and there is no second flag to forget.
      *
      * Cheap to call every frame: an emitter that has not changed costs one integer comparison, and
      * the table coalesces repeated writes to one row within a frame anyway. Walks the context map