@woosh/meep-engine 3.14.6 → 3.16.0

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

@@ -1,117 +1,286 @@
-import { assert } from "../../../../core/assert.js";
-import {
-    EMITTER_ATTACH_NONE,
-    EMITTER_STRIDE,
-    make_emitter_flags,
-    pack_emitter,
-} from "../data/PARTICLE_EMITTER_LAYOUT.js";
-import { ProgramArena } from "./ProgramArena.js";
-
-const IDENTITY = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
-const RENDER_KEYS = ["position", "size", "color", "rotation", "frame", "velocity"];
-
-/**
- * CPU-side registry of emitters. Each emitter binds a compiled effect (from
- * {@link ./create_particle_effect.js}) to instance parameters — world transform, spawn rate, blend /
- * projection / feature flags, bounds, render-attribute binding, atlas region and flipbook grid.
- *
- * {@link build} produces the three upload-ready buffers the GPU passes consume: the packed emitter
- * records, the concatenated program instructions, and the constant pool. Emitters are few and
- * long-lived, so the whole set is repacked when it changes.
- */
-export class EmitterRegistry {
-    constructor() {
-        /** @type {object[]} */
-        this.emitters = [];
-    }
-
-    /** @returns {number} number of registered emitters */
-    get count() {
-        return this.emitters.length;
-    }
-
-    /**
-     * Register an emitter.
-     *
-     * @param {object} config
-     * @param {{layout: object, program: object}} config.effect compiled effect
-     * @param {number[]} [config.transform] 16-element column-major local-to-world matrix
-     * @param {number} [config.seed]
-     * @param {number} [config.spawn_rate] particles/second
-     * @param {object} [config.flags] passed to {@link make_emitter_flags}
-     * @param {{center?: number[], radius?: number}} [config.bounds]
-     * @param {Object<string,string>} [config.render] map of render channel -> attribute name
-     * @param {number[]} [config.atlas_region] [uvOffsetX, uvOffsetY, uvScaleX, uvScaleY]
-     * @param {number[]} [config.flipbook] [cols, rows]
-     * @param {number} [config.attach_row] scene transforms row for bone attachment
-     * @returns {number} the emitter index
-     */
-    add(config) {
-        assert.defined(config.effect, "config.effect");
-        assert.defined(config.effect.program, "config.effect.program");
-        assert.defined(config.effect.layout, "config.effect.layout");
-
-        this.emitters.push(config);
-        return this.emitters.length - 1;
-    }
-
-    /**
-     * Pack all emitters + their programs into upload-ready buffers.
-     *
-     * `program_count` is the number of DISTINCT programs across the emitter set — the bucket count
-     * the simulation-order coherence pass histograms into. It is CPU-known and low-churn (it only
-     * changes when the emitter set does), which is why that pass can size its histogram, its cursor
-     * and its padding dispatch on the host without any of the per-frame counts ever leaving the GPU.
-     *
-     * @returns {{ emitters: Uint32Array, program: Uint32Array, constants: Uint32Array, program_count: number }}
-     */
-    build() {
-        const arena = new ProgramArena();
-        const emitters = new Uint32Array(Math.max(1, this.emitters.length) * EMITTER_STRIDE);
-        const f32 = new Float32Array(emitters.buffer);
-
-        this.emitters.forEach((config, index) => {
-            const offsets = arena.add(config.effect.program);
-            const layout = config.effect.layout;
-
-            const render = {};
-            if (config.render !== undefined) {
-                for (const key of RENDER_KEYS) {
-                    const attribute = config.render[key];
-                    if (attribute !== undefined) {
-                        render[key] = layout.offsetOf(attribute);
-                    }
-                }
-            }
-
-            pack_emitter(emitters, f32, index, {
-                ...offsets,
-                seed: config.seed ?? (index + 1),
-                flags: make_emitter_flags(config.flags ?? {}),
-                spawn_rate: config.spawn_rate ?? 0,
-                transform: config.transform ?? IDENTITY,
-                bounds_center: config.bounds?.center,
-                bounds_radius: config.bounds?.radius,
-                render,
-                atlas_region: config.atlas_region,
-                flipbook: config.flipbook,
-            });
-        });
-
-        return {
-            emitters,
-            program: arena.build_instruction_buffer(),
-            constants: arena.build_constant_buffer(),
-            program_count: Math.max(1, arena.program_count),
-        };
-    }
-
-    /**
-     * The scene-node row an emitter is attached to (for bone attachment), or the "none" sentinel.
-     * @param {number} index
-     * @returns {number}
-     */
-    attachRow(index) {
-        return this.emitters[index]?.attach_row ?? EMITTER_ATTACH_NONE;
-    }
-}
+import { assert } from "../../../../core/assert.js";
+import { GPUDatabase } from "../../buffer/table/GPUDatabase.js";
+import {
+    PARTICLE_DATABASE_INITIAL_SIZE,
+    PARTICLE_DATABASE_SPEC,
+    PARTICLE_EMITTER_STATE_TABLE,
+    PARTICLE_EMITTER_TABLE
+} from "../data/PARTICLE_DATABASE_SPEC.js";
+import { PARTICLE_EMITTER_STATE_EMPTY } from "../data/PARTICLE_EMITTER_STATE.js";
+import { PARTICLE_GENERATION_FIRST, particle_generation_next } from "../data/particle_header.js";
+import { create_emitter_record, ParticleEmitter } from "./ParticleEmitter.js";
+import { ProgramArena } from "./ProgramArena.js";
+
+/**
+ * Staging for one emitter row. Reused across every write — the table serializes it into its page
+ * shadow synchronously, so nothing outlives the call. This is what keeps a frame's flush free of
+ * allocation whatever the number of rows it restages.
+ */
+const RECORD = create_emitter_record();
+
+/**
+ * The emitter set: {@link ParticleEmitter} instances on the CPU, one GPU table row each.
+ *
+ * Rows live in a {@link GPUDatabase} table ({@link ../data/PARTICLE_DATABASE_SPEC.js}), which is
+ * what makes the set editable at runtime. Adding an emitter stages one record; removing one frees
+ * its slot for the next add; changing one restages that record and nothing else. Rows are handed
+ * out by the table and are stable for an emitter's lifetime — they have to be, because every live
+ * particle's record header stores the row of the emitter that spawned it.
+ *
+ * Reuse of a freed row is made safe by the **generation**: every add takes the next value of one
+ * running counter, so no two emitters this registry has ever registered share one, and the
+ * 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}.
+ *
+ * The GPU-owned per-emitter state is the database's second table, claimed and released here at the
+ * emitter's row and never written by the CPU otherwise.
+ *
+ * Programs are the one thing NOT in the database: they are variable-length and shared, so they go
+ * into a packed {@link ProgramArena} buffer and the emitter record carries offsets into it. The arena is
+ * append-only and content-deduplicated — two emitters compiled from the same graph land on one
+ * program id, which is what the simulation-order bucketing buckets on. Removing an emitter does not
+ * reclaim its program: the dense `program_id`s are baked into every other emitter's record, so
+ * compacting them would mean rewriting the whole table to save a few hundred words.
+ */
+export class EmitterRegistry {
+
+    /**
+     * @type {GPUDatabase}
+     */
+    database;
+
+    /**
+     * Packed instruction + constant buffers for every distinct program in the set.
+     * @type {ProgramArena}
+     */
+    arena = new ProgramArena();
+
+    /**
+     * The live emitters, in no particular order — {@link ParticleEmitter#row} is the identity.
+     * @type {ParticleEmitter[]}
+     */
+    emitters = [];
+
+    /**
+     * The live emitters by table row. Sparse: a freed row reads `undefined` until it is reused.
+     * Rows are small dense integers handed out lowest-free-first, so an array is the right index.
+     *
+     * @type {ParticleEmitter[]}
+     */
+    by_row = [];
+
+    /**
+     * Whether {@link arena} has grown since the instruction/constant buffers were last built. Those
+     * two are monolithic (a program is variable-length, so there is no table to page them into), so
+     * a new program means re-uploading them whole — which is why the arena dedupes by content and
+     * why this is a separate flag from the per-row dirtiness the table tracks.
+     *
+     * @type {boolean}
+     */
+    programs_dirty = true;
+
+    /**
+     * The generation the next add will take.
+     * @type {number}
+     */
+    #generation = PARTICLE_GENERATION_FIRST;
+
+    /**
+     * @param {GPUDevice} device
+     */
+    constructor(device) {
+        assert.defined(device, 'device');
+
+        this.database = new GPUDatabase({
+            device,
+            definition: PARTICLE_DATABASE_SPEC,
+            label: 'Particles / Emitters',
+            initial_data_size_bytes: PARTICLE_DATABASE_INITIAL_SIZE,
+        });
+    }
+
+    /**
+     * The emitter table.
+     * @returns {GPUTypedTable}
+     */
+    get table() {
+        return this.database.get(PARTICLE_EMITTER_TABLE);
+    }
+
+    /**
+     * The GPU-owned state table: one row per emitter, at the emitter's row, claimed and released
+     * here and otherwise the GPU's.
+     * @returns {GPUTypedTable}
+     */
+    get state_table() {
+        return this.database.get(PARTICLE_EMITTER_STATE_TABLE);
+    }
+
+    /**
+     * @returns {number} number of live emitters
+     */
+    get count() {
+        return this.emitters.length;
+    }
+
+    /**
+     * Number of distinct compiled programs — the number of buckets the simulation-order coherence
+     * pass histograms into.
+     *
+     * @returns {number}
+     */
+    get program_count() {
+        return this.arena.program_count;
+    }
+
+    /**
+     * Register an emitter and give it a table row.
+     *
+     * @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
+     * @returns {ParticleEmitter}
+     */
+    add(config, transform_row = 0) {
+        const emitter = config.isParticleEmitter === true ? config : ParticleEmitter.from(config);
+
+        assert.equal(emitter.row, -1, 'emitter.row — this emitter is already registered');
+
+        const program_count_before = this.arena.program_count;
+
+        emitter.placement = this.arena.add(emitter.effect.program);
+
+        if (this.arena.program_count !== program_count_before) {
+            this.programs_dirty = true;
+        }
+
+        emitter.generation = this.#generation;
+        this.#generation = particle_generation_next(this.#generation);
+
+        emitter.transform_row = transform_row;
+
+        // An emitter given no seed gets one that tells it apart from every other emitter this
+        // registry has seen. Two emitters of one effect are the common case, and an identical seed
+        // makes them the same particles in the same places.
+        if (emitter.seed === 0) {
+            emitter.seed = emitter.generation;
+        }
+
+        // The table picks the slot — the lowest free one, so a removed emitter's row is reused
+        // rather than the id space growing without bound.
+        emitter.row = this.table.add(emitter.write_record(RECORD));
+        emitter.dirty = false;
+
+        // Claim the state row alongside: zeroed, so the first tick starts it over. The CPU never
+        // writes it again — see PARTICLE_EMITTER_STATE.
+        this.state_table.set(emitter.row, PARTICLE_EMITTER_STATE_EMPTY);
+
+        this.emitters.push(emitter);
+        this.by_row[emitter.row] = emitter;
+
+        return emitter;
+    }
+
+    /**
+     * Unregister an emitter and free its table row.
+     *
+     * Its particles are not touched here; they carry its generation, the row they will read is
+     * zero-filled (or a later tenant's, with a different generation), and the simulate pass frees
+     * them the next time it sees them. Retiring an emitter gently — spawn rate to zero, remove once
+     * its particles have died — remains available to an author who wants the tail to play out.
+     *
+     * @param {ParticleEmitter} emitter
+     */
+    remove(emitter) {
+        assert.defined(emitter, 'emitter');
+        assert.equal(emitter.isParticleEmitter, true, 'emitter.isParticleEmitter !== true');
+
+        const position = this.emitters.indexOf(emitter);
+
+        assert.notEqual(position, -1, 'emitter is not registered here');
+
+        // Swap-remove: order carries no meaning, and a splice would allocate.
+        const last = this.emitters.pop();
+
+        if (last !== emitter) {
+            this.emitters[position] = last;
+        }
+
+        this.by_row[emitter.row] = undefined;
+        this.table.remove(emitter.row);
+        this.state_table.remove(emitter.row);
+
+        emitter.row = -1;
+        emitter.generation = 0;
+        emitter.placement = undefined;
+    }
+
+    /**
+     * Look up a live emitter by its table row.
+     *
+     * @param {number} row
+     * @returns {ParticleEmitter|undefined}
+     */
+    get(row) {
+        return this.by_row[row];
+    }
+
+    /**
+     * Point an emitter's record at its node's row in the scene's `transforms` table. The row is
+     * restaged on the next flush.
+     *
+     * @param {ParticleEmitter} emitter
+     * @param {number} transform_row
+     */
+    set_transform_row(emitter, transform_row) {
+        assert.isNonNegativeInteger(transform_row, 'transform_row');
+
+        if (emitter.transform_row === transform_row) {
+            return;
+        }
+
+        emitter.transform_row = transform_row;
+        emitter.dirty = true;
+    }
+
+    /**
+     * Restage the table rows of every emitter whose fields have moved since the last flush.
+     *
+     * Cheap to call every frame: an emitter that has not changed costs one boolean test, and the
+     * table coalesces repeated writes to one row within a frame anyway. Allocates nothing — every
+     * row goes through the one module-static staging record.
+     */
+    flush() {
+        const table = this.table;
+        const emitters = this.emitters;
+        const count = emitters.length;
+
+        for (let i = 0; i < count; i++) {
+            const emitter = emitters[i];
+
+            if (!emitter.dirty) {
+                continue;
+            }
+
+            table.set(emitter.row, emitter.write_record(RECORD));
+            emitter.dirty = false;
+        }
+    }
+
+    /**
+     * The packed program buffer — header, constant pools, code — rebuilt whole.
+     *
+     * Call when {@link programs_dirty}; it clears the flag. The buffer is monolithic (a program is
+     * variable-length, so there is no table to page it into), so this is a full rebuild — the
+     * arena's content deduplication is what keeps it rare (it only grows when an effect the set has
+     * never seen is registered).
+     *
+     * @returns {Uint32Array}
+     */
+    build_program() {
+        this.programs_dirty = false;
+
+        return this.arena.build_program_buffer();
+    }
+}

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

@@ -0,0 +1,264 @@
+/**
+ * An empty staging record with every field of {@link ../data/PARTICLE_EMITTER_STRUCT.js} present,
+ * typed arrays for the vector fields so {@link ParticleEmitter#write_record} can copy into them.
+ *
+ * @returns {object}
+ */
+export function create_emitter_record(): object;
+/**
+ * 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: string[];
+/**
+ * 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: {
+    [x: string]: number;
+};
+/**
+ * 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 the CPU model of one row of the emitter table
+ * ({@link ../data/PARTICLE_EMITTER_STRUCT.js}): the compiled effect and its placement in the
+ * program arena, spawn rate, blend / projection / feature flags, bounds sphere, render-attribute
+ * bindings, atlas region and flipbook grid. {@link write_record} is the whole of the translation
+ * between the two. Fields are plain data with no setters — after changing any of them, set
+ * {@link dirty} so {@link ./EmitterRegistry.js} restages the row on its next flush. A flag rather
+ * than a setter per field because a row is restaged whole either way: one changed field and ten
+ * cost the same upload.
+ *
+ * What is NOT here is anything the GPU integrates per frame — spawn accumulator, age, sleep. That
+ * is {@link ../data/PARTICLE_EMITTER_STATE.js}, and it stays on the GPU.
+ *
+ * Instances become live through a {@link ./EmitterRegistry.js}, which assigns {@link row} and
+ * {@link generation} and resolves the program placement. Constructing one directly gives you an
+ * emitter no table knows about.
+ */
+export class ParticleEmitter extends Node3D {
+    /**
+     * Build an emitter from a plain description. Every parameter is optional except the effect —
+     * an emitter with no program has nothing to run.
+     *
+     * @param {object} config
+     * @param {{layout: object, program: object}} config.effect compiled effect, see
+     *        {@link ./create_particle_effect.js}
+     * @param {ArrayLike<number>} [config.position] local translation, `[x, y, z]`
+     * @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.atlas_region] [uvOffsetX, uvOffsetY, uvScaleX, uvScaleY]
+     * @param {ArrayLike<number>} [config.flipbook] [cols, rows]
+     * @param {string} [config.name]
+     * @returns {ParticleEmitter}
+     */
+    static from(config: {
+        effect: {
+            layout: object;
+            program: object;
+        };
+        position?: ArrayLike<number>;
+        seed?: number;
+        spawn_rate?: number;
+        flags?: object;
+        bounds?: {
+            center?: ArrayLike<number>;
+            radius?: number;
+        };
+        render?: {
+            [x: string]: string;
+        };
+        atlas_region?: ArrayLike<number>;
+        flipbook?: ArrayLike<number>;
+        name?: string;
+    }): ParticleEmitter;
+    /**
+     * Row this emitter occupies in the emitter table. Stable for the emitter's whole life — it is
+     * what every live particle's record header stores, so it cannot be renumbered while particles
+     * are in flight. `-1` until the registry assigns one.
+     *
+     * Not to be confused with {@link Node3D#id}, which is the node's own identity and the key the
+     * scene context maps to a `transforms` row.
+     *
+     * @type {number}
+     */
+    row: number;
+    /**
+     * Which tenancy of {@link row} this emitter is. Assigned by the registry, distinct from every
+     * other emitter it has ever assigned, never zero. Stamped into every particle the emitter
+     * spawns, and what lets the simulate pass tell those particles from a later tenant's.
+     *
+     * @type {number}
+     */
+    generation: number;
+    /**
+     * Row of the scene database's `transforms` table this node occupies, as the scene context
+     * reported it — what the record's `node` field carries. `0` (the scene root) until bound, so
+     * an emitter that is registered before its node is placed still reads a valid row.
+     *
+     * @type {number}
+     */
+    transform_row: number;
+    /**
+     * Compiled effect: the per-particle attribute layout plus the INIT/UPDATE bytecode.
+     *
+     * @type {{layout: import("../layout/ParticleLayout.js").ParticleLayout, program: import("../isa/ParticleProgram.js").ParticleProgram}}
+     */
+    effect: {
+        layout: import("../layout/ParticleLayout.js").ParticleLayout;
+        program: import("../isa/ParticleProgram.js").ParticleProgram;
+    };
+    /**
+     * Where this emitter's program sits in the shared arena, and the dense program id the
+     * simulation-order bucketing keys on. Assigned by {@link EmitterRegistry#add} from
+     * {@link ../runtime/ProgramArena.js}; emitters compiled from the same graph share one.
+     *
+     * @type {{init_offset: number, init_count: number, update_offset: number, update_count: number, constant_offset: number, program_id: number}}
+     */
+    placement: {
+        init_offset: number;
+        init_count: number;
+        update_offset: number;
+        update_count: number;
+        constant_offset: number;
+        program_id: number;
+    };
+    /**
+     * Base RNG seed.
+     *
+     * Two emitters running one program produce identical particles from identical seeds, so leaving
+     * this at 0 is almost never what an author wants — {@link EmitterRegistry#add} reads 0 as
+     * "unset" and derives one from the generation instead.
+     *
+     * @type {number}
+     */
+    seed: number;
+    /**
+     * Continuous emission rate, particles per second. Integrated on the GPU by the emitter tick
+     * pass; the CPU never counts particles.
+     * @type {number}
+     */
+    spawn_rate: number;
+    /**
+     * Packed feature / blend / projection bits — see {@link make_emitter_flags}.
+     * @type {number}
+     */
+    flags: number;
+    /**
+     * 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: Float32Array;
+    /**
+     * @type {number}
+     */
+    bounds_radius: number;
+    /**
+     * Atlas sub-rect: uv offset `.xy`, uv scale `.zw`. Mirrors meep's `AtlasPatch`.
+     * @type {Float32Array}
+     */
+    atlas_region: Float32Array;
+    /**
+     * Flipbook grid: columns, rows. `[1, 1]` is a single frame.
+     * @type {Float32Array}
+     */
+    flipbook: Float32Array;
+    /** @type {number} record word offset of world position, or {@link EMITTER_ATTRIBUTE_ABSENT} */
+    render_position: number;
+    /** @type {number} record word offset of size */
+    render_size: number;
+    /** @type {number} record word offset of rgba colour */
+    render_color: number;
+    /** @type {number} record word offset of roll angle, radians */
+    render_rotation: number;
+    /** @type {number} record word offset of flipbook frame index */
+    render_frame: number;
+    /** @type {number} record word offset of velocity, read by the STRETCHED projection */
+    render_velocity: number;
+    /**
+     * Whether the table row is out of step with the fields above. Set it after changing anything;
+     * {@link EmitterRegistry#flush} clears it once the row has been staged for upload.
+     *
+     * @type {boolean}
+     */
+    dirty: boolean;
+    get type(): string;
+    /**
+     * 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: {
+        [x: string]: string;
+    }): void;
+    /**
+     * Fill `record` with this emitter as the value the emitter table stores — every field of
+     * {@link ../data/PARTICLE_EMITTER_STRUCT.js}, none omitted.
+     *
+     * Omitting one would not write zeros: the serializer skips absent fields, and table pages are
+     * recycled buffers, so a skipped field keeps whatever the previous tenant of the slot left
+     * there.
+     *
+     * Writes into a caller-supplied object rather than returning a fresh one so the registry can
+     * stage every row of a frame through one module-static record — the table serializes it
+     * synchronously, so nothing outlives the call.
+     *
+     * @param {object} record the staging object, see {@link create_emitter_record}
+     * @returns {object} `record`
+     */
+    write_record(record: object): object;
+    /**
+     * This emitter as a fresh record object. {@link write_record} into a shared one is what the
+     * per-frame path uses; this is for tests and one-off inspection.
+     *
+     * @returns {object}
+     */
+    to_record(): object;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isParticleEmitter: boolean;
+}
+import { Node3D } from "../../scene/Node3D.js";
+//# sourceMappingURL=ParticleEmitter.d.ts.map