@newkrok/three-particles 2.2.0 → 2.3.0

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

@@ -1,26 +1,149 @@
 import * as THREE from 'three';
 import { EmitFrom } from './three-particles-enums.js';
 import { Constant, LifetimeCurve, Point3D, RandomBetweenTwoConstants } from './types.js';
+/**
+ * Calculates random position and velocity for particles emitted from a sphere.
+ *
+ * Supports emission from the entire volume or just the shell of the sphere.
+ * Uses spherical coordinates for uniform distribution across the surface.
+ *
+ * @param position - Output vector for the particle's starting position
+ * @param quaternion - Rotation to apply to the emission shape
+ * @param velocity - Output vector for the particle's initial velocity
+ * @param speed - Speed multiplier for the velocity
+ * @param params - Sphere configuration
+ * @param params.radius - Radius of the sphere
+ * @param params.radiusThickness - Controls emission from volume (1.0) vs shell (0.0)
+ * @param params.arc - Arc angle in degrees (360 = full sphere, 180 = hemisphere)
+ *
+ * @remarks
+ * - `radiusThickness = 1.0`: Emit from entire volume
+ * - `radiusThickness = 0.0`: Emit only from surface shell
+ * - Particles are emitted radially outward from the center
+ *
+ * @see {@link Sphere} - Configuration type for sphere shape
+ */
 export declare const calculateRandomPositionAndVelocityOnSphere: (position: THREE.Vector3, quaternion: THREE.Quaternion, velocity: THREE.Vector3, speed: number, { radius, radiusThickness, arc, }: {
     radius: number;
     radiusThickness: number;
     arc: number;
 }) => void;
+/**
+ * Calculates random position and velocity for particles emitted from a cone.
+ *
+ * Useful for directional particle effects like fire, smoke plumes, fountains,
+ * or spray effects. The cone emits particles in a spreading pattern.
+ *
+ * @param position - Output vector for the particle's starting position
+ * @param quaternion - Rotation to apply to the emission shape
+ * @param velocity - Output vector for the particle's initial velocity
+ * @param speed - Speed multiplier for the velocity
+ * @param params - Cone configuration
+ * @param params.radius - Base radius of the cone
+ * @param params.radiusThickness - Controls emission from volume (1.0) vs shell (0.0)
+ * @param params.arc - Arc angle in degrees (360 = full cone, 180 = half cone)
+ * @param params.angle - Cone opening angle in degrees (default: 90)
+ *                       Smaller values create tighter cones
+ *
+ * @remarks
+ * - The cone emits from its base (circular area) outward
+ * - Particles travel in a conical spread pattern
+ * - `angle = 0`: Straight line (no spread)
+ * - `angle = 90`: Wide cone
+ * - Common for fire (10-30°), smoke (30-60°), explosions (60-90°)
+ *
+ * @see {@link Cone} - Configuration type for cone shape
+ */
 export declare const calculateRandomPositionAndVelocityOnCone: (position: THREE.Vector3, quaternion: THREE.Quaternion, velocity: THREE.Vector3, speed: number, { radius, radiusThickness, arc, angle, }: {
     radius: number;
     radiusThickness: number;
     arc: number;
     angle?: number;
 }) => void;
+/**
+ * Calculates random position and velocity for particles emitted from a box.
+ *
+ * Supports three emission modes: volume, shell (surface), and edges.
+ * Useful for area-based effects like dust clouds, rain, or geometric patterns.
+ *
+ * @param position - Output vector for the particle's starting position
+ * @param quaternion - Rotation to apply to the emission shape
+ * @param velocity - Output vector for the particle's initial velocity
+ * @param speed - Speed multiplier for the velocity
+ * @param params - Box configuration
+ * @param params.scale - Size of the box on each axis (width, height, depth)
+ * @param params.emitFrom - Emission mode:
+ *   - `VOLUME`: Random positions throughout the entire box volume
+ *   - `SHELL`: Random positions on the 6 faces (surface)
+ *   - `EDGE`: Random positions along the 12 edges
+ *
+ * @remarks
+ * - All particles emit with velocity along the +Z axis (forward)
+ * - Box is centered at the origin before rotation
+ * - VOLUME mode: Best for rain, snow, or volumetric clouds
+ * - SHELL mode: Best for hollow effects or surface particles
+ * - EDGE mode: Best for wireframe effects or particle outlines
+ *
+ * @see {@link Box} - Configuration type for box shape
+ * @see {@link EmitFrom} - Emission mode enum
+ */
 export declare const calculateRandomPositionAndVelocityOnBox: (position: THREE.Vector3, quaternion: THREE.Quaternion, velocity: THREE.Vector3, speed: number, { scale, emitFrom }: {
     scale: Point3D;
     emitFrom: EmitFrom;
 }) => void;
+/**
+ * Calculates random position and velocity for particles emitted from a circle.
+ *
+ * Emits particles from a circular area or ring. Useful for ground impacts,
+ * radial effects, magic circles, or any circular planar emission.
+ *
+ * @param position - Output vector for the particle's starting position
+ * @param quaternion - Rotation to apply to the emission shape
+ * @param velocity - Output vector for the particle's initial velocity
+ * @param speed - Speed multiplier for the velocity
+ * @param params - Circle configuration
+ * @param params.radius - Radius of the circle
+ * @param params.radiusThickness - Controls emission from area (1.0) vs edge (0.0)
+ * @param params.arc - Arc angle in degrees (360 = full circle, 180 = semicircle)
+ *
+ * @remarks
+ * - Circle lies in the XY plane by default (Z = 0)
+ * - Particles emit along the +Z axis (perpendicular to circle)
+ * - `radiusThickness = 1.0`: Filled circle (disc)
+ * - `radiusThickness = 0.0`: Ring (circle edge only)
+ * - Good for ground impact effects, teleport circles, or radial bursts
+ *
+ * @see {@link Circle} - Configuration type for circle shape
+ */
 export declare const calculateRandomPositionAndVelocityOnCircle: (position: THREE.Vector3, quaternion: THREE.Quaternion, velocity: THREE.Vector3, speed: number, { radius, radiusThickness, arc, }: {
     radius: number;
     radiusThickness: number;
     arc: number;
 }) => void;
+/**
+ * Calculates random position and velocity for particles emitted from a rectangle.
+ *
+ * Emits particles from a rectangular planar area. Useful for rain on a surface,
+ * screen-space effects, or any planar emission pattern.
+ *
+ * @param position - Output vector for the particle's starting position
+ * @param quaternion - Rotation to apply to the emission shape
+ * @param velocity - Output vector for the particle's initial velocity
+ * @param speed - Speed multiplier for the velocity
+ * @param params - Rectangle configuration
+ * @param params.rotation - Local rotation of the rectangle (degrees) before
+ *                          applying quaternion
+ * @param params.scale - Size of the rectangle (width and height)
+ *
+ * @remarks
+ * - Rectangle lies in the XY plane by default
+ * - Particles emit along the +Z axis (perpendicular to rectangle)
+ * - The rotation parameter allows tilting the rectangle before the main
+ *   quaternion rotation is applied
+ * - Good for rain effects, screen particles, or planar area emissions
+ *
+ * @see {@link Rectangle} - Configuration type for rectangle shape
+ */
 export declare const calculateRandomPositionAndVelocityOnRectangle: (position: THREE.Vector3, quaternion: THREE.Quaternion, velocity: THREE.Vector3, speed: number, { rotation, scale }: {
     rotation: Point3D;
     scale: Point3D;

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

@@ -1 +1 @@
-{"version":3,"file":"three-particles-utils.d.ts","sourceRoot":"","sources":["../../../../src/js/effects/three-particles/three-particles-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,OAAO,EAAE,QAAQ,EAAiB,MAAM,4BAA4B,CAAC;AACrE,OAAO,EACL,QAAQ,EACR,aAAa,EACb,OAAO,EACP,yBAAyB,EAC1B,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,0CAA0C,GACrD,UAAU,KAAK,CAAC,OAAO,EACvB,YAAY,KAAK,CAAC,UAAU,EAC5B,UAAU,KAAK,CAAC,OAAO,EACvB,OAAO,MAAM,EACb,mCAIG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,SAiC5D,CAAC;AAEF,eAAO,MAAM,wCAAwC,GACnD,UAAU,KAAK,CAAC,OAAO,EACvB,YAAY,KAAK,CAAC,UAAU,EAC5B,UAAU,KAAK,CAAC,OAAO,EACvB,OAAO,MAAM,EACb,0CAKG;IACD,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,SAgCF,CAAC;AAEF,eAAO,MAAM,uCAAuC,GAClD,UAAU,KAAK,CAAC,OAAO,EACvB,YAAY,KAAK,CAAC,UAAU,EAC5B,UAAU,KAAK,CAAC,OAAO,EACvB,OAAO,MAAM,EACb,qBAAqB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,SA0C5D,CAAC;AAEF,eAAO,MAAM,0CAA0C,GACrD,UAAU,KAAK,CAAC,OAAO,EACvB,YAAY,KAAK,CAAC,UAAU,EAC5B,UAAU,KAAK,CAAC,OAAO,EACvB,OAAO,MAAM,EACb,mCAIG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,SA2B5D,CAAC;AAEF,eAAO,MAAM,6CAA6C,GACxD,UAAU,KAAK,CAAC,OAAO,EACvB,YAAY,KAAK,CAAC,UAAU,EAC5B,UAAU,KAAK,CAAC,OAAO,EACvB,OAAO,MAAM,EACb,qBAAqB;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,SAiB3D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,4BAA4B,QAAO,KAAK,CAAC,aAAa,GAAG,IA8BrE,CAAC;AAEF,eAAO,MAAM,eAAe,GAC1B,OAAO,QAAQ,GAAG,yBAAyB,GAAG,aAAa,KAC1D,KAAK,IAAI,aAEX,CAAC;AAEF,eAAO,MAAM,0BAA0B,GACrC,kBAAkB,MAAM,EACxB,eAAe,aAAa,uCAc7B,CAAC;AAEF,eAAO,MAAM,cAAc,GACzB,kBAAkB,MAAM,EACxB,OAAO,QAAQ,GAAG,yBAAyB,GAAG,aAAa,EAC3D,OAAM,MAAU,KACf,MAiBF,CAAC"}
+{"version":3,"file":"three-particles-utils.d.ts","sourceRoot":"","sources":["../../../../src/js/effects/three-particles/three-particles-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,OAAO,EAAE,QAAQ,EAAiB,MAAM,4BAA4B,CAAC;AACrE,OAAO,EACL,QAAQ,EACR,aAAa,EACb,OAAO,EACP,yBAAyB,EAC1B,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,0CAA0C,GACrD,UAAU,KAAK,CAAC,OAAO,EACvB,YAAY,KAAK,CAAC,UAAU,EAC5B,UAAU,KAAK,CAAC,OAAO,EACvB,OAAO,MAAM,EACb,mCAIG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,SAiC5D,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,wCAAwC,GACnD,UAAU,KAAK,CAAC,OAAO,EACvB,YAAY,KAAK,CAAC,UAAU,EAC5B,UAAU,KAAK,CAAC,OAAO,EACvB,OAAO,MAAM,EACb,0CAKG;IACD,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,SAgCF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,uCAAuC,GAClD,UAAU,KAAK,CAAC,OAAO,EACvB,YAAY,KAAK,CAAC,UAAU,EAC5B,UAAU,KAAK,CAAC,OAAO,EACvB,OAAO,MAAM,EACb,qBAAqB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,SA0C5D,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,0CAA0C,GACrD,UAAU,KAAK,CAAC,OAAO,EACvB,YAAY,KAAK,CAAC,UAAU,EAC5B,UAAU,KAAK,CAAC,OAAO,EACvB,OAAO,MAAM,EACb,mCAIG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,SA2B5D,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,6CAA6C,GACxD,UAAU,KAAK,CAAC,OAAO,EACvB,YAAY,KAAK,CAAC,UAAU,EAC5B,UAAU,KAAK,CAAC,OAAO,EACvB,OAAO,MAAM,EACb,qBAAqB;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,SAiB3D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,4BAA4B,QAAO,KAAK,CAAC,aAAa,GAAG,IA8BrE,CAAC;AAEF,eAAO,MAAM,eAAe,GAC1B,OAAO,QAAQ,GAAG,yBAAyB,GAAG,aAAa,KAC1D,KAAK,IAAI,aAEX,CAAC;AAEF,eAAO,MAAM,0BAA0B,GACrC,kBAAkB,MAAM,EACxB,eAAe,aAAa,uCAc7B,CAAC;AAEF,eAAO,MAAM,cAAc,GACzB,kBAAkB,MAAM,EACxB,OAAO,QAAQ,GAAG,yBAAyB,GAAG,aAAa,EAC3D,OAAM,MAAU,KACf,MAiBF,CAAC"}

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

@@ -1,5 +1,27 @@
 import * as THREE from 'three';
 import { createBezierCurveFunction } from './three-particles-bezier.js';
+/**
+ * Calculates random position and velocity for particles emitted from a sphere.
+ *
+ * Supports emission from the entire volume or just the shell of the sphere.
+ * Uses spherical coordinates for uniform distribution across the surface.
+ *
+ * @param position - Output vector for the particle's starting position
+ * @param quaternion - Rotation to apply to the emission shape
+ * @param velocity - Output vector for the particle's initial velocity
+ * @param speed - Speed multiplier for the velocity
+ * @param params - Sphere configuration
+ * @param params.radius - Radius of the sphere
+ * @param params.radiusThickness - Controls emission from volume (1.0) vs shell (0.0)
+ * @param params.arc - Arc angle in degrees (360 = full sphere, 180 = hemisphere)
+ *
+ * @remarks
+ * - `radiusThickness = 1.0`: Emit from entire volume
+ * - `radiusThickness = 0.0`: Emit only from surface shell
+ * - Particles are emitted radially outward from the center
+ *
+ * @see {@link Sphere} - Configuration type for sphere shape
+ */
 export const calculateRandomPositionAndVelocityOnSphere = (position, quaternion, velocity, speed, { radius, radiusThickness, arc, }) => {
     const u = Math.random() * (arc / 360);
     const v = Math.random();
@@ -25,6 +47,32 @@ export const calculateRandomPositionAndVelocityOnSphere = (position, quaternion,
     velocity.set(position.x * speedMultiplierByPosition * speed, position.y * speedMultiplierByPosition * speed, position.z * speedMultiplierByPosition * speed);
     velocity.applyQuaternion(quaternion);
 };
+/**
+ * Calculates random position and velocity for particles emitted from a cone.
+ *
+ * Useful for directional particle effects like fire, smoke plumes, fountains,
+ * or spray effects. The cone emits particles in a spreading pattern.
+ *
+ * @param position - Output vector for the particle's starting position
+ * @param quaternion - Rotation to apply to the emission shape
+ * @param velocity - Output vector for the particle's initial velocity
+ * @param speed - Speed multiplier for the velocity
+ * @param params - Cone configuration
+ * @param params.radius - Base radius of the cone
+ * @param params.radiusThickness - Controls emission from volume (1.0) vs shell (0.0)
+ * @param params.arc - Arc angle in degrees (360 = full cone, 180 = half cone)
+ * @param params.angle - Cone opening angle in degrees (default: 90)
+ *                       Smaller values create tighter cones
+ *
+ * @remarks
+ * - The cone emits from its base (circular area) outward
+ * - Particles travel in a conical spread pattern
+ * - `angle = 0`: Straight line (no spread)
+ * - `angle = 90`: Wide cone
+ * - Common for fire (10-30°), smoke (30-60°), explosions (60-90°)
+ *
+ * @see {@link Cone} - Configuration type for cone shape
+ */
 export const calculateRandomPositionAndVelocityOnCone = (position, quaternion, velocity, speed, { radius, radiusThickness, arc, angle = 90, }) => {
     const theta = 2 * Math.PI * Math.random() * (arc / 360);
     const randomizedDistanceRatio = Math.random();
@@ -46,6 +94,33 @@ export const calculateRandomPositionAndVelocityOnCone = (position, quaternion, v
     velocity.set(position.x * sinNormalizedAngle * speedMultiplierByPosition * speed, position.y * sinNormalizedAngle * speedMultiplierByPosition * speed, Math.cos(normalizedAngle) * speed);
     velocity.applyQuaternion(quaternion);
 };
+/**
+ * Calculates random position and velocity for particles emitted from a box.
+ *
+ * Supports three emission modes: volume, shell (surface), and edges.
+ * Useful for area-based effects like dust clouds, rain, or geometric patterns.
+ *
+ * @param position - Output vector for the particle's starting position
+ * @param quaternion - Rotation to apply to the emission shape
+ * @param velocity - Output vector for the particle's initial velocity
+ * @param speed - Speed multiplier for the velocity
+ * @param params - Box configuration
+ * @param params.scale - Size of the box on each axis (width, height, depth)
+ * @param params.emitFrom - Emission mode:
+ *   - `VOLUME`: Random positions throughout the entire box volume
+ *   - `SHELL`: Random positions on the 6 faces (surface)
+ *   - `EDGE`: Random positions along the 12 edges
+ *
+ * @remarks
+ * - All particles emit with velocity along the +Z axis (forward)
+ * - Box is centered at the origin before rotation
+ * - VOLUME mode: Best for rain, snow, or volumetric clouds
+ * - SHELL mode: Best for hollow effects or surface particles
+ * - EDGE mode: Best for wireframe effects or particle outlines
+ *
+ * @see {@link Box} - Configuration type for box shape
+ * @see {@link EmitFrom} - Emission mode enum
+ */
 export const calculateRandomPositionAndVelocityOnBox = (position, quaternion, velocity, speed, { scale, emitFrom }) => {
     const _scale = scale;
     switch (emitFrom) {
@@ -84,6 +159,30 @@ export const calculateRandomPositionAndVelocityOnBox = (position, quaternion, ve
     velocity.set(0, 0, speed);
     velocity.applyQuaternion(quaternion);
 };
+/**
+ * Calculates random position and velocity for particles emitted from a circle.
+ *
+ * Emits particles from a circular area or ring. Useful for ground impacts,
+ * radial effects, magic circles, or any circular planar emission.
+ *
+ * @param position - Output vector for the particle's starting position
+ * @param quaternion - Rotation to apply to the emission shape
+ * @param velocity - Output vector for the particle's initial velocity
+ * @param speed - Speed multiplier for the velocity
+ * @param params - Circle configuration
+ * @param params.radius - Radius of the circle
+ * @param params.radiusThickness - Controls emission from area (1.0) vs edge (0.0)
+ * @param params.arc - Arc angle in degrees (360 = full circle, 180 = semicircle)
+ *
+ * @remarks
+ * - Circle lies in the XY plane by default (Z = 0)
+ * - Particles emit along the +Z axis (perpendicular to circle)
+ * - `radiusThickness = 1.0`: Filled circle (disc)
+ * - `radiusThickness = 0.0`: Ring (circle edge only)
+ * - Good for ground impact effects, teleport circles, or radial bursts
+ *
+ * @see {@link Circle} - Configuration type for circle shape
+ */
 export const calculateRandomPositionAndVelocityOnCircle = (position, quaternion, velocity, speed, { radius, radiusThickness, arc, }) => {
     const theta = 2 * Math.PI * Math.random() * (arc / 360);
     const randomizedDistanceRatio = Math.random();
@@ -103,6 +202,30 @@ export const calculateRandomPositionAndVelocityOnCircle = (position, quaternion,
     velocity.set(position.x * speedMultiplierByPosition * speed, position.y * speedMultiplierByPosition * speed, 0);
     velocity.applyQuaternion(quaternion);
 };
+/**
+ * Calculates random position and velocity for particles emitted from a rectangle.
+ *
+ * Emits particles from a rectangular planar area. Useful for rain on a surface,
+ * screen-space effects, or any planar emission pattern.
+ *
+ * @param position - Output vector for the particle's starting position
+ * @param quaternion - Rotation to apply to the emission shape
+ * @param velocity - Output vector for the particle's initial velocity
+ * @param speed - Speed multiplier for the velocity
+ * @param params - Rectangle configuration
+ * @param params.rotation - Local rotation of the rectangle (degrees) before
+ *                          applying quaternion
+ * @param params.scale - Size of the rectangle (width and height)
+ *
+ * @remarks
+ * - Rectangle lies in the XY plane by default
+ * - Particles emit along the +Z axis (perpendicular to rectangle)
+ * - The rotation parameter allows tilting the rectangle before the main
+ *   quaternion rotation is applied
+ * - Good for rain effects, screen particles, or planar area emissions
+ *
+ * @see {@link Rectangle} - Configuration type for rectangle shape
+ */
 export const calculateRandomPositionAndVelocityOnRectangle = (position, quaternion, velocity, speed, { rotation, scale }) => {
     const _scale = scale;
     const _rotation = rotation;

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

@@ -1,5 +1,20 @@
 import { CycleData, ParticleSystem, ParticleSystemConfig } from './types.js';
 export * from './types.js';
+/**
+ * Mapping of blending mode string identifiers to Three.js blending constants.
+ *
+ * Used for converting serialized particle system configurations (e.g., from JSON)
+ * to actual Three.js blending mode constants.
+ *
+ * @example
+ * ```typescript
+ * import { blendingMap } from '@newkrok/three-particles';
+ *
+ * // Convert string to Three.js constant
+ * const blending = blendingMap['THREE.AdditiveBlending'];
+ * // blending === THREE.AdditiveBlending
+ * ```
+ */
 export declare const blendingMap: {
     'THREE.NoBlending': 0;
     'THREE.NormalBlending': 1;
@@ -7,7 +22,158 @@ export declare const blendingMap: {
     'THREE.SubtractiveBlending': 3;
     'THREE.MultiplyBlending': 4;
 };
+/**
+ * Returns a deep copy of the default particle system configuration.
+ *
+ * This is useful when you want to start with default settings and modify specific properties
+ * without affecting the internal default configuration object.
+ *
+ * @returns A new object containing all default particle system settings
+ *
+ * @example
+ * ```typescript
+ * import { getDefaultParticleSystemConfig, createParticleSystem } from '@newkrok/three-particles';
+ *
+ * // Get default config and modify it
+ * const config = getDefaultParticleSystemConfig();
+ * config.emission.rateOverTime = 100;
+ * config.startColor.min = { r: 1, g: 0, b: 0 };
+ *
+ * const { instance } = createParticleSystem(config);
+ * scene.add(instance);
+ * ```
+ */
 export declare const getDefaultParticleSystemConfig: () => any;
+/**
+ * Creates a new particle system with the specified configuration.
+ *
+ * This is the primary function for instantiating particle effects. It handles the complete
+ * setup of a particle system including geometry creation, material configuration, shader setup,
+ * and initialization of all particle properties.
+ *
+ * @param config - Configuration object for the particle system. If not provided, uses default settings.
+ *                 See {@link ParticleSystemConfig} for all available options.
+ * @param externalNow - Optional custom timestamp in milliseconds. If not provided, uses `Date.now()`.
+ *                      Useful for synchronized particle systems or testing.
+ *
+ * @returns A {@link ParticleSystem} object containing:
+ *   - `instance`: The THREE.Object3D that should be added to your scene
+ *   - `resumeEmitter()`: Function to resume particle emission
+ *   - `pauseEmitter()`: Function to pause particle emission
+ *   - `dispose()`: Function to clean up resources and remove the particle system
+ *
+ * @example
+ * ```typescript
+ * import { createParticleSystem, updateParticleSystems } from '@newkrok/three-particles';
+ *
+ * // Create a basic particle system with default settings
+ * const { instance, dispose } = createParticleSystem();
+ * scene.add(instance);
+ *
+ * // Create a custom fire effect
+ * const fireEffect = createParticleSystem({
+ *   duration: 2.0,
+ *   looping: true,
+ *   startLifetime: { min: 0.5, max: 1.5 },
+ *   startSpeed: { min: 2, max: 4 },
+ *   startSize: { min: 0.5, max: 1.5 },
+ *   startColor: {
+ *     min: { r: 1.0, g: 0.3, b: 0.0 },
+ *     max: { r: 1.0, g: 0.8, b: 0.0 }
+ *   },
+ *   emission: { rateOverTime: 50 },
+ *   shape: {
+ *     shape: Shape.CONE,
+ *     cone: { angle: 10, radius: 0.2 }
+ *   }
+ * });
+ * scene.add(fireEffect.instance);
+ *
+ * // In your animation loop
+ * function animate(time) {
+ *   updateParticleSystems({ now: time, delta: deltaTime, elapsed: elapsedTime });
+ *   renderer.render(scene, camera);
+ * }
+ *
+ * // Clean up when done
+ * fireEffect.dispose();
+ * ```
+ *
+ * @see {@link updateParticleSystems} - Required function to call in your animation loop
+ * @see {@link ParticleSystemConfig} - Complete configuration options
+ */
 export declare const createParticleSystem: (config?: ParticleSystemConfig, externalNow?: number) => ParticleSystem;
+/**
+ * Updates all active particle systems created with {@link createParticleSystem}.
+ *
+ * This function must be called once per frame in your animation loop to animate all particles.
+ * It handles particle emission, movement, lifetime tracking, modifier application, and cleanup
+ * of expired particle systems.
+ *
+ * @param cycleData - Object containing timing information for the current frame:
+ *   - `now`: Current timestamp in milliseconds (typically from `performance.now()` or `Date.now()`)
+ *   - `delta`: Time elapsed since the last frame in seconds
+ *   - `elapsed`: Total time elapsed since the animation started in seconds
+ *
+ * @example
+ * ```typescript
+ * import { createParticleSystem, updateParticleSystems } from '@newkrok/three-particles';
+ *
+ * const { instance } = createParticleSystem({
+ *   // your config
+ * });
+ * scene.add(instance);
+ *
+ * // Animation loop
+ * let lastTime = 0;
+ * let elapsedTime = 0;
+ *
+ * function animate(currentTime) {
+ *   requestAnimationFrame(animate);
+ *
+ *   const delta = (currentTime - lastTime) / 1000; // Convert to seconds
+ *   elapsedTime += delta;
+ *   lastTime = currentTime;
+ *
+ *   // Update all particle systems
+ *   updateParticleSystems({
+ *     now: currentTime,
+ *     delta: delta,
+ *     elapsed: elapsedTime
+ *   });
+ *
+ *   renderer.render(scene, camera);
+ * }
+ *
+ * animate(0);
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using Three.js Clock for timing
+ * import * as THREE from 'three';
+ * import { updateParticleSystems } from '@newkrok/three-particles';
+ *
+ * const clock = new THREE.Clock();
+ *
+ * function animate() {
+ *   requestAnimationFrame(animate);
+ *
+ *   const delta = clock.getDelta();
+ *   const elapsed = clock.getElapsedTime();
+ *
+ *   updateParticleSystems({
+ *     now: performance.now(),
+ *     delta: delta,
+ *     elapsed: elapsed
+ *   });
+ *
+ *   renderer.render(scene, camera);
+ * }
+ * ```
+ *
+ * @see {@link createParticleSystem} - Creates particle systems to be updated
+ * @see {@link CycleData} - Timing data structure
+ */
 export declare const updateParticleSystems: ({ now, delta, elapsed }: CycleData) => void;
 //# sourceMappingURL=three-particles.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"three-particles.d.ts","sourceRoot":"","sources":["../../../../src/js/effects/three-particles/three-particles.ts"],"names":[],"mappings":"AA2BA,OAAO,EAEL,SAAS,EAIT,cAAc,EACd,oBAAoB,EAKrB,MAAM,YAAY,CAAC;AAEpB,cAAc,YAAY,CAAC;AAK3B,eAAO,MAAM,WAAW;;;;;;CAMvB,CAAC;AAEF,eAAO,MAAM,8BAA8B,WACiB,CAAC;AAwP7D,eAAO,MAAM,oBAAoB,GAC/B,SAAQ,oBAAqD,EAC7D,cAAc,MAAM,KACnB,cAojBF,CAAC;AAEF,eAAO,MAAM,qBAAqB,GAAI,yBAAyB,SAAS,SAmPvE,CAAC"}
+{"version":3,"file":"three-particles.d.ts","sourceRoot":"","sources":["../../../../src/js/effects/three-particles/three-particles.ts"],"names":[],"mappings":"AA2BA,OAAO,EAEL,SAAS,EAIT,cAAc,EACd,oBAAoB,EAKrB,MAAM,YAAY,CAAC;AAEpB,cAAc,YAAY,CAAC;AAK3B;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,WAAW;;;;;;CAMvB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,8BAA8B,WACiB,CAAC;AA2Q7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,eAAO,MAAM,oBAAoB,GAC/B,SAAQ,oBAAqD,EAC7D,cAAc,MAAM,KACnB,cAwkBF,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,eAAO,MAAM,qBAAqB,GAAI,yBAAyB,SAAS,SAmPvE,CAAC"}