@woosh/meep-engine 3.18.0 → 3.20.0

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

@@ -0,0 +1,219 @@
+import { ParticleProgram } from "../../../../shade/renderer/particles/isa/ParticleProgram.js";
+import { ParticleLayout } from "../../../../shade/renderer/particles/layout/ParticleLayout.js";
+import { BinaryClassSerializationAdapter } from "../../../ecs/storage/binary/BinaryClassSerializationAdapter.js";
+import { ParticleEffect } from "./ParticleEffect.js";
+
+/**
+ * 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 {
+
+    klass = ParticleEffect;
+    version = 1;
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {ParticleEffect} value
+     */
+    serialize(buffer, value) {
+        buffer.writeUTF8String(value.texture);
+
+        buffer.writeUintVar(value.seed);
+        buffer.writeFloat32(value.spawn_rate);
+        buffer.writeFloat32(value.prewarm);
+        buffer.writeUint8(value.emitting ? 1 : 0);
+        buffer.writeUint32(value.flags);
+
+        buffer.writeFloat32(value.flipbook[0]);
+        buffer.writeFloat32(value.flipbook[1]);
+
+        buffer.writeUint32(value.render_position);
+        buffer.writeUint32(value.render_size);
+        buffer.writeUint32(value.render_color);
+        buffer.writeUint32(value.render_rotation);
+        buffer.writeUint32(value.render_frame);
+        buffer.writeUint32(value.render_velocity);
+
+        /*
+         A component with no effect is an ordinary state, not a half-built one: an entity whose
+         effect is still compiling, or one whose effect was cleared. It saves and loads as itself.
+        */
+        const present = value.layout !== null && value.program !== null;
+
+        buffer.writeUint8(present ? 1 : 0);
+
+        if (!present) {
+            return;
+        }
+
+        write_layout(buffer, value.layout);
+        write_program(buffer, value.program);
+    }
+
+    /**
+     * @param {BinaryBuffer} buffer
+     * @param {ParticleEffect} value
+     */
+    deserialize(buffer, value) {
+        value.texture = buffer.readUTF8String();
+
+        value.seed = buffer.readUintVar();
+        value.spawn_rate = buffer.readFloat32();
+        value.prewarm = buffer.readFloat32();
+        value.emitting = buffer.readUint8() === 1;
+        value.flags = buffer.readUint32();
+
+        value.flipbook[0] = buffer.readFloat32();
+        value.flipbook[1] = buffer.readFloat32();
+
+        value.render_position = buffer.readUint32();
+        value.render_size = buffer.readUint32();
+        value.render_color = buffer.readUint32();
+        value.render_rotation = buffer.readUint32();
+        value.render_frame = buffer.readUint32();
+        value.render_velocity = buffer.readUint32();
+
+        if (buffer.readUint8() !== 1) {
+            value.layout = null;
+            value.program = null;
+
+            return;
+        }
+
+        value.layout = read_layout(buffer);
+        value.program = read_program(buffer);
+    }
+}
+
+/**
+ * @param {BinaryBuffer} buffer
+ * @param {ParticleLayout} layout
+ */
+function write_layout(buffer, layout) {
+    buffer.writeUintVar(layout.attributes.size);
+
+    // Insertion order, which is the order the offsets were assigned in and therefore the order they
+    // have to be rebuilt in. A Map iterates in insertion order by specification, so this is not an
+    // assumption about the implementation.
+    for (const attribute of layout.attributes.values()) {
+        buffer.writeUTF8String(attribute.name);
+        buffer.writeUint8(attribute.components);
+
+        // The semantic tag, and `null` where there is none. An effect saved with a tag this build
+        // has never heard of has to load as the plain vector it is rather than fail, which is why
+        // the tag is a string here as it is on the layout.
+        buffer.writeUTF8String(attribute.type ?? null);
+    }
+}
+
+/**
+ * @param {BinaryBuffer} buffer
+ * @returns {ParticleLayout}
+ */
+function read_layout(buffer) {
+    const count = buffer.readUintVar();
+    const attributes = [];
+
+    for (let i = 0; i < count; i++) {
+        const name = buffer.readUTF8String();
+        const components = buffer.readUint8();
+        const type = buffer.readUTF8String();
+
+        attributes.push(type === null ? { name, components } : { name, components, type });
+    }
+
+    return new ParticleLayout(attributes);
+}
+
+/**
+ * @param {BinaryBuffer} buffer
+ * @param {ParticleProgram} program
+ */
+function write_program(buffer, program) {
+    buffer.writeUint8(program.register_count);
+
+    write_words(buffer, program.init);
+    write_words(buffer, program.update);
+    // bits rather than floats — see the class note
+    write_words(buffer, program.constant_words);
+}
+
+/**
+ * @param {BinaryBuffer} buffer
+ * @returns {ParticleProgram}
+ */
+function read_program(buffer) {
+    const register_count = buffer.readUint8();
+
+    const init = read_words(buffer);
+    const update = read_words(buffer);
+    const constant_words = read_words(buffer);
+
+    return new ParticleProgram({
+        init,
+        update,
+        // the same bytes read as floats: `read_words` allocates its own buffer, so this view owns it
+        constants: new Float32Array(constant_words.buffer, constant_words.byteOffset, constant_words.length),
+        register_count,
+    });
+}
+
+/**
+ * @param {BinaryBuffer} buffer
+ * @param {Uint32Array} words
+ */
+function write_words(buffer, words) {
+    buffer.writeUintVar(words.length);
+    buffer.writeUint32Array(words, 0, words.length);
+}
+
+/**
+ * @param {BinaryBuffer} buffer
+ * @returns {Uint32Array}
+ */
+function read_words(buffer) {
+    const length = buffer.readUintVar();
+    const words = new Uint32Array(length);
+
+    buffer.readUint32Array(words, 0, length);
+
+    return words;
+}

package/src/engine/graphics3/GPUParticleEmitterSystem.d.ts

@@ -1,38 +1,150 @@
+/**
+ * Copy a component onto the scene node built for it, reporting whether anything actually moved.
+ *
+ * Comparing while assigning rather than in a pass of its own is what makes change detection cost
+ * nothing extra: the fields have to be read to be written, and the only addition is an `||` per
+ * field. What it answers is whether the emitter's GPU row has to be restaged, and restaging one that
+ * has not changed is an upload per emitter per frame.
+ *
+ * `spawn_rate` comes from {@link ParticleEffect#effective_spawn_rate}, so an effect switched off
+ * with `emitting = false` reaches the GPU as a rate of zero and keeps its authored rate to come back
+ * to. Layout and program are shared by reference, never copied — two entities of one effect belong
+ * on one program id in the heap.
+ *
+ * @param {ParticleEmitter} node
+ * @param {ParticleEffect} effect
+ * @returns {boolean} whether the node differs from what it held before
+ */
+export function apply_particle_effect(node: ParticleEmitter, effect: ParticleEffect): boolean;
 /**
  * @typedef {object} ParticleAtlasTexture
- * @property {number} references Number of emitters using this URL.
+ * @property {number} references Number of entities using this URL.
  * @property {import("../graphics/texture/atlas/AtlasPatch.js").AtlasPatch|null} patch Null while loading or after failure.
  */
 /**
- * @typedef {object} ParticleAtlasEntry
- * @property {string|null} url Last observed emitter texture URL.
- * @property {ParticleAtlasTexture|null} texture Shared image record, or null for an untextured emitter.
- * @property {number} seen Last membership sweep that visited this emitter.
+ * @typedef {object} ParticleEmitterEntry
+ * @property {number} entity
+ * @property {ParticleEffect} effect the entity's component — what to emit
+ * @property {Transform64} transform the entity's transform — where to emit it
+ * @property {ParticleEmitter|null} node the scene node, once the effect has a program to run
+ * @property {function():void} on_transform_changed
+ * @property {string|null} url last observed {@link ParticleEffect#texture}
+ * @property {ParticleAtlasTexture|null} texture shared image record, or null for an untextured effect
  */
 /**
- * Asset and atlas ownership for Shade's GPU particle emitters in one scene.
+ * Draws the game's GPU particle effects: one emitter per entity carrying
+ * {@link ../graphics/ecs/particles/ParticleEffect.js ParticleEffect} and
+ * {@link ../ecs/transform/Transform64.js Transform64}.
+ *
+ * ```js
+ * entityManager.addSystem(new GPUParticleEmitterSystem(graphics, scene, assetManager));
+ *
+ * new Entity()
+ *     .add(new Transform64())
+ *     .add(ParticleEffect.from({ ...create_particle_effect({ layout, init, update }), spawn_rate: 400 }))
+ *     .build(dataset);
+ * ```
+ *
+ * **The entity is the emitter.** The component says what it emits and the transform says where, the
+ * same division every other placed thing in this engine uses — a `Decal`, an `SGMesh`, a `Light`.
+ * Which means an emitter is spawned, moved, parented, attached to a bone, saved and destroyed by
+ * exactly the machinery that does those things for everything else, and a particle effect stops
+ * being a special case that needs its own scene-graph call.
+ *
+ * ## What this system does with the pair
+ *
+ * It builds a {@link ParticleEmitter} scene node per entity and owns it: the node is added to
+ * {@link scene} when the component has a compiled effect, follows the entity's transform, carries
+ * whatever the component currently says, and leaves the scene when the entity does. The node is not
+ * hidden — {@link node_of} hands it out — but it is not the interface either: write to the
+ * component and the next frame carries it.
  *
- * This ECS system observes the scene's ParticleEmitter nodes, so it needs no additional component
- * or duplicate transform. Add/remove nodes through the scene as usual. One system owns the sprite
- * atlas for that scene; the legacy ParticleEmitterSystem continues to serve CPU particle effects.
+ * Changes are found by **comparison** rather than announced. Once a frame each entity's
+ * fields are compared against what was last written to its node, and the node is marked dirty only
+ * where they differ; `EmitterRegistry` then restages exactly the rows that moved. A component nobody
+ * touched costs a run of integer comparisons and no upload, so there is no change signal to fire and
+ * none to forget. What that buys is that gameplay can write `effect.spawn_rate = 0` anywhere,
+ * including from code that has never heard of this system.
  *
- * Images load through the supplied AssetManager and share a patch by URL. TextureAtlas already
- * handles packing, growth and repacking with MaxRectanglesPacker. A FrameStart extension publishes
- * the pixels and every current patch before the renderer records particle simulation and drawing.
- * Pending/failed images sample transparent; emitters without an image sample white.
+ * ## It owns the scene's sprite atlas
+ *
+ * Every {@link ParticleEffect#texture} is loaded through the supplied `AssetManager` and packed into
+ * one {@link TextureAtlas} shared by the scene, one patch per distinct URL however many entities
+ * name it, reference-counted so the last entity to let go is what unpacks it. A `FrameStart`
+ * extension publishes the pixels and every current patch region before the renderer records the
+ * particle passes — every repack moves UVs that nothing else changed, so the regions are rewritten
+ * whole rather than when a URL changes. Pending and failed images sample a transparent texel;
+ * effects with no image sample a white one.
+ *
+ * An emitter node in this scene that this system did not build — one added to the `Scene` directly —
+ * gets the white texel. The atlas is the scene's and that emitter has nothing in it, so the
+ * alternative is not "its own texture" but a UV rectangle from somebody else's image.
+ *
+ * ## What it is not
+ *
+ * It does not simulate anything and does not record a particle pass. `GPUParticleSystem` does both,
+ * inside the renderer, driven from the emitter table these rows are in — see
+ * `shade/renderer/particles/DESIGN.md`. This system's whole contribution is membership, placement,
+ * the fields, and the sprite sheet.
+ *
+ * It also does not retire the CPU `ParticleEmitterSystem`, which serves the `particular` effects the
+ * game still ships. The two coexist and share nothing.
  */
 export class GPUParticleEmitterSystem extends System<any> {
     /**
      * @param {import("./GraphicsEngine.js").GraphicsEngine} graphics
-     * @param {import("../../shade/renderer/scene/Scene.js").Scene} scene scene whose particle atlas this system owns
+     * @param {import("../../shade/renderer/scene/Scene.js").Scene} scene scene the emitters are put
+     *        in, and whose particle atlas this system owns
      * @param {import("../asset/AssetManager.js").AssetManager} assets
      */
     constructor(graphics: import("./GraphicsEngine.js").GraphicsEngine, scene: import("../../shade/renderer/scene/Scene.js").Scene, assets: import("../asset/AssetManager.js").AssetManager<any>);
+    dependencies: (typeof Transform64 | typeof ParticleEffect)[];
     /**
      * CPU atlas, exposed for inspection. Owned by this system.
      * @type {TextureAtlas}
      */
     atlas: TextureAtlas;
+    /**
+     * The scene the emitters are put in. Received rather than created: meshes and lights come from
+     * systems of their own, and all of them have to be writing into one scene for any of it to be
+     * visible together.
+     *
+     * @returns {import("../../shade/renderer/scene/Scene.js").Scene}
+     */
+    get scene(): import("../../shade/renderer/scene/Scene.js").Scene;
+    /**
+     * The emitter nodes this system currently has in the scene, in no particular order. Read-only —
+     * they follow the entities.
+     *
+     * @returns {ParticleEmitter[]}
+     */
+    get emitters(): ParticleEmitter[];
+    /**
+     * The scene node built for an entity.
+     *
+     * Handed out for the things an entity reference cannot express — parenting something to the
+     * emitter, reading the world matrix the hierarchy pass composed — and for nothing routine: the
+     * component is how an effect is changed, and a node written to behind the component's back is
+     * overwritten by the next comparison.
+     *
+     * @param {number} entity
+     * @returns {ParticleEmitter|null} `null` for an entity this system has not linked, or one whose
+     * component has no compiled effect yet
+     */
+    node_of(entity: number): ParticleEmitter | null;
+    /**
+     * Ask an entity's emitter for `count` particles on top of its rate, on the next frame.
+     *
+     * The one-shot half of the API, and the only thing here the CPU asks for rather than describes:
+     * an impact, a footfall, a muzzle flash. It goes through the same GPU path as continuous
+     * emission — the tick pass folds the burst into the emitter's accumulator, and the pool budget
+     * and the culling apply — so it is a request rather than a guarantee, and an entity whose
+     * emitter is not live by the time the frame starts is silently skipped.
+     *
+     * @param {number} entity
+     * @param {number} count
+     */
+    burst(entity: number, count: number): void;
     /**
      * @param {import("../ecs/EntityManager.js").EntityManager} entityManager
      * @returns {Promise<void>}
@@ -40,9 +152,37 @@ export class GPUParticleEmitterSystem extends System<any> {
     startup(entityManager: import("../ecs/EntityManager.js").EntityManager): Promise<void>;
     /** @returns {Promise<void>} */
     shutdown(): Promise<void>;
-    /** @returns {void} */
-    update(): void;
-    /** Publish atlas data at FrameStart, after scene rows exist and before particle passes record.
+    /**
+     * @param {ParticleEffect} effect
+     * @param {Transform64} transform
+     * @param {number} entity
+     */
+    link(effect: ParticleEffect, transform: Transform64, entity: number): void;
+    /**
+     * @param {ParticleEffect} effect
+     * @param {Transform64} transform
+     * @param {number} entity
+     */
+    unlink(effect: ParticleEffect, transform: Transform64, entity: number): void;
+    /**
+     * Bring every emitter in line with its entity: build nodes for effects that have arrived, retire
+     * nodes for effects that have gone, copy changed fields onto the ones that stay, and follow the
+     * texture URLs.
+     *
+     * @param {number} [time_delta_seconds]
+     * @returns {void}
+     */
+    update(time_delta_seconds?: number): void;
+    /**
+     * Publish the atlas at FrameStart — after the scene context has established transform rows, and
+     * before the renderer records the particle passes that read the emitter table.
+     *
+     * {@link update} is called from here as well as by the entity manager, because a frame must not
+     * depend on a simulation tick having preceded it: an editor draws on demand, and a paused game
+     * still renders. It is idempotent and costs a comparison per emitter when nothing has changed,
+     * which is what makes running it twice a frame the cheap way to be right rather than a saving
+     * worth chasing.
+     *
      * @param {import("../../shade/renderer/extension/FrameContext.js").FrameContext} frame
      * @returns {void}
      */
@@ -51,7 +191,7 @@ export class GPUParticleEmitterSystem extends System<any> {
 }
 export type ParticleAtlasTexture = {
     /**
-     * Number of emitters using this URL.
+     * Number of entities using this URL.
      */
     references: number;
     /**
@@ -59,20 +199,33 @@ export type ParticleAtlasTexture = {
      */
     patch: import("../graphics/texture/atlas/AtlasPatch.js").AtlasPatch | null;
 };
-export type ParticleAtlasEntry = {
+export type ParticleEmitterEntry = {
+    entity: number;
     /**
-     * Last observed emitter texture URL.
+     * the entity's component — what to emit
      */
-    url: string | null;
+    effect: ParticleEffect;
     /**
-     * Shared image record, or null for an untextured emitter.
+     * the entity's transform — where to emit it
      */
-    texture: ParticleAtlasTexture | null;
+    transform: Transform64;
+    /**
+     * the scene node, once the effect has a program to run
+     */
+    node: ParticleEmitter | null;
+    on_transform_changed: () => void;
     /**
-     * Last membership sweep that visited this emitter.
+     * last observed {@link ParticleEffecttexture }
      */
-    seen: number;
+    url: string | null;
+    /**
+     * shared image record, or null for an untextured effect
+     */
+    texture: ParticleAtlasTexture | null;
 };
+import { ParticleEmitter } from "../../shade/renderer/particles/runtime/ParticleEmitter.js";
+import { ParticleEffect } from "../graphics/ecs/particles/ParticleEffect.js";
 import { System } from "../ecs/System.js";
+import { Transform64 } from "../ecs/transform/Transform64.js";
 import { TextureAtlas } from "../graphics/texture/atlas/TextureAtlas.js";
 //# sourceMappingURL=GPUParticleEmitterSystem.d.ts.map

package/src/engine/graphics3/GPUParticleEmitterSystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUParticleEmitterSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/GPUParticleEmitterSystem.js"],"names":[],"mappings":"AAWA;;;;GAIG;AAEH;;;;;GAKG;AAEH;;;;;;;;;;;GAWG;AACH;IA0CI;;;;OAIG;IACH,sBAJW,OAAO,qBAAqB,EAAE,cAAc,SAC5C,OAAO,qCAAqC,EAAE,KAAK,gEAY7D;IAvDD;;;OAGG;IACH,OAFU,YAAY,CAEO;IAqD7B;;;OAGG;IACH,uBAHW,OAAO,yBAAyB,EAAE,aAAa,GAC7C,QAAQ,IAAI,CAAC,CASzB;IAED,+BAA+B;IAC/B,YADc,QAAQ,IAAI,CAAC,CAkB1B;IAUD,sBAAsB;IACtB,UADc,IAAI,CAWjB;IA6DD;;;OAGG;IACH,eAHW,OAAO,gDAAgD,EAAE,YAAY,GACnE,IAAI,CAqChB;;CA2CJ;;;;;gBApRa,MAAM;;;;WACN,OAAO,yCAAyC,EAAE,UAAU,GAAC,IAAI;;;;;;SAKjE,MAAM,GAAC,IAAI;;;;aACX,oBAAoB,GAAC,IAAI;;;;UACzB,MAAM;;uBAjBG,kBAAkB;6BAGZ,2CAA2C"}
+{"version":3,"file":"GPUParticleEmitterSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/GPUParticleEmitterSystem.js"],"names":[],"mappings":"AAqtBA;;;;;;;;;;;;;;;;GAgBG;AACH,4CAJW,eAAe,UACf,cAAc,GACZ,OAAO,CA4BnB;AAvuBD;;;;GAIG;AAEH;;;;;;;;;GASG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH;IAoDI;;;;;OAKG;IACH,sBALW,OAAO,qBAAqB,EAAE,cAAc,SAC5C,OAAO,qCAAqC,EAAE,KAAK,gEAgB7D;IArED,6DAA6C;IAE7C;;;OAGG;IACH,OAFU,YAAY,CAEO;IAiE7B;;;;;;OAMG;IACH,iEAEC;IAED;;;;;OAKG;IACH,kCAEC;IAED;;;;;;;;;;;OAWG;IACH,gBAJW,MAAM,GACJ,eAAe,GAAC,IAAI,CAWhC;IAED;;;;;;;;;;;OAWG;IACH,cAHW,MAAM,SACN,MAAM,QA4BhB;IAED;;;OAGG;IACH,uBAHW,OAAO,yBAAyB,EAAE,aAAa,GAC7C,QAAQ,IAAI,CAAC,CAYzB;IAED,+BAA+B;IAC/B,YADc,QAAQ,IAAI,CAAC,CAyB1B;IAED;;;;OAIG;IACH,aAJW,cAAc,aACd,WAAW,UACX,MAAM,QAgChB;IAED;;;;OAIG;IACH,eAJW,cAAc,aACd,WAAW,UACX,MAAM,QAIhB;IAED;;;;;;;OAOG;IACH,4BAHW,MAAM,GACJ,IAAI,CAQhB;IAED;;;;;;;;;;;;OAYG;IACH,eAHW,OAAO,gDAAgD,EAAE,YAAY,GACnE,IAAI,CAqChB;;CA0TJ;;;;;gBAxrBa,MAAM;;;;WACN,OAAO,yCAAyC,EAAE,UAAU,GAAC,IAAI;;;YAKjE,MAAM;;;;YACN,cAAc;;;;eACd,WAAW;;;;UACX,eAAe,GAAC,IAAI;gCACT,IAAI;;;;SACf,MAAM,GAAC,IAAI;;;;aACX,oBAAoB,GAAC,IAAI;;gCAnCP,2DAA2D;+BAQ5D,6CAA6C;uBANrD,kBAAkB;4BAEb,iCAAiC;6BAKhC,2CAA2C"}