babylon.quarks 0.26.0 → 0.28.0

package/src/EffectPool.ts

@@ -1,10 +1,12 @@
-import {Vector3} from '@babylonjs/core/Maths/math.vector';
+import {Quaternion, Vector3} from '@babylonjs/core/Maths/math.vector';
 import {TransformNode} from '@babylonjs/core/Meshes/transformNode';
 import {Node} from '@babylonjs/core/node';
 import {BatchedRenderer} from './BatchedRenderer';
+import {disposeEffect} from './effectResources';
 import {ParticleSystem} from './ParticleSystem';
 import {QuarksUtil} from './QuarksUtil';
 
+/** Options for a new {@link EffectPool}. */
 export interface EffectPoolOptions {
     /** The renderer every copy the pool makes is added to. */
     renderer: BatchedRenderer;
@@ -14,6 +16,31 @@ export interface EffectPoolOptions {
     maxSize?: number;
 }
 
+/**
+ * Where {@link EffectPool.acquire} puts a copy. Each part left out is the template's own, as the
+ * copy was made, so nothing carries over from the copy's previous use.
+ */
+export interface EffectPlacement {
+    /** Local position under {@link parent}. */
+    position?: Vector3;
+    /** Local rotation as Euler angles in radians; ignored when {@link rotationQuaternion} is set. */
+    rotation?: Vector3;
+    /** Local rotation as a quaternion, for a direction: a hit normal, a muzzle's facing. */
+    rotationQuaternion?: Quaternion;
+    /** Local scale. */
+    scaling?: Vector3;
+    /** The node the copy is parented to; none (world space) by default. */
+    parent?: Node | null;
+}
+
+/** The local transform a copy is put back to on every acquire. */
+interface RestTransform {
+    position: Vector3;
+    rotation: Vector3;
+    rotationQuaternion: Quaternion | null;
+    scaling: Vector3;
+}
+
 /**
  * A pool of copies of one effect, for effects played many times over: hits,
  * footsteps, muzzle flashes, pickups.
@@ -27,6 +54,10 @@ export interface EffectPoolOptions {
  * Idle copies are parked disabled, which costs the renderer nothing, and keep
  * their place in its batches, so acquiring one allocates nothing.
  *
+ * A copy disposed from outside (by its own `dispose()`, or with a parent it
+ * was acquired under) leaves the pool on its own, and the pool makes a new
+ * one when it needs it.
+ *
  * The template itself is never played by the pool; it is only cloned. Disable
  * it, or keep it out of the renderer, if it is not meant to be seen.
  */
@@ -34,6 +65,7 @@ export class EffectPool {
     private readonly idle: TransformNode[] = [];
     private readonly playing = new Set<TransformNode>();
     private readonly systemsOf = new Map<TransformNode, ParticleSystem[]>();
+    private readonly restOf = new Map<TransformNode, RestTransform>();
     private disposed = false;
 
     constructor(
@@ -61,10 +93,15 @@ export class EffectPool {
 
     /**
      * Takes an idle copy (making one when none is idle and the pool is under
-     * its size), parents it, places it and starts it from the beginning.
-     * Null when the pool is full or disposed.
+     * its size), places it and starts it from the beginning. The copy's
+     * transform is put back to the template's first, so a rotation or scale
+     * from its last use does not stay. Null when the pool is full or disposed.
+     *
+     * @param placement - Where to put the copy, or just its position.
+     * @param parent - The node to parent it to, when `placement` is a position;
+     *   ignored otherwise (use {@link EffectPlacement.parent}).
      */
-    acquire(position?: Vector3, parent: Node | null = null): TransformNode | null {
+    acquire(placement?: Vector3 | EffectPlacement, parent: Node | null = null): TransformNode | null {
         if (this.disposed) {
             return null;
         }
@@ -72,10 +109,12 @@ export class EffectPool {
         if (copy === null) {
             return null;
         }
-        copy.parent = parent;
-        if (position !== undefined) {
-            copy.position.copyFrom(position);
-        }
+        // Told apart by shape, not class: a vector from another copy of Babylon is still a position.
+        const place: EffectPlacement =
+            placement === undefined || typeof (placement as Vector3).x === 'number'
+                ? {position: placement as Vector3 | undefined, parent}
+                : (placement as EffectPlacement);
+        this.placeCopy(copy, place);
         copy.setEnabled(true);
         this.playing.add(copy);
         QuarksUtil.restart(copy);
@@ -98,6 +137,10 @@ export class EffectPool {
         if (!this.playing.delete(copy)) {
             return;
         }
+        if (copy.isDisposed()) {
+            this.forget(copy);
+            return;
+        }
         QuarksUtil.stop(copy);
         copy.setEnabled(false);
         copy.parent = null;
@@ -132,21 +175,60 @@ export class EffectPool {
             systems.push(system);
         });
         this.systemsOf.set(copy, systems);
+        this.restOf.set(copy, {
+            position: copy.position.clone(),
+            rotation: copy.rotation.clone(),
+            rotationQuaternion: copy.rotationQuaternion?.clone() ?? null,
+            scaling: copy.scaling.clone(),
+        });
         QuarksUtil.addToBatchRenderer(copy, this.options.renderer);
         copy.setEnabled(false);
         copy.parent = null;
+        // A copy disposed from outside, or with a parent it was placed under, is let go of.
+        copy.onDisposeObservable.addOnce(() => this.forget(copy));
         return copy;
     }
 
-    private disposeCopy(copy: TransformNode): void {
-        const systems = this.systemsOf.get(copy) ?? [];
-        for (const system of systems) {
+    /** Puts the copy back to the template's transform, then applies `place`. */
+    private placeCopy(copy: TransformNode, place: EffectPlacement): void {
+        const rest = this.restOf.get(copy)!;
+        copy.parent = place.parent ?? null;
+        // By components: Babylon's copyFrom reads private fields, which a vector from elsewhere lacks.
+        const position = place.position ?? rest.position;
+        const scaling = place.scaling ?? rest.scaling;
+        copy.position.copyFromFloats(position.x, position.y, position.z);
+        copy.scaling.copyFromFloats(scaling.x, scaling.y, scaling.z);
+        if (place.rotationQuaternion !== undefined) {
+            copy.rotationQuaternion = place.rotationQuaternion.clone();
+        } else if (place.rotation !== undefined) {
+            copy.rotationQuaternion = null;
+            copy.rotation.copyFromFloats(place.rotation.x, place.rotation.y, place.rotation.z);
+        } else {
+            copy.rotationQuaternion = rest.rotationQuaternion?.clone() ?? null;
+            copy.rotation.copyFrom(rest.rotation);
+        }
+    }
+
+    /** Drops every trace of a copy, which was or is being disposed. */
+    private forget(copy: TransformNode): void {
+        for (const system of this.systemsOf.get(copy) ?? []) {
             system.removeEventListener('finished', this.onSystemFinished);
             this.options.renderer.deleteSystem(system);
             system.dispose();
         }
         this.systemsOf.delete(copy);
-        copy.dispose();
+        this.restOf.delete(copy);
+        this.playing.delete(copy);
+        const index = this.idle.indexOf(copy);
+        if (index !== -1) {
+            this.idle.splice(index, 1);
+        }
+    }
+
+    private disposeCopy(copy: TransformNode): void {
+        this.forget(copy);
+        // Lets go of the textures and materials the copy shares with the template.
+        disposeEffect(copy);
     }
 
     /** The copy a system belongs to is done when all of its systems are. */

package/src/MeshSurfaceEmitter.ts

@@ -1,8 +1,20 @@
 import {VertexBuffer} from '@babylonjs/core/Buffers/buffer';
 import {Mesh} from '@babylonjs/core/Meshes/mesh';
 import {EmitterShape, IParticleSystem, Particle, Plugin, random, ShapeJSON, ShapeTransform, Vector3} from 'quarks.core';
-
+import {ensureTriangleIndices} from './geometryUtil';
+import {quarksNodeId} from './nodeId';
+
+/**
+ * Emits from the surface of a Babylon mesh (Unity's Shape: Mesh, Unreal's Skeletal/Static Mesh
+ * Location): a point picked at random over the triangles, weighted by their area, moving along the
+ * triangle's normal at the particle's start speed. The mesh's vertices are read once, when it is
+ * set, in the mesh's own space, and laid in the emitter's space as they are, moved by
+ * {@link transform}; moving the mesh node afterwards does not move the shape. A mesh without an
+ * index buffer is read as a plain triangle list. A shape without a mesh emits from the origin
+ * along +Z.
+ */
 export class MeshSurfaceEmitter implements EmitterShape {
+    /** The shape's type in effect files. */
     type = 'mesh_surface';
 
     private _triangleIndexToArea: number[] = [];
@@ -13,29 +25,43 @@ export class MeshSurfaceEmitter implements EmitterShape {
     /** Offset, rotation and scale of the mesh within the particle system. */
     transform?: ShapeTransform;
 
-    get mesh() {
+    /**
+     * The mesh emitted from. Setting it reads its positions and indices; a mesh without indices is
+     * read as a triangle list (vertices 0-1-2, 3-4-5, ...), and a mesh without positions, or with
+     * no whole triangle, emits from the origin.
+     */
+    get mesh(): Mesh | undefined {
         return this._mesh;
     }
 
     set mesh(mesh: Mesh | undefined) {
         this._mesh = mesh;
+        this._positions = undefined;
+        this._indices = undefined;
+        this._triangleIndexToArea.length = 0;
         if (!mesh) return;
 
         const positions = mesh.getVerticesData(VertexBuffer.PositionKind);
-        const indices = mesh.getIndices();
-        if (!positions || !indices) return;
+        if (!positions || positions.length < 9) return;
+        const vertexPositions = new Float32Array(positions);
+        const read = mesh.getIndices();
+        const indices = ensureTriangleIndices(
+            vertexPositions,
+            read && read.length > 0 ? Uint32Array.from(read) : undefined
+        );
+        const triCount = Math.floor(indices.length / 3);
+        if (triCount === 0) return;
+
+        this._positions = vertexPositions;
+        this._indices = new Int32Array(indices.subarray(0, triCount * 3));
 
-        this._positions = new Float32Array(positions);
-        this._indices = new Int32Array(indices);
-
-        this._triangleIndexToArea.length = 0;
         let area = 0;
-        const triCount = indices.length / 3;
         this._triangleIndexToArea.push(0);
 
         const a = new Vector3();
         const b = new Vector3();
         const c = new Vector3();
+        const cross = new Vector3();
 
         for (let i = 0; i < triCount; i++) {
             const i0 = indices[i * 3];
@@ -48,20 +74,25 @@ export class MeshSurfaceEmitter implements EmitterShape {
 
             b.sub(a);
             c.sub(a);
-            const cross = new Vector3();
             cross.crossVectors(b, c);
             area += cross.length() * 0.5;
             this._triangleIndexToArea.push(area);
         }
     }
 
+    /**
+     * @param mesh The mesh to emit from.
+     * @param meshReferenceId The id of a mesh node in the effect file, kept until the loader links it.
+     * @param transform Offset, rotation and scale of the mesh within the system.
+     */
     constructor(mesh?: Mesh, meshReferenceId?: string, transform?: ShapeTransform) {
         this._meshReferenceId = meshReferenceId;
         this.transform = transform;
         if (mesh) this.mesh = mesh;
     }
 
-    initialize(p: Particle) {
+    /** Places a new particle on the surface and sets its velocity along the triangle's normal. */
+    initialize(p: Particle): void {
         if (!this._positions || !this._indices) {
             p.position.set(0, 0, 0);
             p.velocity.set(0, 0, 1).multiplyScalar(p.startSpeed);
@@ -114,25 +145,30 @@ export class MeshSurfaceEmitter implements EmitterShape {
         this.transform?.apply(p);
     }
 
+    /** The shape in effect-file form; the mesh is written as its node id. */
     toJSON(): ShapeJSON {
         return {
             type: 'mesh_surface',
-            mesh: this._mesh ? (this._mesh as any).uniqueId?.toString() : (this._meshReferenceId ?? ''),
+            mesh: this._mesh ? quarksNodeId(this._mesh) : (this._meshReferenceId ?? ''),
             ...ShapeTransform.toShapeJSON(this.transform),
         };
     }
 
-    static fromJSON(json: any): MeshSurfaceEmitter {
+    /** Reads {@link toJSON} output; the mesh stays an id until `QuarksLoader` links it. */
+    static fromJSON(json: ShapeJSON | undefined): MeshSurfaceEmitter {
         return new MeshSurfaceEmitter(undefined, json?.mesh, ShapeTransform.fromJSON(json?.transform));
     }
 
+    /** A copy emitting from the same mesh. */
     clone(): EmitterShape {
         return new MeshSurfaceEmitter(this._mesh, this._meshReferenceId, this.transform?.clone());
     }
 
+    /** Does nothing: the shape keeps no state between steps. */
     update(_system: IParticleSystem, _delta: number): void {}
 }
 
+/** Registers {@link MeshSurfaceEmitter} with quarks.core's shape table; loaded when the package is imported. */
 export const MeshSurfaceEmitterPlugin: Plugin = {
     id: 'babylon.quarks',
     initialize: () => {},
@@ -141,7 +177,7 @@ export const MeshSurfaceEmitterPlugin: Plugin = {
             type: 'mesh_surface',
             params: [['mesh', ['mesh']]],
             constructor: MeshSurfaceEmitter,
-            loadJSON: (json: any) => MeshSurfaceEmitter.fromJSON(json),
+            loadJSON: (json: ShapeJSON) => MeshSurfaceEmitter.fromJSON(json),
         },
     ],
     behaviors: [],

package/src/ParticleEmitter.ts

@@ -1,8 +1,56 @@
 import {TransformNode} from '@babylonjs/core/Meshes/transformNode';
 import {Scene} from '@babylonjs/core/scene';
 import {IParticleSystem, Matrix4, SerializationOptions} from 'quarks.core';
+import {quarksNodeId} from './nodeId';
+import type {BabylonMetaData} from './system/types';
 
+/** A {@link ParticleEmitter} as its `toJSON` writes it: the node, its transform and its system. */
+export interface ParticleEmitterJSON {
+    /** The node's id in the effect. */
+    uuid: string;
+    /** Always `'ParticleEmitter'`. */
+    type: 'ParticleEmitter';
+    /** The node's name. */
+    name: string;
+    /** `[x, y, z]`. */
+    position: number[];
+    /** Euler angles `[x, y, z]` in radians. */
+    rotation: number[];
+    /** `[x, y, z, w]`, when the node has a rotation quaternion. */
+    quaternion?: number[];
+    /** `[x, y, z]`. */
+    scale: number[];
+    /** The node's own enabled flag. */
+    visible: boolean;
+    /** The system's JSON, as its `toJSON` writes it. */
+    ps: unknown;
+}
+
+/**
+ * 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 +88,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 +97,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 +107,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;
         }
-        return values;
+        super.dispose(doNotRecurse, disposeMaterialAndTextures);
+        if (systemDisposeDepth > 0) {
+            return;
+        }
+        // IParticleSystem (quarks.core) has no dispose(); ParticleSystem does.
+        (this.system as IParticleSystem & {dispose?: () => void}).dispose?.();
     }
 
     clone(name?: string): ParticleEmitter {
@@ -88,9 +140,15 @@ export class ParticleEmitter extends TransformNode {
         return clonedEmitter;
     }
 
-    toJSON(meta?: any, options: SerializationOptions = {}): any {
+    /**
+     * The node and its system in effect-file form: one entry of an effect file's `object` tree,
+     * without its children. Geometry, materials and textures go into `meta` when it is given.
+     * `visible` is the node's own enabled flag, not the one it inherits from its parents. To write
+     * a whole effect, with its children and resources, use `serializeEffect`.
+     */
+    toJSON(meta?: BabylonMetaData, options: SerializationOptions = {}): ParticleEmitterJSON {
         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],
@@ -104,7 +162,7 @@ export class ParticleEmitter extends TransformNode {
                   ]
                 : undefined,
             scale: [this.scaling.x, this.scaling.y, this.scaling.z],
-            visible: this.isEnabled(),
+            visible: this.isEnabled(false),
             ps: this.system.toJSON(meta, options),
         };
     }