babylon.quarks 0.17.9 → 0.18.1

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;
@@ -2626,10 +2645,17 @@ declare class ParticleSystem implements IParticleSystem {
     private materialRef;
     private qualityFactor;
     private useFastTrailHistory;
+    private simulationAccumulator;
+    private destroyed;
     /** @internal **/
     _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 +2701,9 @@ declare class ParticleSystem implements IParticleSystem {
     private firstTimeUpdate;
     /** @internal */
     update(delta: number): void;
+    /** Advances emission, behaviors, motion and culling by one fixed timestep. */
+    private simulateStep;
+    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 +2733,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;
 }
 
@@ -2722,6 +2753,13 @@ declare class QuarksLoader {
     private extractInterleavedAttribute;
     private int32ArrayToFloat32;
     private parseImages;
+    /**
+     * `img.url` is already absolute for data/blob URIs and full http(s) URLs — common for
+     * "portable" exports that embed textures as base64 (see ensurePortableTextureUrl in
+     * babylon.quarks-editor). Prepending baseUrl to those turns e.g.
+     * "data:image/png;base64,AAAA" into an invalid path like "/some/dir/data:image/png;base64,AAAA".
+     */
+    private resolveImageUrl;
     private parseTextures;
     private mapWrapMode;
     private parseMaterials;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "babylon.quarks",
-  "version": "0.17.9",
+  "version": "0.18.1",
   "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

@@ -56,6 +56,8 @@ const tempQ = new Quaternion();
 const tempV = new Vector3();
 const tempV2 = new Vector3();
 const PREWARM_FPS = 60;
+const SIMULATION_STEP = 1 / PREWARM_FPS;
+const MAX_SIMULATION_STEPS_PER_FRAME = 8;
 
 const DEFAULT_POSITIONS = new Float32Array([
     -0.5, -0.5, 0,
@@ -205,6 +207,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();
@@ -216,6 +219,8 @@ export class ParticleSystem implements IParticleSystem {
     private materialRef: any = null;
     private qualityFactor = 1;
     private useFastTrailHistory = true;
+    private simulationAccumulator = 0;
+    private destroyed = false;
     /** @internal **/
     _renderer?: BatchedRenderer;
 
@@ -227,6 +232,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;
     }
@@ -737,6 +788,10 @@ export class ParticleSystem implements IParticleSystem {
     }
 
     dispose() {
+        if (this.destroyed) {
+            return;
+        }
+        this.destroyed = true;
         if (this._renderer) this._renderer.deleteSystem(this);
         this.emitter.dispose();
         this.fire({type: 'destroy', particleSystem: this});
@@ -754,6 +809,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);
@@ -761,6 +817,8 @@ export class ParticleSystem implements IParticleSystem {
         this.startDelayTimeLeft = this.startDelay.genValue(this.memory, 0);
         this.previousEmitterPos = undefined;
         this.emitterVelocity.set(0, 0, 0);
+        this.simulationAccumulator = 0;
+        this.destroyed = false;
     }
 
     private firstTimeUpdate = true;
@@ -774,8 +832,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;
         }
 
@@ -815,6 +872,19 @@ export class ParticleSystem implements IParticleSystem {
             this.startDelayTimeLeft = 0;
         }
 
+        this.simulationAccumulator += delta;
+        const stepsToRun = Math.min(
+            MAX_SIMULATION_STEPS_PER_FRAME,
+            Math.floor((this.simulationAccumulator + 1e-9) / SIMULATION_STEP)
+        );
+        for (let i = 0; i < stepsToRun; i++) {
+            this.simulateStep(SIMULATION_STEP);
+        }
+        this.simulationAccumulator -= stepsToRun * SIMULATION_STEP;
+    }
+
+    /** Advances emission, behaviors, motion and culling by one fixed timestep. */
+    private simulateStep(delta: number): void {
         if (!this.onlyUsedByOther) {
             this.emit(delta, this.emissionState, this.emitter.matrixWorld);
         }
@@ -879,6 +949,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) {
@@ -899,12 +984,6 @@ export class ParticleSystem implements IParticleSystem {
         const emissionBurstCount = emissionBursts.length;
         const qualityFactor = this.qualityFactor;
 
-        const totalSpawn = Math.floor(emissionState.waitEmiting);
-        if (totalSpawn > 0) {
-            this.spawn(totalSpawn, emissionState, emitterMatrix);
-            emissionState.waitEmiting -= totalSpawn;
-        }
-
         while (
             emissionState.burstIndex < emissionBurstCount &&
             emissionBursts[emissionState.burstIndex].time <= emissionState.time
@@ -937,6 +1016,15 @@ export class ParticleSystem implements IParticleSystem {
                 }
             }
         }
+
+        // Accrue before spawning so replacement particles can appear on the same
+        // frame an old one dies (rate * lifetime ≈ 1 would otherwise flicker).
+        const totalSpawn = Math.floor(emissionState.waitEmiting);
+        if (totalSpawn > 0) {
+            this.spawn(totalSpawn, emissionState, emitterMatrix);
+            emissionState.waitEmiting -= totalSpawn;
+        }
+
         if (emissionState.previousWorldPos === undefined) emissionState.previousWorldPos = new Vector3();
         emissionState.previousWorldPos.set(emitterMatrix.elements[12], emitterMatrix.elements[13], emitterMatrix.elements[14]);
         emissionState.time += delta;

package/src/QuarksLoader.ts

@@ -255,10 +255,23 @@ export class QuarksLoader {
     private parseImages(images: any[], baseUrl: string, _meta: LoadedMeta): void {
         (this as any)._images = {};
         for (const img of images) {
-            (this as any)._images[img.uuid] = img.url ? baseUrl + img.url : null;
+            (this as any)._images[img.uuid] = img.url ? this.resolveImageUrl(baseUrl, img.url) : null;
         }
     }
 
+    /**
+     * `img.url` is already absolute for data/blob URIs and full http(s) URLs — common for
+     * "portable" exports that embed textures as base64 (see ensurePortableTextureUrl in
+     * babylon.quarks-editor). Prepending baseUrl to those turns e.g.
+     * "data:image/png;base64,AAAA" into an invalid path like "/some/dir/data:image/png;base64,AAAA".
+     */
+    private resolveImageUrl(baseUrl: string, url: string): string {
+        if (/^(data|blob):/i.test(url) || /^[a-z][a-z0-9+.-]*:\/\//i.test(url) || url.startsWith('/')) {
+            return url;
+        }
+        return baseUrl + url;
+    }
+
     private parseTextures(textures: any[], meta: LoadedMeta): void {
         const images = (this as any)._images || {};
         for (const texDef of textures) {

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));
         }
     }