babylon.quarks 0.26.0 → 0.27.0

package/src/ParticleEmitter.ts

@@ -1,8 +1,33 @@
 import {TransformNode} from '@babylonjs/core/Meshes/transformNode';
 import {Scene} from '@babylonjs/core/scene';
 import {IParticleSystem, Matrix4, SerializationOptions} from 'quarks.core';
+import {quarksNodeId} from './nodeId';
 
+/**
+ * Above 0 while a particle system disposes its own emitter (`ParticleSystem.dispose()`, which
+ * `autoDestroy` calls when the system finishes). Babylon then disposes the child nodes too, and
+ * child emitters keep their systems playing, so an effect's longer-lived children are not cut off
+ * when a short parent finishes. Disposing a node directly (`root.dispose()`) disposes its systems.
+ */
+let systemDisposeDepth = 0;
+
+/** Disposes `emitter` for its own system without disposing the systems of child emitters. */
+export function disposeEmitterForSystem(emitter: TransformNode): void {
+    systemDisposeDepth++;
+    try {
+        emitter.dispose();
+    } finally {
+        systemDisposeDepth--;
+    }
+}
+
+/**
+ * The Babylon node a particle system lives at: its position, rotation and scale place the system,
+ * parenting it moves the effect with another node, and disabling it freezes and hides the system.
+ * Every {@link ParticleSystem} makes its own, as `system.emitter`.
+ */
 export class ParticleEmitter extends TransformNode {
+    /** The particle system this node carries. */
     system: IParticleSystem;
     private _matrixWorld: Matrix4 = new Matrix4();
     private _matrixWorldFlag = -1;
@@ -40,6 +65,7 @@ export class ParticleEmitter extends TransformNode {
         return this._matrixWorld;
     }
 
+    /** Whether the node and its parents are enabled; setting it is `setEnabled`. */
     get visible(): boolean {
         return this.isEnabled();
     }
@@ -48,8 +74,9 @@ export class ParticleEmitter extends TransformNode {
         this.setEnabled(value);
     }
 
+    /** The id effect files know this emitter by; see {@link quarksNodeId}. */
     get uuid(): string {
-        return this.uniqueId.toString();
+        return quarksNodeId(this);
     }
 
     constructor(system: IParticleSystem, scene?: Scene) {
@@ -57,20 +84,22 @@ export class ParticleEmitter extends TransformNode {
         this.system = system;
     }
 
-    dispose(): void {
-        super.dispose();
-    }
-
-    extractFromCache(cache: any): any[] {
-        const values: any[] = [];
-        for (const key in cache) {
-            const data = cache[key];
-            if (data && typeof data === 'object') {
-                delete data.metadata;
-            }
-            values.push(data);
+    /**
+     * Disposes the node and the particle system it carries, so `root.dispose()` on an effect tree
+     * also removes its systems from their renderer. Safe to call more than once. When a system
+     * disposes its own emitter (`ParticleSystem.dispose()`, `autoDestroy`), the systems of child
+     * emitters keep playing until they finish or are disposed themselves.
+     */
+    dispose(doNotRecurse?: boolean, disposeMaterialAndTextures = false): void {
+        if (this.isDisposed()) {
+            return;
+        }
+        super.dispose(doNotRecurse, disposeMaterialAndTextures);
+        if (systemDisposeDepth > 0) {
+            return;
         }
-        return values;
+        // IParticleSystem (quarks.core) has no dispose(); ParticleSystem does.
+        (this.system as IParticleSystem & {dispose?: () => void}).dispose?.();
     }
 
     clone(name?: string): ParticleEmitter {
@@ -88,9 +117,10 @@ export class ParticleEmitter extends TransformNode {
         return clonedEmitter;
     }
 
+    /** The node and its system in effect-file form; `serializeEffect` writes whole effects. @internal */
     toJSON(meta?: any, options: SerializationOptions = {}): any {
         return {
-            uuid: (this as any)._quarksUUID ?? this.uniqueId.toString(),
+            uuid: quarksNodeId(this),
             type: 'ParticleEmitter',
             name: this.name,
             position: [this.position.x, this.position.y, this.position.z],