babylon.quarks 0.18.1 → 0.19.0

package/package.json

@@ -1,70 +1,70 @@
 {
-  "name": "babylon.quarks",
-  "version": "0.18.1",
-  "description": "A High-Performance Particle System for Babylon.js",
-  "type": "module",
-  "types": "./dist/types/index.d.ts",
-  "main": "./dist/babylon.quarks.cjs",
-  "module": "./dist/babylon.quarks.esm.js",
-  "unpkg": "./dist/babylon.quarks.umd.min.js",
-  "jsdelivr": "./dist/babylon.quarks.umd.min.js",
-  "exports": {
-    ".": {
-      "import": "./dist/babylon.quarks.esm.js",
-      "require": "./dist/babylon.quarks.cjs",
-      "types": "./dist/types/index.d.ts"
+    "name": "babylon.quarks",
+    "version": "0.19.0",
+    "description": "A High-Performance Particle System for Babylon.js",
+    "type": "module",
+    "types": "./dist/types/index.d.ts",
+    "main": "./dist/babylon.quarks.cjs",
+    "module": "./dist/babylon.quarks.esm.js",
+    "unpkg": "./dist/babylon.quarks.umd.min.js",
+    "jsdelivr": "./dist/babylon.quarks.umd.min.js",
+    "exports": {
+        ".": {
+            "import": "./dist/babylon.quarks.esm.js",
+            "require": "./dist/babylon.quarks.cjs",
+            "types": "./dist/types/index.d.ts"
+        }
+    },
+    "files": [
+        "dist",
+        "src",
+        "LICENSE",
+        "README.md",
+        "CHANGELOG.md"
+    ],
+    "scripts": {
+        "clean": "rimraf dist dist-types tsconfig.tsbuildinfo",
+        "build:types": "tsc --emitDeclarationOnly",
+        "build:js": "cross-env NODE_ENV=production rollup -c",
+        "build": "npm run clean && npm run build:types && npm run build:js",
+        "test": "jest",
+        "docs": "typedoc",
+        "test:coverage": "jest --coverage",
+        "prettier": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\""
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Soullnik/babylon.quarks-standalone.git"
+    },
+    "keywords": [
+        "babylonjs",
+        "babylon.js",
+        "particles",
+        "particle-system",
+        "particle",
+        "vfx",
+        "visual-effects",
+        "gpu-particles",
+        "webgl",
+        "webgpu",
+        "quarks",
+        "three.quarks",
+        "3d",
+        "game",
+        "performance"
+    ],
+    "author": "soullnik <soullnik96@gmail.com>",
+    "license": "MIT",
+    "bugs": {
+        "url": "https://github.com/Soullnik/babylon.quarks-standalone/issues"
+    },
+    "homepage": "https://github.com/Soullnik/babylon.quarks-standalone#readme",
+    "peerDependencies": {
+        "@babylonjs/core": ">=9.0.0"
+    },
+    "devDependencies": {
+        "@babylonjs/core": "^9.0.0",
+        "@types/jest": "^30.0.0",
+        "quarks.core": "*"
     }
-  },
-  "files": [
-    "dist",
-    "src",
-    "LICENSE",
-    "README.md",
-    "CHANGELOG.md"
-  ],
-  "scripts": {
-    "clean": "rimraf dist dist-types tsconfig.tsbuildinfo",
-    "build:types": "tsc --emitDeclarationOnly",
-    "build:js": "cross-env NODE_ENV=production rollup -c",
-    "build": "npm run clean && npm run build:types && npm run build:js",
-    "test": "jest",
-    "docs": "typedoc",
-    "test:coverage": "jest --coverage",
-    "prettier": "prettier --write --ignore-unknown **/*.ts"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Soullnik/babylon.quarks-standalone.git"
-  },
-  "keywords": [
-    "babylonjs",
-    "babylon.js",
-    "particles",
-    "particle-system",
-    "particle",
-    "vfx",
-    "visual-effects",
-    "gpu-particles",
-    "webgl",
-    "webgpu",
-    "quarks",
-    "three.quarks",
-    "3d",
-    "game",
-    "performance"
-  ],
-  "author": "soullnik <soullnik96@gmail.com>",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/Soullnik/babylon.quarks-standalone/issues"
-  },
-  "homepage": "https://github.com/Soullnik/babylon.quarks-standalone#readme",
-  "peerDependencies": {
-    "@babylonjs/core": ">=9.0.0"
-  },
-  "devDependencies": {
-    "@babylonjs/core": "^9.0.0",
-    "@types/jest": "^30.0.0",
-    "quarks.core": "*"
-  }
 }

package/src/BatchedRenderer.ts

@@ -1,12 +1,12 @@
+import {BaseTexture} from '@babylonjs/core/Materials/Textures/baseTexture';
+import {Texture} from '@babylonjs/core/Materials/Textures/texture';
 import {TransformNode} from '@babylonjs/core/Meshes/transformNode';
 import {Scene} from '@babylonjs/core/scene';
-import {Texture} from '@babylonjs/core/Materials/Textures/texture';
-import {BaseTexture} from '@babylonjs/core/Materials/Textures/baseTexture';
-import {IParticleSystem} from 'quarks.core';
-import {VFXBatch, RenderMode, StoredBatchSettings} from './VFXBatch';
+import {EmitSubParticleSystem, IParticleSystem} from 'quarks.core';
+import {ParticleSystem} from './ParticleSystem';
 import {SpriteBatch} from './SpriteBatch';
 import {TrailBatch} from './TrailBatch';
-import {ParticleSystem} from './ParticleSystem';
+import {RenderMode, StoredBatchSettings, VFXBatch} from './VFXBatch';
 
 export interface VFXBatchSettings {
     instancingGeometry: Float32Array;
@@ -27,6 +27,25 @@ export interface VFXBatchSettings {
     materialDepthWrite: boolean;
     materialAlphaTest: number;
     texture: Texture | null;
+    /**
+     * Cubemap (or other reflection texture) harvested from a Babylon material's
+     * `reflectionTexture`. Mesh batches sample it like StandardMaterial cubic
+     * reflection; other render modes ignore it.
+     */
+    reflectionTexture: BaseTexture | null;
+    /** Multiplier for the reflection sample — mirrors `texture.level`. */
+    reflectionLevel: number;
+    /**
+     * Optional six cube-face 2D textures (px,py,pz,nx,ny,nz). Prefer
+     * `reflectionAtlas` on iOS — many simultaneous face samplers still trip
+     * GL_INVALID_OPERATION on WebKit.
+     */
+    reflectionFaces: BaseTexture[] | null;
+    /**
+     * Single 3×2 atlas of cube faces (px py pz / nx ny nz). One sampler2D —
+     * the path that stays valid on iOS WebKit ShaderMaterial draws.
+     */
+    reflectionAtlas: BaseTexture | null;
     layerMask: number;
 }
 
@@ -38,6 +57,22 @@ export interface AdaptivePerformanceOptions {
     increaseStep: number;
 }
 
+/** True when both face lists are the same six texture references (or both empty). */
+function reflectionFacesEqual(a: BaseTexture[] | null | undefined, b: BaseTexture[] | null | undefined): boolean {
+    if (a === b) {
+        return true;
+    }
+    if (!a || !b || a.length !== b.length) {
+        return false;
+    }
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i]) {
+            return false;
+        }
+    }
+    return true;
+}
+
 export interface AdaptivePerformanceState extends AdaptivePerformanceOptions {
     enabled: boolean;
     currentQuality: number;
@@ -48,6 +83,29 @@ export class BatchedRenderer extends TransformNode {
     batches: Array<VFXBatch> = [];
     systemToBatchIndex: Map<IParticleSystem, number> = new Map<IParticleSystem, number>();
     depthTexture: BaseTexture | null = null;
+    /** Systems in insertion order — iterated every frame, unlike the map. */
+    private systems: Array<IParticleSystem> = [];
+    /**
+     * The same systems, ordered so that one emitting into another comes first.
+     *
+     * A sub emitter's particles are created by its parent's behaviors, part way
+     * through the parent's step. A sub system updated before its parent has
+     * already fixed the list of particles it will run behaviors over, so those
+     * new particles are drawn that frame with nothing but their start values —
+     * white where a colour curve would have coloured them, at their start size,
+     * sitting at the point they were born. Rebuilt only when the set of systems
+     * or their behaviors changes, not per frame.
+     */
+    private orderedSystems: Array<IParticleSystem> = [];
+    private orderedSystemsStale = true;
+    /** Consecutive frames each batch has held no system, parallel to `batches`. */
+    private batchEmptyFrames: Array<number> = [];
+    /**
+     * How long an empty batch is kept before it is disposed. Systems that toggle
+     * a setting back and forth reuse the batch within this window instead of
+     * rebuilding a mesh and material every time.
+     */
+    private static readonly EMPTY_BATCH_GRACE_FRAMES = 120;
     private adaptivePerformanceState: AdaptivePerformanceState = {
         enabled: false,
         targetFrameMs: 16.7,
@@ -76,6 +134,10 @@ export class BatchedRenderer extends TransformNode {
             a.materialDepthWrite === b.materialDepthWrite &&
             a.materialAlphaTest === b.materialAlphaTest &&
             a.texture === b.texture &&
+            a.reflectionTexture === b.reflectionTexture &&
+            a.reflectionLevel === b.reflectionLevel &&
+            reflectionFacesEqual(a.reflectionFaces, b.reflectionFaces) &&
+            a.reflectionAtlas === b.reflectionAtlas &&
             a.renderMode === b.renderMode &&
             a.blendTiles === b.blendTiles &&
             a.softParticles === b.softParticles &&
@@ -92,9 +154,19 @@ export class BatchedRenderer extends TransformNode {
     addSystem(system: IParticleSystem) {
         const particleSystem = system as ParticleSystem;
         particleSystem._renderer = this;
+        if (!this.systemToBatchIndex.has(system) && this.systems.indexOf(system) === -1) {
+            this.systems.push(system);
+            this.orderedSystemsStale = true;
+        }
         if (this.adaptivePerformanceState.enabled) {
             particleSystem.setQualityFactor(this.adaptivePerformanceState.currentQuality);
         }
+        this.assignToBatch(particleSystem);
+    }
+
+    /** Places a system into a compatible batch, creating one when none matches. */
+    private assignToBatch(particleSystem: ParticleSystem) {
+        const system = particleSystem as IParticleSystem;
         const settings = particleSystem.getRendererSettings();
         for (let i = 0; i < this.batches.length; i++) {
             if (BatchedRenderer.equals(this.batches[i].settings, settings)) {
@@ -125,19 +197,44 @@ export class BatchedRenderer extends TransformNode {
         }
         batch.addSystem(system);
         this.batches.push(batch);
+        this.batchEmptyFrames.push(0);
         this.systemToBatchIndex.set(system, this.batches.length - 1);
     }
 
     deleteSystem(system: IParticleSystem) {
+        const removed = this.removeFromBatch(system);
+        const index = this.systems.indexOf(system);
+        if (index !== -1) {
+            this.systems.splice(index, 1);
+            this.orderedSystemsStale = true;
+        }
+        // Also out of the ordered copy, which update() may be iterating right
+        // now: a system that disposes itself from inside its own update leaves
+        // the loop expecting the slot it vacated to hold the next one.
+        const ordered = this.orderedSystems.indexOf(system);
+        if (ordered !== -1) {
+            this.orderedSystems.splice(ordered, 1);
+        }
+        return removed;
+    }
+
+    /** Detaches a system from its batch, leaving the renderer's system list alone. */
+    private removeFromBatch(system: IParticleSystem): boolean {
         const batchIndex = this.systemToBatchIndex.get(system);
-        if (batchIndex !== undefined) {
-            this.batches[batchIndex].removeSystem(system);
-            this.systemToBatchIndex.delete(system);
+        if (batchIndex === undefined) {
+            return false;
         }
+        this.batches[batchIndex].removeSystem(system);
+        this.systemToBatchIndex.delete(system);
+        return true;
     }
 
+    /**
+     * Re-buckets a system whose render settings changed. The system keeps its
+     * place in the update order, so this is safe to call mid-frame.
+     */
     updateSystem(system: IParticleSystem) {
-        this.deleteSystem(system);
+        this.removeFromBatch(system);
         this.addSystem(system);
     }
 
@@ -179,20 +276,90 @@ export class BatchedRenderer extends TransformNode {
         if (quality === this.lastAppliedQuality) {
             return;
         }
-        for (const ps of this.systemToBatchIndex.keys()) {
-            (ps as ParticleSystem).setQualityFactor(quality);
+        for (let i = 0; i < this.systems.length; i++) {
+            (this.systems[i] as ParticleSystem).setQualityFactor(quality);
         }
         this.lastAppliedQuality = quality;
     }
 
+    /** @internal Called when a system's behaviors change, which can add a sub emitter. */
+    _invalidateUpdateOrder(): void {
+        this.orderedSystemsStale = true;
+    }
+
+    /**
+     * Orders the systems so a system emitting into another runs first.
+     *
+     * Depth first over "emits into" edges, recording each system once all the
+     * systems it feeds have been recorded, then reversed — a system therefore
+     * lands ahead of everything it emits into, however deep the chain. A cycle
+     * cannot be satisfied by any order; it is left as found rather than dropped.
+     */
+    private orderSystems(): Array<IParticleSystem> {
+        if (!this.orderedSystemsStale) {
+            return this.orderedSystems;
+        }
+        const ordered: Array<IParticleSystem> = [];
+        const visiting = new Set<IParticleSystem>();
+        const done = new Set<IParticleSystem>();
+        const known = new Set<IParticleSystem>(this.systems);
+
+        const subTargetsOf = (system: IParticleSystem): Array<IParticleSystem> => {
+            const targets: Array<IParticleSystem> = [];
+            for (const behavior of (system as ParticleSystem).behaviors ?? []) {
+                if (behavior.type !== 'EmitSubParticleSystem') {
+                    continue;
+                }
+                const target = (behavior as EmitSubParticleSystem).subParticleSystem?.system;
+                if (target !== undefined && known.has(target)) {
+                    targets.push(target);
+                }
+            }
+            return targets;
+        };
+
+        const visit = (system: IParticleSystem): void => {
+            if (done.has(system) || visiting.has(system)) {
+                return;
+            }
+            visiting.add(system);
+            for (const target of subTargetsOf(system)) {
+                visit(target);
+            }
+            visiting.delete(system);
+            done.add(system);
+            ordered.push(system);
+        };
+
+        for (const system of this.systems) {
+            visit(system);
+        }
+        ordered.reverse();
+        this.orderedSystems = ordered;
+        this.orderedSystemsStale = false;
+        return ordered;
+    }
+
     update(delta: number) {
         const adaptiveState = this.adaptivePerformanceState;
         const frameStart = adaptiveState.enabled ? performance.now() : 0;
         if (adaptiveState.enabled) {
             this.applyAdaptiveQuality();
         }
-        for (const ps of this.systemToBatchIndex.keys()) {
-            (ps as ParticleSystem).update(delta);
+        const systems = this.orderSystems();
+        for (let i = 0; i < systems.length; i++) {
+            const system = systems[i];
+            // 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);
+            }
+            // An autoDestroy system disposes itself from inside update and drops
+            // out of the list; stay on the slot it vacated.
+            if (systems[i] !== system) {
+                i--;
+            }
         }
         this.refreshBatches();
         if (!adaptiveState.enabled) {
@@ -217,8 +384,38 @@ export class BatchedRenderer extends TransformNode {
 
     /** Rebuild instance buffers from current particle state without advancing simulation. */
     refreshBatches(): void {
+        const emptyFrames = this.batchEmptyFrames;
         for (let i = 0; i < this.batches.length; i++) {
-            this.batches[i].update();
+            const batch = this.batches[i];
+            if (batch.systems.size > 0) {
+                emptyFrames[i] = 0;
+                batch.update();
+                continue;
+            }
+            const framesEmpty = (emptyFrames[i] ?? 0) + 1;
+            emptyFrames[i] = framesEmpty;
+            if (framesEmpty === 1) {
+                // One last update clears the instance data left on screen.
+                batch.update();
+            } else if (framesEmpty > BatchedRenderer.EMPTY_BATCH_GRACE_FRAMES) {
+                // Nothing has used these settings for a while: give the mesh,
+                // material and GPU buffers back instead of re-uploading empty
+                // instance data forever.
+                this.removeBatch(i);
+                i--;
+            }
+        }
+    }
+
+    /** Disposes the batch at `index` and repairs the system→batch mapping. */
+    private removeBatch(index: number): void {
+        this.batches[index].dispose();
+        this.batches.splice(index, 1);
+        this.batchEmptyFrames.splice(index, 1);
+        for (const [system, batchIndex] of this.systemToBatchIndex) {
+            if (batchIndex > index) {
+                this.systemToBatchIndex.set(system, batchIndex - 1);
+            }
         }
     }
 
@@ -253,6 +450,8 @@ export class BatchedRenderer extends TransformNode {
             batch.dispose();
         }
         this.batches = [];
+        this.batchEmptyFrames.length = 0;
+        this.systems.length = 0;
         this.systemToBatchIndex.clear();
         super.dispose();
     }

package/src/MeshSurfaceEmitter.ts

@@ -1,13 +1,6 @@
-import {Mesh} from '@babylonjs/core/Meshes/mesh';
 import {VertexBuffer} from '@babylonjs/core/Buffers/buffer';
-import {
-    Particle,
-    EmitterShape,
-    ShapeJSON,
-    IParticleSystem,
-    Vector3,
-    Plugin,
-} from 'quarks.core';
+import {Mesh} from '@babylonjs/core/Meshes/mesh';
+import {EmitterShape, IParticleSystem, Particle, Plugin, ShapeJSON, Vector3} from 'quarks.core';
 
 export class MeshSurfaceEmitter implements EmitterShape {
     type = 'mesh_surface';
@@ -73,7 +66,8 @@ export class MeshSurfaceEmitter implements EmitterShape {
         }
 
         const triCount = this._triangleIndexToArea.length - 1;
-        let left = 0, right = triCount;
+        let left = 0,
+            right = triCount;
         const target = Math.random() * this._triangleIndexToArea[triCount];
 
         while (left + 1 < right) {
@@ -96,9 +90,15 @@ export class MeshSurfaceEmitter implements EmitterShape {
         const idx1 = this._indices[left * 3 + 1];
         const idx2 = this._indices[left * 3 + 2];
 
-        const ax = this._positions[idx0 * 3], ay = this._positions[idx0 * 3 + 1], az = this._positions[idx0 * 3 + 2];
-        const bx = this._positions[idx1 * 3] - ax, by = this._positions[idx1 * 3 + 1] - ay, bz = this._positions[idx1 * 3 + 2] - az;
-        const cx = this._positions[idx2 * 3] - ax, cy = this._positions[idx2 * 3 + 1] - ay, cz = this._positions[idx2 * 3 + 2] - az;
+        const ax = this._positions[idx0 * 3],
+            ay = this._positions[idx0 * 3 + 1],
+            az = this._positions[idx0 * 3 + 2];
+        const bx = this._positions[idx1 * 3] - ax,
+            by = this._positions[idx1 * 3 + 1] - ay,
+            bz = this._positions[idx1 * 3 + 2] - az;
+        const cx = this._positions[idx2 * 3] - ax,
+            cy = this._positions[idx2 * 3 + 1] - ay,
+            cz = this._positions[idx2 * 3 + 2] - az;
 
         p.position.set(ax + bx * u1 + cx * u2, ay + by * u1 + cy * u2, az + bz * u1 + cz * u2);
 
@@ -110,7 +110,10 @@ export class MeshSurfaceEmitter implements EmitterShape {
     }
 
     toJSON(): ShapeJSON {
-        return {type: 'mesh_surface', mesh: this._mesh ? (this._mesh as any).uniqueId?.toString() : this._meshReferenceId ?? ''};
+        return {
+            type: 'mesh_surface',
+            mesh: this._mesh ? (this._mesh as any).uniqueId?.toString() : (this._meshReferenceId ?? ''),
+        };
     }
 
     static fromJSON(json: any): MeshSurfaceEmitter {
@@ -127,11 +130,13 @@ export class MeshSurfaceEmitter implements EmitterShape {
 export const MeshSurfaceEmitterPlugin: Plugin = {
     id: 'babylon.quarks',
     initialize: () => {},
-    emitterShapes: [{
-        type: 'mesh_surface',
-        params: [['mesh', ['mesh']]],
-        constructor: MeshSurfaceEmitter,
-        loadJSON: (json: any) => MeshSurfaceEmitter.fromJSON(json),
-    }],
+    emitterShapes: [
+        {
+            type: 'mesh_surface',
+            params: [['mesh', ['mesh']]],
+            constructor: MeshSurfaceEmitter,
+            loadJSON: (json: any) => MeshSurfaceEmitter.fromJSON(json),
+        },
+    ],
     behaviors: [],
 };

package/src/ParticleEmitter.ts

@@ -1,18 +1,42 @@
 import {TransformNode} from '@babylonjs/core/Meshes/transformNode';
 import {Scene} from '@babylonjs/core/scene';
-import {Matrix4, IParticleSystem, SerializationOptions} from 'quarks.core';
+import {IParticleSystem, Matrix4, SerializationOptions} from 'quarks.core';
 
 export class ParticleEmitter extends TransformNode {
     system: IParticleSystem;
     private _matrixWorld: Matrix4 = new Matrix4();
+    private _matrixWorldFlag = -1;
 
+    /**
+     * The node's world matrix in quarks.core form. Mirrored from Babylon's
+     * matrix only when that matrix actually changed (tracked by its
+     * `updateFlag`), so repeated reads inside a frame are free.
+     */
     get matrixWorld(): Matrix4 {
         const m = this.getWorldMatrix();
+        const flag = m.updateFlag;
+        if (flag === this._matrixWorldFlag) {
+            return this._matrixWorld;
+        }
+        this._matrixWorldFlag = flag;
         const e = this._matrixWorld.elements;
-        e[0] = m.m[0]; e[1] = m.m[1]; e[2] = m.m[2]; e[3] = m.m[3];
-        e[4] = m.m[4]; e[5] = m.m[5]; e[6] = m.m[6]; e[7] = m.m[7];
-        e[8] = m.m[8]; e[9] = m.m[9]; e[10] = m.m[10]; e[11] = m.m[11];
-        e[12] = m.m[12]; e[13] = m.m[13]; e[14] = m.m[14]; e[15] = m.m[15];
+        const s = m.m;
+        e[0] = s[0];
+        e[1] = s[1];
+        e[2] = s[2];
+        e[3] = s[3];
+        e[4] = s[4];
+        e[5] = s[5];
+        e[6] = s[6];
+        e[7] = s[7];
+        e[8] = s[8];
+        e[9] = s[9];
+        e[10] = s[10];
+        e[11] = s[11];
+        e[12] = s[12];
+        e[13] = s[13];
+        e[14] = s[14];
+        e[15] = s[15];
         return this._matrixWorld;
     }
 
@@ -72,11 +96,11 @@ export class ParticleEmitter extends TransformNode {
             rotation: [this.rotation.x, this.rotation.y, this.rotation.z],
             quaternion: this.rotationQuaternion
                 ? [
-                    this.rotationQuaternion.x,
-                    this.rotationQuaternion.y,
-                    this.rotationQuaternion.z,
-                    this.rotationQuaternion.w,
-                ]
+                      this.rotationQuaternion.x,
+                      this.rotationQuaternion.y,
+                      this.rotationQuaternion.z,
+                      this.rotationQuaternion.w,
+                  ]
                 : undefined,
             scale: [this.scaling.x, this.scaling.y, this.scaling.z],
             visible: this.isEnabled(),