Add QuarksUtil class to simplify controlling of particle systems.

README.md

@@ -142,15 +142,7 @@ loader.setCrossOrigin("");
 loader.load(jsonURL, (obj) => {
     // the API uses manuel loading because users may need to 
     // store the VFX somewhere to reuse it later.
-    obj.traverse((child) => {
-        if (child.type === "ParticleEmitter") {
-            // only if want to display the VFX
-            batchRenderer.addSystem(child.system);
-        }
-    });
-    if (obj.type === "ParticleEmitter") {
-        batchRenderer.addSystem(obj.system);
-    }
+    QuarksUtil.addToBatchRenderer(obj, batchRenderer);
     scene.add(obj);
 }, () => {
 }, () => {

packages/three.quarks/examples/explosionDemo.js

@@ -1,6 +1,7 @@
 import {
     BatchedParticleRenderer,
     QuarksLoader,
+    QuarksUtil,
 } from 'three.quarks';
 import {Demo} from './demo.js';
 
@@ -14,14 +15,7 @@ export class ExplosionDemo extends Demo {
         this.scene.add(this.batchRenderer);
 
         new QuarksLoader().load('ps.json', (obj) => {
-            obj.traverse((child) => {
-                if (child.type === 'ParticleEmitter') {
-                    this.batchRenderer.addSystem(child.system);
-                }
-            });
-            if (obj.type === 'ParticleEmitter') {
-                this.batchRenderer.addSystem(obj.system);
-            }
+            QuarksUtil.addToBatchRenderer(obj, this.batchRenderer);
             this.scene.add(obj);
             this.groups.push(obj);
         });

packages/three.quarks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three.quarks",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "description": "A General-Purpose Particle System for three.js",
   "type": "module",
   "types": "./dist/types/index.d.ts",

packages/three.quarks/src/QuarksUtil.ts

@@ -0,0 +1,85 @@
+import {Object3D} from 'three';
+import {ParticleEmitter} from './ParticleEmitter';
+import {BatchedRenderer} from './BatchedRenderer';
+
+
+export class QuarksUtil {
+    /**
+     * Run a function on all particle emitters in the object and the object's children.
+     * @param obj
+     * @param func
+     */
+    static runOnAllParticleEmitters(obj: Object3D, func: (ps: ParticleEmitter) => void) {
+        obj.traverse((child) => {
+            if (child.type === 'ParticleEmitter') {
+                func(child as ParticleEmitter);
+            }
+        });
+        if (obj.type === 'ParticleEmitter') {
+            func(obj as ParticleEmitter);
+        }
+    }
+
+    /**
+     * Add all particle systems in the object and the object's children to the batch renderer.
+     * @param obj
+     * @param batchRenderer
+     */
+    static addToBatchRenderer(obj: Object3D, batchRenderer: BatchedRenderer) {
+        QuarksUtil.runOnAllParticleEmitters(obj, (ps) => {
+            batchRenderer.addSystem(ps.system);
+        });
+    }
+
+    /**
+     * Start playing all particle systems in the object and the object's children.
+     * @param obj
+     */
+    static play(obj: Object3D) {
+        QuarksUtil.runOnAllParticleEmitters(obj, (ps) => {
+            ps.system.play();
+        });
+    }
+
+    /**
+     * Stop all particle systems in the object and the object's children.
+     * this call will clear all existing particles.
+     * @param obj
+     */
+    static stop(obj: Object3D) {
+        QuarksUtil.runOnAllParticleEmitters(obj, (ps) => {
+            ps.system.stop();
+        });
+    }
+
+    /**
+     * Stop emit new particles from all particle systems and
+     * keep simulating the existing particles in the object and the object's children.
+     * @param obj
+     */
+    static endEmit(obj: Object3D) {
+        QuarksUtil.runOnAllParticleEmitters(obj, (ps) => {
+            ps.system.endEmit();
+        });
+    }
+
+    /**
+     * Restart all particle systems in the object and the object's children.
+     * @param obj
+     */
+    static restart(obj: Object3D) {
+        QuarksUtil.runOnAllParticleEmitters(obj, (ps) => {
+            ps.system.restart();
+        });
+    }
+
+    /**
+     * Pause the simulation of all particle systems in the object and the object's children.
+     * @param obj
+     */
+    static pause(obj: Object3D) {
+        QuarksUtil.runOnAllParticleEmitters(obj, (ps) => {
+            ps.system.restart();
+        });
+    }
+}

packages/three.quarks/src/index.ts

@@ -9,6 +9,7 @@ export * from './MeshSurfaceEmitter';
 export * from './BatchedRenderer';
 export * from './BatchedParticleRenderer';
 export * from './QuarksLoader';
+export * from './QuarksUtil';
 export * from './shaders/';
 export * from './materials/';
 export * from 'quarks.core';