babylon.quarks 0.17.9 → 0.18.0

package/dist/types/index.d.ts

@@ -823,7 +823,7 @@ interface IEmitter {
     visible: boolean;
     matrixWorld: any;
 }
-type ParticleSystemEventType = "emitEnd" | "destroy" | "particleDied";
+type ParticleSystemEventType = "emitEnd" | "finished" | "destroy" | "particleDied";
 interface ParticleSystemEvent {
     type: ParticleSystemEventType;
     particleSystem: IParticleSystem;
@@ -877,6 +877,12 @@ interface IParticleSystem {
     rendererEmitterSettings: RendererEmitterSettings;
     emissionState: EmissionState;
     paused: boolean;
+    /** True after `endEmit()` — emission window closed (non-looping duration elapsed). */
+    readonly isEmitEnded: boolean;
+    /** Whether more particles can still spawn (bursts, rate, distance). */
+    hasPendingEmission(): boolean;
+    /** Non-looping system with no live particles and no pending emission. */
+    isFinished(): boolean;
     pause(): void;
     stop(): void;
     play(): void;
@@ -2382,6 +2388,16 @@ declare class BatchedRenderer extends TransformNode {
     getAdaptivePerformanceState(): AdaptivePerformanceState;
     private applyAdaptiveQuality;
     update(delta: number): void;
+    /** Rebuild instance buffers from current particle state without advancing simulation. */
+    refreshBatches(): void;
+    /** Per-batch particle vs GPU instance counts — for diagnosing stale render state. */
+    getBatchRenderStats(): Array<{
+        batchIndex: number;
+        renderMode: RenderMode;
+        instanceCount: number;
+        particleCount: number;
+        systemNames: string[];
+    }>;
     dispose(): void;
 }
 
@@ -2415,6 +2431,8 @@ declare class SpriteBatch extends VFXBatch {
     private rotationMat2_;
     private lastStretchedSpeedFactor;
     update(): void;
+    /** Pushes a zero-alpha instance so stale instancing data cannot linger on screen. */
+    private uploadClearedInstance;
     dispose(): void;
 }
 
@@ -2615,6 +2633,7 @@ declare class ParticleSystem implements IParticleSystem {
     private prewarmed;
     private emitEnded;
     private markForDestroy;
+    private finishedEventFired;
     private startDelayTimeLeft;
     private previousEmitterPos?;
     private tempEmitterPos;
@@ -2630,6 +2649,11 @@ declare class ParticleSystem implements IParticleSystem {
     _renderer?: BatchedRenderer;
     set time(time: number);
     get time(): number;
+    get isEmitEnded(): boolean;
+    /** Whether continuous or queued emission can still spawn particles before the system is done. */
+    hasPendingEmission(): boolean;
+    /** Non-looping system with no particles left and nothing left to emit. */
+    isFinished(): boolean;
     get layers(): {
         mask: number;
     };
@@ -2675,6 +2699,7 @@ declare class ParticleSystem implements IParticleSystem {
     private firstTimeUpdate;
     /** @internal */
     update(delta: number): void;
+    private notifyFinished;
     emit(delta: number, emissionState: EmissionState, emitterMatrix: Matrix4): void;
     toJSON(metaData?: BabylonMetaData | string, _options?: SerializationOptions): ParticleSystemJSONParameters;
     static fromJSON(json: ParticleSystemJSONParameters, meta: BabylonMetaData, dependencies?: {
@@ -2704,6 +2729,8 @@ declare class QuarksUtil {
     static restart(root: Node): void;
     static setAutoDestroy(root: Node, autoDestroy: boolean): void;
     static endEmit(root: Node): void;
+    /** True when every emitter under `root` is a finished non-looping system (or looping). */
+    static isEffectFinished(root: Node): boolean;
     private static traverseNode;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "babylon.quarks",
-  "version": "0.17.9",
+  "version": "0.18.0",
   "description": "A High-Performance Particle System for Babylon.js",
   "type": "module",
   "types": "./dist/types/index.d.ts",

package/src/BatchedRenderer.ts

@@ -194,9 +194,7 @@ export class BatchedRenderer extends TransformNode {
         for (const ps of this.systemToBatchIndex.keys()) {
             (ps as ParticleSystem).update(delta);
         }
-        for (let i = 0; i < this.batches.length; i++) {
-            this.batches[i].update();
-        }
+        this.refreshBatches();
         if (!adaptiveState.enabled) {
             return;
         }
@@ -217,6 +215,39 @@ export class BatchedRenderer extends TransformNode {
         }
     }
 
+    /** Rebuild instance buffers from current particle state without advancing simulation. */
+    refreshBatches(): void {
+        for (let i = 0; i < this.batches.length; i++) {
+            this.batches[i].update();
+        }
+    }
+
+    /** Per-batch particle vs GPU instance counts — for diagnosing stale render state. */
+    getBatchRenderStats(): Array<{
+        batchIndex: number;
+        renderMode: RenderMode;
+        instanceCount: number;
+        particleCount: number;
+        systemNames: string[];
+    }> {
+        return this.batches.map((batch, batchIndex) => {
+            let particleCount = 0;
+            const systemNames: string[] = [];
+            for (const system of batch.systems) {
+                const ps = system as ParticleSystem;
+                particleCount += ps.particleNum;
+                systemNames.push(ps.emitter.name);
+            }
+            return {
+                batchIndex,
+                renderMode: batch.settings.renderMode,
+                instanceCount: batch.mesh.forcedInstanceCount ?? 0,
+                particleCount,
+                systemNames,
+            };
+        });
+    }
+
     dispose(): void {
         for (const batch of this.batches) {
             batch.dispose();

package/src/ParticleSystem.ts

@@ -205,6 +205,7 @@ export class ParticleSystem implements IParticleSystem {
     private prewarmed: boolean;
     private emitEnded: boolean;
     private markForDestroy: boolean;
+    private finishedEventFired = false;
     private startDelayTimeLeft = 0;
     private previousEmitterPos?: Vector3;
     private tempEmitterPos: Vector3 = new Vector3();
@@ -227,6 +228,52 @@ export class ParticleSystem implements IParticleSystem {
         return this.emissionState.time;
     }
 
+    get isEmitEnded(): boolean {
+        return this.emitEnded;
+    }
+
+    /** Whether continuous or queued emission can still spawn particles before the system is done. */
+    hasPendingEmission(): boolean {
+        if (this.looping) {
+            return true;
+        }
+        if (this.emitEnded) {
+            return false;
+        }
+        if (this.onlyUsedByOther) {
+            return false;
+        }
+        const state = this.emissionState;
+        if (state.waitEmiting > 0) {
+            return true;
+        }
+        if (state.burstIndex < this.emissionBursts.length) {
+            return true;
+        }
+        if (state.time >= this.duration) {
+            return false;
+        }
+        const timeRatio = state.time / this.duration;
+        if (this.emissionOverTime.genValue(this.memory, timeRatio) > 0) {
+            return true;
+        }
+        return this.emissionOverDistance.genValue(this.memory, timeRatio) > 0;
+    }
+
+    /** Non-looping system with no particles left and nothing left to emit. */
+    isFinished(): boolean {
+        if (this.looping) {
+            return false;
+        }
+        if (this.particleNum > 0) {
+            return false;
+        }
+        if (this.onlyUsedByOther) {
+            return true;
+        }
+        return !this.hasPendingEmission();
+    }
+
     get layers() {
         return this.layerMaskProxy;
     }
@@ -754,6 +801,7 @@ export class ParticleSystem implements IParticleSystem {
         this.behaviors.forEach((behavior) => behavior.reset());
         this.emitEnded = false;
         this.markForDestroy = false;
+        this.finishedEventFired = false;
         this.prewarmed = false;
         this.emissionBursts.forEach((burst) => burst.count.startGen(this.memory));
         this.emissionOverDistance.startGen(this.memory);
@@ -774,8 +822,7 @@ export class ParticleSystem implements IParticleSystem {
             this.emitter.computeWorldMatrix(true);
         }
 
-        if (this.emitEnded && this.particleNum === 0) {
-            if (this.markForDestroy) this.dispose();
+        if (!this.looping && this.finishedEventFired && this.particleNum === 0) {
             return;
         }
 
@@ -879,6 +926,21 @@ export class ParticleSystem implements IParticleSystem {
             }
         }
         this.particleNum = liveParticleCount;
+        this.notifyFinished();
+    }
+
+    private notifyFinished(): void {
+        if (!this.isFinished()) {
+            return;
+        }
+        if (!this.finishedEventFired) {
+            this.finishedEventFired = true;
+            this.fire({type: 'finished', particleSystem: this});
+        }
+        if (this.autoDestroy) {
+            this.markForDestroy = true;
+            this.dispose();
+        }
     }
 
     emit(delta: number, emissionState: EmissionState, emitterMatrix: Matrix4) {

package/src/QuarksUtil.ts

@@ -56,6 +56,24 @@ export class QuarksUtil {
         });
     }
 
+    /** True when every emitter under `root` is a finished non-looping system (or looping). */
+    static isEffectFinished(root: Node): boolean {
+        let found = false;
+        let finished = true;
+        QuarksUtil.runOnAllParticleEmitters(root, (emitter) => {
+            found = true;
+            const system = emitter.system as unknown as ParticleSystem;
+            if (system.looping) {
+                finished = false;
+                return;
+            }
+            if (!system.isFinished()) {
+                finished = false;
+            }
+        });
+        return found && finished;
+    }
+
     private static traverseNode(node: Node, callback: (node: Node) => void): void {
         callback(node);
         const children = node.getChildren();

package/src/SpriteBatch.ts

@@ -383,15 +383,38 @@ export class SpriteBatch extends VFXBatch {
         // single frame (common with short lifetimes + low emission overlap) causes flicker.
         this.mesh.forcedInstanceCount = index;
 
-        if (index > 0) {
-            this.offsetVB.update(this.offsetBuffer);
-            this.sizeVB.update(this.sizeBuffer);
-            this.colorVB.update(this.colorBuffer);
-            this.uvTileVB.update(this.uvTileBuffer);
-            this.rotationVB.update(this.rotationBuffer);
-            if (isStretchedRender && this.velocityVB && this.velocityBuffer) {
-                this.velocityVB.update(this.velocityBuffer);
-            }
+        if (index === 0) {
+            this.uploadClearedInstance(isMeshRender, isStretchedRender);
+            return;
+        }
+
+        this.offsetVB.update(this.offsetBuffer);
+        this.sizeVB.update(this.sizeBuffer);
+        this.colorVB.update(this.colorBuffer);
+        this.uvTileVB.update(this.uvTileBuffer);
+        this.rotationVB.update(this.rotationBuffer);
+        if (isStretchedRender && this.velocityVB && this.velocityBuffer) {
+            this.velocityVB.update(this.velocityBuffer);
+        }
+    }
+
+    /** Pushes a zero-alpha instance so stale instancing data cannot linger on screen. */
+    private uploadClearedInstance(isMeshRender: boolean, isStretchedRender: boolean): void {
+        this.colorBuffer[3] = 0;
+        this.sizeBuffer[0] = 0;
+        this.sizeBuffer[1] = 0;
+        this.sizeBuffer[2] = 0;
+        this.colorVB.update(this.colorBuffer.subarray(0, 4));
+        this.sizeVB.update(this.sizeBuffer.subarray(0, 3));
+        this.offsetVB.update(this.offsetBuffer.subarray(0, 3));
+        this.uvTileVB.update(this.uvTileBuffer.subarray(0, 1));
+        if (isMeshRender) {
+            this.rotationVB.update(this.rotationBuffer.subarray(0, 4));
+        } else {
+            this.rotationVB.update(this.rotationBuffer.subarray(0, 1));
+        }
+        if (isStretchedRender && this.velocityVB && this.velocityBuffer) {
+            this.velocityVB.update(this.velocityBuffer.subarray(0, 4));
         }
     }