@woosh/meep-engine 3.18.0 → 3.20.0

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

@@ -0,0 +1,266 @@
+/**
+ * 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 {
+    /**
+     * 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?: {
+        layout?: import("../../../../shade/renderer/particles/layout/ParticleLayout.js").ParticleLayout;
+        program?: import("../../../../shade/renderer/particles/isa/ParticleProgram.js").ParticleProgram;
+        texture?: string | null;
+        seed?: number;
+        spawn_rate?: number;
+        emitting?: boolean;
+        prewarm?: number;
+        flags?: object;
+        render?: {
+            [x: string]: string;
+        };
+        flipbook?: ArrayLike<number>;
+    }): 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: import("../../../../shade/renderer/particles/layout/ParticleLayout.js").ParticleLayout | 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: import("../../../../shade/renderer/particles/isa/ParticleProgram.js").ParticleProgram | 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: string | 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: number;
+    /**
+     * Continuous emission rate, particles per second. Integrated on the GPU; the CPU never counts
+     * particles.
+     *
+     * @type {number}
+     */
+    spawn_rate: number;
+    /**
+     * 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: boolean;
+    /**
+     * 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: number;
+    /**
+     * Packed feature / blend / projection bits — see
+     * {@link ../../../../shade/renderer/particles/data/PARTICLE_EMITTER_STRUCT.js make_emitter_flags}.
+     *
+     * @type {number}
+     */
+    flags: number;
+    /**
+     * Flipbook grid: columns, rows, over whatever region {@link texture} was packed into. `[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;
+    /**
+     * 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(): number;
+    /**
+     * 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: {
+        [x: string]: string;
+    }): ParticleEffect;
+    /**
+     * 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: ParticleEffect): boolean;
+    /**
+     * Hash over everything {@link equals} compares, in the same terms.
+     *
+     * @returns {number} int32
+     */
+    hash(): number;
+    /**
+     * 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: ParticleEffect): ParticleEffect;
+    /**
+     * @returns {ParticleEffect}
+     */
+    clone(): ParticleEffect;
+    /**
+     * Enables a fast type check, without having to import the class separately.
+     *
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isParticleEffect: boolean;
+}
+export namespace ParticleEffect {
+    let typeName: string;
+}
+//# sourceMappingURL=ParticleEffect.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ParticleEffect.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/particles/ParticleEffect.js"],"names":[],"mappings":"AAeA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH;IAoRI;;;;;;;;;;;;;;;;;;OAkBG;IACH;QAZ2G,MAAM,GAAtG,OAAO,+DAA+D,EAAE,cAAc;QACS,OAAO,GAAtG,OAAO,6DAA6D,EAAE,eAAe;QAChE,OAAO,GAA5B,MAAM,GAAC,IAAI;QACK,IAAI,GAApB,MAAM;QACU,UAAU,GAA1B,MAAM;QACW,QAAQ,GAAzB,OAAO;QACS,OAAO,GAAvB,MAAM;QACU,KAAK,GAArB,MAAM;QACyB,MAAM;gBAA9B,MAAM,GAAC,MAAM;;QACO,QAAQ,GAAnC,UAAU,MAAM,CAAC;QACf,cAAc,CA8C1B;IAjVD;;;;;;;;;OASG;IACH,QAFU,OAAO,+DAA+D,EAAE,cAAc,GAAC,IAAI,CAEvF;IAEd;;;;;OAKG;IACH,SAFU,OAAO,6DAA6D,EAAE,eAAe,GAAC,IAAI,CAErF;IAEf;;;;;;;;;OASG;IACH,SAFU,MAAM,GAAC,IAAI,CAEN;IAEf;;;;;;;;OAQG;IACH,MAFU,MAAM,CAEP;IAET;;;;;OAKG;IACH,YAFU,MAAM,CAED;IAEf;;;;;;;;;;OAUG;IACH,UAFU,OAAO,CAED;IAEhB;;;;;;;;;;;;;OAaG;IACH,SAFU,MAAM,CAEJ;IAEZ;;;;;OAKG;IACH,OAFU,MAAM,CAEN;IAEV;;;;;OAKG;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,mCAEC;IAED;;;;;;;;;;;;;;;OAeG;IACH;YAJkB,MAAM,GAAC,MAAM;QAElB,cAAc,CAuC1B;IAED;;;;;;;;;OASG;IACH,cAHW,cAAc,GACZ,OAAO,CAsBnB;IAED;;;;OAIG;IACH,QAFa,MAAM,CAuBlB;IAED;;;;;;;;;OASG;IACH,YAHW,cAAc,GACZ,cAAc,CAuB1B;IAED;;OAEG;IACH,SAFa,cAAc,CAI1B;IAgFL;;;;;OAKG;IACH,2BAFU,OAAO,CAEwB;CApBxC;;kBAUS,MAAM"}