@woosh/meep-engine 3.11.2 → 3.12.0

package/src/engine/graphics3/ParticleEmitterSystem.js

@@ -0,0 +1,289 @@
+import { assert } from "../../core/assert.js";
+import { FramePhase } from "../../shade/renderer/extension/FramePhase.js";
+import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
+import { SceneColor } from "../../shade/renderer/extension/SceneColor.js";
+import { ViewTextures } from "../../shade/renderer/extension/ViewTextures.js";
+import { ImageRGBADataLoader } from "../asset/loaders/image/ImageRGBADataLoader.js";
+import { System } from "../ecs/System.js";
+import { Transform } from "../ecs/transform/Transform.js";
+import { ParticleEmitter } from "../graphics/particles/particular/engine/emitter/ParticleEmitter.js";
+import { ParticleEmitterFlag } from "../graphics/particles/particular/engine/emitter/ParticleEmitterFlag.js";
+import { ParticularEngine } from "../graphics/particles/particular/engine/ParticularEngine.js";
+import { GPUParticularRenderer } from "./particles/GPUParticularRenderer.js";
+
+/**
+ * Draws the game's particle effects under Shade.
+ *
+ * **The simulation does not move.** `particular` emits, ages, integrates and colours particles on
+ * the CPU, and that is where it stays: the plan makes Shade's GPU particle system a later, opt-in
+ * upgrade rather than this port. What changes is only what happens to the state it produces each
+ * frame — instead of a three `Points` object per emitter, it is packed into the layout Shade's own
+ * billboard renderer reads.
+ *
+ * **No visibility layer comes across.** The legacy system drives a render layer backed by a BVH and
+ * puts emitters to sleep when they leave the visible set; §4.5 retires CPU render culling, so every
+ * linked emitter simulates and the GPU decides what is on screen. An emitter that should not
+ * simulate says so itself, through {@link ParticleEmitterFlag.Emitting}.
+ */
+export class ParticleEmitterSystem extends System {
+    dependencies = [ParticleEmitter, Transform];
+
+    /**
+     * @type {GraphicsEngine}
+     */
+    #graphics;
+
+    /**
+     * @type {AssetManager}
+     */
+    #assets;
+
+    /**
+     * @type {ParticularEngine}
+     */
+    #engine;
+
+    /**
+     * @type {GPUParticularRenderer}
+     */
+    #renderer = new GPUParticularRenderer();
+
+    /**
+     * The emitters to simulate and draw, in link order.
+     *
+     * @type {ParticleEmitter[]}
+     */
+    #emitters = [];
+
+    /**
+     * @type {Map<number, {emitter: ParticleEmitter, position: Function, rotation: Function, scale: Function}>}
+     */
+    #entries = new Map();
+
+    /**
+     * @type {RenderExtension|null}
+     */
+    #extension = null;
+
+    /**
+     * What the pass draws. Read-only — the emitters follow the entities.
+     *
+     * @returns {ParticleEmitter[]}
+     */
+    get emitters() {
+        return this.#emitters;
+    }
+
+    /**
+     * @param {GraphicsEngine} graphics
+     * @param {AssetManager} assets
+     */
+    constructor(graphics, assets) {
+        super();
+
+        assert.defined(graphics, 'graphics');
+        assert.defined(assets, 'assets');
+
+        this.#graphics = graphics;
+        this.#assets = assets;
+
+        this.#engine = new ParticularEngine(assets);
+    }
+
+    async startup(entityManager) {
+        this.entityManager = entityManager;
+
+        this.#extension = this.#graphics.add_extension(new ParticleExtension(this));
+
+        const assets = this.#assets;
+
+        if (!assets.hasLoaderForType('image')) {
+            await assets.registerLoader('image', new ImageRGBADataLoader());
+        }
+    }
+
+    async shutdown(entityManager) {
+        if (this.#extension !== null) {
+            this.#graphics.remove_extension(this.#extension);
+
+            this.#extension = null;
+        }
+
+        this.#renderer.destroy();
+
+        // every emitter has been unlinked by this point — both teardown paths detach the dataset or
+        // remove the system observer first — so what is left is the shared sprite atlas
+        this.#engine.dispose();
+
+        this.#emitters.length = 0;
+        this.#entries.clear();
+    }
+
+    /**
+     * @param {ParticleEmitter} emitter
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    link(emitter, transform, entity) {
+        const position = (x, y, z) => emitter.position.set(x, y, z);
+        const rotation = (x, y, z, w) => emitter.rotation.set(x, y, z, w);
+        const scale = (x, y, z) => emitter.scale.set(x, y, z);
+
+        transform.position.process(position);
+        transform.rotation.process(rotation);
+        transform.scale.process(scale);
+
+        this.#entries.set(entity, { emitter, position, rotation, scale });
+
+        emitter.id = entity;
+
+        /*
+         Awake from the start. The legacy system links emitters asleep and lets its visibility layer
+         wake them; there is no such layer here, and an emitter that never wakes never emits.
+        */
+        emitter.clearFlag(ParticleEmitterFlag.Sleeping);
+
+        this.#engine.add(emitter);
+
+        this.#emitters.push(emitter);
+    }
+
+    /**
+     * Rebuild an emitter that has been edited structurally — layers added or removed, a sprite
+     * changed, a parameter curve redrawn.
+     *
+     * The pool, the parameter tracks and the atlas references are all built from the emitter's
+     * description, so an edit to that description is only visible once they are built again. Sleep
+     * state is preserved because it is the editor's, not the emitter's.
+     *
+     * @param {ParticleEmitter} emitter one this system has linked
+     */
+    rebuild(emitter) {
+        assert.ok(this.#emitters.includes(emitter), 'emitter is not linked to this system');
+
+        const engine = this.#engine;
+
+        const sleeping = emitter.getFlag(ParticleEmitterFlag.Sleeping);
+
+        engine.remove(emitter);
+
+        emitter.clearFlag(ParticleEmitterFlag.Built | ParticleEmitterFlag.Initialized);
+
+        emitter.registerLayerParameters();
+        emitter.build();
+        emitter.initialize();
+        emitter.computeBoundingBox();
+
+        engine.add(emitter);
+
+        emitter.writeFlag(ParticleEmitterFlag.Sleeping, sleeping);
+    }
+
+    /**
+     * @param {ParticleEmitter} emitter
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    unlink(emitter, transform, entity) {
+        const entry = this.#entries.get(entity);
+
+        if (entry === undefined) {
+            return;
+        }
+
+        transform.position.onChanged.remove(entry.position);
+        transform.rotation.onChanged.remove(entry.rotation);
+        transform.scale.onChanged.remove(entry.scale);
+
+        this.#entries.delete(entity);
+
+        const index = this.#emitters.indexOf(emitter);
+
+        if (index !== -1) {
+            this.#emitters.splice(index, 1);
+        }
+
+        this.#engine.remove(emitter);
+
+        emitter.dispose();
+    }
+
+    update(timeDelta) {
+        this.#engine.advance(timeDelta);
+
+        const emitters = this.#emitters;
+
+        for (let i = 0; i < emitters.length; i++) {
+            // retires dead particles and compacts the pool, which is what makes the live ones a
+            // contiguous run for the packer
+            emitters[i].update();
+        }
+
+        // repacks the sprite atlas when an effect has brought a new sprite in
+        this.#engine.shaderManager.spriteAtlas.atlas.update();
+    }
+
+    /**
+     * @param {FrameContext} frame
+     */
+    record(frame) {
+        const emitters = this.#emitters;
+
+        if (emitters.length === 0) {
+            return;
+        }
+
+        const camera_context = frame.view.camera;
+
+        // the camera's world transform, whose first two columns are the axes a billboard is built on
+        const m = camera_context.camera.transform.matrix;
+
+        /*
+         The particles are packed and uploaded inside the pass rather than here: that needs a
+         `GraphicsContext`, which the frame graph hands out at execution time and the frame does not
+         carry. So the pass is recorded whether or not anything is alive, and draws nothing when
+         nothing is — which leaves the frame's colour exactly as it was either way.
+        */
+        const scene = frame.get(SceneColor);
+
+        scene.color = this.#renderer.graph_draw({
+            graph: frame.graph,
+            color: scene.color,
+            depth: frame.get(ViewTextures).depth,
+            camera: camera_context.buffer,
+            emitters,
+            atlas: this.#engine.shaderManager.spriteAtlas.atlas.sampler,
+            camera_position: [m[12], m[13], m[14]],
+            camera_right: [m[0], m[1], m[2]],
+            camera_up: [m[4], m[5], m[6]]
+        });
+    }
+}
+
+/**
+ * Emitters draw into the scene, so they are subject to the fog of war that conceals it — which is
+ * a declaration on the fog rather than a placement here.
+ */
+export class ParticleExtension extends RenderExtension {
+    name = "particles";
+
+    phase = FramePhase.AfterTransparency;
+
+    /**
+     * @type {ParticleEmitterSystem}
+     */
+    #system;
+
+    /**
+     * @param {ParticleEmitterSystem} system
+     */
+    constructor(system) {
+        super();
+
+        this.#system = system;
+    }
+
+    record(frame) {
+        this.#system.record(frame);
+    }
+}

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

@@ -1,76 +1,10 @@
 /**
- * Draws the game's particle effects under Shade.
+ * @deprecated Renamed to {@link ParticleEmitterSystem}. The trailing `3` marked the 2.x → 3.x renderer transition;
+ * the 2.x name it disambiguated against is gone, so the suffix no longer distinguishes anything.
  *
- * **The simulation does not move.** `particular` emits, ages, integrates and colours particles on
- * the CPU, and that is where it stays: the plan makes Shade's GPU particle system a later, opt-in
- * upgrade rather than this port. What changes is only what happens to the state it produces each
- * frame — instead of a three `Points` object per emitter, it is packed into the layout Shade's own
- * billboard renderer reads.
- *
- * **No visibility layer comes across.** The legacy system drives a render layer backed by a BVH and
- * puts emitters to sleep when they leave the visible set; §4.5 retires CPU render culling, so every
- * linked emitter simulates and the GPU decides what is on screen. An emitter that should not
- * simulate says so itself, through {@link ParticleEmitterFlag.Emitting}.
- */
-export class ParticleEmitterSystem3 extends System<any> {
-    /**
-     * @param {GraphicsEngine3} graphics
-     * @param {AssetManager} assets
-     */
-    constructor(graphics: GraphicsEngine3, assets: AssetManager);
-    dependencies: (typeof Transform | typeof ParticleEmitter)[];
-    /**
-     * What the pass draws. Read-only — the emitters follow the entities.
-     *
-     * @returns {ParticleEmitter[]}
-     */
-    get emitters(): ParticleEmitter[];
-    startup(entityManager: any): Promise<void>;
-    shutdown(entityManager: any): Promise<void>;
-    /**
-     * @param {ParticleEmitter} emitter
-     * @param {Transform} transform
-     * @param {number} entity
-     */
-    link(emitter: ParticleEmitter, transform: Transform, entity: number): void;
-    /**
-     * Rebuild an emitter that has been edited structurally — layers added or removed, a sprite
-     * changed, a parameter curve redrawn.
-     *
-     * The pool, the parameter tracks and the atlas references are all built from the emitter's
-     * description, so an edit to that description is only visible once they are built again. Sleep
-     * state is preserved because it is the editor's, not the emitter's.
-     *
-     * @param {ParticleEmitter} emitter one this system has linked
-     */
-    rebuild(emitter: ParticleEmitter): void;
-    /**
-     * @param {ParticleEmitter} emitter
-     * @param {Transform} transform
-     * @param {number} entity
-     */
-    unlink(emitter: ParticleEmitter, transform: Transform, entity: number): void;
-    update(timeDelta: any): void;
-    /**
-     * @param {FrameContext} frame
-     */
-    record(frame: FrameContext): void;
-    #private;
-}
-/**
- * Emitters draw into the scene, so they are subject to the fog of war that conceals it — which is
- * a declaration on the fog rather than a placement here.
+ * Kept as a re-export rather than removed: this is a library, and an import path is as much a
+ * published interface as a class name.
  */
-export class ParticleExtension extends RenderExtension {
-    /**
-     * @param {ParticleEmitterSystem3} system
-     */
-    constructor(system: ParticleEmitterSystem3);
-    record(frame: any): void;
-    #private;
-}
-import { System } from "../ecs/System.js";
-import { Transform } from "../ecs/transform/Transform.js";
-import { ParticleEmitter } from "../graphics/particles/particular/engine/emitter/ParticleEmitter.js";
-import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
+export const ParticleEmitterSystem3: typeof ParticleEmitterSystem;
+import { ParticleEmitterSystem } from "./ParticleEmitterSystem.js";
 //# sourceMappingURL=ParticleEmitterSystem3.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ParticleEmitterSystem3.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/ParticleEmitterSystem3.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;GAaG;AACH;IAiDI;;;OAGG;IACH,6DAUC;IA9DD,4DAA4C;IAuC5C;;;;OAIG;IACH,kCAEC;IAkBD,2CAUC;IAED,4CAeC;IAED;;;;OAIG;IACH,cAJW,eAAe,aACf,SAAS,UACT,MAAM,QAwBhB;IAED;;;;;;;;;OASG;IACH,iBAFW,eAAe,QAqBzB;IAED;;;;OAIG;IACH,gBAJW,eAAe,aACf,SAAS,UACT,MAAM,QAwBhB;IAED,6BAaC;IAED;;OAEG;IACH,kCA+BC;;CACJ;AAED;;;GAGG;AACH;IAUI;;OAEG;IACH,oBAFW,sBAAsB,EAMhC;IAED,yBAEC;;CACJ;uBA1RsB,kBAAkB;0BACf,+BAA+B;gCACzB,oEAAoE;gCANpE,mDAAmD"}
+{"version":3,"file":"ParticleEmitterSystem3.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/ParticleEmitterSystem3.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,kEAA4D;sCATtB,4BAA4B"}

package/src/engine/graphics3/ParticleEmitterSystem3.js

@@ -1,289 +1,10 @@
-import { assert } from "../../core/assert.js";
-import { FramePhase } from "../../shade/renderer/extension/FramePhase.js";
-import { RenderExtension } from "../../shade/renderer/extension/RenderExtension.js";
-import { SceneColor } from "../../shade/renderer/extension/SceneColor.js";
-import { ViewTextures } from "../../shade/renderer/extension/ViewTextures.js";
-import { ImageRGBADataLoader } from "../asset/loaders/image/ImageRGBADataLoader.js";
-import { System } from "../ecs/System.js";
-import { Transform } from "../ecs/transform/Transform.js";
-import { ParticleEmitter } from "../graphics/particles/particular/engine/emitter/ParticleEmitter.js";
-import { ParticleEmitterFlag } from "../graphics/particles/particular/engine/emitter/ParticleEmitterFlag.js";
-import { ParticularEngine } from "../graphics/particles/particular/engine/ParticularEngine.js";
-import { GPUParticularRenderer } from "./particles/GPUParticularRenderer.js";
+import { ParticleEmitterSystem } from "./ParticleEmitterSystem.js";
 
 /**
- * Draws the game's particle effects under Shade.
+ * @deprecated Renamed to {@link ParticleEmitterSystem}. The trailing `3` marked the 2.x → 3.x renderer transition;
+ * the 2.x name it disambiguated against is gone, so the suffix no longer distinguishes anything.
  *
- * **The simulation does not move.** `particular` emits, ages, integrates and colours particles on
- * the CPU, and that is where it stays: the plan makes Shade's GPU particle system a later, opt-in
- * upgrade rather than this port. What changes is only what happens to the state it produces each
- * frame — instead of a three `Points` object per emitter, it is packed into the layout Shade's own
- * billboard renderer reads.
- *
- * **No visibility layer comes across.** The legacy system drives a render layer backed by a BVH and
- * puts emitters to sleep when they leave the visible set; §4.5 retires CPU render culling, so every
- * linked emitter simulates and the GPU decides what is on screen. An emitter that should not
- * simulate says so itself, through {@link ParticleEmitterFlag.Emitting}.
+ * Kept as a re-export rather than removed: this is a library, and an import path is as much a
+ * published interface as a class name.
  */
-export class ParticleEmitterSystem3 extends System {
-    dependencies = [ParticleEmitter, Transform];
-
-    /**
-     * @type {GraphicsEngine3}
-     */
-    #graphics;
-
-    /**
-     * @type {AssetManager}
-     */
-    #assets;
-
-    /**
-     * @type {ParticularEngine}
-     */
-    #engine;
-
-    /**
-     * @type {GPUParticularRenderer}
-     */
-    #renderer = new GPUParticularRenderer();
-
-    /**
-     * The emitters to simulate and draw, in link order.
-     *
-     * @type {ParticleEmitter[]}
-     */
-    #emitters = [];
-
-    /**
-     * @type {Map<number, {emitter: ParticleEmitter, position: Function, rotation: Function, scale: Function}>}
-     */
-    #entries = new Map();
-
-    /**
-     * @type {RenderExtension|null}
-     */
-    #extension = null;
-
-    /**
-     * What the pass draws. Read-only — the emitters follow the entities.
-     *
-     * @returns {ParticleEmitter[]}
-     */
-    get emitters() {
-        return this.#emitters;
-    }
-
-    /**
-     * @param {GraphicsEngine3} graphics
-     * @param {AssetManager} assets
-     */
-    constructor(graphics, assets) {
-        super();
-
-        assert.defined(graphics, 'graphics');
-        assert.defined(assets, 'assets');
-
-        this.#graphics = graphics;
-        this.#assets = assets;
-
-        this.#engine = new ParticularEngine(assets);
-    }
-
-    async startup(entityManager) {
-        this.entityManager = entityManager;
-
-        this.#extension = this.#graphics.add_extension(new ParticleExtension(this));
-
-        const assets = this.#assets;
-
-        if (!assets.hasLoaderForType('image')) {
-            await assets.registerLoader('image', new ImageRGBADataLoader());
-        }
-    }
-
-    async shutdown(entityManager) {
-        if (this.#extension !== null) {
-            this.#graphics.remove_extension(this.#extension);
-
-            this.#extension = null;
-        }
-
-        this.#renderer.destroy();
-
-        // every emitter has been unlinked by this point — both teardown paths detach the dataset or
-        // remove the system observer first — so what is left is the shared sprite atlas
-        this.#engine.dispose();
-
-        this.#emitters.length = 0;
-        this.#entries.clear();
-    }
-
-    /**
-     * @param {ParticleEmitter} emitter
-     * @param {Transform} transform
-     * @param {number} entity
-     */
-    link(emitter, transform, entity) {
-        const position = (x, y, z) => emitter.position.set(x, y, z);
-        const rotation = (x, y, z, w) => emitter.rotation.set(x, y, z, w);
-        const scale = (x, y, z) => emitter.scale.set(x, y, z);
-
-        transform.position.process(position);
-        transform.rotation.process(rotation);
-        transform.scale.process(scale);
-
-        this.#entries.set(entity, { emitter, position, rotation, scale });
-
-        emitter.id = entity;
-
-        /*
-         Awake from the start. The legacy system links emitters asleep and lets its visibility layer
-         wake them; there is no such layer here, and an emitter that never wakes never emits.
-        */
-        emitter.clearFlag(ParticleEmitterFlag.Sleeping);
-
-        this.#engine.add(emitter);
-
-        this.#emitters.push(emitter);
-    }
-
-    /**
-     * Rebuild an emitter that has been edited structurally — layers added or removed, a sprite
-     * changed, a parameter curve redrawn.
-     *
-     * The pool, the parameter tracks and the atlas references are all built from the emitter's
-     * description, so an edit to that description is only visible once they are built again. Sleep
-     * state is preserved because it is the editor's, not the emitter's.
-     *
-     * @param {ParticleEmitter} emitter one this system has linked
-     */
-    rebuild(emitter) {
-        assert.ok(this.#emitters.includes(emitter), 'emitter is not linked to this system');
-
-        const engine = this.#engine;
-
-        const sleeping = emitter.getFlag(ParticleEmitterFlag.Sleeping);
-
-        engine.remove(emitter);
-
-        emitter.clearFlag(ParticleEmitterFlag.Built | ParticleEmitterFlag.Initialized);
-
-        emitter.registerLayerParameters();
-        emitter.build();
-        emitter.initialize();
-        emitter.computeBoundingBox();
-
-        engine.add(emitter);
-
-        emitter.writeFlag(ParticleEmitterFlag.Sleeping, sleeping);
-    }
-
-    /**
-     * @param {ParticleEmitter} emitter
-     * @param {Transform} transform
-     * @param {number} entity
-     */
-    unlink(emitter, transform, entity) {
-        const entry = this.#entries.get(entity);
-
-        if (entry === undefined) {
-            return;
-        }
-
-        transform.position.onChanged.remove(entry.position);
-        transform.rotation.onChanged.remove(entry.rotation);
-        transform.scale.onChanged.remove(entry.scale);
-
-        this.#entries.delete(entity);
-
-        const index = this.#emitters.indexOf(emitter);
-
-        if (index !== -1) {
-            this.#emitters.splice(index, 1);
-        }
-
-        this.#engine.remove(emitter);
-
-        emitter.dispose();
-    }
-
-    update(timeDelta) {
-        this.#engine.advance(timeDelta);
-
-        const emitters = this.#emitters;
-
-        for (let i = 0; i < emitters.length; i++) {
-            // retires dead particles and compacts the pool, which is what makes the live ones a
-            // contiguous run for the packer
-            emitters[i].update();
-        }
-
-        // repacks the sprite atlas when an effect has brought a new sprite in
-        this.#engine.shaderManager.spriteAtlas.atlas.update();
-    }
-
-    /**
-     * @param {FrameContext} frame
-     */
-    record(frame) {
-        const emitters = this.#emitters;
-
-        if (emitters.length === 0) {
-            return;
-        }
-
-        const camera_context = frame.view.camera;
-
-        // the camera's world transform, whose first two columns are the axes a billboard is built on
-        const m = camera_context.camera.transform.matrix;
-
-        /*
-         The particles are packed and uploaded inside the pass rather than here: that needs a
-         `GraphicsContext`, which the frame graph hands out at execution time and the frame does not
-         carry. So the pass is recorded whether or not anything is alive, and draws nothing when
-         nothing is — which leaves the frame's colour exactly as it was either way.
-        */
-        const scene = frame.get(SceneColor);
-
-        scene.color = this.#renderer.graph_draw({
-            graph: frame.graph,
-            color: scene.color,
-            depth: frame.get(ViewTextures).depth,
-            camera: camera_context.buffer,
-            emitters,
-            atlas: this.#engine.shaderManager.spriteAtlas.atlas.sampler,
-            camera_position: [m[12], m[13], m[14]],
-            camera_right: [m[0], m[1], m[2]],
-            camera_up: [m[4], m[5], m[6]]
-        });
-    }
-}
-
-/**
- * Emitters draw into the scene, so they are subject to the fog of war that conceals it — which is
- * a declaration on the fog rather than a placement here.
- */
-export class ParticleExtension extends RenderExtension {
-    name = "particles";
-
-    phase = FramePhase.AfterTransparency;
-
-    /**
-     * @type {ParticleEmitterSystem3}
-     */
-    #system;
-
-    /**
-     * @param {ParticleEmitterSystem3} system
-     */
-    constructor(system) {
-        super();
-
-        this.#system = system;
-    }
-
-    record(frame) {
-        this.#system.record(frame);
-    }
-}
+export const ParticleEmitterSystem3 = ParticleEmitterSystem;