sparcoon 0.5.0 → 0.6.1

package/dist/materials/FXDiffuseMaterial/FXDiffuseMaterial.d.ts

@@ -1,24 +1,74 @@
 import type { ColorRepresentation } from "three";
-import type { FXColorNode } from "../../nodes/color/FXColorNode";
-import type { FXNormalNode } from "../../nodes/normal/FXNormalNode";
-import type { FXTextureNode } from "../../nodes/texture/FXTextureNode";
+import type { FXNodeColor } from "../../nodes/color/FXNodeColor";
+import type { FXNodeNormal } from "../../nodes/normal/FXNodeNormal";
+import type { FXNodeTexture } from "../../nodes/texture/FXNodeTexture";
 import type { FXMaterialOptions } from "../FXMaterial/FXMaterial";
 import { FXMaterial } from "../FXMaterial/FXMaterial";
+/**
+ * Configuration options for {@link FXDiffuseMaterial}
+ */
 export interface FXDiffuseMaterialOptions extends FXMaterialOptions {
-    normalNodes: (FXTextureNode | FXNormalNode)[];
-    emissionNodes: (FXColorNode | FXTextureNode)[];
+    /**
+     * Normal nodes for lighting; multiple nodes are blended together
+     *
+     * @defaultValue `[new FXNodeSphericalNormal()]`
+     */
+    normalNodes: (FXNodeTexture | FXNodeNormal)[];
+    /**
+     * Emission color nodes composited for emissive output
+     *
+     * @defaultValue `[]`
+     */
+    emissionNodes: (FXNodeColor | FXNodeTexture)[];
+    /**
+     * Enable subsurface scattering approximation
+     *
+     * @defaultValue `false`
+     */
     enableScatter: boolean;
+    /**
+     * Tint color applied to the scatter contribution
+     *
+     * @defaultValue `0xffd999`
+     */
     scatterTint: ColorRepresentation;
+    /**
+     * Scatter lobe sharpness; higher values produce a tighter highlight
+     *
+     * @defaultValue `10`
+     */
     scatterPower: number;
+    /**
+     * Forward scatter intensity (light-facing side)
+     *
+     * @defaultValue `1`
+     */
     forwardScatterStrength: number;
+    /**
+     * Back scatter intensity (back-lit side)
+     *
+     * @defaultValue `1`
+     */
     backScatterStrength: number;
+    /**
+     * Shadow influence (`0` = no shadows, `1` = full shadows)
+     *
+     * @defaultValue `1`
+     */
     shadowSensitivity: number;
 }
+/**
+ * Diffuse particle material with lighting, normals, emission, and optional subsurface scattering
+ */
 export declare class FXDiffuseMaterial extends FXMaterial {
     private readonly normalNodes;
     private readonly emissionNodes;
     private readonly scatterUniforms;
     private readonly shadowSensitivity;
+    /**
+     * @param options - Material configuration
+     */
     constructor(options?: Partial<FXDiffuseMaterialOptions>);
+    /** Releases resources held by all albedo, normal, and emission nodes */
     destroy(): void;
 }

package/dist/materials/FXDiffuseMaterial/FXDiffuseMaterial.js

@@ -1,12 +1,18 @@
 import { FXColor } from '../../miscellaneous/color/FXColor.js';
-import { FXSphericalNormalNode } from '../../nodes/normal/FXSphericalNormalNode.js';
+import { FXNodeSphericalNormal } from '../../nodes/normal/FXNodeSphericalNormal.js';
 import { FXMaterial } from '../FXMaterial/FXMaterial.js';
 import { buildFXDiffuseMaterial } from './FXDiffuseMaterial.Internal.js';
 
+/**
+ * Diffuse particle material with lighting, normals, emission, and optional subsurface scattering
+ */
 class FXDiffuseMaterial extends FXMaterial {
+    /**
+     * @param options - Material configuration
+     */
     constructor(options = {}) {
         super(options);
-        this._private_normalNodes = options.normalNodes ?? [new FXSphericalNormalNode()];
+        this._private_normalNodes = options.normalNodes ?? [new FXNodeSphericalNormal()];
         this._private_emissionNodes = options.emissionNodes ?? [];
         this._private_scatterUniforms =
             options.enableScatter === true
@@ -23,6 +29,7 @@ class FXDiffuseMaterial extends FXMaterial {
                 : undefined;
         this._private_shadowSensitivity = { value: options.shadowSensitivity ?? 1 };
     }
+    /** Releases resources held by all albedo, normal, and emission nodes */
     destroy() {
         super.destroy();
         for (const node of this._private_normalNodes) {

package/dist/materials/FXMaterial/FXDepthMaterial.Internal.d.ts

@@ -1,4 +1,4 @@
 import { MeshDepthMaterial } from "three";
-import type { FXColorNode } from "../../nodes/color/FXColorNode";
-import type { FXTextureNode } from "../../nodes/texture/FXTextureNode";
-export declare function buildDepthMaterial(albedoNodes: readonly (FXColorNode | FXTextureNode)[], depthAlphaTest: number, useDepthAlphaHash: boolean, useSphericalDepth: boolean): MeshDepthMaterial;
+import type { FXNodeColor } from "../../nodes/color/FXNodeColor";
+import type { FXNodeTexture } from "../../nodes/texture/FXNodeTexture";
+export declare function buildDepthMaterial(albedoNodes: readonly (FXNodeColor | FXNodeTexture)[], depthAlphaTest: number, useDepthAlphaHash: boolean, useSphericalDepth: boolean): MeshDepthMaterial;

package/dist/materials/FXMaterial/FXDistanceMaterial.Internal.d.ts

@@ -1,4 +1,4 @@
 import { MeshDistanceMaterial } from "three";
-import type { FXColorNode } from "../../nodes/color/FXColorNode";
-import type { FXTextureNode } from "../../nodes/texture/FXTextureNode";
-export declare function buildDistanceMaterial(albedoNodes: readonly (FXColorNode | FXTextureNode)[], distanceAlphaTest: number, useDistanceAlphaHash: boolean, useSphericalDepth: boolean): MeshDistanceMaterial;
+import type { FXNodeColor } from "../../nodes/color/FXNodeColor";
+import type { FXNodeTexture } from "../../nodes/texture/FXNodeTexture";
+export declare function buildDistanceMaterial(albedoNodes: readonly (FXNodeColor | FXNodeTexture)[], distanceAlphaTest: number, useDistanceAlphaHash: boolean, useSphericalDepth: boolean): MeshDistanceMaterial;

package/dist/materials/FXMaterial/FXMaterial.d.ts

@@ -1,21 +1,67 @@
-import type { Blending, MeshDistanceMaterial } from "three";
-import type { FXColorNode } from "../../nodes/color/FXColorNode";
-import type { FXTextureNode } from "../../nodes/texture/FXTextureNode";
+import type { Blending } from "three";
+import type { FXNodeColor } from "../../nodes/color/FXNodeColor";
+import type { FXNodeTexture } from "../../nodes/texture/FXNodeTexture";
+/**
+ * Configuration options shared by all {@link FXMaterial} subclasses
+ */
 export interface FXMaterialOptions {
-    albedoNodes: (FXColorNode | FXTextureNode)[];
+    /**
+     * Color and texture nodes composited for particle color
+     *
+     * @defaultValue `[]`
+     */
+    albedoNodes: (FXNodeColor | FXNodeTexture)[];
+    /**
+     * Three.js blending mode
+     *
+     * @defaultValue `NormalBlending`
+     */
     blending: Blending;
+    /**
+     * Use alpha hashing instead of standard transparency
+     *
+     * @defaultValue `false`
+     */
     useAlphaHashing: boolean;
+    /**
+     * Alpha cutoff threshold for color passes
+     *
+     * @defaultValue `0.0075`
+     */
     alphaTest: number;
+    /**
+     * Alpha cutoff threshold for depth and shadow passes
+     *
+     * @defaultValue `0.5`
+     */
     depthAlphaTest: number;
+    /**
+     * Use alpha hashing in depth and shadow passes
+     *
+     * @defaultValue `false`
+     */
     useDepthAlphaHash: boolean;
+    /**
+     * Approximate spherical depth for shadow maps
+     *
+     * @defaultValue `true`
+     */
     useSphericalDepth: boolean;
+    /**
+     * Use premultiplied alpha blending
+     *
+     * @defaultValue `true`
+     */
     premultipliedAlpha: boolean;
 }
+/**
+ * Abstract base class for particle materials
+ */
 export declare abstract class FXMaterial {
     private readonly depthAlphaTest;
     private readonly useDepthAlphaHash;
     private readonly useSphericalDepth;
     constructor(options?: Partial<FXMaterialOptions>);
+    /** Releases resources held by all albedo nodes */
     destroy(): void;
-    buildDistanceMaterial(): MeshDistanceMaterial;
 }

package/dist/materials/FXMaterial/FXMaterial.js

@@ -2,6 +2,9 @@ import { NormalBlending } from 'three';
 import { buildDepthMaterial } from './FXDepthMaterial.Internal.js';
 import { buildDistanceMaterial } from './FXDistanceMaterial.Internal.js';
 
+/**
+ * Abstract base class for particle materials
+ */
 class FXMaterial {
     constructor(options = {}) {
         this.albedoNodes = options.albedoNodes ?? [];
@@ -14,6 +17,7 @@ class FXMaterial {
         this._private_useDepthAlphaHash = options.useDepthAlphaHash ?? false;
         this._private_useSphericalDepth = options.useSphericalDepth ?? true;
     }
+    /** Releases resources held by all albedo nodes */
     destroy() {
         for (const node of this.albedoNodes) {
             node.destroy?.();
@@ -23,6 +27,7 @@ class FXMaterial {
     buildDepthMaterial() {
         return buildDepthMaterial(this.albedoNodes, this._private_depthAlphaTest, this._private_useDepthAlphaHash, this._private_useSphericalDepth);
     }
+    /** @internal */
     buildDistanceMaterial() {
         return buildDistanceMaterial(this.albedoNodes, this._private_depthAlphaTest, this._private_useDepthAlphaHash, this._private_useSphericalDepth);
     }

package/dist/materials/FXUnlitMaterial/FXUnlitMaterial.Internal.d.ts

@@ -1,6 +1,6 @@
 import type { Blending } from "three";
 import { MeshBasicMaterial } from "three";
 import type { GLTypeInfo } from "../../instancedParticle/shared";
-import type { FXColorNode } from "../../nodes/color/FXColorNode";
-import type { FXTextureNode } from "../../nodes/texture/FXTextureNode";
-export declare function buildFXUnlitMaterial(varyings: Record<string, GLTypeInfo>, blending: Blending, useAlphaHashing: boolean, alphaTest: number, premultipliedAlpha: boolean, albedoNodes: readonly (FXColorNode | FXTextureNode)[]): MeshBasicMaterial;
+import type { FXNodeColor } from "../../nodes/color/FXNodeColor";
+import type { FXNodeTexture } from "../../nodes/texture/FXNodeTexture";
+export declare function buildFXUnlitMaterial(varyings: Record<string, GLTypeInfo>, blending: Blending, useAlphaHashing: boolean, alphaTest: number, premultipliedAlpha: boolean, albedoNodes: readonly (FXNodeColor | FXNodeTexture)[]): MeshBasicMaterial;

package/dist/materials/FXUnlitMaterial/FXUnlitMaterial.d.ts

@@ -1,6 +1,6 @@
-import type { FXMaterialOptions } from "../FXMaterial/FXMaterial";
 import { FXMaterial } from "../FXMaterial/FXMaterial";
-export type FXUnlitMaterialOptions = FXMaterialOptions;
+/**
+ * Unlit particle material - renders particles without lighting or shadows
+ */
 export declare class FXUnlitMaterial extends FXMaterial {
-    constructor(options?: Partial<FXUnlitMaterialOptions>);
 }

package/dist/materials/FXUnlitMaterial/FXUnlitMaterial.js

@@ -1,10 +1,10 @@
 import { FXMaterial } from '../FXMaterial/FXMaterial.js';
 import { buildFXUnlitMaterial } from './FXUnlitMaterial.Internal.js';
 
+/**
+ * Unlit particle material - renders particles without lighting or shadows
+ */
 class FXUnlitMaterial extends FXMaterial {
-    constructor(options = {}) {
-        super(options);
-    }
     /** @internal */
     buildThreeMaterial(varyings) {
         return buildFXUnlitMaterial(varyings, this.blending, this.useAlphaHashing, this.alphaTest, this.premultipliedAlpha, this.albedoNodes);

package/dist/miscellaneous/curve/FXCurve1D.Internal.d.ts

@@ -0,0 +1,20 @@
+import type { FXCurve1D } from "./FXCurve1D";
+/** Input point for {@link FXCurve1D}. */
+export interface FXCurve1DPoint<T> {
+    /** Output value at this position. */
+    value: T;
+    /** Normalized position in [0, 1]. */
+    position: number;
+}
+/**
+ * Accepts either:
+ * - Explicit anchor points ({@link FXCurve1DPoint}\<T>[])
+ * - A uniform shorthand (`T[]`) where anchors are distributed evenly across [0, 1]
+ * - Another {@link FXCurve1D}\<T> instance to copy anchors from
+ */
+export type FXCurve1DConfig<T> = FXCurve1DPoint<T>[] | T[] | FXCurve1D<T>;
+/** Resolved anchor stored internally by {@link FXCurve1D}. */
+export interface FXCurve1DAnchor<T> {
+    readonly value: T;
+    readonly position: number;
+}

package/dist/miscellaneous/curve/FXCurve1D.d.ts

@@ -0,0 +1,17 @@
+import type { FXCurve1DAnchor, FXCurve1DConfig, FXCurve1DPoint } from "./FXCurve1D.Internal";
+export type { FXCurve1DAnchor, FXCurve1DConfig, FXCurve1DPoint };
+/**
+ * 1D curve defined by anchor points at explicit normalized positions.
+ *
+ * Anchors must be strictly ascending by `value`, first must be `0`, last must be `1`.
+ * Output at each anchor is a value of type `T` - interpolation is left to the caller.
+ */
+export declare class FXCurve1D<T> {
+    private readonly anchorsInternal;
+    /**
+     * @param config - Explicit anchor points, a uniform shorthand array, or another {@link FXCurve1D} to copy
+     */
+    constructor(config: FXCurve1DConfig<T>);
+    /** Resolved anchor points ordered ascending by `value`. */
+    get anchors(): readonly FXCurve1DAnchor<T>[];
+}

package/dist/miscellaneous/curve/FXCurve1D.js

@@ -0,0 +1,94 @@
+import { assertValidNumber } from '../asserts.js';
+
+/**
+ * 1D curve defined by anchor points at explicit normalized positions.
+ *
+ * Anchors must be strictly ascending by `value`, first must be `0`, last must be `1`.
+ * Output at each anchor is a value of type `T` - interpolation is left to the caller.
+ */
+class FXCurve1D {
+    /**
+     * @param config - Explicit anchor points, a uniform shorthand array, or another {@link FXCurve1D} to copy
+     */
+    constructor(config) {
+        if (config instanceof FXCurve1D) {
+            this._private_anchorsInternal = config._private_anchorsInternal.map((anchor) => ({ ...anchor }));
+            return;
+        }
+        const isPointArray = config.length > 0 &&
+            typeof config[0] === "object" &&
+            !Array.isArray(config[0]) &&
+            "value" in config[0];
+        const points = isPointArray
+            ? config
+            : config.map((value, index) => ({
+                value,
+                position: index / (config.length - 1),
+            }));
+        if (points.length < 2) {
+            throw new Error("FXCurve1D: at least 2 anchor points are required");
+        }
+        if (points[0].position !== 0) {
+            throw new Error(`FXCurve1D: first anchor value must be 0, got ${points[0].position}`);
+        }
+        if (points[points.length - 1].position !== 1) {
+            throw new Error(`FXCurve1D: last anchor value must be 1, got ${points[points.length - 1].position}`);
+        }
+        this._private_anchorsInternal = [];
+        for (let index = 0; index < points.length; index++) {
+            const { value, position } = points[index];
+            if (position < 0 || position > 1) {
+                throw new Error(`FXCurve1D: anchor[${index}].value must be in [0, 1], got ${position}`);
+            }
+            if (index > 0 && position <= points[index - 1].position) {
+                throw new Error(`FXCurve1D: anchor[${index}].value (${position}) must be strictly greater than anchor[${index - 1}].value (${points[index - 1].position})`);
+            }
+            this._private_anchorsInternal.push({ value, position });
+        }
+    }
+    /** Resolved anchor points ordered ascending by `value`. */
+    get anchors() {
+        return this._private_anchorsInternal;
+    }
+    /**
+     * Samples the curve at normalized position `t`.
+     *
+     * Returns the two bracketing anchor values and the local interpolation factor `t` in [0, 1].
+     * The caller is responsible for interpolating between `a` and `b` using `t`.
+     *
+     * @param t - Normalized position in [0, 1]
+     * @internal
+     */
+    sample(t) {
+        assertValidNumber(t, "FXCurve1D.sample.t");
+        const anchors = this._private_anchorsInternal;
+        const anchorCount = anchors.length;
+        let segmentIndex;
+        if (anchorCount < 10) {
+            segmentIndex = 0;
+            while (segmentIndex < anchorCount - 2 && anchors[segmentIndex + 1].position <= t) {
+                segmentIndex++;
+            }
+        }
+        else {
+            let low = 0;
+            let high = anchorCount - 2;
+            while (low < high) {
+                const mid = (low + high + 1) >> 1;
+                if (anchors[mid].position <= t) {
+                    low = mid;
+                }
+                else {
+                    high = mid - 1;
+                }
+            }
+            segmentIndex = low;
+        }
+        const anchorA = anchors[segmentIndex];
+        const anchorB = anchors[segmentIndex + 1];
+        const localT = (t - anchorA.position) / (anchorB.position - anchorA.position);
+        return { a: anchorA.value, b: anchorB.value, t: localT };
+    }
+}
+
+export { FXCurve1D };

package/dist/miscellaneous/miscellaneous.d.ts

@@ -3,6 +3,8 @@ import { DataTexture } from "three";
 import type { Vector3Like } from "../miscellaneous/math";
 import type { FXTextureConfig } from "../miscellaneous/texture/FXTextureView.Internal";
 import type { FXColor } from "./color/FXColor";
+import type { FXCurve1D } from "./curve/FXCurve1D";
+export declare function getNextInstanceId(): number;
 export interface FXRange {
     min: number;
     max: number;
@@ -13,7 +15,7 @@ export type FXAspectConfig = number | FXTextureConfig;
 export declare function resolveFXRangeConfig(config: FXRangeConfig): FXRange;
 export declare function resolveFXVector3Config(config: FXVector3Config): Vector3Like;
 export declare function resolveAspect(config: number | FXTextureConfig): number;
-export declare function buildGradientTexture(colors: FXColor[]): DataTexture;
+export declare function buildGradientTexture(curve: FXCurve1D<FXColor>): DataTexture;
 export declare const BUILTIN_OFFSET_POSITION_X = 0;
 export declare const BUILTIN_OFFSET_POSITION_Y = 1;
 export declare const BUILTIN_OFFSET_POSITION_Z = 2;

package/dist/miscellaneous/miscellaneous.js

@@ -1,5 +1,9 @@
 import { Texture, DataTexture, RGBAFormat, UnsignedByteType, UVMapping, ClampToEdgeWrapping, LinearFilter, SRGBColorSpace } from 'three';
 
+let nextInstanceId = 0;
+function getNextInstanceId() {
+    return nextInstanceId++;
+}
 function resolveFXRangeConfig(config) {
     if (typeof config === "number") {
         return { min: config, max: config };
@@ -27,12 +31,12 @@ function resolveAspect(config) {
     }
     return config.sourceSize.w / config.sourceSize.h;
 }
-function buildGradientTexture(colors) {
-    const width = colors.length;
+function buildGradientTexture(curve) {
+    const width = curve.anchors.length;
     const height = 1;
     const data = new Uint8Array(width * height * 4);
     for (let i = 0; i < width; i++) {
-        const color = colors[i];
+        const color = curve.anchors[i].value;
         const index = i * 4;
         data[index] = Math.round(color.r * 255);
         data[index + 1] = Math.round(color.g * 255);
@@ -82,4 +86,4 @@ const PARTICLE_DEFINES = `
   #define PARTICLE_RANDOM_C p_builtin[3][3]
 `;
 
-export { BUILTIN_OFFSET_AGE, BUILTIN_OFFSET_LIFETIME, BUILTIN_OFFSET_POSITION_X, BUILTIN_OFFSET_POSITION_Y, BUILTIN_OFFSET_POSITION_Z, BUILTIN_OFFSET_RANDOM_A, BUILTIN_OFFSET_RANDOM_B, BUILTIN_OFFSET_RANDOM_C, BUILTIN_OFFSET_ROTATION, BUILTIN_OFFSET_SCALE_X, BUILTIN_OFFSET_SCALE_Y, BUILTIN_OFFSET_TORQUE, BUILTIN_OFFSET_VELOCITY_X, BUILTIN_OFFSET_VELOCITY_Y, BUILTIN_OFFSET_VELOCITY_Z, PARTICLE_DEFINES, buildGradientTexture, resolveAspect, resolveFXRangeConfig, resolveFXVector3Config };
+export { BUILTIN_OFFSET_AGE, BUILTIN_OFFSET_LIFETIME, BUILTIN_OFFSET_POSITION_X, BUILTIN_OFFSET_POSITION_Y, BUILTIN_OFFSET_POSITION_Z, BUILTIN_OFFSET_RANDOM_A, BUILTIN_OFFSET_RANDOM_B, BUILTIN_OFFSET_RANDOM_C, BUILTIN_OFFSET_ROTATION, BUILTIN_OFFSET_SCALE_X, BUILTIN_OFFSET_SCALE_Y, BUILTIN_OFFSET_TORQUE, BUILTIN_OFFSET_VELOCITY_X, BUILTIN_OFFSET_VELOCITY_Y, BUILTIN_OFFSET_VELOCITY_Z, PARTICLE_DEFINES, buildGradientTexture, getNextInstanceId, resolveAspect, resolveFXRangeConfig, resolveFXVector3Config };

package/dist/miscellaneous/texture/FXTextureView.Internal.js

@@ -0,0 +1,6 @@
+import { Texture } from 'three';
+
+const TEXTURE_DEFAULT_TEXTURE = new Texture();
+const TEXTURE_DEFAULT_SIZE = 2;
+
+export { TEXTURE_DEFAULT_SIZE, TEXTURE_DEFAULT_TEXTURE };