sparcoon 0.5.0 → 0.6.1

package/README.md

@@ -15,7 +15,7 @@ Interactive visual **[EDITOR](https://jango-git.github.io/sparcoon/)**
 
 - **FXEmitter** extends `Object3D`. Manages emission, lifetime, pooling, rendering. One draw call per emitter. Optional back-to-front sorting.
 - **Spawn modules** set initial particle state: position (box/sphere/point), velocity (cone), rotation, scale, lifetime. Numeric params accept ranges.
-- **Behavior modules** update particles per frame: directional/point gravity, velocity/torque damping, simplex noise, scale-over-life.
+- **Behavior modules** update particles per frame: directional/point force, velocity/torque damping, simplex noise, scale-over-life, velocity/torque over lifetime.
 - **Materials**: `FXUnlitMaterial` (MeshBasicMaterial), `FXDiffuseMaterial` (MeshLambertMaterial + optional subsurface scatter). Shadow support.
 - **Nodes** are composable material inputs: color-over-life, static/animated textures, normals (flat/spherical/map).
 
@@ -30,9 +30,9 @@ const LIFETIME = 6;
 const smoke = new FXEmitter(
   [
     new FXSpawnBox(areaMin, areaMax),
-    new FXSpawnRandomLifetime({ min: LIFETIME * 0.5, max: LIFETIME }),
-    new FXSpawnRandomScale({ min: 8, max: 16 }),
-    new FXSpawnRandomRotation(),
+    new FXSpawnLifetime({ min: LIFETIME * 0.5, max: LIFETIME }),
+    new FXSpawnScale({ min: 8, max: 16 }),
+    new FXSpawnRotation(),
   ],
   [],
   new FXDiffuseMaterial({
@@ -43,13 +43,13 @@ const smoke = new FXEmitter(
     shadowSensitivity: 0.25,
     premultipliedAlpha: true,
     albedoNodes: [
-      new FXAnimatedTextureNode({
+      new FXNodeAnimatedTexture({
         texture: smokeAtlas,
         rows: 8,
         columns: 8,
         interpolate: true,
       }),
-      new FXColorOverLifeNode([
+      new FXNodeColorOverLife([
         new FXColor(0xffffff, 0),
         new FXColor(0xffffff, 0.4),
         new FXColor(0xffffff, 0.4),

package/dist/emitter/FXEmitter.Internal.d.ts

@@ -1,26 +1,74 @@
 import type { Camera } from "three";
 import type { FXPropertyName, GLTypeInfo } from "../instancedParticle/shared";
 import type { FXEmitter } from "./FXEmitter";
+/**
+ * Configuration options for {@link FXEmitter}
+ */
 export interface FXEmitterOptions {
+    /**
+     * Initial buffer size in particles; grows automatically when exceeded
+     *
+     * @defaultValue `32`
+     */
     expectedCapacity: number;
+    /**
+     * Growth increment added to the buffer when capacity is reached
+     *
+     * @defaultValue `32`
+     */
     capacityStep: number;
-    automaticallyDestroyModules: boolean;
+    /**
+     * Enables shadow casting
+     *
+     * @defaultValue `false`
+     */
     castShadow: boolean;
+    /**
+     * Enables shadow receiving
+     *
+     * @defaultValue `false`
+     */
     receiveShadow: boolean;
+    /** Camera used for back-to-front depth sorting; omit to disable sorting */
     sortCamera: Camera;
+    /**
+     * Fraction of frames on which sorting runs (`1` = every frame, `0.1` = ~every 10th frame)
+     *
+     * @defaultValue `0.1`
+     */
     sortFraction: number;
 }
+/**
+ * Options for {@link FXEmitter.burst}
+ */
 export interface FXEmitterBurstOptions {
+    /**
+     * Delay in seconds before particles are spawned
+     *
+     * @defaultValue `0`
+     */
     delay: number;
 }
+/**
+ * Options for {@link FXEmitter.play}
+ */
 export interface FXEmitterPlayOptions {
+    /**
+     * Delay in seconds before emission starts
+     *
+     * @defaultValue `0`
+     */
     delay: number;
+    /**
+     * Total emission duration in seconds
+     *
+     * @defaultValue `Infinity`
+     */
     duration: number;
 }
 export declare const EMITTERS: FXEmitter[];
 export declare const EMITTER_DEFAULT_EXPECTED_CAPACITY = 32;
 export declare const EMITTER_DEFAULT_CAPACITY_STEP = 32;
-export declare const EMITTER_DEFAULT_AUTOMATICALLY_DESTROY_MODULES = true;
 export declare const EMITTER_DEFAULT_CAST_SHADOW = false;
 export declare const EMITTER_DEFAULT_RECEIVE_SHADOW = false;
 export declare const EMITTER_DEFAULT_SORT_FRACTION: number;

package/dist/emitter/FXEmitter.Internal.js

@@ -3,7 +3,6 @@ import { resolveGLSLTypeInfo } from '../instancedParticle/shared.js';
 const EMITTERS = new Array();
 const EMITTER_DEFAULT_EXPECTED_CAPACITY = 32;
 const EMITTER_DEFAULT_CAPACITY_STEP = 32;
-const EMITTER_DEFAULT_AUTOMATICALLY_DESTROY_MODULES = true;
 const EMITTER_DEFAULT_CAST_SHADOW = false;
 const EMITTER_DEFAULT_RECEIVE_SHADOW = false;
 const EMITTER_DEFAULT_SORT_FRACTION = 1 / 10;
@@ -27,4 +26,4 @@ function collectProperties(keeper, modules, debugContext) {
     }
 }
 
-export { EMITTERS, EMITTER_DEFAULT_AUTOMATICALLY_DESTROY_MODULES, EMITTER_DEFAULT_CAPACITY_STEP, EMITTER_DEFAULT_CAST_SHADOW, EMITTER_DEFAULT_EXPECTED_CAPACITY, EMITTER_DEFAULT_PREWARM_MAX_STEP_COUNT, EMITTER_DEFAULT_PREWARM_MIN_STEP_DURATION, EMITTER_DEFAULT_RECEIVE_SHADOW, EMITTER_DEFAULT_SORT_FRACTION, collectProperties };
+export { EMITTERS, EMITTER_DEFAULT_CAPACITY_STEP, EMITTER_DEFAULT_CAST_SHADOW, EMITTER_DEFAULT_EXPECTED_CAPACITY, EMITTER_DEFAULT_PREWARM_MAX_STEP_COUNT, EMITTER_DEFAULT_PREWARM_MIN_STEP_DURATION, EMITTER_DEFAULT_RECEIVE_SHADOW, EMITTER_DEFAULT_SORT_FRACTION, collectProperties };

package/dist/emitter/FXEmitter.d.ts

@@ -4,11 +4,19 @@ import type { FXMaterial } from "../materials/FXMaterial/FXMaterial";
 import type { FXBehavior } from "./behavior/FXBehavior";
 import type { FXEmitterBurstOptions, FXEmitterOptions, FXEmitterPlayOptions } from "./FXEmitter.Internal";
 import type { FXSpawn } from "./spawn/FXSpawn";
+/**
+ * Particle emitter - add to a scene to make particles visible
+ *
+ * @remarks
+ * Drives a pipeline of spawn modules (run once at particle birth) and behavior modules
+ * (run every frame). Call {@link FXEmitter.onWillRender} each frame to tick the system.
+ */
 export declare class FXEmitter extends Object3D {
     private readonly spawnSequence;
     private readonly behaviorSequence;
-    automaticallyDestroyModules: boolean;
+    /** Camera used for back-to-front depth sorting; `undefined` disables sorting */
     sortCamera?: Camera;
+    /** Fraction of frames on which sorting runs (`1` = every frame, `0.1` = ~every 10th frame); defaults to `0.1` */
     sortFraction: number;
     private readonly mesh;
     private readonly material;
@@ -17,13 +25,52 @@ export declare class FXEmitter extends Object3D {
     private readonly activePlays;
     private sortingAccumulator;
     private readonly sortingCameraWorldPosition;
+    /**
+     * @param spawnSequence - Modules executed in order when particles are born
+     * @param behaviorSequence - Modules executed in order every frame for all live particles
+     * @param material - Particle material
+     * @param options - Emitter configuration
+     */
     constructor(spawnSequence: FXSpawn[], behaviorSequence: readonly FXBehavior[], material: FXMaterial, options?: Partial<FXEmitterOptions>);
+    /**
+     * Ticks all active emitters; call once per frame before rendering
+     *
+     * @param deltaTime - Elapsed time in seconds since the last frame
+     */
     static onWillRender: (deltaTime: number) => void;
+    /** Unregisters the emitter, removes it from the scene, and disposes modules and material */
     destroy(): void;
+    /**
+     * Spawns `count` particles immediately, or after a delay when `options.delay` is set
+     *
+     * @param count - Number of particles to spawn
+     * @param options - Burst options
+     * @returns Handler that can be passed to {@link stop} to cancel a pending delayed burst
+     */
     burst(count: number, options?: Partial<FXEmitterBurstOptions>): number;
+    /**
+     * Starts continuous emission at the given rate
+     *
+     * @param rate - Particles per second
+     * @param options - Play options
+     * @returns Handler that can be passed to {@link stop} to cancel
+     */
     play(rate: number, options?: Partial<FXEmitterPlayOptions>): number;
+    /**
+     * Stops an active play or pending burst by handler; stops all when called with no arguments
+     *
+     * @param handler - Handler returned by {@link play} or {@link burst}; omit to stop everything
+     * @returns `true` if anything was stopped
+     */
     stop(handler?: number): boolean;
+    /**
+     * Simulates the emitter forward in time to avoid a cold-start on frame 0
+     *
+     * @param duration - Total time to simulate in seconds
+     * @param stepDuration - Maximum simulation step size in seconds. Defaults to `1/60`
+     */
     prewarm(duration: number, stepDuration?: number): void;
+    /** Kills all live particles and cancels all active plays and pending bursts */
     reset(): void;
     private tick;
     private readonly onRendering;

package/dist/emitter/FXEmitter.js

@@ -1,10 +1,24 @@
 import { Object3D, Vector3 } from 'three';
 import { FXInstancedParticle } from '../instancedParticle/FXInstancedParticle.js';
 import { resolveGLSLTypeInfo } from '../instancedParticle/shared.js';
+import { assertValidPositiveNumber, assertValidNonNegativeNumber } from '../miscellaneous/asserts.js';
 import { BUILTIN_OFFSET_AGE, BUILTIN_OFFSET_POSITION_X, BUILTIN_OFFSET_VELOCITY_X, BUILTIN_OFFSET_POSITION_Y, BUILTIN_OFFSET_VELOCITY_Y, BUILTIN_OFFSET_POSITION_Z, BUILTIN_OFFSET_VELOCITY_Z, BUILTIN_OFFSET_ROTATION, BUILTIN_OFFSET_TORQUE, BUILTIN_OFFSET_RANDOM_A, BUILTIN_OFFSET_RANDOM_B, BUILTIN_OFFSET_RANDOM_C } from '../miscellaneous/miscellaneous.js';
-import { EMITTERS, collectProperties, EMITTER_DEFAULT_EXPECTED_CAPACITY, EMITTER_DEFAULT_CAPACITY_STEP, EMITTER_DEFAULT_CAST_SHADOW, EMITTER_DEFAULT_RECEIVE_SHADOW, EMITTER_DEFAULT_AUTOMATICALLY_DESTROY_MODULES, EMITTER_DEFAULT_SORT_FRACTION, EMITTER_DEFAULT_PREWARM_MIN_STEP_DURATION, EMITTER_DEFAULT_PREWARM_MAX_STEP_COUNT } from './FXEmitter.Internal.js';
+import { EMITTERS, collectProperties, EMITTER_DEFAULT_EXPECTED_CAPACITY, EMITTER_DEFAULT_CAPACITY_STEP, EMITTER_DEFAULT_CAST_SHADOW, EMITTER_DEFAULT_RECEIVE_SHADOW, EMITTER_DEFAULT_SORT_FRACTION, EMITTER_DEFAULT_PREWARM_MIN_STEP_DURATION, EMITTER_DEFAULT_PREWARM_MAX_STEP_COUNT } from './FXEmitter.Internal.js';
 
+/**
+ * Particle emitter - add to a scene to make particles visible
+ *
+ * @remarks
+ * Drives a pipeline of spawn modules (run once at particle birth) and behavior modules
+ * (run every frame). Call {@link FXEmitter.onWillRender} each frame to tick the system.
+ */
 class FXEmitter extends Object3D {
+    /**
+     * @param spawnSequence - Modules executed in order when particles are born
+     * @param behaviorSequence - Modules executed in order every frame for all live particles
+     * @param material - Particle material
+     * @param options - Emitter configuration
+     */
     constructor(_private_spawnSequence, _private_behaviorSequence, material, options = {}) {
         super();
         this._private_spawnSequence = _private_spawnSequence;
@@ -25,6 +39,15 @@ class FXEmitter extends Object3D {
                 }
             }
         };
+        if (options.expectedCapacity !== undefined) {
+            assertValidPositiveNumber(options.expectedCapacity, "FXEmitter.constructor.options.expectedCapacity");
+        }
+        if (options.capacityStep !== undefined) {
+            assertValidPositiveNumber(options.capacityStep, "FXEmitter.constructor.options.capacityStep");
+        }
+        if (options.sortFraction !== undefined) {
+            assertValidNonNegativeNumber(options.sortFraction, "FXEmitter.constructor.options.sortFraction");
+        }
         const collectedProperties = {
             builtin: resolveGLSLTypeInfo("Matrix4"),
         };
@@ -40,33 +63,42 @@ class FXEmitter extends Object3D {
         if (options.receiveShadow ?? EMITTER_DEFAULT_RECEIVE_SHADOW) {
             this._private_mesh.receiveShadow = true;
         }
-        this.automaticallyDestroyModules =
-            options.automaticallyDestroyModules ?? EMITTER_DEFAULT_AUTOMATICALLY_DESTROY_MODULES;
         this.sortCamera = options.sortCamera;
         this.sortFraction = options.sortFraction ?? EMITTER_DEFAULT_SORT_FRACTION;
         this._private_material = material;
         this.add(this._private_mesh);
         EMITTERS.push(this);
     }
+    /** Unregisters the emitter, removes it from the scene, and disposes modules and material */
     destroy() {
         const index = EMITTERS.indexOf(this);
         if (index !== -1) {
             EMITTERS.splice(index, 1);
         }
-        if (this.automaticallyDestroyModules) {
-            for (const module of this._private_spawnSequence) {
-                module.destroy?.();
-            }
-            for (const module of this._private_behaviorSequence) {
-                module.destroy?.();
-            }
-            this._private_material.destroy();
+        for (const module of this._private_spawnSequence) {
+            module.destroy?.();
         }
+        for (const module of this._private_behaviorSequence) {
+            module.destroy?.();
+        }
+        this._private_material.destroy();
+        this._private_mesh.material?.dispose();
+        this._private_mesh.customDepthMaterial?.dispose();
+        this._private_mesh.customDistanceMaterial?.dispose();
         this.removeFromParent();
     }
+    /**
+     * Spawns `count` particles immediately, or after a delay when `options.delay` is set
+     *
+     * @param count - Number of particles to spawn
+     * @param options - Burst options
+     * @returns Handler that can be passed to {@link stop} to cancel a pending delayed burst
+     */
     burst(count, options = {}) {
+        assertValidPositiveNumber(count, "FXEmitter.burst.count");
         const handler = this._private_nextHandler++;
         const delay = options.delay ?? 0;
+        assertValidNonNegativeNumber(delay, "FXEmitter.burst.options.delay");
         if (delay <= 0) {
             this._private_spawnBurst(count);
         }
@@ -75,7 +107,18 @@ class FXEmitter extends Object3D {
         }
         return handler;
     }
+    /**
+     * Starts continuous emission at the given rate
+     *
+     * @param rate - Particles per second
+     * @param options - Play options
+     * @returns Handler that can be passed to {@link stop} to cancel
+     */
     play(rate, options = {}) {
+        assertValidPositiveNumber(rate, "FXEmitter.play.rate");
+        if (options.delay !== undefined) {
+            assertValidNonNegativeNumber(options.delay, "FXEmitter.play.options.delay");
+        }
         const handler = this._private_nextHandler++;
         this._private_activePlays.push({
             handler,
@@ -87,6 +130,12 @@ class FXEmitter extends Object3D {
         });
         return handler;
     }
+    /**
+     * Stops an active play or pending burst by handler; stops all when called with no arguments
+     *
+     * @param handler - Handler returned by {@link play} or {@link burst}; omit to stop everything
+     * @returns `true` if anything was stopped
+     */
     stop(handler) {
         if (handler === undefined) {
             const hadAnything = this._private_pendingBursts.length > 0 || this._private_activePlays.length > 0;
@@ -106,7 +155,15 @@ class FXEmitter extends Object3D {
         }
         return false;
     }
+    /**
+     * Simulates the emitter forward in time to avoid a cold-start on frame 0
+     *
+     * @param duration - Total time to simulate in seconds
+     * @param stepDuration - Maximum simulation step size in seconds. Defaults to `1/60`
+     */
     prewarm(duration, stepDuration = EMITTER_DEFAULT_PREWARM_MIN_STEP_DURATION) {
+        assertValidPositiveNumber(duration, "FXEmitter.prewarm.duration");
+        assertValidPositiveNumber(stepDuration, "FXEmitter.prewarm.stepDuration");
         const stepCount = Math.min(duration / Math.max(stepDuration, EMITTER_DEFAULT_PREWARM_MIN_STEP_DURATION), EMITTER_DEFAULT_PREWARM_MAX_STEP_COUNT);
         const step = duration / stepCount;
         let remaining = duration;
@@ -116,6 +173,7 @@ class FXEmitter extends Object3D {
             remaining -= deltaTime;
         }
     }
+    /** Kills all live particles and cancels all active plays and pending bursts */
     reset() {
         this._private_pendingBursts.length = 0;
         this._private_activePlays.length = 0;
@@ -213,6 +271,11 @@ class FXEmitter extends Object3D {
         }
     }
 }
+/**
+ * Ticks all active emitters; call once per frame before rendering
+ *
+ * @param deltaTime - Elapsed time in seconds since the last frame
+ */
 FXEmitter.onWillRender = (deltaTime) => {
     for (const instance of EMITTERS) {
         instance._private_onRendering(deltaTime);

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

@@ -1,14 +1,24 @@
 import type { InstancedBufferAttribute } from "three";
 import type { FXPropertyName } from "../../instancedParticle/shared";
 /**
- * Base class for particle behavior modules.
+ * Abstract base for particle behavior modules that mutate per-particle properties each frame
  *
- * Behavior modules update particle properties each frame.
+ * @typeParam T - Map of local property keys to {@link FXPropertyName} identifiers,
+ * declaring which particle attributes this behavior reads or writes
  */
 export declare abstract class FXBehavior<T extends Record<string, FXPropertyName> = Record<string, FXPropertyName>> {
+    /** Particle attributes required by this behavior */
     abstract readonly requiredProperties: T;
+    /**
+     * Called once per frame to update all live particles
+     *
+     * @param properties - Buffer attributes keyed by `requiredProperties`
+     * @param instanceCount - Number of currently live particles
+     * @param deltaTime - Elapsed time since the last frame, in seconds
+     */
     abstract update(properties: {
         [K in keyof T]: InstancedBufferAttribute;
     }, instanceCount: number, deltaTime: number): void;
+    /** Releases any resources held by this behavior */
     destroy?(): void;
 }

package/dist/emitter/behavior/FXBehavior.js

@@ -1,7 +1,8 @@
 /**
- * Base class for particle behavior modules.
+ * Abstract base for particle behavior modules that mutate per-particle properties each frame
  *
- * Behavior modules update particle properties each frame.
+ * @typeParam T - Map of local property keys to {@link FXPropertyName} identifiers,
+ * declaring which particle attributes this behavior reads or writes
  */
 class FXBehavior {
 }

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

@@ -0,0 +1,25 @@
+import { type Vector3Like } from "../../miscellaneous/math";
+import type { FXVector3Config } from "../../miscellaneous/miscellaneous";
+import { FXBehavior } from "./FXBehavior";
+/**
+ * Applies constant acceleration to all particles
+ */
+export declare class FXBehaviorDirectionalForce extends FXBehavior<{
+    builtin: "Matrix4";
+}> {
+    private readonly directionInternal;
+    private magnitudeInternal;
+    /**
+     * @param direction - Direction vector (will be normalized)
+     * @param magnitude - Acceleration magnitude in units/second²
+     */
+    constructor(direction: Vector3Like, magnitude: number);
+    /** Direction vector (normalized) */
+    get direction(): Vector3Like;
+    /** Acceleration magnitude in units/second² */
+    get magnitude(): number;
+    /** Direction vector (normalized) */
+    set direction(value: FXVector3Config);
+    /** Acceleration magnitude in units/second² */
+    set magnitude(value: number);
+}

package/dist/emitter/behavior/FXBehaviorDirectionalForce.js

@@ -0,0 +1,74 @@
+import { Vector3 } from 'three';
+import { assertValidNumber } from '../../miscellaneous/asserts.js';
+import { EPSILON } from '../../miscellaneous/math.js';
+import { resolveFXVector3Config, BUILTIN_OFFSET_VELOCITY_X, BUILTIN_OFFSET_VELOCITY_Y, BUILTIN_OFFSET_VELOCITY_Z } from '../../miscellaneous/miscellaneous.js';
+import { FXBehavior } from './FXBehavior.js';
+
+/**
+ * Applies constant acceleration to all particles
+ */
+class FXBehaviorDirectionalForce extends FXBehavior {
+    /**
+     * @param direction - Direction vector (will be normalized)
+     * @param magnitude - Acceleration magnitude in units/second²
+     */
+    constructor(direction, magnitude) {
+        super();
+        /** @internal */
+        this.requiredProperties = { builtin: "Matrix4" };
+        const resolvedDirection = resolveFXVector3Config(direction);
+        assertValidNumber(resolvedDirection.x, "FXBehaviorDirectionalForce.direction.x");
+        assertValidNumber(resolvedDirection.y, "FXBehaviorDirectionalForce.direction.y");
+        assertValidNumber(resolvedDirection.z, "FXBehaviorDirectionalForce.direction.z");
+        assertValidNumber(magnitude, "FXBehaviorDirectionalForce.constructor.magnitude");
+        this._private_directionInternal = new Vector3(resolvedDirection.x, resolvedDirection.y, resolvedDirection.z);
+        if (this._private_directionInternal.lengthSq() <= EPSILON) {
+            throw new Error("FXBehaviorDirectionalForce.direction: vector cannot be zero");
+        }
+        this._private_directionInternal.normalize();
+        this._private_magnitudeInternal = magnitude;
+    }
+    /** Direction vector (normalized) */
+    get direction() {
+        return this._private_directionInternal;
+    }
+    /** Acceleration magnitude in units/second² */
+    get magnitude() {
+        return this._private_magnitudeInternal;
+    }
+    /** Direction vector (normalized) */
+    set direction(value) {
+        const resolved = resolveFXVector3Config(value);
+        assertValidNumber(resolved.x, "FXBehaviorDirectionalForce.direction.x");
+        assertValidNumber(resolved.y, "FXBehaviorDirectionalForce.direction.y");
+        assertValidNumber(resolved.z, "FXBehaviorDirectionalForce.direction.z");
+        this._private_directionInternal.set(resolved.x, resolved.y, resolved.z);
+        if (this._private_directionInternal.lengthSq() < EPSILON) {
+            throw new Error("FXBehaviorDirectionalForce.direction: vector cannot be zero");
+        }
+        this._private_directionInternal.normalize();
+    }
+    /** Acceleration magnitude in units/second² */
+    set magnitude(value) {
+        assertValidNumber(value, "FXBehaviorDirectionalForce.magnitude");
+        this._private_magnitudeInternal = value;
+    }
+    /** @internal */
+    update(properties, instanceCount, deltaTime) {
+        const { builtin } = properties;
+        const { array, itemSize } = builtin;
+        const scale = this._private_magnitudeInternal * deltaTime;
+        const offsetX = this._private_directionInternal.x * scale;
+        const offsetY = this._private_directionInternal.y * scale;
+        const offsetZ = this._private_directionInternal.z * scale;
+        for (let i = 0; i < instanceCount; i++) {
+            const itemOffset = i * itemSize;
+            array[itemOffset + BUILTIN_OFFSET_VELOCITY_X] += offsetX;
+            array[itemOffset + BUILTIN_OFFSET_VELOCITY_Y] += offsetY;
+            array[itemOffset + BUILTIN_OFFSET_VELOCITY_Z] += offsetZ;
+        }
+        builtin.needsUpdate = true;
+    }
+}
+
+export { FXBehaviorDirectionalForce };

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

@@ -0,0 +1,40 @@
+import type { Vector3Like } from "../../miscellaneous/math";
+import type { FXVector3Config } from "../../miscellaneous/miscellaneous";
+import { FXBehavior } from "./FXBehavior";
+/**
+ * Applies attraction or repulsion toward a point
+ *
+ * @remarks
+ * Particles closer than `threshold` are unaffected.
+ */
+export declare class FXBehaviorPointForce extends FXBehavior<{
+    builtin: "Matrix4";
+}> {
+    private centerInternal;
+    private strengthInternal;
+    private exponentInternal;
+    private thresholdInternal;
+    /**
+     * @param center - Force center position
+     * @param strength - Force multiplier
+     * @param exponent - Distance power exponent
+     * @param threshold - Minimum distance
+     */
+    constructor(center: Vector3Like, strength: number, exponent?: number, threshold?: number);
+    /** Force center position */
+    get center(): Vector3Like;
+    /** Force multiplier */
+    get strength(): number;
+    /** Distance power exponent */
+    get exponent(): number;
+    /** Minimum distance */
+    get threshold(): number;
+    /** Force center position */
+    set center(value: FXVector3Config);
+    /** Force multiplier */
+    set strength(value: number);
+    /** Distance power exponent */
+    set exponent(value: number);
+    /** Minimum distance */
+    set threshold(value: number);
+}

package/dist/emitter/behavior/FXBehaviorPointForce.js

@@ -0,0 +1,98 @@
+import { assertValidNumber } from '../../miscellaneous/asserts.js';
+import { resolveFXVector3Config, BUILTIN_OFFSET_POSITION_X, BUILTIN_OFFSET_POSITION_Y, BUILTIN_OFFSET_POSITION_Z, BUILTIN_OFFSET_VELOCITY_X, BUILTIN_OFFSET_VELOCITY_Y, BUILTIN_OFFSET_VELOCITY_Z } from '../../miscellaneous/miscellaneous.js';
+import { FXBehavior } from './FXBehavior.js';
+
+/**
+ * Applies attraction or repulsion toward a point
+ *
+ * @remarks
+ * Particles closer than `threshold` are unaffected.
+ */
+class FXBehaviorPointForce extends FXBehavior {
+    /**
+     * @param center - Force center position
+     * @param strength - Force multiplier
+     * @param exponent - Distance power exponent
+     * @param threshold - Minimum distance
+     */
+    constructor(center, strength, exponent = 2, threshold = 0.1) {
+        super();
+        /** @internal */
+        this.requiredProperties = { builtin: "Matrix4" };
+        this._private_centerInternal = resolveFXVector3Config(center);
+        assertValidNumber(this._private_centerInternal.x, "FXBehaviorPointForce.constructor.center.x");
+        assertValidNumber(this._private_centerInternal.y, "FXBehaviorPointForce.constructor.center.y");
+        assertValidNumber(this._private_centerInternal.z, "FXBehaviorPointForce.constructor.center.z");
+        assertValidNumber(strength, "FXBehaviorPointForce.constructor.strength");
+        this._private_strengthInternal = strength;
+        assertValidNumber(exponent, "FXBehaviorPointForce.constructor.exponent");
+        this._private_exponentInternal = exponent;
+        assertValidNumber(threshold, "FXBehaviorPointForce.constructor.threshold");
+        this._private_thresholdInternal = threshold;
+    }
+    /** Force center position */
+    get center() {
+        return this._private_centerInternal;
+    }
+    /** Force multiplier */
+    get strength() {
+        return this._private_strengthInternal;
+    }
+    /** Distance power exponent */
+    get exponent() {
+        return this._private_exponentInternal;
+    }
+    /** Minimum distance */
+    get threshold() {
+        return this._private_thresholdInternal;
+    }
+    /** Force center position */
+    set center(value) {
+        this._private_centerInternal = resolveFXVector3Config(value);
+        assertValidNumber(this._private_centerInternal.x, "FXBehaviorPointForce.center.x");
+        assertValidNumber(this._private_centerInternal.y, "FXBehaviorPointForce.center.y");
+        assertValidNumber(this._private_centerInternal.z, "FXBehaviorPointForce.center.z");
+    }
+    /** Force multiplier */
+    set strength(value) {
+        assertValidNumber(value, "FXBehaviorPointForce.strength");
+        this._private_strengthInternal = value;
+    }
+    /** Distance power exponent */
+    set exponent(value) {
+        assertValidNumber(value, "FXBehaviorPointForce.exponent");
+        this._private_exponentInternal = value;
+    }
+    /** Minimum distance */
+    set threshold(value) {
+        assertValidNumber(value, "FXBehaviorPointForce.threshold");
+        this._private_thresholdInternal = value;
+    }
+    /** @internal */
+    update(properties, instanceCount, deltaTime) {
+        const { builtin } = properties;
+        const { array, itemSize } = builtin;
+        const thresholdSquared = this._private_thresholdInternal * this._private_thresholdInternal;
+        for (let i = 0; i < instanceCount; i++) {
+            const itemOffset = i * itemSize;
+            const dx = this._private_centerInternal.x - array[itemOffset + BUILTIN_OFFSET_POSITION_X];
+            const dy = this._private_centerInternal.y - array[itemOffset + BUILTIN_OFFSET_POSITION_Y];
+            const dz = this._private_centerInternal.z - array[itemOffset + BUILTIN_OFFSET_POSITION_Z];
+            const distanceSquared = dx * dx + dy * dy + dz * dz;
+            if (distanceSquared < thresholdSquared) {
+                continue;
+            }
+            const distance = Math.sqrt(distanceSquared);
+            const forceMagnitude = this._private_strengthInternal / Math.pow(distance, this._private_exponentInternal);
+            const directionX = dx / distance;
+            const directionY = dy / distance;
+            const directionZ = dz / distance;
+            array[itemOffset + BUILTIN_OFFSET_VELOCITY_X] += directionX * forceMagnitude * deltaTime;
+            array[itemOffset + BUILTIN_OFFSET_VELOCITY_Y] += directionY * forceMagnitude * deltaTime;
+            array[itemOffset + BUILTIN_OFFSET_VELOCITY_Z] += directionZ * forceMagnitude * deltaTime;
+        }
+        builtin.needsUpdate = true;
+    }
+}
+
+export { FXBehaviorPointForce };