@woosh/meep-engine 3.11.2 → 3.12.0

package/src/engine/graphics3/ParticipatingMediaSystem.js

@@ -0,0 +1,184 @@
+import { assert } from "../../core/assert.js";
+import { isArrayEqualStrict } from "../../core/collection/array/isArrayEqualStrict.js";
+import { ParticipatingMediaVolume } from "../../shade/renderer/volumetrics/ParticipatingMediaVolume.js";
+import { System } from "../ecs/System.js";
+import { Transform } from "../ecs/transform/Transform.js";
+import { ParticipatingMedia } from "./ParticipatingMedia.js";
+
+/**
+ * Mirrors fog, smoke and cloud entities into Shade's volumetrics.
+ *
+ * The same shape as {@link LightSystem}: the ECS says what exists and where, and this keeps the
+ * renderer's own objects in step. A {@link ParticipatingMediaVolume} is a unit cube posed by a
+ * transform, so an entity's `Transform` is the volume — position, size and orientation with no
+ * translation step in between.
+ *
+ * **The transform is taken as world-space, with no hierarchy applied**, which is what the volume
+ * model can express: a volume is an oriented box in the scene and Shade has no parent chain to walk
+ * for it. Parenting a fog volume to a moving entity therefore leaves the fog where the child's own
+ * transform puts it. The lights are placed the same way, for the same reason.
+ *
+ * **Changes are polled once a frame rather than subscribed to.** A `Transform` announces itself and
+ * nothing else here does — a density tuned by an editor slider, a particle spec swapped wholesale
+ * for a different Mie solution — so subscribing would cover one field in three and the other two
+ * would still have to be polled. Two paths that have to agree, where one does the whole job. It
+ * costs about two dozen float comparisons per volume per frame and a scene holds volumes in the
+ * tens, so the comparison is cheaper than the signal plumbing it replaces. The price is latency: a
+ * change is visible within a frame rather than instantly.
+ *
+ * **Nothing is uploaded unless something actually changed.** The GPU table is repacked whole
+ * whenever {@link SceneVolumetrics.version} moves, so an unconditional copy every frame would
+ * re-upload every volume in the scene forever. The comparison is what decides, and on almost every
+ * frame it decides nothing has to happen.
+ *
+ * @see ParticipatingMedia the component
+ * @see SceneVolumetrics what the volumes are handed to
+ */
+export class ParticipatingMediaSystem extends System {
+
+    dependencies = [ParticipatingMedia, Transform];
+
+    /**
+     * @type {GraphicsEngine}
+     */
+    #graphics;
+
+    /**
+     * @type {Scene}
+     */
+    #scene;
+
+    /**
+     * @type {Map<number, {component: ParticipatingMedia, transform: Transform, volume: ParticipatingMediaVolume}>}
+     */
+    #entries = new Map();
+
+    /**
+     * @param {GraphicsEngine} graphics
+     * @param {Scene} scene
+     */
+    constructor(graphics, scene) {
+        super();
+
+        assert.defined(graphics, 'graphics');
+        assert.defined(scene, 'scene');
+        assert.equal(scene.isScene, true, 'scene.isScene !== true');
+
+        this.#graphics = graphics;
+        this.#scene = scene;
+    }
+
+    async startup(entityManager) {
+        this.entityManager = entityManager;
+
+        this.#graphics.set_scene(this.#scene);
+    }
+
+    async shutdown(entityManager) {
+        for (const entity of Array.from(this.#entries.keys())) {
+            this.#drop(entity);
+        }
+    }
+
+    /**
+     * @param {ParticipatingMedia} component
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    link(component, transform, entity) {
+        const volume = new ParticipatingMediaVolume();
+
+        participating_media_volume_write(volume, component, transform);
+
+        this.#scene.volumetrics.add(volume);
+
+        this.#entries.set(entity, { component, transform, volume });
+    }
+
+    /**
+     * @param {ParticipatingMedia} component
+     * @param {Transform} transform
+     * @param {number} entity
+     */
+    unlink(component, transform, entity) {
+        this.#drop(entity);
+    }
+
+    /**
+     * @param {number} time_delta_seconds
+     */
+    update(time_delta_seconds) {
+        const volumetrics = this.#scene.volumetrics;
+
+        for (const entry of this.#entries.values()) {
+            const volume = entry.volume;
+
+            if (participating_media_volume_is_current(volume, entry.component, entry.transform)) {
+                continue;
+            }
+
+            participating_media_volume_write(volume, entry.component, entry.transform);
+
+            volumetrics.invalidate();
+        }
+    }
+
+    /**
+     * @param {number} entity
+     */
+    #drop(entity) {
+        const entry = this.#entries.get(entity);
+
+        if (entry === undefined) {
+            return;
+        }
+
+        this.#scene.volumetrics.remove(entry.volume);
+
+        this.#entries.delete(entity);
+    }
+}
+
+/**
+ * Copy what the component and its transform say onto the volume Shade will render.
+ *
+ * The particle spec is **copied, not referenced**: two entities are routinely built from the same
+ * blueprint and would otherwise share one spec, so tuning one volume's particle would silently
+ * retune the other's.
+ *
+ * @param {ParticipatingMediaVolume} volume Shade's
+ * @param {ParticipatingMedia} component meep's
+ * @param {Transform} transform where the box is
+ */
+export function participating_media_volume_write(volume, component, transform) {
+    volume.density = component.density;
+    volume.fade_distance = component.fade_distance;
+
+    volume.particle_spec.copy(component.particle_spec);
+
+    volume.transform.copy(transform);
+}
+
+/**
+ * Whether the volume already says what the component and transform say.
+ *
+ * True on all but a handful of frames, which is the point of asking: a `false` here costs the whole
+ * scene's volumetrics table a trip to the GPU.
+ *
+ * **The transform is compared by its matrix rather than by `Transform.equals`**, because the matrix
+ * is the entire transform the GPU is given — the volume's position, rotation and scale are never
+ * read on their own. That makes this exactly the question worth asking, "would the upload differ",
+ * and it catches a transform posed by writing its matrix, which comparing position, rotation and
+ * scale would not.
+ *
+ * @param {ParticipatingMediaVolume} volume
+ * @param {ParticipatingMedia} component
+ * @param {Transform} transform
+ * @returns {boolean}
+ */
+export function participating_media_volume_is_current(volume, component, transform) {
+    return volume.density === component.density
+        && volume.fade_distance === component.fade_distance
+        && isArrayEqualStrict(volume.transform.matrix, transform.matrix)
+        && volume.particle_spec.equals(component.particle_spec);
+}

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

@@ -1,87 +1,10 @@
 /**
- * Copy what the component and its transform say onto the volume Shade will render.
+ * @deprecated Renamed to {@link ParticipatingMediaSystem}. 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 particle spec is **copied, not referenced**: two entities are routinely built from the same
- * blueprint and would otherwise share one spec, so tuning one volume's particle would silently
- * retune the other's.
- *
- * @param {ParticipatingMediaVolume} volume Shade's
- * @param {ParticipatingMedia} component meep's
- * @param {Transform} transform where the box is
- */
-export function participating_media_volume_write(volume: ParticipatingMediaVolume, component: ParticipatingMedia, transform: Transform): void;
-/**
- * Whether the volume already says what the component and transform say.
- *
- * True on all but a handful of frames, which is the point of asking: a `false` here costs the whole
- * scene's volumetrics table a trip to the GPU.
- *
- * **The transform is compared by its matrix rather than by `Transform.equals`**, because the matrix
- * is the entire transform the GPU is given — the volume's position, rotation and scale are never
- * read on their own. That makes this exactly the question worth asking, "would the upload differ",
- * and it catches a transform posed by writing its matrix, which comparing position, rotation and
- * scale would not.
- *
- * @param {ParticipatingMediaVolume} volume
- * @param {ParticipatingMedia} component
- * @param {Transform} transform
- * @returns {boolean}
- */
-export function participating_media_volume_is_current(volume: ParticipatingMediaVolume, component: ParticipatingMedia, transform: Transform): boolean;
-/**
- * Mirrors fog, smoke and cloud entities into Shade's volumetrics.
- *
- * The same shape as {@link LightSystem3}: the ECS says what exists and where, and this keeps the
- * renderer's own objects in step. A {@link ParticipatingMediaVolume} is a unit cube posed by a
- * transform, so an entity's `Transform` is the volume — position, size and orientation with no
- * translation step in between.
- *
- * **The transform is taken as world-space, with no hierarchy applied**, which is what the volume
- * model can express: a volume is an oriented box in the scene and Shade has no parent chain to walk
- * for it. Parenting a fog volume to a moving entity therefore leaves the fog where the child's own
- * transform puts it. The lights are placed the same way, for the same reason.
- *
- * **Changes are polled once a frame rather than subscribed to.** A `Transform` announces itself and
- * nothing else here does — a density tuned by an editor slider, a particle spec swapped wholesale
- * for a different Mie solution — so subscribing would cover one field in three and the other two
- * would still have to be polled. Two paths that have to agree, where one does the whole job. It
- * costs about two dozen float comparisons per volume per frame and a scene holds volumes in the
- * tens, so the comparison is cheaper than the signal plumbing it replaces. The price is latency: a
- * change is visible within a frame rather than instantly.
- *
- * **Nothing is uploaded unless something actually changed.** The GPU table is repacked whole
- * whenever {@link SceneVolumetrics.version} moves, so an unconditional copy every frame would
- * re-upload every volume in the scene forever. The comparison is what decides, and on almost every
- * frame it decides nothing has to happen.
- *
- * @see ParticipatingMedia the component
- * @see SceneVolumetrics what the volumes are handed to
+ * 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 ParticipatingMediaSystem3 extends System<any> {
-    /**
-     * @param {GraphicsEngine3} graphics
-     * @param {Scene} scene
-     */
-    constructor(graphics: GraphicsEngine3, scene: Scene);
-    dependencies: (typeof Transform | typeof ParticipatingMedia)[];
-    startup(entityManager: any): Promise<void>;
-    shutdown(entityManager: any): Promise<void>;
-    /**
-     * @param {ParticipatingMedia} component
-     * @param {Transform} transform
-     * @param {number} entity
-     */
-    link(component: ParticipatingMedia, transform: Transform, entity: number): void;
-    /**
-     * @param {ParticipatingMedia} component
-     * @param {Transform} transform
-     * @param {number} entity
-     */
-    unlink(component: ParticipatingMedia, transform: Transform, entity: number): void;
-    #private;
-}
-import { ParticipatingMediaVolume } from "../../shade/renderer/volumetrics/ParticipatingMediaVolume.js";
-import { ParticipatingMedia } from "./ParticipatingMedia.js";
-import { Transform } from "../ecs/transform/Transform.js";
-import { System } from "../ecs/System.js";
+export const ParticipatingMediaSystem3: typeof ParticipatingMediaSystem;
+import { ParticipatingMediaSystem } from "./ParticipatingMediaSystem.js";
 //# sourceMappingURL=ParticipatingMediaSystem3.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"ParticipatingMediaSystem3.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/ParticipatingMediaSystem3.js"],"names":[],"mappings":"AA6IA;;;;;;;;;;GAUG;AACH,yDAJW,wBAAwB,aACxB,kBAAkB,aAClB,SAAS,QASnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,8DALW,wBAAwB,aACxB,kBAAkB,aAClB,SAAS,GACP,OAAO,CAOnB;AAhLD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH;IAmBI;;;OAGG;IACH,qDASC;IA9BD,+DAA+C;IAgC/C,2CAIC;IAED,4CAIC;IAED;;;;OAIG;IACH,gBAJW,kBAAkB,aAClB,SAAS,UACT,MAAM,QAUhB;IAED;;;;OAIG;IACH,kBAJW,kBAAkB,aAClB,SAAS,UACT,MAAM,QAIhB;;CAmCJ;yCAzIwC,8DAA8D;mCAGpE,yBAAyB;0BADlC,+BAA+B;uBADlC,kBAAkB"}
+{"version":3,"file":"ParticipatingMediaSystem3.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/ParticipatingMediaSystem3.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,wEAAkE;yCATzB,+BAA+B"}

package/src/engine/graphics3/ParticipatingMediaSystem3.js

@@ -1,184 +1,10 @@
-import { assert } from "../../core/assert.js";
-import { isArrayEqualStrict } from "../../core/collection/array/isArrayEqualStrict.js";
-import { ParticipatingMediaVolume } from "../../shade/renderer/volumetrics/ParticipatingMediaVolume.js";
-import { System } from "../ecs/System.js";
-import { Transform } from "../ecs/transform/Transform.js";
-import { ParticipatingMedia } from "./ParticipatingMedia.js";
+import { ParticipatingMediaSystem } from "./ParticipatingMediaSystem.js";
 
 /**
- * Mirrors fog, smoke and cloud entities into Shade's volumetrics.
+ * @deprecated Renamed to {@link ParticipatingMediaSystem}. 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 same shape as {@link LightSystem3}: the ECS says what exists and where, and this keeps the
- * renderer's own objects in step. A {@link ParticipatingMediaVolume} is a unit cube posed by a
- * transform, so an entity's `Transform` is the volume — position, size and orientation with no
- * translation step in between.
- *
- * **The transform is taken as world-space, with no hierarchy applied**, which is what the volume
- * model can express: a volume is an oriented box in the scene and Shade has no parent chain to walk
- * for it. Parenting a fog volume to a moving entity therefore leaves the fog where the child's own
- * transform puts it. The lights are placed the same way, for the same reason.
- *
- * **Changes are polled once a frame rather than subscribed to.** A `Transform` announces itself and
- * nothing else here does — a density tuned by an editor slider, a particle spec swapped wholesale
- * for a different Mie solution — so subscribing would cover one field in three and the other two
- * would still have to be polled. Two paths that have to agree, where one does the whole job. It
- * costs about two dozen float comparisons per volume per frame and a scene holds volumes in the
- * tens, so the comparison is cheaper than the signal plumbing it replaces. The price is latency: a
- * change is visible within a frame rather than instantly.
- *
- * **Nothing is uploaded unless something actually changed.** The GPU table is repacked whole
- * whenever {@link SceneVolumetrics.version} moves, so an unconditional copy every frame would
- * re-upload every volume in the scene forever. The comparison is what decides, and on almost every
- * frame it decides nothing has to happen.
- *
- * @see ParticipatingMedia the component
- * @see SceneVolumetrics what the volumes are handed to
- */
-export class ParticipatingMediaSystem3 extends System {
-
-    dependencies = [ParticipatingMedia, Transform];
-
-    /**
-     * @type {GraphicsEngine3}
-     */
-    #graphics;
-
-    /**
-     * @type {Scene}
-     */
-    #scene;
-
-    /**
-     * @type {Map<number, {component: ParticipatingMedia, transform: Transform, volume: ParticipatingMediaVolume}>}
-     */
-    #entries = new Map();
-
-    /**
-     * @param {GraphicsEngine3} graphics
-     * @param {Scene} scene
-     */
-    constructor(graphics, scene) {
-        super();
-
-        assert.defined(graphics, 'graphics');
-        assert.defined(scene, 'scene');
-        assert.equal(scene.isScene, true, 'scene.isScene !== true');
-
-        this.#graphics = graphics;
-        this.#scene = scene;
-    }
-
-    async startup(entityManager) {
-        this.entityManager = entityManager;
-
-        this.#graphics.set_scene(this.#scene);
-    }
-
-    async shutdown(entityManager) {
-        for (const entity of Array.from(this.#entries.keys())) {
-            this.#drop(entity);
-        }
-    }
-
-    /**
-     * @param {ParticipatingMedia} component
-     * @param {Transform} transform
-     * @param {number} entity
-     */
-    link(component, transform, entity) {
-        const volume = new ParticipatingMediaVolume();
-
-        participating_media_volume_write(volume, component, transform);
-
-        this.#scene.volumetrics.add(volume);
-
-        this.#entries.set(entity, { component, transform, volume });
-    }
-
-    /**
-     * @param {ParticipatingMedia} component
-     * @param {Transform} transform
-     * @param {number} entity
-     */
-    unlink(component, transform, entity) {
-        this.#drop(entity);
-    }
-
-    /**
-     * @param {number} time_delta_seconds
-     */
-    update(time_delta_seconds) {
-        const volumetrics = this.#scene.volumetrics;
-
-        for (const entry of this.#entries.values()) {
-            const volume = entry.volume;
-
-            if (participating_media_volume_is_current(volume, entry.component, entry.transform)) {
-                continue;
-            }
-
-            participating_media_volume_write(volume, entry.component, entry.transform);
-
-            volumetrics.invalidate();
-        }
-    }
-
-    /**
-     * @param {number} entity
-     */
-    #drop(entity) {
-        const entry = this.#entries.get(entity);
-
-        if (entry === undefined) {
-            return;
-        }
-
-        this.#scene.volumetrics.remove(entry.volume);
-
-        this.#entries.delete(entity);
-    }
-}
-
-/**
- * Copy what the component and its transform say onto the volume Shade will render.
- *
- * The particle spec is **copied, not referenced**: two entities are routinely built from the same
- * blueprint and would otherwise share one spec, so tuning one volume's particle would silently
- * retune the other's.
- *
- * @param {ParticipatingMediaVolume} volume Shade's
- * @param {ParticipatingMedia} component meep's
- * @param {Transform} transform where the box is
- */
-export function participating_media_volume_write(volume, component, transform) {
-    volume.density = component.density;
-    volume.fade_distance = component.fade_distance;
-
-    volume.particle_spec.copy(component.particle_spec);
-
-    volume.transform.copy(transform);
-}
-
-/**
- * Whether the volume already says what the component and transform say.
- *
- * True on all but a handful of frames, which is the point of asking: a `false` here costs the whole
- * scene's volumetrics table a trip to the GPU.
- *
- * **The transform is compared by its matrix rather than by `Transform.equals`**, because the matrix
- * is the entire transform the GPU is given — the volume's position, rotation and scale are never
- * read on their own. That makes this exactly the question worth asking, "would the upload differ",
- * and it catches a transform posed by writing its matrix, which comparing position, rotation and
- * scale would not.
- *
- * @param {ParticipatingMediaVolume} volume
- * @param {ParticipatingMedia} component
- * @param {Transform} transform
- * @returns {boolean}
+ * 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 function participating_media_volume_is_current(volume, component, transform) {
-    return volume.density === component.density
-        && volume.fade_distance === component.fade_distance
-        && isArrayEqualStrict(volume.transform.matrix, transform.matrix)
-        && volume.particle_spec.equals(component.particle_spec);
-}
+export const ParticipatingMediaSystem3 = ParticipatingMediaSystem;

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

@@ -0,0 +1,76 @@
+/**
+ * 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<any> {
+    /**
+     * @param {GraphicsEngine} graphics
+     * @param {AssetManager} assets
+     */
+    constructor(graphics: GraphicsEngine, 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.
+ */
+export class ParticleExtension extends RenderExtension {
+    /**
+     * @param {ParticleEmitterSystem} system
+     */
+    constructor(system: ParticleEmitterSystem);
+    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";
+//# sourceMappingURL=ParticleEmitterSystem.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ParticleEmitterSystem.d.ts","sourceRoot":"","sources":["../../../../src/engine/graphics3/ParticleEmitterSystem.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;GAaG;AACH;IAiDI;;;OAGG;IACH,4DAUC;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,qBAAqB,EAM/B;IAED,yBAEC;;CACJ;uBA1RsB,kBAAkB;0BACf,+BAA+B;gCACzB,oEAAoE;gCANpE,mDAAmD"}