@woosh/meep-engine 3.15.0 → 3.16.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"ParticleEmitter.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/ParticleEmitter.js"],"names":[],"mappings":"AAiXA;;;;;GAKG;AACH,yCAFa,MAAM,CA8BlB;AA/YD;;;;;GAKG;AACH,sCAFU,MAAM,EAAE,CAIf;AAEH;;;;;;;;;;;;GAYG;AACH;QAFiB,MAAM,GAAE,MAAM;EAS5B;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IAqOI;;;;;;;;;;;;;;;;;OAiBG;IACH;QAbqD,MAAM,EAAhD;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAC;QAEN,QAAQ,GAAnC,UAAU,MAAM,CAAC;QACD,IAAI,GAApB,MAAM;QACU,UAAU,GAA1B,MAAM;QACU,KAAK,GAArB,MAAM;QACiD,MAAM,GAA7D;YAAC,MAAM,CAAC,EAAE,UAAU,MAAM,CAAC,CAAC;YAAC,MAAM,CAAC,EAAE,MAAM,CAAA;SAAC;QACd,MAAM;gBAA9B,MAAM,GAAC,MAAM;;QACO,YAAY,GAAvC,UAAU,MAAM,CAAC;QACU,QAAQ,GAAnC,UAAU,MAAM,CAAC;QACD,IAAI,GAApB,MAAM;QACJ,eAAe,CAqD3B;IAxSD;;;;;;;;;OASG;IACH,KAFU,MAAM,CAEP;IAET;;;;;;OAMG;IACH,YAFU,MAAM,CAED;IAEf;;;;;;OAMG;IACH,eAFU,MAAM,CAEE;IAElB;;;;OAIG;IACH,QAFU;QAAC,MAAM,EAAE,OAAO,6BAA6B,EAAE,cAAc,CAAC;QAAC,OAAO,EAAE,OAAO,2BAA2B,EAAE,eAAe,CAAA;KAAC,CAE/H;IAEP;;;;;;OAMG;IACH,WAFU;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAEnI;IAEV;;;;;;;;OAQG;IACH,MAFU,MAAM,CAEP;IAET;;;;OAIG;IACH,YAFU,MAAM,CAED;IAEf;;;OAGG;IACH,OAFU,MAAM,CAEN;IAEV;;;;;;;;;;;;;;OAcG;IACH,eAFU,YAAY,CAEc;IAEpC;;OAEG;IACH,eAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,cAFU,YAAY,CAEwB;IAE9C;;;OAGG;IACH,UAFU,YAAY,CAEc;IAEpC,+FAA+F;IAC/F,iBADW,MAAM,CAC0B;IAC3C,gDAAgD;IAChD,aADW,MAAM,CACsB;IACvC,uDAAuD;IACvD,cADW,MAAM,CACuB;IACxC,+DAA+D;IAC/D,iBADW,MAAM,CAC0B;IAC3C,gEAAgE;IAChE,cADW,MAAM,CACuB;IACxC,sFAAsF;IACtF,iBADW,MAAM,CAC0B;IAE3C;;;;;OAKG;IACH,OAFU,OAAO,CAEJ;IAEb,mBAEC;IAED;;;;;;;;;;;;OAYG;IACH;YAHkB,MAAM,GAAC,MAAM;aA2B9B;IAED;;;;;;;;;;;;;;OAcG;IACH,qBAHW,MAAM,GACJ,MAAM,CAkClB;IAED;;;;;OAKG;IACH,aAFa,MAAM,CAIlB;IA0EL;;;OAGG;IACH,4BAFU,OAAO,CAE0B;CAN1C;uBAxWsB,uBAAuB"}

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

@@ -0,0 +1,404 @@
+import { assert } from "../../../../core/assert.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 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 {
+
+    /**
+     * 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 = -1;
+
+    /**
+     * 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 = 0;
+
+    /**
+     * 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 = 0;
+
+    /**
+     * 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;
+
+    /**
+     * 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;
+
+    /**
+     * 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 = 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;
+
+    /**
+     * Atlas sub-rect: uv offset `.xy`, uv scale `.zw`. Mirrors meep's `AtlasPatch`.
+     * @type {Float32Array}
+     */
+    atlas_region = new Float32Array([0, 0, 1, 1]);
+
+    /**
+     * Flipbook grid: columns, rows. `[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;
+
+    /**
+     * 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 = true;
+
+    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.effect, 'effect');
+
+        const layout = this.effect.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.dirty = true;
+    }
+
+    /**
+     * 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) {
+        assert.defined(this.placement, 'placement');
+
+        const placement = this.placement;
+
+        record.init_offset = placement.init_offset;
+        record.init_count = placement.init_count;
+        record.update_offset = placement.update_offset;
+        record.update_count = placement.update_count;
+        record.constant_offset = placement.constant_offset;
+        record.program_id = placement.program_id;
+
+        record.seed = this.seed;
+        record.flags = this.flags;
+        record.spawn_rate = this.spawn_rate;
+        record.node = this.transform_row;
+        record.generation = this.generation;
+
+        record.bounds_center.set(this.bounds_center);
+        record.bounds_radius = this.bounds_radius;
+
+        record.render_position = this.render_position;
+        record.render_size = this.render_size;
+        record.render_color = this.render_color;
+        record.render_rotation = this.render_rotation;
+        record.render_frame = this.render_frame;
+        record.render_velocity = this.render_velocity;
+
+        record.atlas_region.set(this.atlas_region);
+        record.flipbook.set(this.flipbook);
+
+        return record;
+    }
+
+    /**
+     * 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() {
+        return this.write_record(create_emitter_record());
+    }
+
+    /**
+     * 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) {
+        assert.isObject(config, 'config');
+        assert.defined(config.effect, 'config.effect');
+        assert.defined(config.effect.program, 'config.effect.program');
+        assert.defined(config.effect.layout, 'config.effect.layout');
+
+        const emitter = new ParticleEmitter();
+
+        emitter.effect = config.effect;
+
+        if (config.name !== undefined) {
+            emitter.name = config.name;
+        }
+
+        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.atlas_region !== undefined) {
+            emitter.atlas_region.set(config.atlas_region);
+        }
+
+        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;
+
+/**
+ * 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() {
+    return {
+        init_offset: 0,
+        init_count: 0,
+        update_offset: 0,
+        update_count: 0,
+        constant_offset: 0,
+        program_id: 0,
+
+        seed: 0,
+        flags: 0,
+        spawn_rate: 0,
+        node: 0,
+        generation: 0,
+
+        bounds_center: new Float32Array(3),
+        bounds_radius: 0,
+
+        render_position: 0,
+        render_size: 0,
+        render_color: 0,
+        render_rotation: 0,
+        render_frame: 0,
+        render_velocity: 0,
+
+        atlas_region: new Float32Array(4),
+        flipbook: new Float32Array(2),
+    };
+}

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

@@ -1,6 +1,6 @@
 /**
  * CPU-side spawn scheduling. Each frame it turns per-emitter spawn rates (and the cull/sleep state)
- * into a flat list of spawn requests (packed emitter index + batch fraction per particle to create,
+ * into a flat list of spawn requests (packed emitter id + batch fraction per particle to create,
  * see {@link spawn_request_pack}) that the emit pass consumes. Emitters are few and CPU-authored,
  * so deciding *how many* to spawn on the CPU is cheap and keeps the GPU emit pass a simple
  * "one thread per new particle".
@@ -8,6 +8,10 @@
  * Sleep-when-culled: a culled emitter accumulates sleep time and spawns nothing. When it becomes
  * visible again it emits a bounded catch-up burst approximating the spawns it missed, mirroring the
  * catch-up in meep's ParticularEngine (but capped so a long occlusion can't spike the pool).
+ *
+ * State is keyed by {@link Emitter#id}, not by position in the emitter array: ids are stable and
+ * sparse, positions are neither, and a positional key would silently hand a new emitter the
+ * accumulator and sleep debt of whichever one used to sit at its index.
  */
 export class ParticleSpawnScheduler {
     /**
@@ -17,27 +21,57 @@ export class ParticleSpawnScheduler {
     constructor({ max_catchup_seconds }?: {
         max_catchup_seconds?: number;
     });
+    /**
+     * Cap on how much missed time a wake-up burst covers, in seconds.
+     * @type {number}
+     */
     max_catchup_seconds: number;
-    /** @type {Array<{accumulator: number, sleep_time: number, was_visible: boolean}>} */
-    state: Array<{
-        accumulator: number;
-        sleep_time: number;
-        was_visible: boolean;
-    }>;
-    /** Ensure per-emitter state exists for `count` emitters. */
-    ensure(count: any): void;
+    /**
+     * Emitter id -> its bookkeeping.
+     * @type {Map<number, ParticleSpawnState>}
+     */
+    state: Map<number, ParticleSpawnState>;
+    /**
+     * Drop bookkeeping for an emitter that is no longer registered, so a later emitter reusing that
+     * table row starts from zero instead of inheriting a stranger's accumulator.
+     *
+     * @param {number} id
+     */
+    forget(id: number): void;
     /**
      * Produce this frame's spawn requests.
      *
-     * @param {Array<{spawn_rate: number}>} emitters
+     * @param {Iterable<import("./Emitter.js").Emitter>} emitters the live emitters
      * @param {number} dt seconds
-     * @param {(index: number) => boolean} [is_visible] cull predicate (default: all visible)
+     * @param {(emitter: import("./Emitter.js").Emitter) => boolean} [is_visible] cull predicate
+     *        (default: all visible)
      * @param {number} [capacity] optional hard cap on total requests this frame
-     * @returns {Uint32Array} flat list of packed spawn requests (emitter index + batch fraction),
+     * @returns {Uint32Array} flat list of packed spawn requests (emitter id + batch fraction),
      *     one per particle to spawn — see {@link spawn_request_pack}
      */
-    tick(emitters: Array<{
-        spawn_rate: number;
-    }>, dt: number, is_visible?: (index: number) => boolean, capacity?: number): Uint32Array;
+    tick(emitters: Iterable<import("./Emitter.js").Emitter>, dt: number, is_visible?: (emitter: import("./Emitter.js").Emitter) => boolean, capacity?: number): Uint32Array;
+    #private;
+}
+/**
+ * Per-emitter spawn bookkeeping, carried across frames.
+ */
+declare class ParticleSpawnState {
+    /**
+     * Fractional particles owed. A rate of 0.5/s at 60fps owes 1/120 of a particle per frame; the
+     * whole part is emitted and the remainder carried, so the emitter fires once every two seconds
+     * rather than never.
+     * @type {number}
+     */
+    accumulator: number;
+    /**
+     * Seconds spent culled since the emitter was last visible.
+     * @type {number}
+     */
+    sleep_time: number;
+    /**
+     * @type {boolean}
+     */
+    was_visible: boolean;
 }
+export {};
 //# sourceMappingURL=ParticleSpawnScheduler.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ParticleSpawnScheduler.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/ParticleSpawnScheduler.js"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH;IACI;;;OAGG;IACH;QAF4B,mBAAmB,GAApC,MAAM;OAMhB;IAHG,4BAA8C;IAC9C,qFAAqF;IACrF,OADW,MAAM;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,OAAO,CAAA;KAAC,CAAC,CAClE;IAGnB,4DAA4D;IAC5D,yBAIC;IAED;;;;;;;;;OASG;IACH,eAPW,MAAM;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAAC,MAC3B,MAAM,uBACE,MAAM,KAAK,OAAO,aAC1B,MAAM,GACJ,WAAW,CA8CvB;CACJ"}
+{"version":3,"file":"ParticleSpawnScheduler.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/ParticleSpawnScheduler.js"],"names":[],"mappings":"AA0BA;;;;;;;;;;;;;;GAcG;AACH;IAcI;;;OAGG;IACH;QAF4B,mBAAmB,GAApC,MAAM;OAIhB;IAlBD;;;OAGG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,OAFU,IAAI,MAAM,EAAE,kBAAkB,CAAC,CAEvB;IA2BlB;;;;;OAKG;IACH,WAFW,MAAM,QAIhB;IAED;;;;;;;;;;OAUG;IACH,eARW,SAAS,OAAO,cAAc,EAAE,OAAO,CAAC,MACxC,MAAM,yBACI,OAAO,cAAc,EAAE,OAAO,KAAK,OAAO,aAEpD,MAAM,GACJ,WAAW,CA6CvB;;CACJ;AA9ID;;GAEG;AACH;IACI;;;;;OAKG;IACH,aAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,YAFU,MAAM,CAED;IAEf;;OAEG;IACH,aAFU,OAAO,CAEE;CACtB"}

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

@@ -1,22 +1,51 @@
 /**
- * Packs many compiled {@link ../isa/ParticleProgram.js} programs into two shared buffers — one of
- * instruction words, one of constant words — and hands back the offsets each emitter records.
+ * Packs many compiled {@link ../isa/ParticleProgram.js} programs into one shared buffer — a header,
+ * every program's constant pool, then every program's instruction words — and hands back the
+ * offsets each emitter records.
+ *
+ * Data before code, behind a four-word header whose first word says where the code starts: the VM
+ * reads both sections through one binding (a storage buffer per stage is not free, and code and
+ * constants are read together), and an emitter's constant pool sits next to the pools of the
+ * programs it shares a wave with.
  *
  * Because VM instructions carry no absolute code addresses (control flow is branchless) and
- * constant references are program-local (the shader adds the emitter's `constant_offset`), programs
- * can be concatenated at any offset. SPAWN and UPDATE sections are laid out back-to-back per program.
+ * constant references are program-local (the VM adds the emitter's `constant_offset`), programs
+ * can be concatenated at any offset. INIT and UPDATE sections are laid out back-to-back per program.
  */
 export class ProgramArena {
-    /** @type {number[]} flat instruction words */
+    /**
+     * Flat instruction words, every program's INIT and UPDATE sections concatenated.
+     * @type {number[]}
+     */
     instruction_words: number[];
-    /** @type {number[]} flat constant words (f32 bit patterns) */
+    /**
+     * Flat constant words (f32 bit patterns), every program's pool concatenated.
+     * @type {number[]}
+     */
     constant_words: number[];
-    /** @type {number} running instruction index (SPAWN/UPDATE offsets are in these units) */
+    /**
+     * Running instruction index — INIT/UPDATE offsets are in these units.
+     * @type {number}
+     */
     instruction_count: number;
-    /** @type {number} running vec4 constant index */
-    constant_count: number;
-    /** @type {Map<string, object>} content key -> the placement the first identical program got */
-    programs: Map<string, object>;
+    /**
+     * Running constant word index — the pool is addressed by word, so a scalar literal costs one
+     * rather than the four a `vec4` entry used to.
+     * @type {number}
+     */
+    constant_word_count: number;
+    /**
+     * Content key -> the placement the first identical program got.
+     * @type {Map<string, {init_offset: number, init_count: number, update_offset: number, update_count: number, constant_offset: number, program_id: number}>}
+     */
+    programs: Map<string, {
+        init_offset: number;
+        init_count: number;
+        update_offset: number;
+        update_count: number;
+        constant_offset: number;
+        program_id: number;
+    }>;
     /**
      * Number of distinct programs in the arena — and therefore the number of buckets the
      * simulation-order pass histograms into. Program ids are dense in `[0, program_count)`.
@@ -37,20 +66,24 @@ export class ProgramArena {
      * which both wastes lanes and splits a run that was already program-coherent.
      *
      * @param {import("../isa/ParticleProgram.js").ParticleProgram} program
-     * @returns {{spawn_offset: number, spawn_count: number, update_offset: number, update_count: number, constant_offset: number, program_id: number}}
+     * @returns {{init_offset: number, init_count: number, update_offset: number, update_count: number, constant_offset: number, program_id: number}}
      */
     add(program: import("../isa/ParticleProgram.js").ParticleProgram): {
-        spawn_offset: number;
-        spawn_count: number;
+        init_offset: number;
+        init_count: number;
         update_offset: number;
         update_count: number;
         constant_offset: number;
         program_id: number;
     };
-    /** @returns {Uint32Array} the packed instruction buffer (at least length 1) */
-    build_instruction_buffer(): Uint32Array;
-    /** @returns {Uint32Array} the packed constant buffer (at least length 4 for one vec4) */
-    build_constant_buffer(): Uint32Array;
+    /**
+     * The packed buffer: `[header][constants][code]`. Word {@link PARTICLE_PROGRAM_CODE_BASE_WORD} of
+     * the header is the word index the code starts at, which moves every time a program's constants
+     * are appended — the emitter records never carry it, they carry offsets into each section.
+     *
+     * @returns {Uint32Array}
+     */
+    build_program_buffer(): Uint32Array;
     #private;
 }
 //# sourceMappingURL=ProgramArena.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ProgramArena.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/ProgramArena.js"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH;IAEQ,8CAA8C;IAC9C,mBADW,MAAM,EAAE,CACQ;IAC3B,8DAA8D;IAC9D,gBADW,MAAM,EAAE,CACK;IACxB,yFAAyF;IACzF,mBADW,MAAM,CACS;IAC1B,iDAAiD;IACjD,gBADW,MAAM,CACM;IACvB,+FAA+F;IAC/F,UADW,IAAI,MAAM,EAAE,MAAM,CAAC,CACL;IAG7B;;;;OAIG;IACH,4BAEC;IAED;;;;;;;;;;;;;;;OAeG;IACH,aAHW,OAAO,2BAA2B,EAAE,eAAe;sBAClC,MAAM;qBAAe,MAAM;uBAAiB,MAAM;sBAAgB,MAAM;yBAAmB,MAAM;oBAAc,MAAM;MAgChJ;IAUD,+EAA+E;IAC/E,4BADc,WAAW,CAGxB;IAED,yFAAyF;IACzF,yBADc,WAAW,CAGxB;;CACJ"}
+{"version":3,"file":"ProgramArena.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/runtime/ProgramArena.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;GAaG;AACH;IAEI;;;OAGG;IACH,mBAFU,MAAM,EAAE,CAEK;IAEvB;;;OAGG;IACH,gBAFU,MAAM,EAAE,CAEE;IAEpB;;;OAGG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;;OAIG;IACH,qBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,UAFU,IAAI,MAAM,EAAE;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAC,CAAC,CAErI;IAErB;;;;OAIG;IACH,4BAEC;IAED;;;;;;;;;;;;;;;OAeG;IACH,aAHW,OAAO,2BAA2B,EAAE,eAAe;qBACnC,MAAM;oBAAc,MAAM;uBAAiB,MAAM;sBAAgB,MAAM;yBAAmB,MAAM;oBAAc,MAAM;MAgC9I;IAUD;;;;;;OAMG;IACH,wBAFa,WAAW,CAcvB;;CACJ"}