sparcoon 0.5.0 → 0.6.1

package/dist/emitter/behavior/FXBehaviorScaleOverLife.d.ts

@@ -1,20 +1,21 @@
-import type { FXAspectConfig, FXRangeConfig } from "../../miscellaneous/miscellaneous";
+import type { FXCurve1DConfig } from "../../miscellaneous/curve/FXCurve1D";
+import { FXCurve1D } from "../../miscellaneous/curve/FXCurve1D";
+import type { FXAspectConfig, FXRange } from "../../miscellaneous/miscellaneous";
 import { FXBehavior } from "./FXBehavior";
 /**
- * Animates particle scale over lifetime.
- *
- * Interpolates between scale anchors based on particle age. Requires at least 2 anchors.
+ * Animates particle scale over lifetime using a {@link FXCurve1D}
  */
 export declare class FXBehaviorScaleOverLife extends FXBehavior<{
     builtin: "Matrix4";
 }> {
-    private readonly scales;
+    /** Active scale curve */
+    curve: FXCurve1D<FXRange>;
     private aspectInternal;
     /**
-     * @param scales - Scale anchor points. Each accepts number, tuple, or range object
-     * @param aspect - Width/height ratio. Accepts number or texture
+     * @param curve - Scale curve; accepts a {@link FXCurve1D} instance or a `FXRange[]` shorthand
+     * @param aspect - Width/height ratio; must be positive. Defaults to `1`
      */
-    constructor(scales: FXRangeConfig[], aspect?: FXAspectConfig);
+    constructor(curve: FXCurve1DConfig<FXRange>, aspect?: FXAspectConfig);
     /** Width/height aspect ratio */
     get aspect(): number;
     /** Width/height aspect ratio */

package/dist/emitter/behavior/FXBehaviorScaleOverLife.js

@@ -1,32 +1,22 @@
 import { MathUtils } from 'three';
-import { assertValidNonNegativeNumber, assertValidPositiveNumber } from '../../miscellaneous/asserts.js';
-import { resolveFXRangeConfig, resolveAspect, BUILTIN_OFFSET_AGE, BUILTIN_OFFSET_LIFETIME, BUILTIN_OFFSET_RANDOM_A, BUILTIN_OFFSET_SCALE_X, BUILTIN_OFFSET_SCALE_Y } from '../../miscellaneous/miscellaneous.js';
+import { assertValidPositiveNumber } from '../../miscellaneous/asserts.js';
+import { FXCurve1D } from '../../miscellaneous/curve/FXCurve1D.js';
+import { resolveAspect, BUILTIN_OFFSET_AGE, BUILTIN_OFFSET_LIFETIME, BUILTIN_OFFSET_RANDOM_A, BUILTIN_OFFSET_SCALE_X, BUILTIN_OFFSET_SCALE_Y } from '../../miscellaneous/miscellaneous.js';
 import { FXBehavior } from './FXBehavior.js';
 
 /**
- * Animates particle scale over lifetime.
- *
- * Interpolates between scale anchors based on particle age. Requires at least 2 anchors.
+ * Animates particle scale over lifetime using a {@link FXCurve1D}
  */
 class FXBehaviorScaleOverLife extends FXBehavior {
     /**
-     * @param scales - Scale anchor points. Each accepts number, tuple, or range object
-     * @param aspect - Width/height ratio. Accepts number or texture
+     * @param curve - Scale curve; accepts a {@link FXCurve1D} instance or a `FXRange[]` shorthand
+     * @param aspect - Width/height ratio; must be positive. Defaults to `1`
      */
-    constructor(scales, aspect = 1) {
+    constructor(curve, aspect = 1) {
         super();
         /** @internal */
         this.requiredProperties = { builtin: "Matrix4" };
-        this._private_scales = [];
-        if (scales.length < 2) {
-            throw new Error("FXBehaviorScaleOverLife.scales: the number of scale anchors must be more than two");
-        }
-        for (let i = 0; i < scales.length; i++) {
-            const scale = resolveFXRangeConfig(scales[i]);
-            assertValidNonNegativeNumber(scale.min, `FXBehaviorScaleOverLife.constructor.scales[${i}].min`);
-            assertValidNonNegativeNumber(scale.max, `FXBehaviorScaleOverLife.constructor.scales[${i}].max`);
-            this._private_scales.push(scale);
-        }
+        this.curve = new FXCurve1D(curve);
         this._private_aspectInternal = resolveAspect(aspect);
         assertValidPositiveNumber(this._private_aspectInternal, "FXBehaviorScaleOverLife.constructor.aspect");
     }
@@ -46,18 +36,11 @@ class FXBehaviorScaleOverLife extends FXBehavior {
         for (let i = 0; i < instanceCount; i++) {
             const itemOffset = i * itemSize;
             const lifeT = Math.min(array[itemOffset + BUILTIN_OFFSET_AGE] / array[itemOffset + BUILTIN_OFFSET_LIFETIME], 1);
-            const segment = (this._private_scales.length - 1) * lifeT;
-            const index = Math.floor(segment);
-            // Constant over the life of a particle but different for each particle
             const scaleT = array[itemOffset + BUILTIN_OFFSET_RANDOM_A];
-            const localT = segment - index;
-            const scaleRange0 = this._private_scales[index];
-            const scaleRange1 = this._private_scales[index + 1];
-            const scale0 = MathUtils.lerp(scaleRange0.min, scaleRange0.max, scaleT);
-            const scale1 = MathUtils.lerp(scaleRange1.min, scaleRange1.max, scaleT);
-            const interpolatedScale = scale0 + (scale1 - scale0) * localT;
-            array[itemOffset + BUILTIN_OFFSET_SCALE_X] = interpolatedScale * this._private_aspectInternal;
-            array[itemOffset + BUILTIN_OFFSET_SCALE_Y] = interpolatedScale;
+            const { a, b, t: localT } = this.curve.sample(lifeT);
+            const scale = MathUtils.lerp(MathUtils.lerp(a.min, a.max, scaleT), MathUtils.lerp(b.min, b.max, scaleT), localT);
+            array[itemOffset + BUILTIN_OFFSET_SCALE_X] = scale * this._private_aspectInternal;
+            array[itemOffset + BUILTIN_OFFSET_SCALE_Y] = scale;
         }
         builtin.needsUpdate = true;
     }

package/dist/emitter/behavior/FXBehaviorTorqueDamping.d.ts

@@ -1,9 +1,10 @@
 import type { FXRange, FXRangeConfig } from "../../miscellaneous/miscellaneous";
 import { FXBehavior } from "./FXBehavior";
 /**
- * Reduces particle angular velocity over time.
+ * Reduces particle angular velocity over time
  *
- * Applies exponential decay to torque. Damping of 0 means no effect, 1 means instant stop.
+ * @remarks
+ * A damping value of `0` has no effect; `1` stops the particle instantly.
  */
 export declare class FXBehaviorTorqueDamping extends FXBehavior<{
     builtin: "Matrix4";
@@ -12,7 +13,7 @@ export declare class FXBehaviorTorqueDamping extends FXBehavior<{
     /**
      * @param damping - Damping coefficient range (0-1). Accepts number, tuple, or range object
      */
-    constructor(damping: number);
+    constructor(damping: FXRangeConfig);
     /** Damping coefficient range (0-1) */
     get damping(): FXRange;
     /** Damping coefficient range (0-1) */

package/dist/emitter/behavior/FXBehaviorTorqueDamping.js

@@ -4,9 +4,10 @@ import { resolveFXRangeConfig, BUILTIN_OFFSET_RANDOM_B, BUILTIN_OFFSET_TORQUE }
 import { FXBehavior } from './FXBehavior.js';
 
 /**
- * Reduces particle angular velocity over time.
+ * Reduces particle angular velocity over time
  *
- * Applies exponential decay to torque. Damping of 0 means no effect, 1 means instant stop.
+ * @remarks
+ * A damping value of `0` has no effect; `1` stops the particle instantly.
  */
 class FXBehaviorTorqueDamping extends FXBehavior {
     /**

package/dist/emitter/behavior/FXBehaviorTorqueNoise.d.ts

@@ -1,9 +1,10 @@
 import type { FXRange, FXRangeConfig } from "../../miscellaneous/miscellaneous";
 import { FXBehavior } from "./FXBehavior";
 /**
- * Applies noise-based angular acceleration to particles.
+ * Applies noise-based angular acceleration to particles
  *
- * Uses 2D noise based on particle position. Higher scale means finer noise detail.
+ * @remarks
+ * Higher `scale` values produce finer noise detail.
  */
 export declare class FXBehaviorTorqueNoise extends FXBehavior<{
     builtin: "Matrix4";
@@ -14,7 +15,7 @@ export declare class FXBehaviorTorqueNoise extends FXBehavior<{
      * @param scale - Noise frequency range. Accepts number, tuple, or range object
      * @param strength - Force multiplier range. Accepts number, tuple, or range object
      */
-    constructor(scale: number, strength: number);
+    constructor(scale: FXRangeConfig, strength: FXRangeConfig);
     /** Noise frequency range */
     get scale(): FXRange;
     /** Force multiplier range */

package/dist/emitter/behavior/FXBehaviorTorqueNoise.js

@@ -6,9 +6,10 @@ import { FXBehavior } from './FXBehavior.js';
 
 const generateNoise3D = modExports.makeNoise3D();
 /**
- * Applies noise-based angular acceleration to particles.
+ * Applies noise-based angular acceleration to particles
  *
- * Uses 2D noise based on particle position. Higher scale means finer noise detail.
+ * @remarks
+ * Higher `scale` values produce finer noise detail.
  */
 class FXBehaviorTorqueNoise extends FXBehavior {
     /**

package/dist/emitter/behavior/FXBehaviorTorqueOverLife.d.ts

@@ -0,0 +1,17 @@
+import type { FXCurve1DConfig } from "../../miscellaneous/curve/FXCurve1D";
+import { FXCurve1D } from "../../miscellaneous/curve/FXCurve1D";
+import type { FXRange } from "../../miscellaneous/miscellaneous";
+import { FXBehavior } from "./FXBehavior";
+/**
+ * Animates particle angular velocity over lifetime using a {@link FXCurve1D}
+ */
+export declare class FXBehaviorTorqueOverLife extends FXBehavior<{
+    builtin: "Matrix4";
+}> {
+    /** Active torque curve */
+    curve: FXCurve1D<FXRange>;
+    /**
+     * @param curve - Torque curve; accepts a {@link FXCurve1D} instance or a `FXRange[]` shorthand
+     */
+    constructor(curve: FXCurve1DConfig<FXRange>);
+}

package/dist/emitter/behavior/FXBehaviorTorqueOverLife.js

@@ -0,0 +1,34 @@
+import { MathUtils } from 'three';
+import { FXCurve1D } from '../../miscellaneous/curve/FXCurve1D.js';
+import { BUILTIN_OFFSET_AGE, BUILTIN_OFFSET_LIFETIME, BUILTIN_OFFSET_RANDOM_B, BUILTIN_OFFSET_TORQUE } from '../../miscellaneous/miscellaneous.js';
+import { FXBehavior } from './FXBehavior.js';
+
+/**
+ * Animates particle angular velocity over lifetime using a {@link FXCurve1D}
+ */
+class FXBehaviorTorqueOverLife extends FXBehavior {
+    /**
+     * @param curve - Torque curve; accepts a {@link FXCurve1D} instance or a `FXRange[]` shorthand
+     */
+    constructor(curve) {
+        super();
+        /** @internal */
+        this.requiredProperties = { builtin: "Matrix4" };
+        this.curve = new FXCurve1D(curve);
+    }
+    /** @internal */
+    update(properties, instanceCount) {
+        const { builtin } = properties;
+        const { array, itemSize } = builtin;
+        for (let i = 0; i < instanceCount; i++) {
+            const itemOffset = i * itemSize;
+            const lifeT = Math.min(array[itemOffset + BUILTIN_OFFSET_AGE] / array[itemOffset + BUILTIN_OFFSET_LIFETIME], 1);
+            const torqueT = array[itemOffset + BUILTIN_OFFSET_RANDOM_B];
+            const { a, b, t: localT } = this.curve.sample(lifeT);
+            array[itemOffset + BUILTIN_OFFSET_TORQUE] = MathUtils.lerp(MathUtils.lerp(a.min, a.max, torqueT), MathUtils.lerp(b.min, b.max, torqueT), localT);
+        }
+        builtin.needsUpdate = true;
+    }
+}
+
+export { FXBehaviorTorqueOverLife };

package/dist/emitter/behavior/FXBehaviorVelocityDamping.d.ts

@@ -1,9 +1,10 @@
 import type { FXRange, FXRangeConfig } from "../../miscellaneous/miscellaneous";
 import { FXBehavior } from "./FXBehavior";
 /**
- * Reduces particle velocity over time.
+ * Reduces particle velocity over time
  *
- * Applies exponential decay to velocity. Damping of 0 means no effect, 1 means instant stop.
+ * @remarks
+ * A damping value of `0` has no effect; `1` stops the particle instantly.
  */
 export declare class FXBehaviorVelocityDamping extends FXBehavior<{
     builtin: "Matrix4";

package/dist/emitter/behavior/FXBehaviorVelocityDamping.js

@@ -4,9 +4,10 @@ import { resolveFXRangeConfig, BUILTIN_OFFSET_RANDOM_B, BUILTIN_OFFSET_VELOCITY_
 import { FXBehavior } from './FXBehavior.js';
 
 /**
- * Reduces particle velocity over time.
+ * Reduces particle velocity over time
  *
- * Applies exponential decay to velocity. Damping of 0 means no effect, 1 means instant stop.
+ * @remarks
+ * A damping value of `0` has no effect; `1` stops the particle instantly.
  */
 class FXBehaviorVelocityDamping extends FXBehavior {
     /**

package/dist/emitter/behavior/FXBehaviorVelocityNoise.d.ts

@@ -1,9 +1,10 @@
 import type { FXRange, FXRangeConfig } from "../../miscellaneous/miscellaneous";
 import { FXBehavior } from "./FXBehavior";
 /**
- * Applies noise-based acceleration to particles.
+ * Applies noise-based acceleration to particles
  *
- * Uses 2D noise based on particle position. Higher scale means finer noise detail.
+ * @remarks
+ * Higher `scale` values produce finer noise detail.
  */
 export declare class FXBehaviorVelocityNoise extends FXBehavior<{
     builtin: "Matrix4";
@@ -11,10 +12,10 @@ export declare class FXBehaviorVelocityNoise extends FXBehavior<{
     private scaleInternal;
     private strengthInternal;
     /**
-     * @param scale - Noise frequency range. Accepts number, tuple, or range object
-     * @param strength - Force multiplier range. Accepts number, tuple, or range object
+     * @param scale - Noise frequency range; must be positive.
+     * @param strength - Force multiplier range; must be non-negative.
      */
-    constructor(scale?: number, strength?: number);
+    constructor(scale: FXRangeConfig, strength: FXRangeConfig);
     /** Noise frequency range */
     get scale(): FXRange;
     /** Force multiplier range */

package/dist/emitter/behavior/FXBehaviorVelocityNoise.js

@@ -8,16 +8,17 @@ const generateNoise3D0 = modExports.makeNoise3D();
 const generateNoise3D1 = modExports.makeNoise3D();
 const generateNoise3D2 = modExports.makeNoise3D();
 /**
- * Applies noise-based acceleration to particles.
+ * Applies noise-based acceleration to particles
  *
- * Uses 2D noise based on particle position. Higher scale means finer noise detail.
+ * @remarks
+ * Higher `scale` values produce finer noise detail.
  */
 class FXBehaviorVelocityNoise extends FXBehavior {
     /**
-     * @param scale - Noise frequency range. Accepts number, tuple, or range object
-     * @param strength - Force multiplier range. Accepts number, tuple, or range object
+     * @param scale - Noise frequency range; must be positive.
+     * @param strength - Force multiplier range; must be non-negative.
      */
-    constructor(scale = 100, strength = 500) {
+    constructor(scale, strength) {
         super();
         /** @internal */
         this.requiredProperties = { builtin: "Matrix4" };

package/dist/emitter/behavior/FXBehaviorVelocityOverLife.d.ts

@@ -0,0 +1,20 @@
+import type { FXCurve1DConfig } from "../../miscellaneous/curve/FXCurve1D";
+import { FXCurve1D } from "../../miscellaneous/curve/FXCurve1D";
+import type { FXRange } from "../../miscellaneous/miscellaneous";
+import { FXBehavior } from "./FXBehavior";
+/**
+ * Animates particle speed over lifetime using a {@link FXCurve1D}
+ *
+ * @remarks
+ * Particles with zero velocity are not affected.
+ */
+export declare class FXBehaviorVelocityOverLife extends FXBehavior<{
+    builtin: "Matrix4";
+}> {
+    /** Active speed curve */
+    curve: FXCurve1D<FXRange>;
+    /**
+     * @param curve - Speed curve; accepts a {@link FXCurve1D} instance or a `FXRange[]` shorthand
+     */
+    constructor(curve: FXCurve1DConfig<FXRange>);
+}

package/dist/emitter/behavior/FXBehaviorVelocityOverLife.js

@@ -0,0 +1,48 @@
+import { MathUtils } from 'three';
+import { FXCurve1D } from '../../miscellaneous/curve/FXCurve1D.js';
+import { BUILTIN_OFFSET_AGE, BUILTIN_OFFSET_LIFETIME, BUILTIN_OFFSET_VELOCITY_X, BUILTIN_OFFSET_VELOCITY_Y, BUILTIN_OFFSET_VELOCITY_Z, BUILTIN_OFFSET_RANDOM_A } from '../../miscellaneous/miscellaneous.js';
+import { FXBehavior } from './FXBehavior.js';
+
+/**
+ * Animates particle speed over lifetime using a {@link FXCurve1D}
+ *
+ * @remarks
+ * Particles with zero velocity are not affected.
+ */
+class FXBehaviorVelocityOverLife extends FXBehavior {
+    /**
+     * @param curve - Speed curve; accepts a {@link FXCurve1D} instance or a `FXRange[]` shorthand
+     */
+    constructor(curve) {
+        super();
+        /** @internal */
+        this.requiredProperties = { builtin: "Matrix4" };
+        this.curve = new FXCurve1D(curve);
+    }
+    /** @internal */
+    update(properties, instanceCount) {
+        const { builtin } = properties;
+        const { array, itemSize } = builtin;
+        for (let i = 0; i < instanceCount; i++) {
+            const itemOffset = i * itemSize;
+            const lifeT = Math.min(array[itemOffset + BUILTIN_OFFSET_AGE] / array[itemOffset + BUILTIN_OFFSET_LIFETIME], 1);
+            const velocityX = array[itemOffset + BUILTIN_OFFSET_VELOCITY_X];
+            const velocityY = array[itemOffset + BUILTIN_OFFSET_VELOCITY_Y];
+            const velocityZ = array[itemOffset + BUILTIN_OFFSET_VELOCITY_Z];
+            const currentSpeed = Math.sqrt(velocityX * velocityX + velocityY * velocityY + velocityZ * velocityZ);
+            if (currentSpeed === 0) {
+                continue;
+            }
+            const velocityT = array[itemOffset + BUILTIN_OFFSET_RANDOM_A];
+            const { a, b, t: localT } = this.curve.sample(lifeT);
+            const targetSpeed = MathUtils.lerp(MathUtils.lerp(a.min, a.max, velocityT), MathUtils.lerp(b.min, b.max, velocityT), localT);
+            const scaleFactor = targetSpeed / currentSpeed;
+            array[itemOffset + BUILTIN_OFFSET_VELOCITY_X] = velocityX * scaleFactor;
+            array[itemOffset + BUILTIN_OFFSET_VELOCITY_Y] = velocityY * scaleFactor;
+            array[itemOffset + BUILTIN_OFFSET_VELOCITY_Z] = velocityZ * scaleFactor;
+        }
+        builtin.needsUpdate = true;
+    }
+}
+
+export { FXBehaviorVelocityOverLife };

package/dist/emitter/spawn/FXSpawn.d.ts

@@ -1,9 +1,11 @@
 import type { FXPropertyName } from "../../instancedParticle/shared";
 /**
- * Base class for particle spawn modules.
+ * Abstract base for particle spawn modules that initialize per-particle properties at birth
  *
- * Spawn modules initialize particle properties when particles are created.
+ * @typeParam T - Map of local property keys to {@link FXPropertyName} identifiers,
+ * declaring which particle attributes this spawn module writes
  */
 export declare abstract class FXSpawn<T extends Record<string, FXPropertyName> = Record<string, FXPropertyName>> {
+    /** Releases any resources held by this spawn module */
     destroy?(): void;
 }

package/dist/emitter/spawn/FXSpawn.js

@@ -1,7 +1,8 @@
 /**
- * Base class for particle spawn modules.
+ * Abstract base for particle spawn modules that initialize per-particle properties at birth
  *
- * Spawn modules initialize particle properties when particles are created.
+ * @typeParam T - Map of local property keys to {@link FXPropertyName} identifiers,
+ * declaring which particle attributes this spawn module writes
  */
 class FXSpawn {
 }

package/dist/emitter/spawn/FXSpawnBox.d.ts

@@ -2,26 +2,18 @@ import type { Vector3Like } from "../../miscellaneous/math";
 import type { FXVector3Config } from "../../miscellaneous/miscellaneous";
 import { FXSpawn } from "./FXSpawn";
 /**
- * Spawns particles at random positions within an axis-aligned bounding box.
- *
- * Position is chosen uniformly within the bounds defined by min and max.
+ * Spawns particles at random positions within an axis-aligned bounding box centered at the origin
  */
 export declare class FXSpawnBox extends FXSpawn<{
     builtin: "Matrix4";
 }> {
-    private minInternal;
-    private maxInternal;
+    private sizeInternal;
     /**
-     * @param min - Minimum corner of the spawn box
-     * @param max - Maximum corner of the spawn box
+     * @param size - Dimensions of the spawn box. Defaults to `{ x: 1, y: 1, z: 1 }`
      */
-    constructor(min?: FXVector3Config, max?: FXVector3Config);
-    /** Minimum corner of the spawn box */
-    get min(): Vector3Like;
-    /** Maximum corner of the spawn box */
-    get max(): Vector3Like;
-    /** Minimum corner of the spawn box */
-    set min(value: FXVector3Config);
-    /** Maximum corner of the spawn box */
-    set max(value: FXVector3Config);
+    constructor(size?: FXVector3Config);
+    /** Size of the spawn box */
+    get size(): Vector3Like;
+    /** Size of the spawn box */
+    set size(value: FXVector3Config);
 }

package/dist/emitter/spawn/FXSpawnBox.js

@@ -4,61 +4,45 @@ import { resolveFXVector3Config, BUILTIN_OFFSET_POSITION_X, BUILTIN_OFFSET_POSIT
 import { FXSpawn } from './FXSpawn.js';
 
 /**
- * Spawns particles at random positions within an axis-aligned bounding box.
- *
- * Position is chosen uniformly within the bounds defined by min and max.
+ * Spawns particles at random positions within an axis-aligned bounding box centered at the origin
  */
 class FXSpawnBox extends FXSpawn {
     /**
-     * @param min - Minimum corner of the spawn box
-     * @param max - Maximum corner of the spawn box
+     * @param size - Dimensions of the spawn box. Defaults to `{ x: 1, y: 1, z: 1 }`
      */
-    constructor(min = { x: -1, y: -1, z: -1 }, max = { x: 1, y: 1, z: 1 }) {
+    constructor(size = { x: 1, y: 1, z: 1 }) {
         super();
         /** @internal */
         this.requiredProperties = { builtin: "Matrix4" };
-        this._private_minInternal = resolveFXVector3Config(min);
-        this._private_maxInternal = resolveFXVector3Config(max);
-        assertValidNumber(this._private_minInternal.x, "FXSpawnBox.constructor.min.x");
-        assertValidNumber(this._private_minInternal.y, "FXSpawnBox.constructor.min.y");
-        assertValidNumber(this._private_minInternal.z, "FXSpawnBox.constructor.min.z");
-        assertValidNumber(this._private_maxInternal.x, "FXSpawnBox.constructor.max.x");
-        assertValidNumber(this._private_maxInternal.y, "FXSpawnBox.constructor.max.y");
-        assertValidNumber(this._private_maxInternal.z, "FXSpawnBox.constructor.max.z");
+        this._private_sizeInternal = resolveFXVector3Config(size);
+        assertValidNumber(this._private_sizeInternal.x, "FXSpawnBox.constructor.size.x");
+        assertValidNumber(this._private_sizeInternal.y, "FXSpawnBox.constructor.size.y");
+        assertValidNumber(this._private_sizeInternal.z, "FXSpawnBox.constructor.size.z");
     }
-    /** Minimum corner of the spawn box */
-    get min() {
-        return this._private_minInternal;
+    /** Size of the spawn box */
+    get size() {
+        return this._private_sizeInternal;
     }
-    /** Maximum corner of the spawn box */
-    get max() {
-        return this._private_maxInternal;
-    }
-    /** Minimum corner of the spawn box */
-    set min(value) {
-        this._private_minInternal = resolveFXVector3Config(value);
-        assertValidNumber(this._private_minInternal.x, "FXSpawnBox.min.x");
-        assertValidNumber(this._private_minInternal.y, "FXSpawnBox.min.y");
-        assertValidNumber(this._private_minInternal.z, "FXSpawnBox.min.z");
-    }
-    /** Maximum corner of the spawn box */
-    set max(value) {
-        this._private_maxInternal = resolveFXVector3Config(value);
-        assertValidNumber(this._private_maxInternal.x, "FXSpawnBox.max.x");
-        assertValidNumber(this._private_maxInternal.y, "FXSpawnBox.max.y");
-        assertValidNumber(this._private_maxInternal.z, "FXSpawnBox.max.z");
+    /** Size of the spawn box */
+    set size(value) {
+        this._private_sizeInternal = resolveFXVector3Config(value);
+        assertValidNumber(this._private_sizeInternal.x, "FXSpawnBox.size.x");
+        assertValidNumber(this._private_sizeInternal.y, "FXSpawnBox.size.y");
+        assertValidNumber(this._private_sizeInternal.z, "FXSpawnBox.size.z");
     }
     /** @internal */
     spawn(properties, instanceBegin, instanceEnd) {
         const { builtin } = properties;
         const { array, itemSize } = builtin;
-        const { x: minX, y: minY, z: minZ } = this._private_minInternal;
-        const { x: maxX, y: maxY, z: maxZ } = this._private_maxInternal;
+        const { x: sizeX, y: sizeY, z: sizeZ } = this._private_sizeInternal;
+        const halfX = sizeX * 0.5;
+        const halfY = sizeY * 0.5;
+        const halfZ = sizeZ * 0.5;
         for (let i = instanceBegin; i < instanceEnd; i++) {
             const itemOffset = i * itemSize;
-            array[itemOffset + BUILTIN_OFFSET_POSITION_X] = MathUtils.randFloat(minX, maxX);
-            array[itemOffset + BUILTIN_OFFSET_POSITION_Y] = MathUtils.randFloat(minY, maxY);
-            array[itemOffset + BUILTIN_OFFSET_POSITION_Z] = MathUtils.randFloat(minZ, maxZ);
+            array[itemOffset + BUILTIN_OFFSET_POSITION_X] = MathUtils.randFloat(-halfX, halfX);
+            array[itemOffset + BUILTIN_OFFSET_POSITION_Y] = MathUtils.randFloat(-halfY, halfY);
+            array[itemOffset + BUILTIN_OFFSET_POSITION_Z] = MathUtils.randFloat(-halfZ, halfZ);
         }
         builtin.needsUpdate = true;
     }

package/dist/emitter/spawn/{FXSpawnRandomLifetime.d.ts → FXSpawnLifetime.d.ts}

@@ -1,16 +1,14 @@
 import type { FXRange, FXRangeConfig } from "../../miscellaneous/miscellaneous";
 import { FXSpawn } from "./FXSpawn";
 /**
- * Assigns random lifetime to particles.
- *
- * Lifetime is chosen uniformly from the specified range. Age is set to 0.
+ * Assigns a random lifetime to each spawned particle
  */
-export declare class FXSpawnRandomLifetime extends FXSpawn<{
+export declare class FXSpawnLifetime extends FXSpawn<{
     builtin: "Matrix4";
 }> {
     private lifetimeInternal;
     /**
-     * @param lifetime - Lifetime range in seconds. Accepts number, tuple, or range object
+     * @param lifetime - Lifetime range in seconds; must be positive. Defaults to `{ min: 4, max: 8 }`
      */
     constructor(lifetime?: FXRangeConfig);
     /** Lifetime range in seconds */

package/dist/emitter/spawn/{FXSpawnRandomLifetime.js → FXSpawnLifetime.js}

@@ -4,21 +4,19 @@ import { resolveFXRangeConfig, BUILTIN_OFFSET_LIFETIME, BUILTIN_OFFSET_AGE } fro
 import { FXSpawn } from './FXSpawn.js';
 
 /**
- * Assigns random lifetime to particles.
- *
- * Lifetime is chosen uniformly from the specified range. Age is set to 0.
+ * Assigns a random lifetime to each spawned particle
  */
-class FXSpawnRandomLifetime extends FXSpawn {
+class FXSpawnLifetime extends FXSpawn {
     /**
-     * @param lifetime - Lifetime range in seconds. Accepts number, tuple, or range object
+     * @param lifetime - Lifetime range in seconds; must be positive. Defaults to `{ min: 4, max: 8 }`
      */
     constructor(lifetime = { min: 4, max: 8 }) {
         super();
         /** @internal */
         this.requiredProperties = { builtin: "Matrix4" };
         this._private_lifetimeInternal = resolveFXRangeConfig(lifetime);
-        assertValidPositiveNumber(this._private_lifetimeInternal.min, "FXSpawnRandomLifetime.constructor.lifetime.min");
-        assertValidPositiveNumber(this._private_lifetimeInternal.max, "FXSpawnRandomLifetime.constructor.lifetime.max");
+        assertValidPositiveNumber(this._private_lifetimeInternal.min, "FXSpawnLifetime.constructor.lifetime.min");
+        assertValidPositiveNumber(this._private_lifetimeInternal.max, "FXSpawnLifetime.constructor.lifetime.max");
     }
     /** Lifetime range in seconds */
     get lifetime() {
@@ -27,8 +25,8 @@ class FXSpawnRandomLifetime extends FXSpawn {
     /** Lifetime range in seconds */
     set lifetime(value) {
         this._private_lifetimeInternal = resolveFXRangeConfig(value);
-        assertValidPositiveNumber(this._private_lifetimeInternal.min, "FXSpawnRandomLifetime.lifetime.min");
-        assertValidPositiveNumber(this._private_lifetimeInternal.max, "FXSpawnRandomLifetime.lifetime.max");
+        assertValidPositiveNumber(this._private_lifetimeInternal.min, "FXSpawnLifetime.lifetime.min");
+        assertValidPositiveNumber(this._private_lifetimeInternal.max, "FXSpawnLifetime.lifetime.max");
     }
     /** @internal */
     spawn(properties, instanceBegin, instanceEnd) {
@@ -44,4 +42,4 @@ class FXSpawnRandomLifetime extends FXSpawn {
     }
 }
 
-export { FXSpawnRandomLifetime };
+export { FXSpawnLifetime };

package/dist/emitter/spawn/FXSpawnOffset.d.ts

@@ -1,10 +1,19 @@
 import type { Vector3Like } from "../../miscellaneous/math";
 import type { FXVector3Config } from "../../miscellaneous/miscellaneous";
 import { FXSpawn } from "./FXSpawn";
+/**
+ * Shifts particle spawn positions by a fixed offset
+ *
+ * @remarks
+ * Adds to the position set by any preceding spawn step rather than overwriting it.
+ */
 export declare class FXSpawnOffset extends FXSpawn<{
     builtin: "Matrix4";
 }> {
     private offsetInternal;
+    /**
+     * @param offset - Position offset applied to each spawned particle. Defaults to `{ x: 0, y: 0, z: 0 }`
+     */
     constructor(offset?: FXVector3Config);
     /** Particle position offset */
     get offset(): Vector3Like;

package/dist/emitter/spawn/FXSpawnOffset.js

@@ -2,7 +2,16 @@ import { assertValidNumber } from '../../miscellaneous/asserts.js';
 import { resolveFXVector3Config, BUILTIN_OFFSET_POSITION_X, BUILTIN_OFFSET_POSITION_Y, BUILTIN_OFFSET_POSITION_Z } from '../../miscellaneous/miscellaneous.js';
 import { FXSpawn } from './FXSpawn.js';
 
+/**
+ * Shifts particle spawn positions by a fixed offset
+ *
+ * @remarks
+ * Adds to the position set by any preceding spawn step rather than overwriting it.
+ */
 class FXSpawnOffset extends FXSpawn {
+    /**
+     * @param offset - Position offset applied to each spawned particle. Defaults to `{ x: 0, y: 0, z: 0 }`
+     */
     constructor(offset = { x: 0, y: 0, z: 0 }) {
         super();
         /** @internal */