@woosh/meep-engine 3.17.1 → 3.18.0

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

@@ -1,425 +1,424 @@
-import { assert } from "../../../../core/assert.js";
-import { is_typed_array_equals } from "../../../../core/collection/array/typed/is_typed_array_equals.js";
-import { float32_array_hash } from "../../../../core/collection/array/typed/float32_array_hash.js";
-import { hash_mix2 } from "../../../../core/math/hash/hash_mix2.js";
-import { hash_mix3 } from "../../../../core/math/hash/hash_mix3.js";
-import { computeHashFloat } from "../../../../core/primitives/numbers/computeHashFloat.js";
-import { computeStringHash } from "../../../../core/primitives/strings/computeStringHash.js";
-import { Node3D } from "../../scene/Node3D.js";
-import { EMITTER_ATTRIBUTE_ABSENT, make_emitter_flags } from "../data/PARTICLE_EMITTER_STRUCT.js";
-
-/**
- * Render channels an emitter can bind to one of its effect's per-particle attributes. The names
- * match the `render_*` fields of {@link ../data/PARTICLE_EMITTER_STRUCT.js}.
- *
- * @type {string[]}
- */
-export const EMITTER_RENDER_CHANNELS = Object.freeze([
-    "position", "size", "color", "rotation", "frame", "velocity",
-]);
-
-/**
- * How many record words the render pass reads for each channel.
- *
- * A channel is read at a fixed width — `chunk_particle_billboard_vertex.js` takes four words for
- * colour and three for position, whatever the attribute behind the offset happens to be. Binding one
- * to a narrower attribute is therefore not a smaller read but a read into whatever the layout put
- * next, and nothing downstream objects: the particles simply come out wrong.
- *
- * Binding is deliberately not made to enforce this — the offsets are the record's, and an author who
- * knows what is packed where may mean it — but an editor has this table so it can say so.
- *
- * @type {Object<string, number>}
- */
-export const EMITTER_RENDER_CHANNEL_COMPONENTS = Object.freeze({
-    position: 3,
-    size: 1,
-    color: 4,
-    rotation: 1,
-    frame: 1,
-    velocity: 3,
-});
-
-/**
- * One particle emitter: a scene node that runs a compiled effect.
- *
- * Being a {@link Node3D} is what places it. Add it to a scene and it gets a row in the scene
- * database's `transforms` table like any other node; parent it to a joint and the GPU hierarchy
- * pass composes its world matrix from the joint's every frame, animation included, with nothing
- * copied through the CPU. Remove it from the scene and the row goes with it — and so do its
- * particles, within a frame, because the emitter's table row is retired with it and its particles
- * carry that row's generation. There is no transform of its own to keep in step with anything.
- *
- * The rest is a description of an effect and nothing else: the attribute {@link layout} and the
- * compiled {@link program}, the {@link texture} to draw with, spawn rate, blend / projection /
- * feature flags, bounds sphere, render-attribute bindings and flipbook grid. Every one of those is
- * the author's, means the same thing with no device present, and is what a saved effect is made of.
- *
- * **Nothing here is the GPU's.** Which table row the emitter was given, which tenancy of it, where
- * its program was placed in the program heap, which `transforms` row its node ended up in, where
- * its texture was packed into the atlas — all of that is
- * {@link ./GPUParticleEmitterContext.js GPUParticleEmitterContext}, held by the
- * {@link ./EmitterRegistry.js} that registered the emitter and reachable through
- * {@link ./EmitterRegistry.js#context}. An emitter no registry holds has none, which is also how
- * "is this emitter live?" is asked. Nor is anything the GPU integrates per frame here — spawn
- * accumulator, age, sleep are {@link ../data/PARTICLE_EMITTER_STATE.js}, and they stay on the GPU.
- *
- * Fields are plain data with no setters. After changing any of them, set `needsUpdate = true` — the
- * node's own change counter, the same one the renderer reads to decide whether a transform needs
- * re-uploading — and {@link ./EmitterRegistry.js#flush} restages the row on its next flush. One
- * counter rather than a setter per field because a row is restaged whole either way: one changed
- * field and ten cost the same upload.
- */
-export class ParticleEmitter extends Node3D {
-
-    /**
-     * The per-particle attribute schema: which named attributes a particle of this emitter has, how
-     * wide each is, and what word of the record it sits at.
-     *
-     * @type {import("../layout/ParticleLayout.js").ParticleLayout}
-     */
-    layout;
-
-    /**
-     * The compiled INIT/UPDATE bytecode run for every particle of this emitter.
-     *
-     * @type {import("../isa/ParticleProgram.js").ParticleProgram}
-     */
-    program;
-
-    /**
-     * Image to draw the particles with, by URL, or `null` to draw against the default atlas — a
-     * single white texel, so an untextured emitter is a flat quad of its colour.
-     *
-     * A URL rather than a texture, and no uv rect: the particle system packs every emitter's image
-     * into one sheet so that a hundred effects sharing a puff of smoke pay for one image, and where
-     * a given image lands in that sheet is the system's answer, not the author's — it changes on
-     * every repack, without the emitter changing. The resolved patch is
-     * {@link ./GPUParticleEmitterContext.js#atlas_region}.
-     *
-     * @type {string|null}
-     */
-    texture = null;
-
-    /**
-     * Base RNG seed.
-     *
-     * Two emitters running one program produce identical particles from identical seeds. `0` reads
-     * as "unset", and the row written for such an emitter takes its registration's generation
-     * instead, which no other emitter of that registry shares.
-     *
-     * @type {number}
-     */
-    seed = 0;
-
-    /**
-     * Continuous emission rate, particles per second. Integrated on the GPU by the emitter tick
-     * pass; the CPU never counts particles.
-     * @type {number}
-     */
-    spawn_rate = 0;
-
-    /**
-     * Packed feature / blend / projection bits — see {@link make_emitter_flags}.
-     * @type {number}
-     */
-    flags = 0;
-
-    /**
-     * Bounding sphere in emitter-local space, scaled and placed by the node's world matrix.
-     *
-     * Two passes read it: the optional simulation culling (a culled emitter sleeps), and the AVBOIT
-     * occupancy, which marks the depth slices this emitter's particles may reach. The second gives
-     * it teeth even for an emitter that does not opt into culling — a particle outside the sphere
-     * still draws, but its extinction lands in whatever physical slice the warp put nearest, so it
-     * occludes at slightly the wrong depth. Size it to hold the effect.
-     *
-     * Hold the *quads*, not the centres. A camera-facing billboard has almost no depth extent, but
-     * an axis-locked, world-oriented or velocity-stretched one reaches a particle size — or, when
-     * stretched, several — in front of and behind the particle it belongs to.
-     *
-     * @type {Float32Array}
-     */
-    bounds_center = new Float32Array(3);
-
-    /**
-     * @type {number}
-     */
-    bounds_radius = 1;
-
-    /**
-     * Flipbook grid: columns, rows, over whatever region {@link texture} was packed into. `[1, 1]`
-     * is a single frame.
-     * @type {Float32Array}
-     */
-    flipbook = new Float32Array([1, 1]);
-
-    /** @type {number} record word offset of world position, or {@link EMITTER_ATTRIBUTE_ABSENT} */
-    render_position = EMITTER_ATTRIBUTE_ABSENT;
-    /** @type {number} record word offset of size */
-    render_size = EMITTER_ATTRIBUTE_ABSENT;
-    /** @type {number} record word offset of rgba colour */
-    render_color = EMITTER_ATTRIBUTE_ABSENT;
-    /** @type {number} record word offset of roll angle, radians */
-    render_rotation = EMITTER_ATTRIBUTE_ABSENT;
-    /** @type {number} record word offset of flipbook frame index */
-    render_frame = EMITTER_ATTRIBUTE_ABSENT;
-    /** @type {number} record word offset of velocity, read by the STRETCHED projection */
-    render_velocity = EMITTER_ATTRIBUTE_ABSENT;
-
-    get type() {
-        return "ParticleEmitter";
-    }
-
-    /**
-     * Bind render channels to per-particle attributes of this emitter's effect, by attribute name.
-     * Channels left out of `channels` keep whatever they had; a channel that was never bound stays
-     * at {@link EMITTER_ATTRIBUTE_ABSENT}, which the passes read as "this emitter has no such
-     * attribute" — the render pass substitutes a default, the sort pass treats the particle as
-     * being at the origin.
-     *
-     * The record stores word offsets rather than names because that is what the render and sort
-     * passes index a particle record with; resolving here is the only place a name is involved.
-     *
-     * @param {Object<string,string>} channels channel name (see {@link EMITTER_RENDER_CHANNELS}) ->
-     *        attribute name in the effect's layout
-     */
-    bind_render(channels) {
-        assert.isObject(channels, 'channels');
-        assert.defined(this.layout, 'layout');
-
-        const layout = this.layout;
-
-        for (const channel of Object.keys(channels)) {
-            const offset = layout.offsetOf(channels[channel]);
-
-            switch (channel) {
-                case "position": this.render_position = offset; break;
-                case "size": this.render_size = offset; break;
-                case "color": this.render_color = offset; break;
-                case "rotation": this.render_rotation = offset; break;
-                case "frame": this.render_frame = offset; break;
-                case "velocity": this.render_velocity = offset; break;
-                default:
-                    throw new Error(
-                        `Unknown render channel '${channel}', expected one of ${EMITTER_RENDER_CHANNELS.join(', ')}`
-                    );
-            }
-        }
-
-        this.needsUpdate = true;
-    }
-
-    /**
-     * Structural equality over everything an emitter *is*: where it sits, what it runs, what it
-     * draws with, and how it is bound to the renderer. Two emitters that compare equal describe one
-     * effect in one place, and one row would serve both.
-     *
-     * The node's identity is not part of it — `id`, parent and children say where an emitter is in
-     * a scene, not what it is — and neither is anything the GPU assigned it, which is not here to
-     * be compared. {@link transform_global} is left out too, being derived from
-     * {@link transform_local} and the parent chain.
-     *
-     * @param {ParticleEmitter} other
-     * @returns {boolean}
-     */
-    equals(other) {
-        if (this === other) {
-            return true;
-        }
-
-        return this.name === other.name
-            && this.texture === other.texture
-            && this.seed === other.seed
-            && this.spawn_rate === other.spawn_rate
-            && this.flags === other.flags
-            && this.bounds_radius === other.bounds_radius
-            && this.render_position === other.render_position
-            && this.render_size === other.render_size
-            && this.render_color === other.render_color
-            && this.render_rotation === other.render_rotation
-            && this.render_frame === other.render_frame
-            && this.render_velocity === other.render_velocity
-            && is_typed_array_equals(this.bounds_center, other.bounds_center)
-            && is_typed_array_equals(this.flipbook, other.flipbook)
-            && this.transform_local.equals(other.transform_local)
-            && this.layout.equals(other.layout)
-            && this.program.equals(other.program);
-    }
-
-    /**
-     * Hash over everything {@link equals} compares, in the same terms — the compiled program hashes
-     * by its own bytecode rather than by object identity, so two emitters separately compiled from
-     * one graph hash equally, as they compare equally.
-     *
-     * @returns {number} int32
-     */
-    hash() {
-        const bindings = hash_mix3(
-            hash_mix3(this.render_position, this.render_size, this.render_color),
-            hash_mix3(this.render_rotation, this.render_frame, this.render_velocity),
-            this.flags
-        );
-
-        const geometry = hash_mix3(
-            float32_array_hash(this.bounds_center, 0, this.bounds_center.length),
-            computeHashFloat(this.bounds_radius),
-            float32_array_hash(this.flipbook, 0, this.flipbook.length)
-        );
-
-        const appearance = hash_mix3(
-            computeStringHash(this.name),
-            computeStringHash(this.texture),
-            hash_mix2(this.seed, computeHashFloat(this.spawn_rate))
-        );
-
-        return hash_mix3(
-            hash_mix2(bindings, geometry),
-            hash_mix2(appearance, this.transform_local.hash()),
-            hash_mix2(this.layout.hash(), this.program.hash())
-        );
-    }
-
-    /**
-     * Make this emitter a copy of `other`: same effect, same settings, same placement.
-     *
-     * The layout and the compiled program are shared rather than duplicated — both are immutable
-     * once compiled, and sharing them is what puts two emitters of one effect on one program id in
-     * the program heap, hence in one simulation bucket.
-     *
-     * What is not copied is the node's identity and its place in a scene ({@link Node3D#id},
-     * parent, children), and anything a registry gave the original: a copy is a second emitter, not
-     * a second reference to the first one's table row.
-     *
-     * @param {ParticleEmitter} other
-     */
-    copy(other) {
-        super.copy(other);
-
-        this.name = other.name;
-
-        this.layout = other.layout;
-        this.program = other.program;
-        this.texture = other.texture;
-
-        this.seed = other.seed;
-        this.spawn_rate = other.spawn_rate;
-        this.flags = other.flags;
-
-        this.bounds_center.set(other.bounds_center);
-        this.bounds_radius = other.bounds_radius;
-        this.flipbook.set(other.flipbook);
-
-        this.render_position = other.render_position;
-        this.render_size = other.render_size;
-        this.render_color = other.render_color;
-        this.render_rotation = other.render_rotation;
-        this.render_frame = other.render_frame;
-        this.render_velocity = other.render_velocity;
-    }
-
-    /**
-     * A second emitter equal to this one, and registered with nothing. Its subtree is cloned the
-     * way {@link Node3D#clone} clones one — overridden only because the base builds a plain
-     * `Node3D`, which would keep the transform and drop the effect.
-     *
-     * @returns {ParticleEmitter}
-     */
-    clone() {
-        const r = new ParticleEmitter();
-
-        r.copy(this);
-
-        for (const child of this.children) {
-            const clone = child.clone();
-
-            clone.parent = r;
-
-            r.children.push(clone);
-        }
-
-        return r;
-    }
-
-    /**
-     * Build an emitter from a plain description. Every parameter is optional except the compiled
-     * effect — an emitter with no program has nothing to run.
-     *
-     * `layout` and `program` are the two halves of what {@link ./create_particle_effect.js} returns,
-     * so an effect goes in by spreading it: `ParticleEmitter.from({ ...effect, spawn_rate: 100 })`.
-     *
-     * @param {object} config
-     * @param {import("../layout/ParticleLayout.js").ParticleLayout} config.layout per-particle
-     *        attribute schema
-     * @param {import("../isa/ParticleProgram.js").ParticleProgram} config.program compiled INIT /
-     *        UPDATE bytecode
-     * @param {ArrayLike<number>} [config.position] local translation, `[x, y, z]`
-     * @param {string|null} [config.texture] image URL to draw with
-     * @param {number} [config.seed]
-     * @param {number} [config.spawn_rate] particles/second
-     * @param {object} [config.flags] passed to {@link make_emitter_flags}
-     * @param {{center?: ArrayLike<number>, radius?: number}} [config.bounds]
-     * @param {Object<string,string>} [config.render] render channel -> attribute name
-     * @param {ArrayLike<number>} [config.flipbook] [cols, rows]
-     * @param {string} [config.name]
-     * @returns {ParticleEmitter}
-     */
-    static from(config) {
-        assert.isObject(config, 'config');
-        assert.defined(config.layout, 'config.layout');
-        assert.defined(config.program, 'config.program');
-
-        const emitter = new ParticleEmitter();
-
-        emitter.layout = config.layout;
-        emitter.program = config.program;
-
-        if (config.name !== undefined) {
-            emitter.name = config.name;
-        }
-
-        if (config.texture !== undefined) {
-            emitter.texture = config.texture;
-        }
-
-        if (config.position !== undefined) {
-            emitter.transform_local.setTranslation(config.position[0], config.position[1], config.position[2]);
-            emitter.updateMatrices();
-        }
-
-        if (config.seed !== undefined) {
-            emitter.seed = config.seed;
-        }
-
-        if (config.spawn_rate !== undefined) {
-            emitter.spawn_rate = config.spawn_rate;
-        }
-
-        emitter.flags = make_emitter_flags(config.flags ?? {});
-
-        if (config.bounds !== undefined) {
-            if (config.bounds.center !== undefined) {
-                emitter.bounds_center.set(config.bounds.center);
-            }
-            if (config.bounds.radius !== undefined) {
-                emitter.bounds_radius = config.bounds.radius;
-            }
-        }
-
-        if (config.flipbook !== undefined) {
-            emitter.flipbook.set(config.flipbook);
-        }
-
-        if (config.render !== undefined) {
-            emitter.bind_render(config.render);
-        }
-
-        return emitter;
-    }
-}
-
-/**
- * @readonly
- * @type {boolean}
- */
-ParticleEmitter.prototype.isParticleEmitter = true;
+import { assert } from "../../../../core/assert.js";
+import { is_typed_array_equals } from "../../../../core/collection/array/typed/is_typed_array_equals.js";
+import { float32_array_hash } from "../../../../core/collection/array/typed/float32_array_hash.js";
+import { hash_mix2 } from "../../../../core/math/hash/hash_mix2.js";
+import { hash_mix3 } from "../../../../core/math/hash/hash_mix3.js";
+import { computeHashFloat } from "../../../../core/primitives/numbers/computeHashFloat.js";
+import { computeStringHash } from "../../../../core/primitives/strings/computeStringHash.js";
+import { Node3D } from "../../scene/Node3D.js";
+import { EMITTER_ATTRIBUTE_ABSENT, make_emitter_flags } from "../data/PARTICLE_EMITTER_STRUCT.js";
+
+/**
+ * Render channels an emitter can bind to one of its effect's per-particle attributes. The names
+ * match the `render_*` fields of {@link ../data/PARTICLE_EMITTER_STRUCT.js}.
+ *
+ * @type {string[]}
+ */
+export const EMITTER_RENDER_CHANNELS = Object.freeze([
+    "position", "size", "color", "rotation", "frame", "velocity",
+]);
+
+/**
+ * How many record words the render pass reads for each channel.
+ *
+ * A channel is read at a fixed width — `chunk_particle_billboard_vertex.js` takes four words for
+ * colour and three for position, whatever the attribute behind the offset happens to be. Binding one
+ * to a narrower attribute is therefore not a smaller read but a read into whatever the layout put
+ * next, and nothing downstream objects: the particles simply come out wrong.
+ *
+ * Binding is deliberately not made to enforce this — the offsets are the record's, and an author who
+ * knows what is packed where may mean it — but an editor has this table so it can say so.
+ *
+ * @type {Object<string, number>}
+ */
+export const EMITTER_RENDER_CHANNEL_COMPONENTS = Object.freeze({
+    position: 3,
+    size: 1,
+    color: 4,
+    rotation: 1,
+    frame: 1,
+    velocity: 3,
+});
+
+/**
+ * One particle emitter: a scene node that runs a compiled effect.
+ *
+ * Being a {@link Node3D} is what places it. Add it to a scene and it gets a row in the scene
+ * database's `transforms` table like any other node; parent it to a joint and the GPU hierarchy
+ * pass composes its world matrix from the joint's every frame, animation included, with nothing
+ * copied through the CPU. Remove it from the scene and the row goes with it — and so do its
+ * particles, within a frame, because the emitter's table row is retired with it and its particles
+ * carry that row's generation. There is no transform of its own to keep in step with anything.
+ *
+ * The rest is a description of an effect and nothing else: the attribute {@link layout} and the
+ * compiled {@link program}, the {@link texture} to draw with, spawn rate, pre-warm duration, blend /
+ * projection / feature flags, render-attribute bindings and flipbook grid. Every one of those is the author's,
+ * means the same thing with no device present, and is what a saved effect is made of.
+ *
+ * There are no bounds among them, and there is nowhere here they could go. An emitter's particles
+ * are simulated in world space by arbitrary bytecode: they go where the program sends them, at
+ * whatever size it gives them, for as long as it keeps them alive. Nothing an author could write
+ * down would bound that except "infinite", which culls nothing and marks every depth slice. So the
+ * box is measured instead — from the live particles, by a pass of its own at the end of every frame
+ * (`../bounds/`) — and it lives with the rest of the measured state in
+ * {@link ../data/PARTICLE_EMITTER_STATE.js}. The one thing that IS the author's is whether the
+ * emitter opts into culling at all: `EMITTER_FLAG.CULL` in {@link flags}.
+ *
+ * **Nothing here is the GPU's.** Which table row the emitter was given, which tenancy of it, where
+ * its program was placed in the program heap, which `transforms` row its node ended up in, where
+ * its texture was packed into the atlas — all of that is
+ * {@link ./GPUParticleEmitterContext.js GPUParticleEmitterContext}, held by the
+ * {@link ./EmitterRegistry.js} that registered the emitter and reachable through
+ * {@link ./EmitterRegistry.js#context}. An emitter no registry holds has none, which is also how
+ * "is this emitter live?" is asked. Nor is anything the GPU integrates per frame here — spawn
+ * accumulator, age, sleep are {@link ../data/PARTICLE_EMITTER_STATE.js}, and they stay on the GPU.
+ *
+ * Fields are plain data with no setters. After changing any of them, set `needsUpdate = true` — the
+ * node's own change counter, the same one the renderer reads to decide whether a transform needs
+ * re-uploading — and {@link ./EmitterRegistry.js#flush} restages the row on its next flush. One
+ * counter rather than a setter per field because a row is restaged whole either way: one changed
+ * field and ten cost the same upload.
+ */
+export class ParticleEmitter extends Node3D {
+
+    /**
+     * The per-particle attribute schema: which named attributes a particle of this emitter has, how
+     * wide each is, and what word of the record it sits at.
+     *
+     * @type {import("../layout/ParticleLayout.js").ParticleLayout}
+     */
+    layout;
+
+    /**
+     * The compiled INIT/UPDATE bytecode run for every particle of this emitter.
+     * Replace the immutable program to edit it; do not mutate its bytecode in place.
+     *
+     * @type {import("../isa/ParticleProgram.js").ParticleProgram}
+     */
+    program;
+
+    /**
+     * Image to draw the particles with, by URL, or `null` to draw against the default atlas — a
+     * single white texel, so an untextured emitter is a flat quad of its colour.
+     *
+     * The ECS GPUParticleEmitterSystem loads this URL through AssetManager and packs the image
+     * into a shared sheet. Standalone callers provide their own atlas and regions. Where
+     * a given image lands in that sheet is the system's answer, not the author's — it changes on
+     * every repack, without the emitter changing. The resolved patch is
+     * {@link ./GPUParticleEmitterContext.js#atlas_region}.
+     *
+     * @type {string|null}
+     */
+    texture = null;
+
+    /**
+     * Base RNG seed.
+     *
+     * Two emitters running one program produce identical particles from identical seeds. `0` reads
+     * as "unset", and the row written for such an emitter takes its registration's generation
+     * instead, which no other emitter of that registry shares.
+     *
+     * @type {number}
+     */
+    seed = 0;
+
+    /**
+     * Continuous emission rate, particles per second. Integrated on the GPU by the emitter tick
+     * pass; the CPU never counts particles.
+     * @type {number}
+     */
+    spawn_rate = 0;
+
+    /**
+     * Seconds this emitter is run forward before it is first shown, `0` for none.
+     *
+     * A continuous effect — a smoke column, a dust field — starts empty and grows into its steady
+     * state over one particle lifetime, in front of whoever is watching. Setting this to about the
+     * effect's particle lifetime means the population that arrives on the first visible frame is the
+     * one the emitter would have had by then: spawned, aged, and thinned by its own program over
+     * that long, rather than a crowd of newborns.
+     *
+     * The author's number, and the only thing about a warm-up that is authored. It is not written to
+     * the GPU record: the system queues an emitter that has one at the moment it is registered, and
+     * the warm-up pipeline (`../warmup/`) runs its simulation forward on that frame, over a
+     * population of its own, before moving the result into the scene. Longer costs a longer loop on
+     * that one frame and nothing after it.
+     *
+     * Prewarm controls the initial population's age distribution. It is not needed to bootstrap
+     * culling: emitters without a measured population have unknown bounds and remain eligible to spawn.
+     *
+     * @type {number}
+     */
+    prewarm = 0;
+
+    /**
+     * Packed feature / blend / projection bits — see {@link make_emitter_flags}.
+     * @type {number}
+     */
+    flags = 0;
+
+    /**
+     * Flipbook grid: columns, rows, over whatever region {@link texture} was packed into. `[1, 1]`
+     * is a single frame.
+     * @type {Float32Array}
+     */
+    flipbook = new Float32Array([1, 1]);
+
+    /** @type {number} record word offset of world position, or {@link EMITTER_ATTRIBUTE_ABSENT} */
+    render_position = EMITTER_ATTRIBUTE_ABSENT;
+    /** @type {number} record word offset of size */
+    render_size = EMITTER_ATTRIBUTE_ABSENT;
+    /** @type {number} record word offset of rgba colour */
+    render_color = EMITTER_ATTRIBUTE_ABSENT;
+    /** @type {number} record word offset of roll angle, radians */
+    render_rotation = EMITTER_ATTRIBUTE_ABSENT;
+    /** @type {number} record word offset of flipbook frame index */
+    render_frame = EMITTER_ATTRIBUTE_ABSENT;
+    /** @type {number} record word offset of velocity, read by the STRETCHED projection */
+    render_velocity = EMITTER_ATTRIBUTE_ABSENT;
+
+    get type() {
+        return "ParticleEmitter";
+    }
+
+    /**
+     * Bind render channels to per-particle attributes of this emitter's effect, by attribute name.
+     * Channels left out of `channels` keep whatever they had; a channel that was never bound stays
+     * at {@link EMITTER_ATTRIBUTE_ABSENT}, which the passes read as "this emitter has no such
+     * attribute" — the render pass substitutes a default, the sort pass treats the particle as
+     * being at the origin.
+     *
+     * The record stores word offsets rather than names because that is what the render and sort
+     * passes index a particle record with; resolving here is the only place a name is involved.
+     *
+     * @param {Object<string,string>} channels channel name (see {@link EMITTER_RENDER_CHANNELS}) ->
+     *        attribute name in the effect's layout
+     */
+    bind_render(channels) {
+        assert.isObject(channels, 'channels');
+        assert.defined(this.layout, 'layout');
+
+        const layout = this.layout;
+
+        for (const channel of Object.keys(channels)) {
+            const offset = layout.offsetOf(channels[channel]);
+
+            switch (channel) {
+                case "position": this.render_position = offset; break;
+                case "size": this.render_size = offset; break;
+                case "color": this.render_color = offset; break;
+                case "rotation": this.render_rotation = offset; break;
+                case "frame": this.render_frame = offset; break;
+                case "velocity": this.render_velocity = offset; break;
+                default:
+                    throw new Error(
+                        `Unknown render channel '${channel}', expected one of ${EMITTER_RENDER_CHANNELS.join(', ')}`
+                    );
+            }
+        }
+
+        this.needsUpdate = true;
+    }
+
+    /**
+     * Structural equality over everything an emitter *is*: where it sits, what it runs, what it
+     * draws with, and how it is bound to the renderer. Two emitters that compare equal describe one
+     * effect in one place, and one row would serve both.
+     *
+     * The node's identity is not part of it — `id`, parent and children say where an emitter is in
+     * a scene, not what it is — and neither is anything the GPU assigned it, which is not here to
+     * be compared. {@link transform_global} is left out too, being derived from
+     * {@link transform_local} and the parent chain.
+     *
+     * @param {ParticleEmitter} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        if (this === other) {
+            return true;
+        }
+
+        return this.name === other.name
+            && this.texture === other.texture
+            && this.seed === other.seed
+            && this.spawn_rate === other.spawn_rate
+            && this.prewarm === other.prewarm
+            && this.flags === other.flags
+            && this.render_position === other.render_position
+            && this.render_size === other.render_size
+            && this.render_color === other.render_color
+            && this.render_rotation === other.render_rotation
+            && this.render_frame === other.render_frame
+            && this.render_velocity === other.render_velocity
+            && is_typed_array_equals(this.flipbook, other.flipbook)
+            && this.transform_local.equals(other.transform_local)
+            && this.layout.equals(other.layout)
+            && this.program.equals(other.program);
+    }
+
+    /**
+     * Hash over everything {@link equals} compares, in the same terms — the compiled program hashes
+     * by its own bytecode rather than by object identity, so two emitters separately compiled from
+     * one graph hash equally, as they compare equally.
+     *
+     * @returns {number} int32
+     */
+    hash() {
+        const bindings = hash_mix3(
+            hash_mix3(this.render_position, this.render_size, this.render_color),
+            hash_mix3(this.render_rotation, this.render_frame, this.render_velocity),
+            this.flags
+        );
+
+        const flipbook = float32_array_hash(this.flipbook, 0, this.flipbook.length);
+
+        const appearance = hash_mix3(
+            computeStringHash(this.name),
+            computeStringHash(this.texture),
+            hash_mix3(this.seed, computeHashFloat(this.spawn_rate), computeHashFloat(this.prewarm))
+        );
+
+        return hash_mix3(
+            hash_mix2(bindings, flipbook),
+            hash_mix2(appearance, this.transform_local.hash()),
+            hash_mix2(this.layout.hash(), this.program.hash())
+        );
+    }
+
+    /**
+     * Make this emitter a copy of `other`: same effect, same settings, same placement.
+     *
+     * The layout and the compiled program are shared rather than duplicated — both are immutable
+     * once compiled, and sharing them is what puts two emitters of one effect on one program id in
+     * the program heap, hence in one simulation bucket.
+     *
+     * What is not copied is the node's identity and its place in a scene ({@link Node3D#id},
+     * parent, children), and anything a registry gave the original: a copy is a second emitter, not
+     * a second reference to the first one's table row.
+     *
+     * @param {ParticleEmitter} other
+     */
+    copy(other) {
+        super.copy(other);
+
+        this.name = other.name;
+
+        this.layout = other.layout;
+        this.program = other.program;
+        this.texture = other.texture;
+
+        this.seed = other.seed;
+        this.spawn_rate = other.spawn_rate;
+        this.prewarm = other.prewarm;
+        this.flags = other.flags;
+
+        this.flipbook.set(other.flipbook);
+
+        this.render_position = other.render_position;
+        this.render_size = other.render_size;
+        this.render_color = other.render_color;
+        this.render_rotation = other.render_rotation;
+        this.render_frame = other.render_frame;
+        this.render_velocity = other.render_velocity;
+    }
+
+    /**
+     * A second emitter equal to this one, and registered with nothing. Its subtree is cloned the
+     * way {@link Node3D#clone} clones one — overridden only because the base builds a plain
+     * `Node3D`, which would keep the transform and drop the effect.
+     *
+     * @returns {ParticleEmitter}
+     */
+    clone() {
+        const r = new ParticleEmitter();
+
+        r.copy(this);
+
+        for (const child of this.children) {
+            const clone = child.clone();
+
+            clone.parent = r;
+
+            r.children.push(clone);
+        }
+
+        return r;
+    }
+
+    /**
+     * Build an emitter from a plain description. Every parameter is optional except the compiled
+     * effect — an emitter with no program has nothing to run.
+     *
+     * `layout` and `program` are the two halves of what {@link ./create_particle_effect.js} returns,
+     * so an effect goes in by spreading it: `ParticleEmitter.from({ ...effect, spawn_rate: 100 })`.
+     *
+     * @param {object} config
+     * @param {import("../layout/ParticleLayout.js").ParticleLayout} config.layout per-particle
+     *        attribute schema
+     * @param {import("../isa/ParticleProgram.js").ParticleProgram} config.program compiled INIT /
+     *        UPDATE bytecode
+     * @param {ArrayLike<number>} [config.position] local translation, `[x, y, z]`
+     * @param {string|null} [config.texture] image URL to draw with
+     * @param {number} [config.seed]
+     * @param {number} [config.spawn_rate] particles/second
+     * @param {number} [config.prewarm] seconds of emission to run forward before the first frame
+     * @param {object} [config.flags] passed to {@link make_emitter_flags}
+     * @param {Object<string,string>} [config.render] render channel -> attribute name
+     * @param {ArrayLike<number>} [config.flipbook] [cols, rows]
+     * @param {string} [config.name]
+     * @returns {ParticleEmitter}
+     */
+    static from(config) {
+        assert.isObject(config, 'config');
+        assert.defined(config.layout, 'config.layout');
+        assert.defined(config.program, 'config.program');
+
+        const emitter = new ParticleEmitter();
+
+        emitter.layout = config.layout;
+        emitter.program = config.program;
+
+        if (config.name !== undefined) {
+            emitter.name = config.name;
+        }
+
+        if (config.texture !== undefined) {
+            emitter.texture = config.texture;
+        }
+
+        if (config.position !== undefined) {
+            emitter.transform_local.setTranslation(config.position[0], config.position[1], config.position[2]);
+            emitter.updateMatrices();
+        }
+
+        if (config.seed !== undefined) {
+            emitter.seed = config.seed;
+        }
+
+        if (config.spawn_rate !== undefined) {
+            emitter.spawn_rate = config.spawn_rate;
+        }
+
+        if (config.prewarm !== undefined) {
+            emitter.prewarm = config.prewarm;
+        }
+
+        emitter.flags = make_emitter_flags(config.flags ?? {});
+
+        if (config.flipbook !== undefined) {
+            emitter.flipbook.set(config.flipbook);
+        }
+
+        if (config.render !== undefined) {
+            emitter.bind_render(config.render);
+        }
+
+        return emitter;
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+ParticleEmitter.prototype.isParticleEmitter = true;