@woosh/meep-engine 3.18.0 → 3.19.0

package/src/engine/graphics/ecs/particles/ParticleEffect.js

@@ -0,0 +1,455 @@
+import { assert } from "../../../../core/assert.js";
+import { float32_array_hash } from "../../../../core/collection/array/typed/float32_array_hash.js";
+import { is_typed_array_equals } from "../../../../core/collection/array/typed/is_typed_array_equals.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 {
+    EMITTER_ATTRIBUTE_ABSENT,
+    make_emitter_flags
+} from "../../../../shade/renderer/particles/data/PARTICLE_EMITTER_STRUCT.js";
+import { EMITTER_RENDER_CHANNELS } from "../../../../shade/renderer/particles/runtime/ParticleEmitter.js";
+
+/**
+ * What an entity emits. Paired with a {@link ../../../ecs/transform/Transform64.js Transform64},
+ * which says where, this is the whole of an emitter in the ECS:
+ *
+ * ```js
+ * new Entity()
+ *     .add(new Transform64())
+ *     .add(ParticleEffect.from({ ...create_particle_effect({ layout, init, update }), spawn_rate: 400 }))
+ *     .build(dataset);
+ * ```
+ *
+ * {@link ../../../graphics3/GPUParticleEmitterSystem.js GPUParticleEmitterSystem} is what turns the
+ * pair into particles: it gives the entity a
+ * {@link ../../../../shade/renderer/particles/runtime/ParticleEmitter.js ParticleEmitter} node in
+ * the scene it owns, keeps that node where the transform says, packs {@link texture} into the
+ * scene's sprite atlas, and follows every field below. Nothing here reaches a device by itself, and
+ * an entity carrying one of these with no such system in the profile simply emits nothing.
+ *
+ * ## It is a description, and only a description
+ *
+ * Everything on it means the same thing with no renderer present: the attribute {@link layout} and
+ * the compiled {@link program} that make up an effect, the {@link texture} to draw with, the rate,
+ * the pre-warm, the blend / projection / feature {@link flags}, the render-attribute bindings and
+ * the flipbook grid. That is deliberate, and it is what makes the component the unit an editor
+ * inspects, a prefab carries and a system diffs.
+ *
+ * What is **not** here: the scene node the system built, the emitter's row in the GPU emitter table,
+ * the generation of that row, where the program was placed in the program heap, and where the
+ * texture landed in the atlas. All of that belongs to whoever registered the emitter — see
+ * {@link ../../../../shade/renderer/particles/runtime/GPUParticleEmitterContext.js} — and none of it
+ * survives a device restart, which is exactly why it is not on a component that does.
+ *
+ * There are no bounds here either. An emitter's particles are moved by arbitrary bytecode, so the
+ * box is **measured** from the live particles by a GPU pass at the end of every frame rather than
+ * authored; the one authored part of it is whether this effect opts into culling at all
+ * (`cull` in {@link flags}).
+ *
+ * ## Sharing
+ *
+ * {@link layout} and {@link program} are immutable once compiled and are meant to be shared: fifty
+ * campfires hold fifty components pointing at one compiled effect, which is what puts them on one id
+ * in the program heap and therefore in one simulation bucket. {@link copy} shares them rather than
+ * duplicating them for that reason.
+ *
+ * ## Changing one
+ *
+ * Assign to the fields. The system compares what it holds against what it last wrote to the scene
+ * node, once per frame per entity, so there is no flag to set and no signal to fire — a component
+ * whose fields have not moved costs a run of comparisons and no upload. That is a deliberate trade
+ * against the observable-per-field shape the older components use: an effect has fifteen fields,
+ * gameplay writes them in bursts, and a row is restaged whole either way.
+ *
+ * ## Saving one
+ *
+ * {@link ./ParticleEffectSerializationAdapter.js} writes all of it, the compiled program included.
+ * The VM's instruction set is a durable format by design — fixed-width opcodes and a constant pool —
+ * so a level carries the bytecode the way it carries a mesh's indices, and a shipped build needs
+ * neither the graph the effect was compiled from nor a compiler at runtime. Authoring belongs to an
+ * editor.
+ *
+ * Two things are consequently wire format: the opcode numbers, and the **order** of the attributes
+ * in {@link layout}, because the offsets in the render bindings are assigned from that order.
+ */
+export class ParticleEffect {
+
+    /**
+     * The per-particle attribute schema: which named attributes a particle of this effect has, how
+     * wide each is, and what word of the record it sits at.
+     *
+     * `null` until an effect is assigned. An entity whose component has none is linked and idle
+     * rather than an error — an effect that is still compiling or still loading is ordinary — and it
+     * starts emitting on the frame after both this and {@link program} are set.
+     *
+     * @type {import("../../../../shade/renderer/particles/layout/ParticleLayout.js").ParticleLayout|null}
+     */
+    layout = null;
+
+    /**
+     * The compiled INIT/UPDATE bytecode run for every particle. Replace the immutable program to
+     * edit the effect; do not mutate its bytecode in place.
+     *
+     * @type {import("../../../../shade/renderer/particles/isa/ParticleProgram.js").ParticleProgram|null}
+     */
+    program = null;
+
+    /**
+     * Image to draw the particles with, by URL, or `null` to draw against a single white texel — so
+     * an untextured effect is a flat quad of its own colour.
+     *
+     * The system loads this through `AssetManager` and packs it into the sprite atlas its scene
+     * shares, one patch per distinct URL however many entities name it. Where it lands is the
+     * system's answer and changes on every repack, without this component changing.
+     *
+     * @type {string|null}
+     */
+    texture = null;
+
+    /**
+     * Base RNG seed.
+     *
+     * Two entities running one program produce identical particles from identical seeds. `0` reads
+     * as "unset", and the emitter then takes its registration's generation instead, which no other
+     * live emitter shares — so leaving this alone is what makes fifty campfires burn differently.
+     *
+     * @type {number}
+     */
+    seed = 0;
+
+    /**
+     * Continuous emission rate, particles per second. Integrated on the GPU; the CPU never counts
+     * particles.
+     *
+     * @type {number}
+     */
+    spawn_rate = 0;
+
+    /**
+     * Whether the effect is currently emitting.
+     *
+     * Turning it off holds {@link spawn_rate} at zero without the caller having to remember what the
+     * rate was — which is the whole reason it exists, because "put the torch out and light it again"
+     * otherwise means every caller keeping a shadow copy of the number. Particles already alive are
+     * **not** killed: a fire that stops emitting burns down, which is what stopping a fire looks
+     * like. Kill them from the effect's own UPDATE program if an effect wants to vanish.
+     *
+     * @type {boolean}
+     */
+    emitting = true;
+
+    /**
+     * Seconds this effect is run forward before it is first shown, `0` for none.
+     *
+     * A continuous effect 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 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.
+     *
+     * It is paid once, on the frame the emitter is registered, by a pipeline of its own that
+     * simulates a private population and moves the result into the scene. Longer costs a longer loop
+     * on that one frame and nothing after it.
+     *
+     * @type {number}
+     */
+    prewarm = 0;
+
+    /**
+     * Packed feature / blend / projection bits — see
+     * {@link ../../../../shade/renderer/particles/data/PARTICLE_EMITTER_STRUCT.js 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;
+
+    /**
+     * The rate the emitter actually runs at: {@link spawn_rate} while {@link emitting}, and zero
+     * otherwise. What the system writes to the GPU record.
+     *
+     * @returns {number}
+     */
+    get effective_spawn_rate() {
+        return this.emitting ? this.spawn_rate : 0;
+    }
+
+    /**
+     * Bind render channels to per-particle attributes of this 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 effect has no such
+     * attribute" — the render pass substitutes a default and the sort pass treats the particle as
+     * being at the origin.
+     *
+     * Word offsets are stored 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, which is
+     * also why this needs {@link layout} to have been set first.
+     *
+     * @param {Object<string,string>} channels channel name (see `EMITTER_RENDER_CHANNELS`) ->
+     *        attribute name in this effect's layout
+     * @returns {ParticleEffect} this
+     */
+    bind_render(channels) {
+        assert.isObject(channels, 'channels');
+        assert.notEqual(this.layout, null, 'layout must be set before render channels are bound');
+        assert.defined(this.layout, 'this.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(', ')}`
+                    );
+            }
+        }
+
+        return this;
+    }
+
+    /**
+     * Structural equality over everything the component *is*. Two components that compare equal
+     * describe one effect, and one emitter row would serve both.
+     *
+     * The compiled program compares by its own bytecode rather than by object identity, so two
+     * components separately compiled from one graph compare equal.
+     *
+     * @param {ParticleEffect} other
+     * @returns {boolean}
+     */
+    equals(other) {
+        if (this === other) {
+            return true;
+        }
+
+        return this.texture === other.texture
+            && this.seed === other.seed
+            && this.spawn_rate === other.spawn_rate
+            && this.emitting === other.emitting
+            && 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)
+            && optional_equals(this.layout, other.layout)
+            && optional_equals(this.program, other.program);
+    }
+
+    /**
+     * Hash over everything {@link equals} compares, in the same terms.
+     *
+     * @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 appearance = hash_mix3(
+            computeStringHash(this.texture),
+            hash_mix3(this.seed, computeHashFloat(this.spawn_rate), computeHashFloat(this.prewarm)),
+            this.emitting ? 1 : 0
+        );
+
+        return hash_mix3(
+            hash_mix2(bindings, float32_array_hash(this.flipbook, 0, this.flipbook.length)),
+            appearance,
+            hash_mix2(
+                this.layout === null ? 0 : this.layout.hash(),
+                this.program === null ? 0 : this.program.hash()
+            )
+        );
+    }
+
+    /**
+     * Make this a copy of `other`: same effect, same settings.
+     *
+     * The layout and the compiled program are **shared** rather than duplicated — both are immutable
+     * once compiled, and sharing them is what puts two entities of one effect on one program id in
+     * the heap, hence in one simulation bucket.
+     *
+     * @param {ParticleEffect} other
+     * @returns {ParticleEffect} this
+     */
+    copy(other) {
+        this.layout = other.layout;
+        this.program = other.program;
+        this.texture = other.texture;
+
+        this.seed = other.seed;
+        this.spawn_rate = other.spawn_rate;
+        this.emitting = other.emitting;
+        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;
+
+        return this;
+    }
+
+    /**
+     * @returns {ParticleEffect}
+     */
+    clone() {
+        return new ParticleEffect().copy(this);
+    }
+
+    /**
+     * Build a component from a plain description. Every field is optional — a component with no
+     * effect is a placeholder waiting for one — so an effect goes in by spreading what
+     * {@link ../../../../shade/renderer/particles/runtime/create_particle_effect.js create_particle_effect}
+     * returns: `ParticleEffect.from({ ...effect, spawn_rate: 100 })`.
+     *
+     * @param {object} [config]
+     * @param {import("../../../../shade/renderer/particles/layout/ParticleLayout.js").ParticleLayout} [config.layout]
+     * @param {import("../../../../shade/renderer/particles/isa/ParticleProgram.js").ParticleProgram} [config.program]
+     * @param {string|null} [config.texture] image URL to draw with
+     * @param {number} [config.seed]
+     * @param {number} [config.spawn_rate] particles/second
+     * @param {boolean} [config.emitting]
+     * @param {number} [config.prewarm] seconds of emission to run forward before the first frame
+     * @param {object} [config.flags] passed to `make_emitter_flags`
+     * @param {Object<string,string>} [config.render] render channel -> attribute name
+     * @param {ArrayLike<number>} [config.flipbook] `[columns, rows]`
+     * @returns {ParticleEffect}
+     */
+    static from(config = {}) {
+        assert.isObject(config, 'config');
+
+        const effect = new ParticleEffect();
+
+        if (config.layout !== undefined) {
+            effect.layout = config.layout;
+        }
+
+        if (config.program !== undefined) {
+            effect.program = config.program;
+        }
+
+        if (config.texture !== undefined) {
+            effect.texture = config.texture;
+        }
+
+        if (config.seed !== undefined) {
+            effect.seed = config.seed;
+        }
+
+        if (config.spawn_rate !== undefined) {
+            effect.spawn_rate = config.spawn_rate;
+        }
+
+        if (config.emitting !== undefined) {
+            effect.emitting = config.emitting;
+        }
+
+        if (config.prewarm !== undefined) {
+            effect.prewarm = config.prewarm;
+        }
+
+        effect.flags = make_emitter_flags(config.flags ?? {});
+
+        if (config.flipbook !== undefined) {
+            effect.flipbook.set(config.flipbook);
+        }
+
+        if (config.render !== undefined) {
+            effect.bind_render(config.render);
+        }
+
+        return effect;
+    }
+}
+
+/**
+ * Compare two things that are either both absent or both know how to compare themselves.
+ *
+ * A component with no effect is an ordinary state — it is what an entity has while its effect is
+ * still being compiled — so `null` has to be a value here rather than a precondition.
+ *
+ * @param {{equals: function(*): boolean}|null} a
+ * @param {{equals: function(*): boolean}|null} b
+ * @returns {boolean}
+ */
+function optional_equals(a, b) {
+    if (a === null || b === null) {
+        return a === b;
+    }
+
+    return a.equals(b);
+}
+
+/**
+ * The name this component is written under, and looked up by when a save is read. A serialization
+ * registry infers nothing from a class — see
+ * {@link ../../../ecs/storage/binary/BinarySerializationRegistry.js} — so this is what makes
+ * {@link ./ParticleEffectSerializationAdapter.js} reachable, and it is wire format: renaming the
+ * class is free, renaming this is a save-format break.
+ *
+ * @readonly
+ * @type {string}
+ */
+ParticleEffect.typeName = "ParticleEffect";
+
+/**
+ * Enables a fast type check, without having to import the class separately.
+ *
+ * @readonly
+ * @type {boolean}
+ */
+ParticleEffect.prototype.isParticleEffect = true;

package/src/engine/graphics/ecs/particles/ParticleEffectSerializationAdapter.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Binary serialization for {@link ParticleEffect}.
+ *
+ * **The compiled effect is written, not a reference to one.** The VM's instruction set was designed
+ * to be a durable format — a fixed-width opcode encoding with a constant pool beside it — so a
+ * compiled program is content in exactly the way a mesh's index buffer is content, and a level that
+ * carries one needs neither the graph it came from nor a compiler at runtime. Authoring is an
+ * editor's job; a shipped build opens a save, reads instruction words, and runs them.
+ *
+ * That is also what makes the format's stability a real obligation. Two things here are wire format
+ * and cannot be renumbered without a version bump and an upgrader:
+ *
+ * - **opcodes**, whose numbers are `../../../../shade/renderer/particles/isa/ParticleVMISA.js`, and
+ * - **attribute order in the layout**, because a layout assigns word offsets sequentially from the
+ *   order it is built in, and the render bindings below are those offsets. Offsets are therefore not
+ *   written: they are recomputed on load from the same order, and a change to how
+ *   {@link ParticleLayout} packs would silently repoint every binding in every save.
+ *
+ * ## The constant pool is written as bits
+ *
+ * The pool holds constants, not measurements, and two of them can be the same number: `-0` and `+0`
+ * are distinct pool words because a `DIV` by each disagrees about the sign of the infinity it
+ * produces, and the assembler interns with `Object.is` to keep them apart. `ParticleProgram` compares
+ * and hashes the pool through its bit view (`constant_words`) for exactly that reason.
+ *
+ * So does this. Not because a float path is known to lose something — measured on V8 it does not,
+ * `-0` survives `setFloat32` and so does a NaN's payload — but because whether a NaN survives a
+ * round trip through a JS `number` is **implementation-defined**: the language permits an engine to
+ * canonicalize, and the one this runs on is not the only one it will ever run on. Writing the words
+ * the program is already compared by makes the reload exact by construction rather than by an
+ * engine's discretion, and it means there is one representation of the pool rather than two.
+ *
+ * ## Nothing device-shaped is written
+ *
+ * There is nothing here that a device assigned: no table row, no generation, no program-heap
+ * placement, no atlas patch. Those belong to the registry that registered the emitter and are
+ * rebuilt on load like every other GPU resource. What is written is what an author typed.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ParticleEffectSerializationAdapter extends BinaryClassSerializationAdapter<any> {
+    constructor();
+    klass: typeof ParticleEffect;
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {ParticleEffect} value
+     */
+    serialize(buffer: BinaryBuffer, value: ParticleEffect): void;
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {ParticleEffect} value
+     */
+    deserialize(buffer: BinaryBuffer, value: ParticleEffect): void;
+}
+import { BinaryClassSerializationAdapter } from "../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { ParticleEffect } from "./ParticleEffect.js";
+//# sourceMappingURL=ParticleEffectSerializationAdapter.d.ts.map

package/src/engine/graphics/ecs/particles/ParticleEffectSerializationAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ParticleEffectSerializationAdapter.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/particles/ParticleEffectSerializationAdapter.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH;;IAEI,6BAAuB;IAGvB;;;OAGG;IACH,uCAFW,cAAc,QAmCxB;IAED;;;OAGG;IACH,yCAFW,cAAc,QA8BxB;CACJ;gDAzH+C,gEAAgE;+BACjF,qBAAqB"}