@newkrok/three-particles 0.8.4 → 1.0.1

package/package.json

@@ -1,37 +1,37 @@
-{
-  "name": "@newkrok/three-particles",
-  "version": "0.8.4",
-  "description": "Particle system for ThreeJS",
-  "main": "src/js/three-particles.js",
-  "bin": {
-    "three-particles": "src/js/three-particles.js"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/NewKrok/three-particles.git"
-  },
-  "keywords": [
-    "threejs",
-    "particle",
-    "particles",
-    "particle engine",
-    "effects",
-    "3d",
-    "lib"
-  ],
-  "author": "Istvan Krisztian Somoracz",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/NewKrok/three-particles/issues"
-  },
-  "homepage": "https://github.com/NewKrok/three-particles#readme",
-  "dependencies": {
-    "easing-functions": "1.0.1",
-    "three": "^0.141.0",
-    "three-noise": "1.1.2",
-    "@newkrok/three-utils": "^0.3.0"
-  },
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  }
-}
+{
+  "name": "@newkrok/three-particles",
+  "version": "1.0.1",
+  "description": "Particle system for ThreeJS",
+  "main": "src/js/effects/three-particles.js",
+  "bin": {
+    "three-particles": "src/js/effects/three-particles.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NewKrok/three-particles.git"
+  },
+  "keywords": [
+    "threejs",
+    "particle",
+    "particles",
+    "particle engine",
+    "effects",
+    "3d",
+    "lib"
+  ],
+  "author": "Istvan Krisztian Somoracz",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/NewKrok/three-particles/issues"
+  },
+  "homepage": "https://github.com/NewKrok/three-particles#readme",
+  "dependencies": {
+    "easing-functions": "1.0.1",
+    "three": "^0.144.0",
+    "three-noise": "1.1.2",
+    "@newkrok/three-utils": "^1.0.0"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  }
+}

package/src/js/effects/three-particles/three-particles-enums.js

@@ -0,0 +1,23 @@
+export const SimulationSpace = {
+  LOCAL: "LOCAL",
+  WORLD: "WORLD",
+};
+
+export const Shape = {
+  SPHERE: "SPHERE",
+  CONE: "CONE",
+  BOX: "BOX",
+  CIRCLE: "CIRCLE",
+  RECTANGLE: "RECTANGLE",
+};
+
+export const EmitFrom = {
+  VOLUME: "VOLUME",
+  SHELL: "SHELL",
+  EDGE: "EDGE",
+};
+
+export const TimeMode = {
+  LIFETIME: "LIFETIME",
+  FPS: "FPS",
+};

package/src/js/effects/three-particles/three-particles-utils.js

@@ -1,6 +1,6 @@
 import * as THREE from "three";
 
-import { EmitFrom } from "../three-particles.js";
+import { EmitFrom } from "./three-particles-enums.js";
 
 export const calculateRandomPositionAndVelocityOnSphere = (
   position,

package/src/js/effects/three-particles.d.ts

@@ -0,0 +1,70 @@
+export type Point3D = {
+  x?: number;
+  y?: number;
+  z?: number;
+};
+
+export type Transform = {
+  position?: Point3D;
+  rotation?: Point3D;
+  scale?: Point3D;
+};
+
+export type MinMaxNumber = {
+  min: number;
+  max: number;
+};
+
+export type Rgb = {
+  r: number;
+  g: number;
+  b: number;
+};
+
+export type MinMaxColor = {
+  min: Rgb;
+  max: Rgb;
+};
+
+export type Emission = {
+  rateOverTime: number;
+  rateOverDistance: number;
+};
+
+export type ParticleSystemConfig = {
+  transform: Transform;
+  duration: number;
+  looping: boolean;
+  startDelay: MinMaxNumber;
+  startLifetime: MinMaxNumber;
+  startSpeed: MinMaxNumber;
+  startSize: MinMaxNumber;
+  startRotation: MinMaxNumber;
+  startColor: MinMaxColor;
+  startOpacity: MinMaxNumber;
+  gravity: number;
+  simulationSpace: "LOCAL" | "WORLD";
+  maxParticles: number;
+  emission: Emission;
+  shape: any;
+  map: any;
+  renderer: any;
+  velocityOverLifetime: any;
+  sizeOverLifetime: any;
+  opacityOverLifetime: any;
+  rotationOverLifetime: any;
+  noise: any;
+  textureSheetAnimation: any;
+};
+
+export type ParticleSystem = {
+  instance: THREE.Object3D;
+  resumeEmitter: () => void;
+  pauseEmitter: () => void;
+  dispose: () => void;
+};
+
+export function createParticleSystem(
+  config: ParticleSystemConfig,
+  externalNow?: number
+): ParticleSystem;

package/src/js/effects/three-particles.js

@@ -1,5 +1,11 @@
 import * as THREE from "three";
 
+import {
+  EmitFrom,
+  Shape,
+  SimulationSpace,
+  TimeMode,
+} from "./three-particles/three-particles-enums.js";
 import {
   calculateRandomPositionAndVelocityOnBox,
   calculateRandomPositionAndVelocityOnCircle,
@@ -11,38 +17,14 @@ import {
 import { CurveFunction } from "./three-particles/three-particles-curves.js";
 import { FBM } from "three-noise/build/three-noise.module.js";
 import { Gyroscope } from "three/examples/jsm/misc/Gyroscope.js";
+import { ObjectUtils } from "@newkrok/three-utils";
 import ParticleSystemFragmentShader from "./three-particles/shaders/particle-system-fragment-shader.glsl.js";
 import ParticleSystemVertexShader from "./three-particles/shaders/particle-system-vertex-shader.glsl.js";
 import { applyModifiers } from "./three-particles/three-particles-modifiers.js";
 import { createBezierCurveFunction } from "./three-particles/three-particles-bezier";
-import { patchObject } from "@newkrok/three-utils/src/js/newkrok/three-utils/object-utils.js";
 
 let createdParticleSystems = [];
 
-export const SimulationSpace = {
-  LOCAL: "LOCAL",
-  WORLD: "WORLD",
-};
-
-export const Shape = {
-  SPHERE: "SPHERE",
-  CONE: "CONE",
-  BOX: "BOX",
-  CIRCLE: "CIRCLE",
-  RECTANGLE: "RECTANGLE",
-};
-
-export const EmitFrom = {
-  VOLUME: "VOLUME",
-  SHELL: "SHELL",
-  EDGE: "EDGE",
-};
-
-export const TimeMode = {
-  LIFETIME: "LIFETIME",
-  FPS: "FPS",
-};
-
 export const blendingMap = {
   "THREE.NoBlending": THREE.NoBlending,
   "THREE.NormalBlending": THREE.NormalBlending,
@@ -283,6 +265,29 @@ const calculatePositionAndVelocity = (
   }
 };
 
+/**
+ * @deprecated Since version 1.0.1. Will be deleted in version 1.1.0. Use particleSystem.dispose instead.
+ */
+export const destroyParticleSystem = (particleSystem) => {
+  createdParticleSystems = createdParticleSystems.filter(
+    ({ particleSystem: savedParticleSystem, wrapper }) => {
+      if (
+        savedParticleSystem !== particleSystem &&
+        wrapper !== particleSystem &&
+        particleSystem.instance !== particleSystem
+      ) {
+        return true;
+      }
+
+      savedParticleSystem.geometry.dispose();
+      savedParticleSystem.material.dispose();
+      if (savedParticleSystem.parent)
+        savedParticleSystem.parent.remove(savedParticleSystem);
+      return false;
+    }
+  );
+};
+
 export const createParticleSystem = (
   config = DEFAULT_PARTICLE_SYSTEM_CONFIG,
   externalNow
@@ -304,9 +309,13 @@ export const createParticleSystem = (
     lifetimeValues: {},
     creationTimes: [],
     noise: null,
+    isEnabled: true,
   };
 
-  const normalizedConfig = patchObject(DEFAULT_PARTICLE_SYSTEM_CONFIG, config);
+  const normalizedConfig = ObjectUtils.patchObject(
+    DEFAULT_PARTICLE_SYSTEM_CONFIG,
+    config
+  );
 
   const bezierCompatibleProperties = [
     "sizeOverLifetime",
@@ -577,9 +586,10 @@ export const createParticleSystem = (
     generalData.startValues.startOpacity[particleIndex] =
       THREE.MathUtils.randFloat(startOpacity.min, startOpacity.max);
 
-    geometry.attributes.rotation.array[particleIndex] = THREE.MathUtils.degToRad(
-      THREE.MathUtils.randFloat(startRotation.min, startRotation.max)
-    );
+    geometry.attributes.rotation.array[particleIndex] =
+      THREE.MathUtils.degToRad(
+        THREE.MathUtils.randFloat(startRotation.min, startRotation.max)
+      );
 
     if (normalizedConfig.rotationOverLifetime.isActive)
       generalData.lifetimeValues.rotationOverLifetime[particleIndex] =
@@ -691,25 +701,16 @@ export const createParticleSystem = (
     activateParticle,
   });
 
-  return wrapper || particleSystem;
-};
-
-export const destroyParticleSystem = (particleSystem) => {
-  createdParticleSystems = createdParticleSystems.filter(
-    ({ particleSystem: savedParticleSystem, wrapper }) => {
-      if (
-        savedParticleSystem !== particleSystem &&
-        wrapper !== particleSystem
-      ) {
-        return true;
-      }
+  const resumeEmitter = () => (generalData.isEnabled = true);
+  const pauseEmitter = () => (generalData.isEnabled = false);
+  const dispose = () => destroyParticleSystem(particleSystem);
 
-      savedParticleSystem.geometry.dispose();
-      savedParticleSystem.material.dispose();
-      savedParticleSystem.parent.remove(savedParticleSystem);
-      return false;
-    }
-  );
+  return {
+    instance: wrapper || particleSystem,
+    resumeEmitter,
+    pauseEmitter,
+    dispose,
+  };
 };
 
 export const updateParticleSystems = ({ now, delta, elapsed }) => {
@@ -742,6 +743,7 @@ export const updateParticleSystems = ({ now, delta, elapsed }) => {
       worldQuaternion,
       worldEuler,
       gravityVelocity,
+      isEnabled,
     } = generalData;
 
     if (wrapper) generalData.wrapperQuaternion.copy(wrapper.parent.quaternion);
@@ -842,7 +844,7 @@ export const updateParticleSystems = ({ now, delta, elapsed }) => {
       }
     });
 
-    if (looping || lifetime < duration * 1000) {
+    if (isEnabled && (looping || lifetime < duration * 1000)) {
       const emissionDelta = now - lastEmissionTime;
       const neededParticlesByTime = Math.floor(
         emission.rateOverTime * (emissionDelta / 1000)