@newkrok/three-particles 2.1.0 → 2.3.0

package/README.md

@@ -66,3 +66,53 @@ updateParticleSystems({now, delta, elapsed});
 # Documentation
 
 Automatically generated TypeDoc: [https://newkrok.github.io/three-particles/](https://newkrok.github.io/three-particles/)
+
+## Important Notes
+
+### Color Over Lifetime
+
+The `colorOverLifetime` feature uses a **multiplier-based approach** (similar to Unity's particle system), where each RGB channel curve acts as a multiplier applied to the particle's `startColor`.
+
+**Formula:** `finalColor = startColor * colorOverLifetime`
+
+**⚠️ Important:** To achieve full color transitions, set `startColor` to white `{ r: 1, g: 1, b: 1 }`. If any channel in `startColor` is set to 0, that channel cannot be modified by `colorOverLifetime`.
+
+**Example - Rainbow effect:**
+```javascript
+{
+  startColor: {
+    min: { r: 1, g: 1, b: 1 },  // White - allows full color range
+    max: { r: 1, g: 1, b: 1 }
+  },
+  colorOverLifetime: {
+    isActive: true,
+    r: {  // Red: full → half → off
+      type: 'BEZIER',
+      scale: 1,
+      bezierPoints: [
+        { x: 0, y: 1, percentage: 0 },
+        { x: 0.5, y: 0.5, percentage: 0.5 },
+        { x: 1, y: 0, percentage: 1 }
+      ]
+    },
+    g: {  // Green: off → full → off
+      type: 'BEZIER',
+      scale: 1,
+      bezierPoints: [
+        { x: 0, y: 0, percentage: 0 },
+        { x: 0.5, y: 1, percentage: 0.5 },
+        { x: 1, y: 0, percentage: 1 }
+      ]
+    },
+    b: {  // Blue: off → half → full
+      type: 'BEZIER',
+      scale: 1,
+      bezierPoints: [
+        { x: 0, y: 0, percentage: 0 },
+        { x: 0.5, y: 0.5, percentage: 0.5 },
+        { x: 1, y: 1, percentage: 1 }
+      ]
+    }
+  }
+}
+```

package/dist/bundle-report.json

@@ -1 +1 @@
-[{"label":"three-particles.min.js","isAsset":true,"statSize":82622,"groups":[{"label":"dist","path":"./dist","statSize":72757,"groups":[{"id":69,"label":"index.js + 14 modules (concatenated)","path":"./dist/index.js + 14 modules (concatenated)","statSize":72757,"parsedSize":0,"gzipSize":0,"concatenated":true,"groups":[{"label":"dist","path":"./dist/index.js + 14 modules (concatenated)/dist","statSize":52974,"groups":[{"id":null,"label":"index.js","path":"./dist/index.js + 14 modules (concatenated)/dist/index.js","statSize":426,"parsedSize":0,"gzipSize":0,"inaccurateSizes":true},{"label":"js/effects/three-particles","path":"./dist/index.js + 14 modules (concatenated)/dist/js/effects/three-particles","statSize":52548,"groups":[{"id":null,"label":"three-particles-bezier.js","path":"./dist/index.js + 14 modules (concatenated)/dist/js/effects/three-particles/three-particles-bezier.js","statSize":2350,"parsedSize":0,"gzipSize":0,"inaccurateSizes":true},{"id":null,"label":"three-particles-curves.js","path":"./dist/index.js + 14 modules (concatenated)/dist/js/effects/three-particles/three-particles-curves.js","statSize":2628,"parsedSize":0,"gzipSize":0,"inaccurateSizes":true},{"id":null,"label":"three-particles-modifiers.js","path":"./dist/index.js + 14 modules (concatenated)/dist/js/effects/three-particles/three-particles-modifiers.js","statSize":4748,"parsedSize":0,"gzipSize":0,"inaccurateSizes":true},{"id":null,"label":"three-particles-utils.js","path":"./dist/index.js + 14 modules (concatenated)/dist/js/effects/three-particles/three-particles-utils.js","statSize":8634,"parsedSize":0,"gzipSize":0,"inaccurateSizes":true},{"id":null,"label":"three-particles.js","path":"./dist/index.js + 14 modules (concatenated)/dist/js/effects/three-particles/three-particles.js","statSize":31198,"parsedSize":0,"gzipSize":0,"inaccurateSizes":true},{"label":"shaders","path":"./dist/index.js + 14 modules (concatenated)/dist/js/effects/three-particles/shaders","statSize":2990,"groups":[{"id":null,"label":"particle-system-fragment-shader.glsl.js","path":"./dist/index.js + 14 modules (concatenated)/dist/js/effects/three-particles/shaders/particle-system-fragment-shader.glsl.js","statSize":2039,"parsedSize":0,"gzipSize":0,"inaccurateSizes":true},{"id":null,"label":"particle-system-vertex-shader.glsl.js","path":"./dist/index.js + 14 modules (concatenated)/dist/js/effects/three-particles/shaders/particle-system-vertex-shader.glsl.js","statSize":951,"parsedSize":0,"gzipSize":0,"inaccurateSizes":true}],"parsedSize":0,"gzipSize":0,"inaccurateSizes":true}],"parsedSize":0,"gzipSize":0,"inaccurateSizes":true}],"parsedSize":0,"gzipSize":0,"inaccurateSizes":true},{"label":"node_modules","path":"./dist/index.js + 14 modules (concatenated)/node_modules","statSize":19741,"groups":[{"label":"@newkrok/three-utils/src/js/newkrok/three-utils","path":"./dist/index.js + 14 modules (concatenated)/node_modules/@newkrok/three-utils/src/js/newkrok/three-utils","statSize":5203,"groups":[{"id":null,"label":"index.js","path":"./dist/index.js + 14 modules (concatenated)/node_modules/@newkrok/three-utils/src/js/newkrok/three-utils/index.js","statSize":349,"parsedSize":0,"gzipSize":0,"inaccurateSizes":true},{"id":null,"label":"callback-utils.js","path":"./dist/index.js + 14 modules (concatenated)/node_modules/@newkrok/three-utils/src/js/newkrok/three-utils/callback-utils.js","statSize":1350,"parsedSize":0,"gzipSize":0,"inaccurateSizes":true},{"id":null,"label":"object-utils.js","path":"./dist/index.js + 14 modules (concatenated)/node_modules/@newkrok/three-utils/src/js/newkrok/three-utils/object-utils.js","statSize":2458,"parsedSize":0,"gzipSize":0,"inaccurateSizes":true},{"id":null,"label":"time-utils.js","path":"./dist/index.js + 14 modules (concatenated)/node_modules/@newkrok/three-utils/src/js/newkrok/three-utils/time-utils.js","statSize":1046,"parsedSize":0,"gzipSize":0,"inaccurateSizes":true}],"parsedSize":0,"gzipSize":0,"inaccurateSizes":true},{"label":"three/examples/jsm/misc","path":"./dist/index.js + 14 modules (concatenated)/node_modules/three/examples/jsm/misc","statSize":1617,"groups":[{"id":null,"label":"Gyroscope.js","path":"./dist/index.js + 14 modules (concatenated)/node_modules/three/examples/jsm/misc/Gyroscope.js","statSize":1617,"parsedSize":0,"gzipSize":0,"inaccurateSizes":true}],"parsedSize":0,"gzipSize":0,"inaccurateSizes":true},{"label":"three-noise/build","path":"./dist/index.js + 14 modules (concatenated)/node_modules/three-noise/build","statSize":12921,"groups":[{"id":null,"label":"three-noise.module.js","path":"./dist/index.js + 14 modules (concatenated)/node_modules/three-noise/build/three-noise.module.js","statSize":12921,"parsedSize":0,"gzipSize":0,"inaccurateSizes":true}],"parsedSize":0,"gzipSize":0,"inaccurateSizes":true}],"parsedSize":0,"gzipSize":0,"inaccurateSizes":true}]}],"parsedSize":0,"gzipSize":0},{"label":"node_modules/easing-functions","path":"./node_modules/easing-functions","statSize":9865,"groups":[{"id":300,"label":"index.js","path":"./node_modules/easing-functions/index.js","statSize":9865}],"parsedSize":0,"gzipSize":0}],"isInitialByEntrypoint":{"main":true}}]
+[{"label":"three-particles.min.js","isAsset":true,"statSize":483424,"parsedSize":123254,"gzipSize":37926,"groups":[{"label":"dist","path":"./dist","statSize":473559,"groups":[{"id":706,"label":"index.js + 26 modules (concatenated)","path":"./dist/index.js + 26 modules (concatenated)","statSize":473559,"parsedSize":123254,"gzipSize":37926,"concatenated":true,"groups":[{"label":"dist","path":"./dist/index.js + 26 modules (concatenated)/dist","statSize":70181,"groups":[{"id":null,"label":"index.js","path":"./dist/index.js + 26 modules (concatenated)/dist/index.js","statSize":426,"parsedSize":110,"gzipSize":34,"inaccurateSizes":true},{"label":"js/effects/three-particles","path":"./dist/index.js + 26 modules (concatenated)/dist/js/effects/three-particles","statSize":69755,"groups":[{"id":null,"label":"three-particles-bezier.js","path":"./dist/index.js + 26 modules (concatenated)/dist/js/effects/three-particles/three-particles-bezier.js","statSize":2350,"parsedSize":611,"gzipSize":188,"inaccurateSizes":true},{"id":null,"label":"three-particles-curves.js","path":"./dist/index.js + 26 modules (concatenated)/dist/js/effects/three-particles/three-particles-curves.js","statSize":3617,"parsedSize":941,"gzipSize":289,"inaccurateSizes":true},{"id":null,"label":"three-particles-modifiers.js","path":"./dist/index.js + 26 modules (concatenated)/dist/js/effects/three-particles/three-particles-modifiers.js","statSize":8644,"parsedSize":2249,"gzipSize":692,"inaccurateSizes":true},{"id":null,"label":"three-particles-utils.js","path":"./dist/index.js + 26 modules (concatenated)/dist/js/effects/three-particles/three-particles-utils.js","statSize":14332,"parsedSize":3730,"gzipSize":1147,"inaccurateSizes":true},{"id":null,"label":"three-particles.js","path":"./dist/index.js + 26 modules (concatenated)/dist/js/effects/three-particles/three-particles.js","statSize":37822,"parsedSize":9843,"gzipSize":3029,"inaccurateSizes":true},{"label":"shaders","path":"./dist/index.js + 26 modules (concatenated)/dist/js/effects/three-particles/shaders","statSize":2990,"groups":[{"id":null,"label":"particle-system-fragment-shader.glsl.js","path":"./dist/index.js + 26 modules (concatenated)/dist/js/effects/three-particles/shaders/particle-system-fragment-shader.glsl.js","statSize":2039,"parsedSize":530,"gzipSize":163,"inaccurateSizes":true},{"id":null,"label":"particle-system-vertex-shader.glsl.js","path":"./dist/index.js + 26 modules (concatenated)/dist/js/effects/three-particles/shaders/particle-system-vertex-shader.glsl.js","statSize":951,"parsedSize":247,"gzipSize":76,"inaccurateSizes":true}],"parsedSize":778,"gzipSize":239,"inaccurateSizes":true}],"parsedSize":18155,"gzipSize":5586,"inaccurateSizes":true}],"parsedSize":18266,"gzipSize":5620,"inaccurateSizes":true},{"label":"node_modules","path":"./dist/index.js + 26 modules (concatenated)/node_modules","statSize":403336,"groups":[{"label":"@newkrok/three-utils/dist","path":"./dist/index.js + 26 modules (concatenated)/node_modules/@newkrok/three-utils/dist","statSize":25076,"groups":[{"id":null,"label":"index.js","path":"./dist/index.js + 26 modules (concatenated)/node_modules/@newkrok/three-utils/dist/index.js","statSize":411,"parsedSize":106,"gzipSize":32,"inaccurateSizes":true},{"id":null,"label":"callback-utils.js","path":"./dist/index.js + 26 modules (concatenated)/node_modules/@newkrok/three-utils/dist/callback-utils.js","statSize":1408,"parsedSize":366,"gzipSize":112,"inaccurateSizes":true},{"id":null,"label":"object-utils.js","path":"./dist/index.js + 26 modules (concatenated)/node_modules/@newkrok/three-utils/dist/object-utils.js","statSize":2889,"parsedSize":751,"gzipSize":231,"inaccurateSizes":true},{"id":null,"label":"time-utils.js","path":"./dist/index.js + 26 modules (concatenated)/node_modules/@newkrok/three-utils/dist/time-utils.js","statSize":1037,"parsedSize":269,"gzipSize":83,"inaccurateSizes":true},{"label":"assets","path":"./dist/index.js + 26 modules (concatenated)/node_modules/@newkrok/three-utils/dist/assets","statSize":15614,"groups":[{"id":null,"label":"index.js","path":"./dist/index.js + 26 modules (concatenated)/node_modules/@newkrok/three-utils/dist/assets/index.js","statSize":44,"parsedSize":11,"gzipSize":3,"inaccurateSizes":true},{"id":null,"label":"assets.js","path":"./dist/index.js + 26 modules (concatenated)/node_modules/@newkrok/three-utils/dist/assets/assets.js","statSize":9027,"parsedSize":2349,"gzipSize":722,"inaccurateSizes":true},{"id":null,"label":"loaders.js","path":"./dist/index.js + 26 modules (concatenated)/node_modules/@newkrok/three-utils/dist/assets/loaders.js","statSize":6543,"parsedSize":1702,"gzipSize":524,"inaccurateSizes":true}],"parsedSize":4063,"gzipSize":1250,"inaccurateSizes":true},{"label":"audio","path":"./dist/index.js + 26 modules (concatenated)/node_modules/@newkrok/three-utils/dist/audio","statSize":3717,"groups":[{"id":null,"label":"index.js","path":"./dist/index.js + 26 modules (concatenated)/node_modules/@newkrok/three-utils/dist/audio/index.js","statSize":42,"parsedSize":10,"gzipSize":3,"inaccurateSizes":true},{"id":null,"label":"audio.js","path":"./dist/index.js + 26 modules (concatenated)/node_modules/@newkrok/three-utils/dist/audio/audio.js","statSize":3675,"parsedSize":956,"gzipSize":294,"inaccurateSizes":true}],"parsedSize":967,"gzipSize":297,"inaccurateSizes":true}],"parsedSize":6526,"gzipSize":2008,"inaccurateSizes":true},{"label":"three/examples/jsm","path":"./dist/index.js + 26 modules (concatenated)/node_modules/three/examples/jsm","statSize":365339,"groups":[{"label":"misc","path":"./dist/index.js + 26 modules (concatenated)/node_modules/three/examples/jsm/misc","statSize":1617,"groups":[{"id":null,"label":"Gyroscope.js","path":"./dist/index.js + 26 modules (concatenated)/node_modules/three/examples/jsm/misc/Gyroscope.js","statSize":1617,"parsedSize":420,"gzipSize":129,"inaccurateSizes":true}],"parsedSize":420,"gzipSize":129,"inaccurateSizes":true},{"label":"helpers","path":"./dist/index.js + 26 modules (concatenated)/node_modules/three/examples/jsm/helpers","statSize":4384,"groups":[{"id":null,"label":"PositionalAudioHelper.js","path":"./dist/index.js + 26 modules (concatenated)/node_modules/three/examples/jsm/helpers/PositionalAudioHelper.js","statSize":4384,"parsedSize":1141,"gzipSize":351,"inaccurateSizes":true}],"parsedSize":1141,"gzipSize":351,"inaccurateSizes":true},{"label":"loaders","path":"./dist/index.js + 26 modules (concatenated)/node_modules/three/examples/jsm/loaders","statSize":219725,"groups":[{"id":null,"label":"FBXLoader.js","path":"./dist/index.js + 26 modules (concatenated)/node_modules/three/examples/jsm/loaders/FBXLoader.js","statSize":104842,"parsedSize":27287,"gzipSize":8396,"inaccurateSizes":true},{"id":null,"label":"GLTFLoader.js","path":"./dist/index.js + 26 modules (concatenated)/node_modules/three/examples/jsm/loaders/GLTFLoader.js","statSize":114883,"parsedSize":29900,"gzipSize":9200,"inaccurateSizes":true}],"parsedSize":57188,"gzipSize":17597,"inaccurateSizes":true},{"label":"libs","path":"./dist/index.js + 26 modules (concatenated)/node_modules/three/examples/jsm/libs","statSize":89384,"groups":[{"id":null,"label":"fflate.module.js","path":"./dist/index.js + 26 modules (concatenated)/node_modules/three/examples/jsm/libs/fflate.module.js","statSize":89384,"parsedSize":23264,"gzipSize":7158,"inaccurateSizes":true}],"parsedSize":23264,"gzipSize":7158,"inaccurateSizes":true},{"label":"curves","path":"./dist/index.js + 26 modules (concatenated)/node_modules/three/examples/jsm/curves","statSize":14690,"groups":[{"id":null,"label":"NURBSCurve.js","path":"./dist/index.js + 26 modules (concatenated)/node_modules/three/examples/jsm/curves/NURBSCurve.js","statSize":3888,"parsedSize":1011,"gzipSize":311,"inaccurateSizes":true},{"id":null,"label":"NURBSUtils.js","path":"./dist/index.js + 26 modules (concatenated)/node_modules/three/examples/jsm/curves/NURBSUtils.js","statSize":10802,"parsedSize":2811,"gzipSize":865,"inaccurateSizes":true}],"parsedSize":3823,"gzipSize":1176,"inaccurateSizes":true},{"label":"utils","path":"./dist/index.js + 26 modules (concatenated)/node_modules/three/examples/jsm/utils","statSize":35539,"groups":[{"id":null,"label":"BufferGeometryUtils.js","path":"./dist/index.js + 26 modules (concatenated)/node_modules/three/examples/jsm/utils/BufferGeometryUtils.js","statSize":35539,"parsedSize":9249,"gzipSize":2846,"inaccurateSizes":true}],"parsedSize":9249,"gzipSize":2846,"inaccurateSizes":true}],"parsedSize":95087,"gzipSize":29258,"inaccurateSizes":true},{"label":"three-noise/build","path":"./dist/index.js + 26 modules (concatenated)/node_modules/three-noise/build","statSize":12921,"groups":[{"id":null,"label":"three-noise.module.js","path":"./dist/index.js + 26 modules (concatenated)/node_modules/three-noise/build/three-noise.module.js","statSize":12921,"parsedSize":3362,"gzipSize":1034,"inaccurateSizes":true}],"parsedSize":3362,"gzipSize":1034,"inaccurateSizes":true}],"parsedSize":104976,"gzipSize":32302,"inaccurateSizes":true}]}],"parsedSize":123254,"gzipSize":37926},{"label":"node_modules/easing-functions","path":"./node_modules/easing-functions","statSize":9865,"groups":[{"id":300,"label":"index.js","path":"./node_modules/easing-functions/index.js","statSize":9865}],"parsedSize":0,"gzipSize":0}],"isInitialByEntrypoint":{"main":true}}]

package/dist/js/effects/three-particles/three-particles-curves.d.ts

@@ -1,37 +1,108 @@
 import { CurveFunction } from './types.js';
+/**
+ * Predefined easing function identifiers for animating particle properties
+ * over their lifetime.
+ *
+ * These functions control the rate of change and create different animation
+ * feels. Each type has three variants:
+ * - **IN**: Starts slow, accelerates toward the end
+ * - **OUT**: Starts fast, decelerates toward the end
+ * - **IN_OUT**: Combines both, slow at start and end, fast in middle
+ *
+ * @enum {string}
+ *
+ * @see {@link https://easings.net/} - Visual reference for easing functions
+ */
 export declare const enum CurveFunctionId {
+    /** Use custom Bezier curve (not an easing function) */
     BEZIER = "BEZIER",
+    /** Linear interpolation with constant rate of change */
     LINEAR = "LINEAR",
+    /** Quadratic (t²) easing - gentle acceleration */
     QUADRATIC_IN = "QUADRATIC_IN",
+    /** Quadratic (t²) easing - gentle deceleration */
     QUADRATIC_OUT = "QUADRATIC_OUT",
+    /** Quadratic (t²) easing - gentle acceleration then deceleration */
     QUADRATIC_IN_OUT = "QUADRATIC_IN_OUT",
+    /** Cubic (t³) easing - moderate acceleration */
     CUBIC_IN = "CUBIC_IN",
+    /** Cubic (t³) easing - moderate deceleration */
     CUBIC_OUT = "CUBIC_OUT",
+    /** Cubic (t³) easing - moderate acceleration then deceleration */
     CUBIC_IN_OUT = "CUBIC_IN_OUT",
+    /** Quartic (t⁴) easing - strong acceleration */
     QUARTIC_IN = "QUARTIC_IN",
+    /** Quartic (t⁴) easing - strong deceleration */
     QUARTIC_OUT = "QUARTIC_OUT",
+    /** Quartic (t⁴) easing - strong acceleration then deceleration */
     QUARTIC_IN_OUT = "QUARTIC_IN_OUT",
+    /** Quintic (t⁵) easing - very strong acceleration */
     QUINTIC_IN = "QUINTIC_IN",
+    /** Quintic (t⁵) easing - very strong deceleration */
     QUINTIC_OUT = "QUINTIC_OUT",
+    /** Quintic (t⁵) easing - very strong acceleration then deceleration */
     QUINTIC_IN_OUT = "QUINTIC_IN_OUT",
+    /** Sinusoidal easing - smooth, natural acceleration */
     SINUSOIDAL_IN = "SINUSOIDAL_IN",
+    /** Sinusoidal easing - smooth, natural deceleration */
     SINUSOIDAL_OUT = "SINUSOIDAL_OUT",
+    /** Sinusoidal easing - smooth acceleration then deceleration */
     SINUSOIDAL_IN_OUT = "SINUSOIDAL_IN_OUT",
+    /** Exponential easing - dramatic, explosive acceleration */
     EXPONENTIAL_IN = "EXPONENTIAL_IN",
+    /** Exponential easing - dramatic, explosive deceleration */
     EXPONENTIAL_OUT = "EXPONENTIAL_OUT",
+    /** Exponential easing - dramatic acceleration then deceleration */
     EXPONENTIAL_IN_OUT = "EXPONENTIAL_IN_OUT",
+    /** Circular easing - sharp acceleration with curved trajectory */
     CIRCULAR_IN = "CIRCULAR_IN",
+    /** Circular easing - sharp deceleration with curved trajectory */
     CIRCULAR_OUT = "CIRCULAR_OUT",
+    /** Circular easing - sharp acceleration then deceleration */
     CIRCULAR_IN_OUT = "CIRCULAR_IN_OUT",
+    /** Elastic easing - oscillates back before accelerating (spring-like) */
     ELASTIC_IN = "ELASTIC_IN",
+    /** Elastic easing - overshoots then oscillates back (spring-like) */
     ELASTIC_OUT = "ELASTIC_OUT",
+    /** Elastic easing - oscillates at both ends (spring-like) */
     ELASTIC_IN_OUT = "ELASTIC_IN_OUT",
+    /** Back easing - pulls back before accelerating forward */
     BACK_IN = "BACK_IN",
+    /** Back easing - overshoots forward then pulls back */
     BACK_OUT = "BACK_OUT",
+    /** Back easing - pulls back, overshoots, then settles */
     BACK_IN_OUT = "BACK_IN_OUT",
+    /** Bounce easing - bounces at the start */
     BOUNCE_IN = "BOUNCE_IN",
+    /** Bounce easing - bounces at the end (like a ball landing) */
     BOUNCE_OUT = "BOUNCE_OUT",
+    /** Bounce easing - bounces at both start and end */
     BOUNCE_IN_OUT = "BOUNCE_IN_OUT"
 }
+/**
+ * Resolves a curve function from an identifier or returns the function itself.
+ *
+ * This utility function allows you to use either a {@link CurveFunctionId} string
+ * identifier or a custom function directly.
+ *
+ * @param curveFunctionId - Either a {@link CurveFunctionId} enum value or a
+ *                          custom {@link CurveFunction} implementation
+ * @returns The actual easing function that takes a normalized time value (0-1)
+ *          and returns the eased value
+ *
+ * @example
+ * ```typescript
+ * import { getCurveFunction, CurveFunctionId } from '@newkrok/three-particles';
+ *
+ * // Using a predefined easing function
+ * const easingFunc = getCurveFunction(CurveFunctionId.CUBIC_OUT);
+ * console.log(easingFunc(0.5)); // Returns eased value at 50% progress
+ *
+ * // Using a custom function
+ * const customEasing = (t: number) => t * t; // Quadratic
+ * const customFunc = getCurveFunction(customEasing);
+ * console.log(customFunc(0.5)); // Returns 0.25
+ * ```
+ */
 export declare const getCurveFunction: (curveFunctionId: CurveFunctionId | CurveFunction) => CurveFunction;
 //# sourceMappingURL=three-particles-curves.d.ts.map

package/dist/js/effects/three-particles/three-particles-curves.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"three-particles-curves.d.ts","sourceRoot":"","sources":["../../../../src/js/effects/three-particles/three-particles-curves.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,0BAAkB,eAAe;IAC/B,MAAM,WAAW;IACjB,MAAM,WAAW;IACjB,YAAY,iBAAiB;IAC7B,aAAa,kBAAkB;IAC/B,gBAAgB,qBAAqB;IACrC,QAAQ,aAAa;IACrB,SAAS,cAAc;IACvB,YAAY,iBAAiB;IAC7B,UAAU,eAAe;IACzB,WAAW,gBAAgB;IAC3B,cAAc,mBAAmB;IACjC,UAAU,eAAe;IACzB,WAAW,gBAAgB;IAC3B,cAAc,mBAAmB;IACjC,aAAa,kBAAkB;IAC/B,cAAc,mBAAmB;IACjC,iBAAiB,sBAAsB;IACvC,cAAc,mBAAmB;IACjC,eAAe,oBAAoB;IACnC,kBAAkB,uBAAuB;IACzC,WAAW,gBAAgB;IAC3B,YAAY,iBAAiB;IAC7B,eAAe,oBAAoB;IACnC,UAAU,eAAe;IACzB,WAAW,gBAAgB;IAC3B,cAAc,mBAAmB;IACjC,OAAO,YAAY;IACnB,QAAQ,aAAa;IACrB,WAAW,gBAAgB;IAC3B,SAAS,cAAc;IACvB,UAAU,eAAe;IACzB,aAAa,kBAAkB;CAChC;AAoCD,eAAO,MAAM,gBAAgB,GAC3B,iBAAiB,eAAe,GAAG,aAAa,KAC/C,aAGuC,CAAC"}
+{"version":3,"file":"three-particles-curves.d.ts","sourceRoot":"","sources":["../../../../src/js/effects/three-particles/three-particles-curves.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;;;;;;;;GAaG;AACH,0BAAkB,eAAe;IAC/B,uDAAuD;IACvD,MAAM,WAAW;IAEjB,wDAAwD;IACxD,MAAM,WAAW;IAEjB,kDAAkD;IAClD,YAAY,iBAAiB;IAC7B,kDAAkD;IAClD,aAAa,kBAAkB;IAC/B,oEAAoE;IACpE,gBAAgB,qBAAqB;IAErC,gDAAgD;IAChD,QAAQ,aAAa;IACrB,gDAAgD;IAChD,SAAS,cAAc;IACvB,kEAAkE;IAClE,YAAY,iBAAiB;IAE7B,gDAAgD;IAChD,UAAU,eAAe;IACzB,gDAAgD;IAChD,WAAW,gBAAgB;IAC3B,kEAAkE;IAClE,cAAc,mBAAmB;IAEjC,qDAAqD;IACrD,UAAU,eAAe;IACzB,qDAAqD;IACrD,WAAW,gBAAgB;IAC3B,uEAAuE;IACvE,cAAc,mBAAmB;IAEjC,uDAAuD;IACvD,aAAa,kBAAkB;IAC/B,uDAAuD;IACvD,cAAc,mBAAmB;IACjC,gEAAgE;IAChE,iBAAiB,sBAAsB;IAEvC,4DAA4D;IAC5D,cAAc,mBAAmB;IACjC,4DAA4D;IAC5D,eAAe,oBAAoB;IACnC,mEAAmE;IACnE,kBAAkB,uBAAuB;IAEzC,kEAAkE;IAClE,WAAW,gBAAgB;IAC3B,kEAAkE;IAClE,YAAY,iBAAiB;IAC7B,6DAA6D;IAC7D,eAAe,oBAAoB;IAEnC,yEAAyE;IACzE,UAAU,eAAe;IACzB,qEAAqE;IACrE,WAAW,gBAAgB;IAC3B,6DAA6D;IAC7D,cAAc,mBAAmB;IAEjC,2DAA2D;IAC3D,OAAO,YAAY;IACnB,uDAAuD;IACvD,QAAQ,aAAa;IACrB,yDAAyD;IACzD,WAAW,gBAAgB;IAE3B,2CAA2C;IAC3C,SAAS,cAAc;IACvB,+DAA+D;IAC/D,UAAU,eAAe;IACzB,oDAAoD;IACpD,aAAa,kBAAkB;CAChC;AAoCD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,gBAAgB,GAC3B,iBAAiB,eAAe,GAAG,aAAa,KAC/C,aAGuC,CAAC"}

package/dist/js/effects/three-particles/three-particles-curves.js

@@ -32,6 +32,31 @@ const CurveFunctionIdMap = {
     ["BOUNCE_OUT" /* CurveFunctionId.BOUNCE_OUT */]: Easing.Bounce.Out,
     ["BOUNCE_IN_OUT" /* CurveFunctionId.BOUNCE_IN_OUT */]: Easing.Bounce.InOut,
 };
+/**
+ * Resolves a curve function from an identifier or returns the function itself.
+ *
+ * This utility function allows you to use either a {@link CurveFunctionId} string
+ * identifier or a custom function directly.
+ *
+ * @param curveFunctionId - Either a {@link CurveFunctionId} enum value or a
+ *                          custom {@link CurveFunction} implementation
+ * @returns The actual easing function that takes a normalized time value (0-1)
+ *          and returns the eased value
+ *
+ * @example
+ * ```typescript
+ * import { getCurveFunction, CurveFunctionId } from '@newkrok/three-particles';
+ *
+ * // Using a predefined easing function
+ * const easingFunc = getCurveFunction(CurveFunctionId.CUBIC_OUT);
+ * console.log(easingFunc(0.5)); // Returns eased value at 50% progress
+ *
+ * // Using a custom function
+ * const customEasing = (t: number) => t * t; // Quadratic
+ * const customFunc = getCurveFunction(customEasing);
+ * console.log(customFunc(0.5)); // Returns 0.25
+ * ```
+ */
 export const getCurveFunction = (curveFunctionId) => typeof curveFunctionId === 'function'
     ? curveFunctionId
     : CurveFunctionIdMap[curveFunctionId];

package/dist/js/effects/three-particles/three-particles-enums.d.ts

@@ -1,25 +1,115 @@
+/**
+ * Defines the coordinate space in which particles are simulated.
+ *
+ * @enum {string}
+ */
 export declare const enum SimulationSpace {
+    /**
+     * Particles move relative to the emitter's local coordinate system.
+     * When the emitter moves or rotates, particles move with it.
+     * Ideal for effects attached to moving objects (e.g., engine trails, character auras).
+     */
     LOCAL = "LOCAL",
+    /**
+     * Particles move in world space and are independent of the emitter's transform.
+     * Once emitted, particles remain stationary or move according to their velocity in world coordinates.
+     * Ideal for environmental effects (e.g., smoke, explosions, ambient particles).
+     */
     WORLD = "WORLD"
 }
+/**
+ * Defines the geometric shape from which particles are emitted.
+ *
+ * @enum {string}
+ */
 export declare const enum Shape {
+    /**
+     * Emit particles from a spherical volume or shell.
+     * Configure with {@link Sphere} properties (radius, arc, radiusThickness).
+     */
     SPHERE = "SPHERE",
+    /**
+     * Emit particles from a conical volume or shell.
+     * Configure with {@link Cone} properties (angle, radius, arc, radiusThickness).
+     * Useful for directional effects like fire, smoke plumes, or spray effects.
+     */
     CONE = "CONE",
+    /**
+     * Emit particles from a box volume, shell, or edges.
+     * Configure with {@link Box} properties (scale, emitFrom).
+     * Useful for area-based effects like dust clouds or rain.
+     */
     BOX = "BOX",
+    /**
+     * Emit particles from a circular area or edge.
+     * Configure with {@link Circle} properties (radius, arc, radiusThickness).
+     * Useful for ground impacts, rings, or radial effects.
+     */
     CIRCLE = "CIRCLE",
+    /**
+     * Emit particles from a rectangular area.
+     * Configure with {@link Rectangle} properties (scale, rotation).
+     * Useful for planar effects like rain on a surface or screen effects.
+     */
     RECTANGLE = "RECTANGLE"
 }
+/**
+ * Defines where on a shape particles are emitted from.
+ * Not all shapes support all emit modes.
+ *
+ * @enum {string}
+ */
 export declare const enum EmitFrom {
+    /**
+     * Emit particles from random positions within the entire volume of the shape.
+     * Supported by: SPHERE, CONE, BOX.
+     */
     VOLUME = "VOLUME",
+    /**
+     * Emit particles from the surface/shell of the shape.
+     * Supported by: SPHERE, CONE, BOX.
+     */
     SHELL = "SHELL",
+    /**
+     * Emit particles from the edges of the shape.
+     * Supported by: BOX.
+     */
     EDGE = "EDGE"
 }
+/**
+ * Defines how texture sheet animation is timed.
+ *
+ * @enum {string}
+ */
 export declare const enum TimeMode {
+    /**
+     * Animation frames are based on the particle's lifetime percentage.
+     * The animation completes once over the particle's lifetime.
+     */
     LIFETIME = "LIFETIME",
+    /**
+     * Animation frames are based on frames per second (FPS).
+     * The animation runs at a fixed speed regardless of particle lifetime.
+     */
     FPS = "FPS"
 }
+/**
+ * Defines the type of curve function used for animating values over a particle's lifetime.
+ *
+ * @enum {string}
+ */
 export declare const enum LifeTimeCurve {
+    /**
+     * Use custom Bezier curves with control points.
+     * Provides maximum control over the animation curve shape.
+     * See {@link BezierCurve} for configuration.
+     */
     BEZIER = "BEZIER",
+    /**
+     * Use predefined easing functions (e.g., easeInQuad, easeOutCubic).
+     * Convenient for common animation patterns.
+     * See {@link EasingCurve} and {@link CurveFunctionId} for available functions.
+     */
     EASING = "EASING"
 }
 //# sourceMappingURL=three-particles-enums.d.ts.map

package/dist/js/effects/three-particles/three-particles-enums.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"three-particles-enums.d.ts","sourceRoot":"","sources":["../../../../src/js/effects/three-particles/three-particles-enums.ts"],"names":[],"mappings":"AAAA,0BAAkB,eAAe;IAC/B,KAAK,UAAU;IACf,KAAK,UAAU;CAChB;AAED,0BAAkB,KAAK;IACrB,MAAM,WAAW;IACjB,IAAI,SAAS;IACb,GAAG,QAAQ;IACX,MAAM,WAAW;IACjB,SAAS,cAAc;CACxB;AAED,0BAAkB,QAAQ;IACxB,MAAM,WAAW;IACjB,KAAK,UAAU;IACf,IAAI,SAAS;CACd;AAED,0BAAkB,QAAQ;IACxB,QAAQ,aAAa;IACrB,GAAG,QAAQ;CACZ;AAED,0BAAkB,aAAa;IAC7B,MAAM,WAAW;IACjB,MAAM,WAAW;CAClB"}
+{"version":3,"file":"three-particles-enums.d.ts","sourceRoot":"","sources":["../../../../src/js/effects/three-particles/three-particles-enums.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,0BAAkB,eAAe;IAC/B;;;;OAIG;IACH,KAAK,UAAU;IAEf;;;;OAIG;IACH,KAAK,UAAU;CAChB;AAED;;;;GAIG;AACH,0BAAkB,KAAK;IACrB;;;OAGG;IACH,MAAM,WAAW;IAEjB;;;;OAIG;IACH,IAAI,SAAS;IAEb;;;;OAIG;IACH,GAAG,QAAQ;IAEX;;;;OAIG;IACH,MAAM,WAAW;IAEjB;;;;OAIG;IACH,SAAS,cAAc;CACxB;AAED;;;;;GAKG;AACH,0BAAkB,QAAQ;IACxB;;;OAGG;IACH,MAAM,WAAW;IAEjB;;;OAGG;IACH,KAAK,UAAU;IAEf;;;OAGG;IACH,IAAI,SAAS;CACd;AAED;;;;GAIG;AACH,0BAAkB,QAAQ;IACxB;;;OAGG;IACH,QAAQ,aAAa;IAErB;;;OAGG;IACH,GAAG,QAAQ;CACZ;AAED;;;;GAIG;AACH,0BAAkB,aAAa;IAC7B;;;;OAIG;IACH,MAAM,WAAW;IAEjB;;;;OAIG;IACH,MAAM,WAAW;CAClB"}

package/dist/js/effects/three-particles/three-particles-modifiers.d.ts

@@ -1,5 +1,67 @@
 import * as THREE from 'three';
 import { GeneralData, NormalizedParticleSystemConfig } from './types.js';
+/**
+ * Applies all active modifiers to a single particle during the update cycle.
+ *
+ * This function handles the animation and modification of particle properties over its lifetime,
+ * including velocity (linear and orbital), size, opacity, color, rotation, and noise-based effects.
+ * It is called once per particle per frame by the {@link updateParticleSystems} function.
+ *
+ * @param params - Configuration object containing:
+ * @param params.delta - Time elapsed since the last frame in seconds. Used for velocity and rotation calculations.
+ * @param params.generalData - Internal particle system state and cached values.
+ * @param params.normalizedConfig - The normalized particle system configuration with all modifiers.
+ * @param params.attributes - Three.js buffer attributes for position, size, rotation, and color.
+ * @param params.particleLifetimePercentage - Normalized lifetime of the particle (0.0 to 1.0).
+ *   - 0.0 = particle just born
+ *   - 1.0 = particle at end of life
+ * @param params.particleIndex - Index of the particle in the buffer arrays.
+ *
+ * @remarks
+ * The function modifies the following particle properties based on configuration:
+ *
+ * - **Linear Velocity**: Moves particles in a straight line (velocityOverLifetime.linear)
+ * - **Orbital Velocity**: Rotates particles around their emission point (velocityOverLifetime.orbital)
+ * - **Size Over Lifetime**: Scales particle size based on lifetime curve (sizeOverLifetime)
+ * - **Opacity Over Lifetime**: Fades particles in/out based on lifetime curve (opacityOverLifetime)
+ * - **Color Over Lifetime**: Animates RGB channels independently based on lifetime curves (colorOverLifetime)
+ * - **Rotation Over Lifetime**: Rotates particles around their center (rotationOverLifetime)
+ * - **Noise**: Adds organic, turbulent motion to position, rotation, and size (noise)
+ *
+ * Each modifier only runs if it's active in the configuration, optimizing performance for simple effects.
+ *
+ * @example
+ * ```typescript
+ * // This function is called internally by updateParticleSystems
+ * // You typically don't need to call it directly
+ *
+ * // However, understanding its behavior helps configure particle systems:
+ * const config = {
+ *   sizeOverLifetime: {
+ *     isActive: true,
+ *     lifetimeCurve: {
+ *       type: 'BEZIER',
+ *       bezierPoints: [
+ *         { x: 0, y: 0, percentage: 0 },    // Start at 0% size
+ *         { x: 0.5, y: 1, percentage: 0.5 }, // Grow to 100% at midlife
+ *         { x: 1, y: 0, percentage: 1 }      // Shrink to 0% at end
+ *       ]
+ *     }
+ *   },
+ *   opacityOverLifetime: {
+ *     isActive: true,
+ *     lifetimeCurve: {
+ *       type: 'EASING',
+ *       curveFunction: 'easeOutQuad'
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * @see {@link updateParticleSystems} - Calls this function for each active particle
+ * @see {@link VelocityOverLifetime} - Configuration for velocity modifiers
+ * @see {@link NoiseConfig} - Configuration for noise-based effects
+ */
 export declare const applyModifiers: ({ delta, generalData, normalizedConfig, attributes, particleLifetimePercentage, particleIndex, }: {
     delta: number;
     generalData: GeneralData;

package/dist/js/effects/three-particles/three-particles-modifiers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"three-particles-modifiers.d.ts","sourceRoot":"","sources":["../../../../src/js/effects/three-particles/three-particles-modifiers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,OAAO,EAAE,WAAW,EAAE,8BAA8B,EAAE,MAAM,YAAY,CAAC;AAKzE,eAAO,MAAM,cAAc,GAAI,kGAO5B;IACD,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,WAAW,CAAC;IACzB,gBAAgB,EAAE,8BAA8B,CAAC;IACjD,UAAU,EAAE,KAAK,CAAC,sBAAsB,CAAC;IACzC,0BAA0B,EAAE,MAAM,CAAC;IACnC,aAAa,EAAE,MAAM,CAAC;CACvB,SA8IA,CAAC"}
+{"version":3,"file":"three-particles-modifiers.d.ts","sourceRoot":"","sources":["../../../../src/js/effects/three-particles/three-particles-modifiers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,OAAO,EAAE,WAAW,EAAE,8BAA8B,EAAE,MAAM,YAAY,CAAC;AAKzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,eAAO,MAAM,cAAc,GAAI,kGAO5B;IACD,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,WAAW,CAAC;IACzB,gBAAgB,EAAE,8BAA8B,CAAC;IACjD,UAAU,EAAE,KAAK,CAAC,sBAAsB,CAAC;IACzC,0BAA0B,EAAE,MAAM,CAAC;IACnC,aAAa,EAAE,MAAM,CAAC;CACvB,SA2KA,CAAC"}

package/dist/js/effects/three-particles/three-particles-modifiers.js

@@ -2,6 +2,68 @@ import * as THREE from 'three';
 import { calculateValue } from './three-particles-utils.js';
 const noiseInput = new THREE.Vector3(0, 0, 0);
 const orbitalEuler = new THREE.Euler();
+/**
+ * Applies all active modifiers to a single particle during the update cycle.
+ *
+ * This function handles the animation and modification of particle properties over its lifetime,
+ * including velocity (linear and orbital), size, opacity, color, rotation, and noise-based effects.
+ * It is called once per particle per frame by the {@link updateParticleSystems} function.
+ *
+ * @param params - Configuration object containing:
+ * @param params.delta - Time elapsed since the last frame in seconds. Used for velocity and rotation calculations.
+ * @param params.generalData - Internal particle system state and cached values.
+ * @param params.normalizedConfig - The normalized particle system configuration with all modifiers.
+ * @param params.attributes - Three.js buffer attributes for position, size, rotation, and color.
+ * @param params.particleLifetimePercentage - Normalized lifetime of the particle (0.0 to 1.0).
+ *   - 0.0 = particle just born
+ *   - 1.0 = particle at end of life
+ * @param params.particleIndex - Index of the particle in the buffer arrays.
+ *
+ * @remarks
+ * The function modifies the following particle properties based on configuration:
+ *
+ * - **Linear Velocity**: Moves particles in a straight line (velocityOverLifetime.linear)
+ * - **Orbital Velocity**: Rotates particles around their emission point (velocityOverLifetime.orbital)
+ * - **Size Over Lifetime**: Scales particle size based on lifetime curve (sizeOverLifetime)
+ * - **Opacity Over Lifetime**: Fades particles in/out based on lifetime curve (opacityOverLifetime)
+ * - **Color Over Lifetime**: Animates RGB channels independently based on lifetime curves (colorOverLifetime)
+ * - **Rotation Over Lifetime**: Rotates particles around their center (rotationOverLifetime)
+ * - **Noise**: Adds organic, turbulent motion to position, rotation, and size (noise)
+ *
+ * Each modifier only runs if it's active in the configuration, optimizing performance for simple effects.
+ *
+ * @example
+ * ```typescript
+ * // This function is called internally by updateParticleSystems
+ * // You typically don't need to call it directly
+ *
+ * // However, understanding its behavior helps configure particle systems:
+ * const config = {
+ *   sizeOverLifetime: {
+ *     isActive: true,
+ *     lifetimeCurve: {
+ *       type: 'BEZIER',
+ *       bezierPoints: [
+ *         { x: 0, y: 0, percentage: 0 },    // Start at 0% size
+ *         { x: 0.5, y: 1, percentage: 0.5 }, // Grow to 100% at midlife
+ *         { x: 1, y: 0, percentage: 1 }      // Shrink to 0% at end
+ *       ]
+ *     }
+ *   },
+ *   opacityOverLifetime: {
+ *     isActive: true,
+ *     lifetimeCurve: {
+ *       type: 'EASING',
+ *       curveFunction: 'easeOutQuad'
+ *     }
+ *   }
+ * };
+ * ```
+ *
+ * @see {@link updateParticleSystems} - Calls this function for each active particle
+ * @see {@link VelocityOverLifetime} - Configuration for velocity modifiers
+ * @see {@link NoiseConfig} - Configuration for noise-based effects
+ */
 export const applyModifiers = ({ delta, generalData, normalizedConfig, attributes, particleLifetimePercentage, particleIndex, }) => {
     const { particleSystemId, startValues, lifetimeValues, linearVelocityData, orbitalVelocityData, noise, } = generalData;
     const positionIndex = particleIndex * 3;
@@ -55,6 +117,20 @@ export const applyModifiers = ({ delta, generalData, normalizedConfig, attribute
             startValues.startOpacity[particleIndex] * multiplier;
         attributes.colorA.needsUpdate = true;
     }
+    if (normalizedConfig.colorOverLifetime.isActive) {
+        const rMultiplier = calculateValue(particleSystemId, normalizedConfig.colorOverLifetime.r, particleLifetimePercentage);
+        const gMultiplier = calculateValue(particleSystemId, normalizedConfig.colorOverLifetime.g, particleLifetimePercentage);
+        const bMultiplier = calculateValue(particleSystemId, normalizedConfig.colorOverLifetime.b, particleLifetimePercentage);
+        attributes.colorR.array[particleIndex] =
+            startValues.startColorR[particleIndex] * rMultiplier;
+        attributes.colorG.array[particleIndex] =
+            startValues.startColorG[particleIndex] * gMultiplier;
+        attributes.colorB.array[particleIndex] =
+            startValues.startColorB[particleIndex] * bMultiplier;
+        attributes.colorR.needsUpdate = true;
+        attributes.colorG.needsUpdate = true;
+        attributes.colorB.needsUpdate = true;
+    }
     if (lifetimeValues.rotationOverLifetime) {
         attributes.rotation.array[particleIndex] +=
             lifetimeValues.rotationOverLifetime[particleIndex] * delta * 0.02;