@newkrok/three-particles 2.6.2 → 2.6.4

package/dist/index.d.ts

@@ -1,7 +1,1782 @@
-export * from './js/effects/three-particles/three-particles-bezier.js';
-export * from './js/effects/three-particles/three-particles-curves.js';
-export * from './js/effects/three-particles/three-particles-enums.js';
-export * from './js/effects/three-particles/three-particles-modifiers.js';
-export * from './js/effects/three-particles/three-particles-utils.js';
-export * from './js/effects/three-particles/three-particles.js';
-//# sourceMappingURL=index.d.ts.map
+import * as THREE from 'three';
+import { Gyroscope } from 'three/examples/jsm/misc/Gyroscope.js';
+import { FBM } from 'three-noise/build/three-noise.module.js';
+
+/**
+ * Defines the coordinate space in which particles are simulated.
+ *
+ * @enum {string}
+ */
+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}
+ */
+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}
+ */
+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}
+ */
+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}
+ */
+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"
+}
+
+/**
+ * A fixed numerical value.
+ * Used for properties that require a constant value.
+ *
+ * @example
+ * const delay: Constant = 2; // Fixed delay of 2 seconds.
+ */
+type Constant = number;
+/**
+ * An object that defines a range for random number generation.
+ * Contains `min` and `max` properties.
+ *
+ * @property min - The minimum value for the random range.
+ * @property max - The maximum value for the random range.
+ *
+ * @example
+ * const randomDelay: RandomBetweenTwoConstants = { min: 0.5, max: 2 }; // Random delay between 0.5 and 2 seconds.
+ */
+type RandomBetweenTwoConstants = {
+    min?: number;
+    max?: number;
+};
+/**
+ * Base type for curves, containing common properties.
+ * @property scale - A scaling factor for the curve.
+ */
+type CurveBase = {
+    scale?: number;
+};
+/**
+ * A function that defines how the value changes over time.
+ * @param time - A normalized value between 0 and 1 representing the progress of the curve.
+ * @returns The corresponding value based on the curve function.
+ */
+type CurveFunction = (time: number) => number;
+/**
+ * A Bézier curve point representing a control point.
+ * @property x - The time (normalized between 0 and 1).
+ * @property y - The value at that point.
+ * @property percentage - (Optional) Normalized position within the curve (for additional flexibility).
+ */
+type BezierPoint = {
+    x: number;
+    y: number;
+    percentage?: number;
+};
+/**
+ * A Bézier curve representation for controlling particle properties.
+ * @property type - Specifies that this curve is of type `bezier`.
+ * @property bezierPoints - An array of control points defining the Bézier curve.
+ * @example
+ * {
+ *   type: LifeTimeCurve.BEZIER,
+ *   bezierPoints: [
+ *     { x: 0, y: 0.275, percentage: 0 },
+ *     { x: 0.1666, y: 0.4416 },
+ *     { x: 0.5066, y: 0.495, percentage: 0.5066 },
+ *     { x: 1, y: 1, percentage: 1 }
+ *   ]
+ * }
+ */
+type BezierCurve = CurveBase & {
+    type: LifeTimeCurve.BEZIER;
+    bezierPoints: Array<BezierPoint>;
+};
+/**
+ * An easing curve representation using a custom function.
+ * @property type - Specifies that this curve is of type `easing`.
+ * @property curveFunction - A function defining how the value changes over time.
+ * @example
+ * {
+ *   type: LifeTimeCurve.EASING,
+ *   curveFunction: (time) => Math.sin(time * Math.PI) // Simple easing function
+ * }
+ */
+type EasingCurve = CurveBase & {
+    type: LifeTimeCurve.EASING;
+    curveFunction: CurveFunction;
+};
+/**
+ * A flexible curve representation that supports Bézier curves and easing functions.
+ */
+type LifetimeCurve = BezierCurve | EasingCurve;
+/**
+ * Represents a point in 3D space with optional x, y, and z coordinates.
+ * Each coordinate is a number and is optional, allowing for partial definitions.
+ *
+ * @example
+ * // A point with all coordinates defined
+ * const point: Point3D = { x: 10, y: 20, z: 30 };
+ *
+ * @example
+ * // A point with only one coordinate defined
+ * const point: Point3D = { x: 10 };
+ *
+ * @default
+ * // Default values are undefined for all coordinates.
+ * const point: Point3D = {};
+ */
+type Point3D = {
+    x?: number;
+    y?: number;
+    z?: number;
+};
+/**
+ * Represents a transform in 3D space, including position, rotation, and scale.
+ * Each property is optional and represented as a THREE.Vector3 instance.
+ *
+ * - `position`: Defines the translation of an object in 3D space.
+ * - `rotation`: Defines the rotation of an object in radians for each axis (x, y, z).
+ * - `scale`: Defines the scale of an object along each axis.
+ *
+ * @example
+ * // A transform with all properties defined
+ * const transform: Transform = {
+ *   position: new THREE.Vector3(10, 20, 30),
+ *   rotation: new THREE.Vector3(Math.PI / 2, 0, 0),
+ *   scale: new THREE.Vector3(1, 1, 1),
+ * };
+ *
+ * @example
+ * // A transform with only position defined
+ * const transform: Transform = {
+ *   position: new THREE.Vector3(5, 5, 5),
+ * };
+ *
+ * @default
+ * // Default values are undefined for all properties.
+ * const transform: Transform = {};
+ */
+type Transform = {
+    position?: THREE.Vector3;
+    rotation?: THREE.Vector3;
+    scale?: THREE.Vector3;
+};
+/**
+ * Represents an RGB color with normalized values (0.0 to 1.0).
+ *
+ * @example
+ * ```typescript
+ * // Pure red
+ * const red: Rgb = { r: 1.0, g: 0.0, b: 0.0 };
+ *
+ * // Pure white
+ * const white: Rgb = { r: 1.0, g: 1.0, b: 1.0 };
+ *
+ * // Orange
+ * const orange: Rgb = { r: 1.0, g: 0.5, b: 0.0 };
+ * ```
+ */
+type Rgb = {
+    /** Red channel (0.0 to 1.0) */
+    r?: number;
+    /** Green channel (0.0 to 1.0) */
+    g?: number;
+    /** Blue channel (0.0 to 1.0) */
+    b?: number;
+};
+/**
+ * Defines a color range for random particle colors.
+ * Each particle will receive a random color between min and max on emission.
+ *
+ * @example
+ * ```typescript
+ * // Random colors between red and yellow
+ * const fireColors: MinMaxColor = {
+ *   min: { r: 1.0, g: 0.0, b: 0.0 }, // Red
+ *   max: { r: 1.0, g: 1.0, b: 0.0 }  // Yellow
+ * };
+ *
+ * // Fixed white color (no randomness)
+ * const white: MinMaxColor = {
+ *   min: { r: 1.0, g: 1.0, b: 1.0 },
+ *   max: { r: 1.0, g: 1.0, b: 1.0 }
+ * };
+ * ```
+ */
+type MinMaxColor = {
+    /** Minimum color values (lower bound for random selection) */
+    min?: Rgb;
+    /** Maximum color values (upper bound for random selection) */
+    max?: Rgb;
+};
+/**
+ * Defines a burst emission event that emits a specific number of particles at a given time.
+ * Bursts are useful for explosions, impacts, fireworks, and other instantaneous particle effects.
+ *
+ * @property time - The time (in seconds) after the particle system starts when this burst should occur.
+ * @property count - The number of particles to emit. Can be a constant or a random range.
+ * @property cycles - The number of times this burst should repeat. Defaults to 1 (single burst).
+ * @property interval - The time interval (in seconds) between burst cycles. Only used when cycles > 1.
+ * @property probability - The probability (0.0 to 1.0) that this burst will occur. Defaults to 1.0.
+ *
+ * @example
+ * // Simple burst at start
+ * { time: 0, count: 50 }
+ *
+ * // Random count burst at 1 second
+ * { time: 1, count: { min: 20, max: 30 } }
+ *
+ * // Repeating burst with interval
+ * { time: 0.5, count: 10, cycles: 3, interval: 0.2 }
+ * // Emits at 0.5s, 0.7s, 0.9s
+ *
+ * // Probabilistic burst (50% chance)
+ * { time: 2, count: 100, probability: 0.5 }
+ */
+type Burst = {
+    /** Time in seconds when the burst should occur */
+    time: number;
+    /** Number of particles to emit (constant or random range) */
+    count: Constant | RandomBetweenTwoConstants;
+    /** Number of times to repeat this burst. Defaults to 1. */
+    cycles?: number;
+    /** Time interval in seconds between burst cycles. Defaults to 0. */
+    interval?: number;
+    /** Probability (0-1) that this burst will occur. Defaults to 1. */
+    probability?: number;
+};
+/**
+ * Defines the emission behavior of the particles.
+ * Supports rates defined over time or distance using constant values, random ranges, or curves (Bézier or easing).
+ * Also supports burst emissions for instantaneous particle effects.
+ *
+ * @default
+ * rateOverTime: 10.0
+ * rateOverDistance: 0.0
+ * bursts: []
+ *
+ * @example
+ * // Rate over time as a constant value
+ * rateOverTime: 10;
+ *
+ * // Rate over time as a random range
+ * rateOverTime: { min: 5, max: 15 };
+ *
+ * // Rate over time using a Bézier curve
+ * rateOverTime: {
+ *   type: 'bezier',
+ *   bezierPoints: [
+ *     { x: 0, y: 0, percentage: 0 },
+ *     { x: 0.5, y: 50 },
+ *     { x: 1, y: 100, percentage: 1 }
+ *   ],
+ *   scale: 1
+ * };
+ *
+ * // Rate over distance as a constant value
+ * rateOverDistance: 2;
+ *
+ * // Rate over distance as a random range
+ * rateOverDistance: { min: 1, max: 3 };
+ *
+ * // Rate over distance using an easing curve
+ * rateOverDistance: {
+ *   type: 'easing',
+ *   curveFunction: (distance) => Math.sin(distance),
+ *   scale: 0.5
+ * };
+ *
+ * // Burst emissions for explosions
+ * bursts: [
+ *   { time: 0, count: 50 },
+ *   { time: 1, count: { min: 20, max: 30 }, probability: 0.8 },
+ *   { time: 0.5, count: 10, cycles: 3, interval: 0.2 }
+ * ];
+ */
+type Emission = {
+    rateOverTime?: Constant | RandomBetweenTwoConstants | LifetimeCurve;
+    rateOverDistance?: Constant | RandomBetweenTwoConstants | LifetimeCurve;
+    /** Array of burst configurations for instantaneous particle emissions */
+    bursts?: Array<Burst>;
+};
+/**
+ * Configuration for a sphere shape used in particle systems.
+ *
+ * @property radius - The radius of the sphere.
+ * @property radiusThickness - The thickness of the sphere's shell (0 to 1, where 1 is solid).
+ * @property arc - The angular arc of the sphere (in radians).
+ *
+ * @example
+ * const sphere: Sphere = {
+ *   radius: 5,
+ *   radiusThickness: 0.8,
+ *   arc: Math.PI,
+ * };
+ */
+type Sphere = {
+    radius?: number;
+    radiusThickness?: number;
+    arc?: number;
+};
+/**
+ * Configuration for a cone shape used in particle systems.
+ *
+ * @property angle - The angle of the cone (in radians).
+ * @property radius - The radius of the cone's base.
+ * @property radiusThickness - The thickness of the cone's base (0 to 1, where 1 is solid).
+ * @property arc - The angular arc of the cone's base (in radians).
+ *
+ * @example
+ * const cone: Cone = {
+ *   angle: Math.PI / 4,
+ *   radius: 10,
+ *   radiusThickness: 0.5,
+ *   arc: Math.PI * 2,
+ * };
+ */
+type Cone = {
+    angle?: number;
+    radius?: number;
+    radiusThickness?: number;
+    arc?: number;
+};
+/**
+ * Configuration for a circle shape used in particle systems.
+ *
+ * @property radius - The radius of the circle.
+ * @property radiusThickness - The thickness of the circle's shell (0 to 1, where 1 is solid).
+ * @property arc - The angular arc of the circle (in radians).
+ *
+ * @example
+ * const circle: Circle = {
+ *   radius: 10,
+ *   radiusThickness: 0.5,
+ *   arc: Math.PI,
+ * };
+ */
+type Circle = {
+    radius?: number;
+    radiusThickness?: number;
+    arc?: number;
+};
+/**
+ * Configuration for a rectangle shape used in particle systems.
+ *
+ * @property rotation - The rotation of the rectangle as a 3D point (in radians for each axis).
+ * @property scale - The scale of the rectangle as a 3D point.
+ *
+ * @example
+ * const rectangle: Rectangle = {
+ *   rotation: { x: Math.PI / 4, y: 0, z: 0 },
+ *   scale: { x: 10, y: 5, z: 1 },
+ * };
+ */
+type Rectangle = {
+    rotation?: Point3D;
+    scale?: Point3D;
+};
+/**
+ * Configuration for a box shape used in particle systems.
+ *
+ * @property scale - The scale of the box as a 3D point.
+ * @property emitFrom - Specifies where particles are emitted from within the box.
+ *
+ * @example
+ * const box: Box = {
+ *   scale: { x: 10, y: 10, z: 10 },
+ *   emitFrom: EmitFrom.EDGE,
+ * };
+ */
+type Box = {
+    scale?: Point3D;
+    emitFrom?: EmitFrom;
+};
+/**
+ * Configuration for defining a 3D shape used in particle systems.
+ * Specifies the shape type and its parameters, including spheres, cones, circles, rectangles, and boxes.
+ *
+ * @property shape - The type of the shape to be used.
+ * @property sphere - Configuration for a sphere shape.
+ * @property cone - Configuration for a cone shape.
+ * @property circle - Configuration for a circle shape.
+ * @property rectangle - Configuration for a rectangle shape.
+ * @property box - Configuration for a box shape.
+ *
+ * @example
+ * const shapeConfig: ShapeConfig = {
+ *   shape: Shape.SPHERE,
+ *   sphere: {
+ *     radius: 5,
+ *     radiusThickness: 0.8,
+ *     arc: Math.PI,
+ *   },
+ * };
+ */
+type ShapeConfig = {
+    shape?: Shape;
+    sphere?: Sphere;
+    cone?: Cone;
+    circle?: Circle;
+    rectangle?: Rectangle;
+    box?: Box;
+};
+/**
+ * Defines the texture sheet animation settings for particles.
+ * Allows configuring the animation frames, timing mode, frames per second, and the starting frame.
+ *
+ * @default
+ * tiles: new THREE.Vector2(1.0, 1.0)
+ * timeMode: TimeMode.LIFETIME
+ * fps: 30.0
+ * startFrame: 0
+ *
+ * @example
+ * // Basic configuration with default values
+ * textureSheetAnimation: {
+ *   tiles: new THREE.Vector2(1.0, 1.0),
+ *   timeMode: TimeMode.LIFETIME,
+ *   fps: 30.0,
+ *   startFrame: 0
+ * };
+ *
+ * // Custom configuration
+ * textureSheetAnimation: {
+ *   tiles: new THREE.Vector2(4, 4), // 4x4 grid of animation tiles
+ *   timeMode: TimeMode.SPEED,
+ *   fps: 60.0,
+ *   startFrame: { min: 0, max: 15 } // Random start frame between 0 and 15
+ * };
+ */
+type TextureSheetAnimation = {
+    tiles?: THREE.Vector2;
+    timeMode?: TimeMode;
+    fps?: number;
+    startFrame?: Constant | RandomBetweenTwoConstants;
+};
+/**
+ * Configuration for the particle system renderer, controlling blending, transparency, depth, and background color behavior.
+ *
+ * @property blending - Defines the blending mode for the particle system (e.g., additive blending).
+ * @property discardBackgroundColor - Whether to discard particles that match the background color.
+ * @property backgroundColorTolerance - The tolerance for matching the background color when `discardBackgroundColor` is true.
+ * @property backgroundColor - The background color as an RGB value, used when `discardBackgroundColor` is enabled.
+ * @property transparent - Whether the particle system uses transparency.
+ * @property depthTest - Whether to enable depth testing for particles (determines if particles are rendered behind or in front of other objects).
+ * @property depthWrite - Whether to write depth information for the particles (affects sorting and rendering order).
+ *
+ * @example
+ * // A renderer configuration with additive blending and transparent particles
+ * const renderer: Renderer = {
+ *   blending: THREE.AdditiveBlending,
+ *   discardBackgroundColor: true,
+ *   backgroundColorTolerance: 0.1,
+ *   backgroundColor: { r: 0, g: 0, b: 0 },
+ *   transparent: true,
+ *   depthTest: true,
+ *   depthWrite: false,
+ * };
+ *
+ * @default
+ * // Default values for the renderer configuration
+ * const renderer: Renderer = {
+ *   blending: THREE.NormalBlending,
+ *   discardBackgroundColor: false,
+ *   backgroundColorTolerance: 1.0,
+ *   backgroundColor: { r: 0, g: 0, b: 0 },
+ *   transparent: false,
+ *   depthTest: true,
+ *   depthWrite: true,
+ * };
+ */
+type Renderer = {
+    blending: THREE.Blending;
+    discardBackgroundColor: boolean;
+    backgroundColorTolerance: number;
+    backgroundColor: Rgb;
+    transparent: boolean;
+    depthTest: boolean;
+    depthWrite: boolean;
+};
+/**
+ * Configuration for noise effects applied to particles in a particle system.
+ * Noise can affect particle position, rotation, and size dynamically.
+ *
+ * @property isActive - Whether noise is enabled for the particle system.
+ * @property strength - The overall strength of the noise effect.
+ * @property positionAmount - The amount of noise applied to particle positions.
+ * @property rotationAmount - The amount of noise applied to particle rotations.
+ * @property sizeAmount - The amount of noise applied to particle sizes.
+ * @property sampler - An optional noise sampler (e.g., FBM for fractal Brownian motion) to generate noise values.
+ * @property offsets - An optional array of offsets to randomize noise generation per particle.
+ *
+ * @example
+ * // A noise configuration with position and rotation noise
+ * const noise: Noise = {
+ *   isActive: true,
+ *   strength: 0.5,
+ *   positionAmount: 1.0,
+ *   rotationAmount: 0.3,
+ *   sizeAmount: 0.0,
+ *   sampler: new FBM(),
+ *   offsets: [0.1, 0.2, 0.3],
+ * };
+ *
+ * @default
+ * // Default values for noise configuration
+ * const noise: Noise = {
+ *   isActive: false,
+ *   strength: 1.0,
+ *   positionAmount: 0.0,
+ *   rotationAmount: 0.0,
+ *   sizeAmount: 0.0,
+ *   sampler: undefined,
+ *   offsets: undefined,
+ * };
+ */
+type Noise = {
+    isActive: boolean;
+    strength: number;
+    noisePower: number;
+    positionAmount: number;
+    rotationAmount: number;
+    sizeAmount: number;
+    sampler?: FBM;
+    offsets?: Array<number>;
+};
+type NoiseConfig = {
+    isActive: boolean;
+    useRandomOffset: boolean;
+    strength: number;
+    frequency: number;
+    octaves: number;
+    positionAmount: number;
+    rotationAmount: number;
+    sizeAmount: number;
+};
+/**
+ * Defines the velocity of particles over their lifetime, allowing for linear and orbital velocity (in degrees) adjustments.
+ * Supports constant values, random ranges, or curves (Bézier or easing) for each axis.
+ *
+ * @default
+ * isActive: false
+ * linear: { x: 0.0, y: 0.0, z: 0.0 }
+ * orbital: { x: 0.0, y: 0.0, z: 0.0 }
+ *
+ * @example
+ * // Linear velocity with a constant value
+ * linear: { x: 1, y: 0, z: -0.5 };
+ *
+ * // Linear velocity with random ranges
+ * linear: {
+ *   x: { min: -1, max: 1 },
+ *   y: { min: 0, max: 2 }
+ * };
+ *
+ * // Linear velocity using a Bézier curve
+ * linear: {
+ *   z: {
+ *     type: 'bezier',
+ *     bezierPoints: [
+ *       { x: 0, y: 0, percentage: 0 },
+ *       { x: 0.5, y: 2 },
+ *       { x: 1, y: 10, percentage: 1 }
+ *     ],
+ *     scale: 2
+ *   }
+ * };
+ *
+ * // Orbital velocity with a constant value
+ * orbital: { x: 3, y: 5, z: 0 };
+ *
+ * // Orbital velocity using an easing curve
+ * orbital: {
+ *   x: {
+ *     type: 'easing',
+ *     curveFunction: (time) => Math.sin(time * Math.PI),
+ *     scale: 1.5
+ *   }
+ * };
+ */
+type VelocityOverLifetime = {
+    isActive: boolean;
+    linear: {
+        x?: Constant | RandomBetweenTwoConstants | LifetimeCurve;
+        y?: Constant | RandomBetweenTwoConstants | LifetimeCurve;
+        z?: Constant | RandomBetweenTwoConstants | LifetimeCurve;
+    };
+    orbital: {
+        x?: Constant | RandomBetweenTwoConstants | LifetimeCurve;
+        y?: Constant | RandomBetweenTwoConstants | LifetimeCurve;
+        z?: Constant | RandomBetweenTwoConstants | LifetimeCurve;
+    };
+};
+/**
+ * Configuration object for the particle system.
+ * Defines all aspects of the particle system, including its appearance, behavior, and runtime events.
+ */
+type ParticleSystemConfig = {
+    /**
+     * Defines the position, rotation, and scale of the particle system.
+     *
+     * @see Transform
+     * @default
+     * transform: {
+     *   position: new THREE.Vector3(),
+     *   rotation: new THREE.Vector3(),
+     *   scale: new THREE.Vector3(1, 1, 1),
+     * }
+     */
+    transform?: Transform;
+    /**
+     * Duration of the particle system in seconds.
+     * Must be a positive value.
+     * @default 5.0
+     * @example
+     * const duration: number = 5; // System runs for 5 seconds.
+     */
+    duration?: number;
+    /**
+     * Indicates whether the system should loop after finishing.
+     * @default true
+     * @example
+     * looping: true; // System loops continuously.
+     */
+    looping?: boolean;
+    /**
+     * Delay before the particle system starts emitting particles.
+     * Supports a fixed value (`Constant`) or a random range (`RandomBetweenTwoConstants`).
+     * @default 0.0
+     * @example
+     * startDelay: 2; // Fixed 2-second delay.
+     * startDelay: { min: 0.5, max: 2 }; // Random delay between 0.5 and 2 seconds.
+     */
+    startDelay?: Constant | RandomBetweenTwoConstants;
+    /**
+     * Initial lifetime of the particles.
+     * Supports constant value, random range, or curves (Bézier or easing).
+     * @default 5.0
+     * @example
+     * // Constant 3 seconds.
+     * startLifetime: 3;
+     *
+     * // Random range between 1 and 4 seconds.
+     * startLifetime: { min: 1, max: 4 };
+     *
+     * // Bézier curve example with scaling.
+     * startLifetime: {
+     *   type: LifeTimeCurve.BEZIER,
+     *   bezierPoints: [
+     *     { x: 0, y: 0.275, percentage: 0 },
+     *     { x: 0.5, y: 0.5 },
+     *     { x: 1, y: 1, percentage: 1 }
+     *   ],
+     *   scale: 2
+     * };
+     *
+     * // Easing curve example with scaling.
+     * startLifetime: {
+     *   type: LifeTimeCurve.EASING,
+     *   curveFunction: (time) => Math.sin(time * Math.PI),
+     *   scale: 0.5
+     * };
+     */
+    startLifetime?: Constant | RandomBetweenTwoConstants | LifetimeCurve;
+    /**
+     * Defines the initial speed of the particles.
+     * Supports constant values, random ranges, or curves (Bézier or easing).
+     * @default 1.0
+     * @example
+     * // Constant value
+     * startSpeed: 3;
+     *
+     * // Random range
+     * startSpeed: { min: 1, max: 4 };
+     *
+     * // Bézier curve example with scaling.
+     * startSpeed: {
+     *   type: 'bezier',
+     *   bezierPoints: [
+     *     { x: 0, y: 0.275, percentage: 0 },
+     *     { x: 0.5, y: 0.5 },
+     *     { x: 1, y: 1, percentage: 1 }
+     *   ],
+     *   scale: 2
+     * };
+     *
+     * // Easing curve example with scaling.
+     * startSpeed: {
+     *   type: 'easing',
+     *   curveFunction: (time) => Math.sin(time * Math.PI),
+     *   scale: 1.5
+     * };
+     */
+    startSpeed?: Constant | RandomBetweenTwoConstants | LifetimeCurve;
+    /**
+     * Defines the initial size of the particles.
+     * Supports constant values, random ranges, or curves (Bézier or easing).
+     * @default 1.0
+     * @example
+     * // Constant value
+     * startSize: 3;
+     *
+     * // Random range
+     * startSize: { min: 1, max: 4 };
+     *
+     * // Bézier curve example with scaling.
+     * startSize: {
+     *   type: 'bezier',
+     *   bezierPoints: [
+     *     { x: 0, y: 0.275, percentage: 0 },
+     *     { x: 0.5, y: 0.5 },
+     *     { x: 1, y: 1, percentage: 1 }
+     *   ],
+     *   scale: 2
+     * };
+     *
+     * // Easing curve example with scaling.
+     * startSize: {
+     *   type: 'easing',
+     *   curveFunction: (time) => Math.sin(time * Math.PI),
+     *   scale: 1.5
+     * };
+     */
+    startSize?: Constant | RandomBetweenTwoConstants | LifetimeCurve;
+    /**
+     * Defines the initial opacity of the particles.
+     * Supports constant values, random ranges, or curves (Bézier or easing).
+     * @default 1.0
+     * @example
+     * // Constant value
+     * startOpacity: 3;
+     *
+     * // Random range
+     * startOpacity: { min: 1, max: 4 };
+     *
+     * // Bézier curve example with scaling.
+     * startOpacity: {
+     *   type: 'bezier',
+     *   bezierPoints: [
+     *     { x: 0, y: 0.275, percentage: 0 },
+     *     { x: 0.5, y: 0.5 },
+     *     { x: 1, y: 1, percentage: 1 }
+     *   ],
+     *   scale: 2
+     * };
+     *
+     * // Easing curve example with scaling.
+     * startOpacity: {
+     *   type: 'easing',
+     *   curveFunction: (time) => Math.sin(time * Math.PI),
+     *   scale: 1.5
+     * };
+     */
+    startOpacity?: Constant | RandomBetweenTwoConstants | LifetimeCurve;
+    /**
+     * Defines the initial rotation of the particles in degrees.
+     * Supports constant values, random ranges, or curves (Bézier or easing).
+     * @default 0.0
+     * @example
+     * // Constant value
+     * startRotation: 3;
+     *
+     * // Random range
+     * startRotation: { min: 1, max: 4 };
+     *
+     * // Bézier curve example with scaling.
+     * startRotation: {
+     *   type: 'bezier',
+     *   bezierPoints: [
+     *     { x: 0, y: 0.275, percentage: 0 },
+     *     { x: 0.5, y: 0.5 },
+     *     { x: 1, y: 1, percentage: 1 }
+     *   ],
+     *   scale: 2
+     * };
+     *
+     * // Easing curve example with scaling.
+     * startRotation: {
+     *   type: 'easing',
+     *   curveFunction: (time) => Math.sin(time * Math.PI),
+     *   scale: 1.5
+     * };
+     */
+    startRotation?: Constant | RandomBetweenTwoConstants | LifetimeCurve;
+    /**
+     * Initial color of the particles.
+     * Supports a min-max range for color interpolation.
+     *
+     * @default
+     * startColor: {
+     *   min: { r: 1.0, g: 1.0, b: 1.0 },
+     *   max: { r: 1.0, g: 1.0, b: 1.0 },
+     * }
+     */
+    startColor?: MinMaxColor;
+    /**
+     * Defines the gravity strength applied to particles.
+     * This value affects the downward acceleration of particles over time.
+     *
+     * @default 0.0
+     *
+     * @example
+     * // No gravity
+     * gravity: 0;
+     *
+     * // Moderate gravity
+     * gravity: 9.8; // Similar to Earth's gravity
+     *
+     * // Strong gravity
+     * gravity: 20.0;
+     */
+    gravity?: Constant;
+    /**
+     * Defines the simulation space in which particles are simulated.
+     * Determines whether the particles move relative to the local object space or the world space.
+     *
+     * @default SimulationSpace.LOCAL
+     *
+     * @example
+     * // Simulate particles in local space (default)
+     * simulationSpace: SimulationSpace.LOCAL;
+     *
+     * // Simulate particles in world space
+     * simulationSpace: SimulationSpace.WORLD;
+     */
+    simulationSpace?: SimulationSpace;
+    /**
+     * Defines the maximum number of particles allowed in the system.
+     * This value limits the total number of active particles at any given time.
+     *
+     * @default 100.0
+     *
+     * @example
+     * // Default value
+     * maxParticles: 100.0;
+     *
+     * // Increase the maximum number of particles
+     * maxParticles: 500.0;
+     *
+     * // Limit to a small number of particles
+     * maxParticles: 10.0;
+     */
+    maxParticles?: Constant;
+    /**
+     * Defines the particle emission settings.
+     * Configures the emission rate over time and distance.
+     *
+     * @see Emission
+     * @default
+     * emission: {
+     *   rateOverTime: 10.0,
+     *   rateOverDistance: 0.0,
+     * }
+     */
+    emission?: Emission;
+    /**
+     * Configuration for the emitter shape.
+     * Determines the shape and parameters for particle emission.
+     *
+     * @see ShapeConfig
+     */
+    shape?: ShapeConfig;
+    /**
+     * Defines the texture used for rendering particles.
+     * This texture is applied to all particles in the system, and can be used to control their appearance.
+     *
+     * @default undefined
+     *
+     * @example
+     * // Using a predefined texture
+     * map: new THREE.TextureLoader().load('path/to/texture.png');
+     *
+     * // No texture (default behavior)
+     * map: undefined;
+     */
+    map?: THREE.Texture;
+    /**
+     * Renderer configuration for blending, transparency, and depth testing.
+     *
+     * @see Renderer
+     * @default
+     * renderer: {
+     *   blending: THREE.NormalBlending,
+     *   discardBackgroundColor: false,
+     *   backgroundColorTolerance: 1.0,
+     *   backgroundColor: { r: 1.0, g: 1.0, b: 1.0 },
+     *   transparent: true,
+     *   depthTest: true,
+     *   depthWrite: false
+     * }
+     */
+    renderer?: Renderer;
+    /**
+     * Defines the velocity settings of particles over their lifetime.
+     * Configures both linear and orbital velocity changes.
+     *
+     * @see VelocityOverLifetime
+     * @default
+     * velocityOverLifetime: {
+     *   isActive: false,
+     *   linear: {
+     *     x: 0,
+     *     y: 0,
+     *     z: 0,
+     *   },
+     *   orbital: {
+     *     x: 0,
+     *     y: 0,
+     *     z: 0,
+     *   },
+     * }
+     */
+    velocityOverLifetime?: VelocityOverLifetime;
+    /**
+     * Controls the size of particles over their lifetime.
+     * The size can be adjusted using a lifetime curve (Bézier or other supported types).
+     *
+     * @default
+     * sizeOverLifetime: {
+     *   isActive: false,
+     *   lifetimeCurve: {
+     *     type: LifeTimeCurve.BEZIER,
+     *     scale: 1,
+     *     bezierPoints: [
+     *       { x: 0, y: 0, percentage: 0 },
+     *       { x: 1, y: 1, percentage: 1 },
+     *     ],
+     *   },
+     * }
+     */
+    sizeOverLifetime?: {
+        isActive: boolean;
+        lifetimeCurve: LifetimeCurve;
+    };
+    /**
+     * Controls the opacity of particles over their lifetime.
+     * The opacity can be adjusted using a lifetime curve (Bézier or other supported types).
+     *
+     * @default
+     * opacityOverLifetime: {
+     *   isActive: false,
+     *   lifetimeCurve: {
+     *     type: LifeTimeCurve.BEZIER,
+     *     scale: 1,
+     *     bezierPoints: [
+     *       { x: 0, y: 0, percentage: 0 },
+     *       { x: 1, y: 1, percentage: 1 },
+     *     ],
+     *   },
+     * }
+     */
+    opacityOverLifetime?: {
+        isActive: boolean;
+        lifetimeCurve: LifetimeCurve;
+    };
+    /**
+     * Controls the color of particles over their lifetime.
+     * Each RGB channel can be adjusted independently using a lifetime curve (Bézier or easing).
+     * The curves act as multipliers (0-1 range) that are applied to the particle's start color.
+     *
+     * This follows Unity's Color over Lifetime behavior where the final color is:
+     * finalColor = startColor * colorOverLifetime
+     *
+     * **IMPORTANT**: To achieve full color transitions, set startColor to white { r: 1, g: 1, b: 1 }.
+     * If startColor has any channel set to 0, that channel cannot be modified by colorOverLifetime.
+     *
+     * @example
+     * // Rainbow effect - requires white startColor
+     * startColor: { min: { r: 1, g: 1, b: 1 }, max: { r: 1, g: 1, b: 1 } }
+     * colorOverLifetime: {
+     *   isActive: true,
+     *   r: { // Red: full -> half -> off
+     *     type: LifeTimeCurve.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: LifeTimeCurve.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: LifeTimeCurve.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 },
+     *     ],
+     *   },
+     * }
+     *
+     * @default
+     * colorOverLifetime: {
+     *   isActive: false,
+     *   r: {
+     *     type: LifeTimeCurve.BEZIER,
+     *     scale: 1,
+     *     bezierPoints: [
+     *       { x: 0, y: 1, percentage: 0 },
+     *       { x: 1, y: 1, percentage: 1 },
+     *     ],
+     *   },
+     *   g: {
+     *     type: LifeTimeCurve.BEZIER,
+     *     scale: 1,
+     *     bezierPoints: [
+     *       { x: 0, y: 1, percentage: 0 },
+     *       { x: 1, y: 1, percentage: 1 },
+     *     ],
+     *   },
+     *   b: {
+     *     type: LifeTimeCurve.BEZIER,
+     *     scale: 1,
+     *     bezierPoints: [
+     *       { x: 0, y: 1, percentage: 0 },
+     *       { x: 1, y: 1, percentage: 1 },
+     *     ],
+     *   },
+     * }
+     */
+    colorOverLifetime?: {
+        isActive: boolean;
+        r: LifetimeCurve;
+        g: LifetimeCurve;
+        b: LifetimeCurve;
+    };
+    /**
+     * Controls the rotation of particles over their lifetime.
+     * The rotation can be randomized between two constants, and the feature can be toggled on or off.
+     *
+     * @default
+     * rotationOverLifetime: {
+     *   isActive: false,
+     *   min: 0.0,
+     *   max: 0.0,
+     * }
+     */
+    rotationOverLifetime?: {
+        isActive: boolean;
+    } & RandomBetweenTwoConstants;
+    /**
+     * Noise configuration affecting position, rotation, and size.
+     *
+     * @see NoiseConfig
+     * @default
+     * noise: {
+     *   isActive: false,
+     *   useRandomOffset: false,
+     *   strength: 1.0,
+     *   frequency: 0.5,
+     *   octaves: 1,
+     *   positionAmount: 1.0,
+     *   rotationAmount: 0.0,
+     *   sizeAmount: 0.0,
+     * }
+     */
+    noise?: NoiseConfig;
+    /**
+     * Configures the texture sheet animation settings for particles.
+     * Controls how textures are animated over the lifetime of particles.
+     *
+     * @see TextureSheetAnimation
+     * @default
+     * textureSheetAnimation: {
+     *   tiles: new THREE.Vector2(1.0, 1.0),
+     *   timeMode: TimeMode.LIFETIME,
+     *   fps: 30.0,
+     *   startFrame: 0,
+     * }
+     */
+    textureSheetAnimation?: TextureSheetAnimation;
+    /**
+     * Called on every update frame with particle system data.
+     */
+    onUpdate?: (data: {
+        particleSystem: THREE.Points;
+        delta: number;
+        elapsed: number;
+        lifetime: number;
+        iterationCount: number;
+    }) => void;
+    /**
+     * Called when the system completes an iteration.
+     */
+    onComplete?: () => void;
+};
+type NormalizedParticleSystemConfig = Required<ParticleSystemConfig>;
+/**
+ * Tracks the state of a burst emission event.
+ * Used internally to determine when bursts should fire and how many cycles remain.
+ */
+type BurstState = {
+    /** Number of cycles that have been executed so far */
+    cyclesExecuted: number;
+    /** Time (in ms) when the last cycle was executed */
+    lastCycleTime: number;
+    /** Whether the probability check passed for this iteration */
+    probabilityPassed: boolean;
+};
+type GeneralData = {
+    particleSystemId: number;
+    normalizedLifetimePercentage: number;
+    creationTimes: Array<number>;
+    distanceFromLastEmitByDistance: number;
+    lastWorldPosition: THREE.Vector3;
+    currentWorldPosition: THREE.Vector3;
+    worldPositionChange: THREE.Vector3;
+    wrapperQuaternion: THREE.Quaternion;
+    lastWorldQuaternion: THREE.Quaternion;
+    worldQuaternion: THREE.Quaternion;
+    worldEuler: THREE.Euler;
+    gravityVelocity: THREE.Vector3;
+    startValues: Record<string, Array<number>>;
+    linearVelocityData?: Array<{
+        speed: THREE.Vector3;
+        valueModifiers: {
+            x?: CurveFunction;
+            y?: CurveFunction;
+            z?: CurveFunction;
+        };
+    }>;
+    orbitalVelocityData?: Array<{
+        speed: THREE.Vector3;
+        positionOffset: THREE.Vector3;
+        valueModifiers: {
+            x?: CurveFunction;
+            y?: CurveFunction;
+            z?: CurveFunction;
+        };
+    }>;
+    lifetimeValues: Record<string, Array<number>>;
+    noise: Noise;
+    isEnabled: boolean;
+    /** Tracks the state of each burst emission event */
+    burstStates?: Array<BurstState>;
+};
+type ParticleSystemInstance = {
+    particleSystem: THREE.Points;
+    wrapper?: Gyroscope;
+    elapsedUniform: {
+        value: number;
+    };
+    generalData: GeneralData;
+    onUpdate: (data: {
+        particleSystem: THREE.Points;
+        delta: number;
+        elapsed: number;
+        lifetime: number;
+        normalizedLifetime: number;
+        iterationCount: number;
+    }) => void;
+    onComplete: (data: {
+        particleSystem: THREE.Points;
+    }) => void;
+    creationTime: number;
+    lastEmissionTime: number;
+    duration: number;
+    looping: boolean;
+    simulationSpace: SimulationSpace;
+    gravity: number;
+    emission: Emission;
+    normalizedConfig: NormalizedParticleSystemConfig;
+    iterationCount: number;
+    velocities: Array<THREE.Vector3>;
+    freeList: Array<number>;
+    deactivateParticle: (particleIndex: number) => void;
+    activateParticle: (data: {
+        particleIndex: number;
+        activationTime: number;
+        position: Required<Point3D>;
+    }) => void;
+};
+/**
+ * Represents a particle system instance, providing methods to control and manage its lifecycle.
+ *
+ * @property instance - The underlying Three.js `Points` object or a `Gyroscope` used for particle rendering.
+ * @property resumeEmitter - Resumes the particle emitter, allowing particles to be emitted again.
+ * @property pauseEmitter - Pauses the particle emitter, stopping any new particles from being emitted.
+ * @property dispose - Disposes of the particle system, cleaning up resources to free memory.
+ *
+ * @example
+ * const particleSystem: ParticleSystem = {
+ *   instance: new THREE.Points(geometry, material),
+ *   resumeEmitter: () => { /* resume logic * / },
+ *   pauseEmitter: () => { /* pause logic * / },
+ *   dispose: () => { /* cleanup logic * / },
+ * };
+ *
+ * particleSystem.pauseEmitter(); // Stop particle emission
+ * particleSystem.resumeEmitter(); // Resume particle emission
+ * particleSystem.dispose(); // Cleanup the particle system
+ */
+type ParticleSystem = {
+    instance: THREE.Points | Gyroscope;
+    resumeEmitter: () => void;
+    pauseEmitter: () => void;
+    dispose: () => void;
+    update: (cycleData: CycleData) => void;
+};
+/**
+ * Data representing the current cycle of the particle system's update loop.
+ *
+ * @property now - The current timestamp in milliseconds.
+ * @property delta - The time elapsed since the last update, in seconds.
+ * @property elapsed - The total time elapsed since the particle system started, in seconds.
+ *
+ * @example
+ * const cycleData: CycleData = {
+ *   now: performance.now(),
+ *   delta: 0.016, // 16ms frame time
+ *   elapsed: 1.25, // 1.25 seconds since start
+ * };
+ */
+type CycleData = {
+    now: number;
+    delta: number;
+    elapsed: number;
+};
+
+declare const createBezierCurveFunction: (particleSystemId: number, bezierPoints: Array<BezierPoint>) => CurveFunction;
+declare const removeBezierCurveFunction: (particleSystemId: number) => void;
+declare const getBezierCacheSize: () => number;
+
+/**
+ * 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
+ */
+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
+ * ```
+ */
+declare const getCurveFunction: (curveFunctionId: CurveFunctionId | CurveFunction) => CurveFunction;
+
+/**
+ * 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
+ */
+declare const applyModifiers: ({ delta, generalData, normalizedConfig, attributes, particleLifetimePercentage, particleIndex, }: {
+    delta: number;
+    generalData: GeneralData;
+    normalizedConfig: NormalizedParticleSystemConfig;
+    attributes: THREE.NormalBufferAttributes;
+    particleLifetimePercentage: number;
+    particleIndex: number;
+}) => void;
+
+/**
+ * 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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+declare const calculateRandomPositionAndVelocityOnRectangle: (position: THREE.Vector3, quaternion: THREE.Quaternion, velocity: THREE.Vector3, speed: number, { rotation, scale }: {
+    rotation: Point3D;
+    scale: Point3D;
+}) => void;
+/**
+ * Creates a default white circle texture using CanvasTexture.
+ * @returns {THREE.CanvasTexture | null} The generated texture or null if context fails.
+ */
+declare const createDefaultParticleTexture: () => THREE.CanvasTexture | null;
+declare const isLifeTimeCurve: (value: Constant | RandomBetweenTwoConstants | LifetimeCurve) => value is LifetimeCurve;
+declare const getCurveFunctionFromConfig: (particleSystemId: number, lifetimeCurve: LifetimeCurve) => CurveFunction;
+declare const calculateValue: (particleSystemId: number, value: Constant | RandomBetweenTwoConstants | LifetimeCurve, time?: number) => number;
+
+/**
+ * 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
+ * ```
+ */
+declare const blendingMap: {
+    'THREE.NoBlending': 0;
+    'THREE.NormalBlending': 1;
+    'THREE.AdditiveBlending': 2;
+    '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);
+ * ```
+ */
+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
+ */
+declare const createParticleSystem: (config?: ParticleSystemConfig, externalNow?: number) => ParticleSystem;
+declare const updateParticleSystems: (cycleData: CycleData) => void;
+
+export { type BezierCurve, type BezierPoint, type Box, type Burst, type BurstState, type Circle, type Cone, type Constant, type CurveBase, type CurveFunction, CurveFunctionId, type CycleData, type EasingCurve, type Emission, EmitFrom, type GeneralData, LifeTimeCurve, type LifetimeCurve, type MinMaxColor, type Noise, type NoiseConfig, type NormalizedParticleSystemConfig, type ParticleSystem, type ParticleSystemConfig, type ParticleSystemInstance, type Point3D, type RandomBetweenTwoConstants, type Rectangle, type Renderer, type Rgb, Shape, type ShapeConfig, SimulationSpace, type Sphere, type TextureSheetAnimation, TimeMode, type Transform, type VelocityOverLifetime, applyModifiers, blendingMap, calculateRandomPositionAndVelocityOnBox, calculateRandomPositionAndVelocityOnCircle, calculateRandomPositionAndVelocityOnCone, calculateRandomPositionAndVelocityOnRectangle, calculateRandomPositionAndVelocityOnSphere, calculateValue, createBezierCurveFunction, createDefaultParticleTexture, createParticleSystem, getBezierCacheSize, getCurveFunction, getCurveFunctionFromConfig, getDefaultParticleSystemConfig, isLifeTimeCurve, removeBezierCurveFunction, updateParticleSystems };