babylon.quarks 0.23.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "babylon.quarks",
-    "version": "0.23.0",
+    "version": "0.24.0",
     "description": "A High-Performance Particle System for Babylon.js",
     "type": "module",
     "types": "./dist/types/index.d.ts",
@@ -63,7 +63,7 @@
         "@babylonjs/core": ">=9.0.0"
     },
     "devDependencies": {
-        "@babylonjs/core": "^9.0.0",
+        "@babylonjs/core": "^9.31.0",
         "@types/jest": "^30.0.0",
         "quarks.core": "*"
     }

package/src/BatchedRenderer.ts

@@ -1,5 +1,8 @@
+import {Camera} from '@babylonjs/core/Cameras/camera';
 import {BaseTexture} from '@babylonjs/core/Materials/Textures/baseTexture';
 import {Texture} from '@babylonjs/core/Materials/Textures/texture';
+import {Frustum} from '@babylonjs/core/Maths/math.frustum';
+import {Plane} from '@babylonjs/core/Maths/math.plane';
 import {TransformNode} from '@babylonjs/core/Meshes/transformNode';
 import {Scene} from '@babylonjs/core/scene';
 import {EmitSubParticleSystem, IParticleSystem, Vector3} from 'quarks.core';
@@ -13,6 +16,7 @@ import {
     MeshRim,
     meshRimEqual,
     RenderMode,
+    SortMode,
     StoredBatchSettings,
     VFXBatch,
 } from './VFXBatch';
@@ -56,6 +60,17 @@ export interface VFXBatchSettings {
      */
     reflectionAtlas: BaseTexture | null;
     layerMask: number;
+    /**
+     * Babylon rendering group (`mesh.renderingGroupId`) the batch draws in,
+     * 0 by default. Systems with different groups are batched apart.
+     */
+    renderingGroupId: number;
+    /**
+     * Whether the scene's fog applies to the particles, as it does to any other
+     * mesh; true by default. Additive particles fade toward black rather than
+     * the fog colour. Systems that differ are batched apart.
+     */
+    applyFog: boolean;
     /**
      * Offset of billboard quads from their particle, in particle-size units
      * (Unity's renderer Pivot). On billboards x/y move the quad in its own plane
@@ -64,6 +79,20 @@ export interface VFXBatchSettings {
      * y across, and z is unused. Absent or zero: no offset. Meshes ignore it.
      */
     pivot?: Vector3;
+    /** Draw order within the batch, see {@link SortMode}. Unset is `'none'`. Systems that differ are batched apart. */
+    sortMode?: SortMode;
+    /**
+     * Smallest size a billboard or stretched particle may have on screen, as a
+     * fraction of the viewport height (Unity's Min Particle Size); 0 by default.
+     * Meshes and trails ignore it. Systems that differ are batched apart.
+     */
+    minParticleSize?: number;
+    /**
+     * Largest size a billboard or stretched particle may have on screen, as a
+     * fraction of the viewport height (Unity's Max Particle Size); unlimited by
+     * default. Meshes and trails ignore it. Systems that differ are batched apart.
+     */
+    maxParticleSize?: number;
     /**
      * How mesh particles are lit (`'unlit'`, `'fixed'` or `'scene'`); unset is
      * `'fixed'`. See {@link MeshLighting}. Other render modes ignore it.
@@ -148,10 +177,107 @@ export class BatchedRenderer extends TransformNode {
     private lastAppliedQuality = Number.NaN;
     private meshLighting: MeshLightingSettings = defaultMeshLighting();
 
+    /**
+     * Whether systems whose {@link ParticleSystem.cullingMode} is not
+     * `'always'` are tested against the active cameras each frame and paused
+     * while unseen. Off, every system simulates every frame; the batches' own
+     * frustum culling of the draw stays on either way.
+     */
+    cullingEnabled = true;
+
+    /**
+     * Time per frame, in milliseconds, that systems coming back into view may
+     * spend together on the steps they missed while culled (`'pauseAndCatchUp'`).
+     * Steps that do not fit are dropped, not deferred, so a crowd of effects
+     * reappearing at once costs at most this. 2 by default.
+     */
+    catchUpBudgetMs = 2;
+
+    /**
+     * Time per frame, in milliseconds, after which the systems still to be
+     * advanced run one step instead of catching up on a long frame. The time
+     * the skipped steps would have covered is dropped, so a frame that already
+     * ran long cannot make the next one longer still. Unlimited by default;
+     * {@link configureAdaptivePerformance} does not set it.
+     */
+    simulationBudgetMs = Infinity;
+
+    /** Frustum planes of the active cameras, six per camera, rebuilt each update. */
+    private frustumPlanes: Plane[] = [];
+    private readonly boundsMin = new Vector3();
+    private readonly boundsMax = new Vector3();
+
     constructor(name: string, scene: Scene) {
         super(name, scene);
     }
 
+    /**
+     * Gathers the frustum planes of the cameras the scene renders with, six per
+     * camera. Empty when there is no camera yet; systems are then never culled.
+     */
+    private collectFrustumPlanes(): Plane[] {
+        const scene = this.getScene();
+        const planes = this.frustumPlanes;
+        const activeCameras = scene.activeCameras;
+        const activeCamera = scene.activeCamera;
+        const cameras: Camera[] =
+            activeCameras && activeCameras.length > 0 ? activeCameras : activeCamera ? [activeCamera] : [];
+        const needed = cameras.length * 6;
+        while (planes.length < needed) {
+            planes.push(new Plane(0, 0, 0, 0));
+        }
+        planes.length = needed;
+        for (let c = 0; c < cameras.length; c++) {
+            const camera = cameras[c];
+            // Both matrices are recomputed only on demand: a camera moved since
+            // the last render would otherwise be tested where it was, and one
+            // that has not rendered yet has no projection at all.
+            camera.getViewMatrix();
+            camera.getProjectionMatrix();
+            const transform = camera.getTransformationMatrix();
+            const slice = c === 0 ? planes : planes.slice(c * 6, c * 6 + 6);
+            Frustum.GetPlanesToRef(transform, slice);
+            if (c !== 0) {
+                for (let p = 0; p < 6; p++) {
+                    planes[c * 6 + p] = slice[p];
+                }
+            }
+        }
+        return planes;
+    }
+
+    /**
+     * True when `system`'s world bounds reach into at least one camera's
+     * frustum, or when it has no bounds to test (empty, or not yet measured).
+     */
+    private isSystemInView(system: ParticleSystem, planes: Plane[]): boolean {
+        const min = this.boundsMin;
+        const max = this.boundsMax;
+        if (!system.getWorldBounds(min, max)) {
+            return true;
+        }
+        for (let c = 0; c < planes.length; c += 6) {
+            let inside = true;
+            for (let p = c; p < c + 6; p++) {
+                const plane = planes[p];
+                const n = plane.normal;
+                // The box corner farthest along the plane's normal: if even it
+                // is behind the plane, the whole box is.
+                const x = n.x >= 0 ? max.x : min.x;
+                const y = n.y >= 0 ? max.y : min.y;
+                const z = n.z >= 0 ? max.z : min.z;
+                if (n.x * x + n.y * y + n.z * z + plane.d < 0) {
+                    inside = false;
+                    break;
+                }
+            }
+            if (inside) {
+                return true;
+            }
+        }
+        return false;
+    }
+
     private static clamp(value: number, min: number, max: number): number {
         return Math.max(min, Math.min(max, value));
     }
@@ -178,7 +304,12 @@ export class BatchedRenderer extends TransformNode {
             a.instancingGeometry === b.instancingGeometry &&
             a.renderOrder === b.renderOrder &&
             a.layerMask === b.layerMask &&
+            a.renderingGroupId === b.renderingGroupId &&
+            a.applyFog === b.applyFog &&
             pivotEqual(a.pivot, b.pivot) &&
+            a.sortMode === (b.sortMode ?? 'none') &&
+            a.minParticleSize === (b.minParticleSize ?? 0) &&
+            a.maxParticleSize === (b.maxParticleSize ?? Infinity) &&
             (a.lighting ?? 'fixed') === (b.lighting ?? 'fixed') &&
             meshRimEqual(a.rim, b.rim)
         );
@@ -418,13 +549,26 @@ export class BatchedRenderer extends TransformNode {
             this.applyAdaptiveQuality();
         }
         const systems = this.orderSystems();
+        const planes = this.cullingEnabled ? this.collectFrustumPlanes() : null;
+        const budgetStart =
+            this.simulationBudgetMs !== Infinity || this.catchUpBudgetMs !== Infinity ? performance.now() : 0;
+        const stepDeadline = this.simulationBudgetMs === Infinity ? Infinity : budgetStart + this.simulationBudgetMs;
+        const catchUpDeadline = this.catchUpBudgetMs === Infinity ? Infinity : budgetStart + this.catchUpBudgetMs;
         for (let i = 0; i < systems.length; i++) {
-            const system = systems[i];
+            const system = systems[i] as ParticleSystem;
             // A disabled emitter holds its particles frozen instead of simulating
             // them unseen, matching how Unity treats a disabled ParticleSystem.
             // Pooled effects parked with setEnabled(false) then cost nothing.
             if (system.emitter.visible) {
-                (system as ParticleSystem).update(delta);
+                // A system no camera sees pauses, by its own choice. One that
+                // only serves as a sub emitter target follows its parent.
+                system.culled =
+                    planes !== null &&
+                    planes.length > 0 &&
+                    system.cullingMode !== 'always' &&
+                    system.onlyUsedByOther !== true &&
+                    !this.isSystemInView(system, planes);
+                system.update(delta, stepDeadline, catchUpDeadline);
             }
             // An autoDestroy system disposes itself from inside update and drops
             // out of the list; stay on the slot it vacated.

package/src/EffectPool.ts

@@ -0,0 +1,165 @@
+import {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 {ParticleSystem} from './ParticleSystem';
+import {QuarksUtil} from './QuarksUtil';
+
+export interface EffectPoolOptions {
+    /** The renderer every copy the pool makes is added to. */
+    renderer: BatchedRenderer;
+    /** Copies made up front, so the first plays do not pay for cloning. Default 0. */
+    prewarm?: number;
+    /** Most copies the pool will ever hold; {@link EffectPool.acquire} returns null past it. Default unlimited. */
+    maxSize?: number;
+}
+
+/**
+ * A pool of copies of one effect, for effects played many times over: hits,
+ * footsteps, muzzle flashes, pickups.
+ *
+ * {@link acquire} hands out an idle copy (or makes one), places it and plays
+ * it; a copy whose every system has finished goes back to the pool by itself,
+ * so a one-shot effect needs nothing more. A looping effect is ended with
+ * {@link stop}, which lets its particles die out before the copy returns, or
+ * dropped at once with {@link release}.
+ *
+ * Idle copies are parked disabled, which costs the renderer nothing, and keep
+ * their place in its batches, so acquiring one allocates nothing.
+ *
+ * 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.
+ */
+export class EffectPool {
+    private readonly idle: TransformNode[] = [];
+    private readonly playing = new Set<TransformNode>();
+    private readonly systemsOf = new Map<TransformNode, ParticleSystem[]>();
+    private disposed = false;
+
+    constructor(
+        private readonly template: TransformNode,
+        private readonly options: EffectPoolOptions
+    ) {
+        for (let i = 0; i < (options.prewarm ?? 0); i++) {
+            const copy = this.makeCopy();
+            if (copy === null) {
+                break;
+            }
+            this.idle.push(copy);
+        }
+    }
+
+    /** Copies currently playing. */
+    get activeCount(): number {
+        return this.playing.size;
+    }
+
+    /** Copies parked and ready. */
+    get idleCount(): number {
+        return this.idle.length;
+    }
+
+    /**
+     * 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.
+     */
+    acquire(position?: Vector3, parent: Node | null = null): TransformNode | null {
+        if (this.disposed) {
+            return null;
+        }
+        const copy = this.idle.pop() ?? this.makeCopy();
+        if (copy === null) {
+            return null;
+        }
+        copy.parent = parent;
+        if (position !== undefined) {
+            copy.position.copyFrom(position);
+        }
+        copy.setEnabled(true);
+        this.playing.add(copy);
+        QuarksUtil.restart(copy);
+        QuarksUtil.play(copy);
+        return copy;
+    }
+
+    /**
+     * Ends the emission of a playing copy; it returns to the pool on its own
+     * once its particles have died, looping systems included.
+     */
+    stop(copy: TransformNode): void {
+        if (this.playing.has(copy)) {
+            QuarksUtil.endEmit(copy);
+        }
+    }
+
+    /** Puts a copy back at once, particles and all, parked and disabled. */
+    release(copy: TransformNode): void {
+        if (!this.playing.delete(copy)) {
+            return;
+        }
+        QuarksUtil.stop(copy);
+        copy.setEnabled(false);
+        copy.parent = null;
+        if (!this.disposed) {
+            this.idle.push(copy);
+        }
+    }
+
+    /** Disposes every copy, playing or idle. The template is left alone. */
+    dispose(): void {
+        this.disposed = true;
+        for (const copy of [...this.playing, ...this.idle]) {
+            this.playing.delete(copy);
+            this.disposeCopy(copy);
+        }
+        this.idle.length = 0;
+    }
+
+    private makeCopy(): TransformNode | null {
+        const made = this.idle.length + this.playing.size;
+        if (made >= (this.options.maxSize ?? Infinity)) {
+            return null;
+        }
+        const copy = QuarksUtil.instantiate(this.template);
+        const systems: ParticleSystem[] = [];
+        QuarksUtil.runOnAllParticleEmitters(copy, (emitter) => {
+            const system = emitter.system as unknown as ParticleSystem;
+            // The pool owns the copy's life; a system disposing itself would
+            // pull one emitter out of an effect that is meant to play again.
+            system.autoDestroy = false;
+            system.addEventListener('finished', this.onSystemFinished);
+            systems.push(system);
+        });
+        this.systemsOf.set(copy, systems);
+        QuarksUtil.addToBatchRenderer(copy, this.options.renderer);
+        copy.setEnabled(false);
+        copy.parent = null;
+        return copy;
+    }
+
+    private disposeCopy(copy: TransformNode): void {
+        const systems = this.systemsOf.get(copy) ?? [];
+        for (const system of systems) {
+            system.removeEventListener('finished', this.onSystemFinished);
+            this.options.renderer.deleteSystem(system);
+            system.dispose();
+        }
+        this.systemsOf.delete(copy);
+        copy.dispose();
+    }
+
+    /** The copy a system belongs to is done when all of its systems are. */
+    private readonly onSystemFinished = (event: {particleSystem: unknown}): void => {
+        const system = event.particleSystem as ParticleSystem;
+        for (const copy of this.playing) {
+            const systems = this.systemsOf.get(copy);
+            if (systems !== undefined && systems.includes(system)) {
+                if (QuarksUtil.isEffectFinished(copy)) {
+                    this.release(copy);
+                }
+                return;
+            }
+        }
+    };
+}

package/src/MeshSurfaceEmitter.ts

@@ -1,6 +1,6 @@
 import {VertexBuffer} from '@babylonjs/core/Buffers/buffer';
 import {Mesh} from '@babylonjs/core/Meshes/mesh';
-import {EmitterShape, IParticleSystem, Particle, Plugin, ShapeJSON, ShapeTransform, Vector3} from 'quarks.core';
+import {EmitterShape, IParticleSystem, Particle, Plugin, random, ShapeJSON, ShapeTransform, Vector3} from 'quarks.core';
 
 export class MeshSurfaceEmitter implements EmitterShape {
     type = 'mesh_surface';
@@ -72,7 +72,7 @@ export class MeshSurfaceEmitter implements EmitterShape {
         const triCount = this._triangleIndexToArea.length - 1;
         let left = 0,
             right = triCount;
-        const target = Math.random() * this._triangleIndexToArea[triCount];
+        const target = random() * this._triangleIndexToArea[triCount];
 
         while (left + 1 < right) {
             const mid = Math.floor((left + right) / 2);
@@ -83,8 +83,8 @@ export class MeshSurfaceEmitter implements EmitterShape {
             }
         }
 
-        let u1 = Math.random();
-        let u2 = Math.random();
+        let u1 = random();
+        let u2 = random();
         if (u1 + u2 > 1) {
             u1 = 1 - u1;
             u2 = 1 - u2;

package/src/ParticleEmitter.ts

@@ -83,7 +83,8 @@ export class ParticleEmitter extends TransformNode {
         if (this.rotationQuaternion) {
             clonedEmitter.rotationQuaternion = this.rotationQuaternion.clone();
         }
-        clonedEmitter.setEnabled(this.isEnabled());
+        // Its own flag only: a clone of an emitter under a disabled parent is not itself disabled.
+        clonedEmitter.setEnabled(this.isEnabled(false));
         return clonedEmitter;
     }