sparcoon 0.2.0 → 0.3.1

package/dist/emitter/spawn/FXSpawnSphere.js

@@ -1,7 +1,7 @@
 import { MathUtils } from 'three';
 import { assertValidNonNegativeNumber, assertValidNumber } from '../../miscellaneous/asserts.js';
 import { BUILTIN_OFFSET_POSITION_X, BUILTIN_OFFSET_POSITION_Y, BUILTIN_OFFSET_POSITION_Z } from '../../miscellaneous/miscellaneous.js';
-import { FXSpawnModule } from './FXSpawnModule.js';
+import { FXSpawn } from './FXSpawn.js';
 
 /**
  * Spawns particles at random positions within a spherical shell.
@@ -11,7 +11,7 @@ import { FXSpawnModule } from './FXSpawnModule.js';
  * - `Math.PI / 2` - full sphere
  * - Values in between produce a spherical band/zone
  */
-class FXSpawnSphere extends FXSpawnModule {
+class FXSpawnSphere extends FXSpawn {
     /**
      * @param innerRadius - Minimum spawn radius (0 = spawn from center)
      * @param outerRadius - Maximum spawn radius

package/dist/index.d.ts

@@ -7,18 +7,22 @@ export { FXBehaviorVelocityDamping } from "./emitter/behavior/FXBehaviorVelocity
 export { FXBehaviorVelocityNoise } from "./emitter/behavior/FXBehaviorVelocityNoise";
 export { FXEmitter } from "./emitter/FXEmitter";
 export { FXSpawnBox } from "./emitter/spawn/FXSpawnBox";
-export { FXSpawnOffset } from "./emitter/spawn/FXSpawnOffset";
+export { FXSpawnPoint as FXSpawnOffset } from "./emitter/spawn/FXSpawnPoint";
 export { FXSpawnRandomLifetime } from "./emitter/spawn/FXSpawnRandomLifetime";
 export { FXSpawnRandomRotation } from "./emitter/spawn/FXSpawnRandomRotation";
 export { FXSpawnRandomScale } from "./emitter/spawn/FXSpawnRandomScale";
 export { FXSpawnRandomTorque } from "./emitter/spawn/FXSpawnRandomTorque";
 export { FXSpawnRandomVelocity } from "./emitter/spawn/FXSpawnRandomVelocity";
 export { FXSpawnSphere } from "./emitter/spawn/FXSpawnSphere";
-export { FXAnimatedTextureNode } from "./materials/color-nodes/FXAnimatedTextureNode";
-export { FXColorNode } from "./materials/color-nodes/FXColorNode";
-export { FXColorOverLifeNode } from "./materials/color-nodes/FXColorOverLifeNode";
-export { FXStaticTextureNode } from "./materials/color-nodes/FXStaticTextureNode";
-export { FXDiffuseMaterial, FXParticleNormalsMode, } from "./materials/FXDiffuseMaterial/FXDiffuseMaterial";
-export { FXMaterial } from "./materials/FXMaterial";
+export { FXDiffuseMaterial } from "./materials/FXDiffuseMaterial/FXDiffuseMaterial";
+export { FXMaterial } from "./materials/FXMaterial/FXMaterial";
 export { FXUnlitMaterial } from "./materials/FXUnlitMaterial/FXUnlitMaterial";
 export { FXColor } from "./miscellaneous/color/FXColor";
+export { FXColorNode } from "./nodes/color/FXColorNode";
+export { FXColorOverLifeNode } from "./nodes/color/FXColorOverLifeNode";
+export { FXFlatNormalNode } from "./nodes/normal/FXFlatNormalNode";
+export { FXNormalNode } from "./nodes/normal/FXNormalNode";
+export { FXSphericalNormalNode } from "./nodes/normal/FXSphericalNormalNode";
+export { FXAnimatedTextureNode } from "./nodes/texture/FXAnimatedTextureNode";
+export { FXStaticTextureNode } from "./nodes/texture/FXStaticTextureNode";
+export { FXTextureNode } from "./nodes/texture/FXTextureNode";

package/dist/index.js

@@ -7,19 +7,22 @@ export { FXBehaviorVelocityDamping } from './emitter/behavior/FXBehaviorVelocity
 export { FXBehaviorVelocityNoise } from './emitter/behavior/FXBehaviorVelocityNoise.js';
 export { FXEmitter } from './emitter/FXEmitter.js';
 export { FXSpawnBox } from './emitter/spawn/FXSpawnBox.js';
-export { FXSpawnOffset } from './emitter/spawn/FXSpawnOffset.js';
+export { FXSpawnPoint as FXSpawnOffset } from './emitter/spawn/FXSpawnPoint.js';
 export { FXSpawnRandomLifetime } from './emitter/spawn/FXSpawnRandomLifetime.js';
 export { FXSpawnRandomRotation } from './emitter/spawn/FXSpawnRandomRotation.js';
 export { FXSpawnRandomScale } from './emitter/spawn/FXSpawnRandomScale.js';
 export { FXSpawnRandomTorque } from './emitter/spawn/FXSpawnRandomTorque.js';
 export { FXSpawnRandomVelocity } from './emitter/spawn/FXSpawnRandomVelocity.js';
 export { FXSpawnSphere } from './emitter/spawn/FXSpawnSphere.js';
-export { FXAnimatedTextureNode } from './materials/color-nodes/FXAnimatedTextureNode.js';
-export { FXColorNode } from './materials/color-nodes/FXColorNode.js';
-export { FXColorOverLifeNode } from './materials/color-nodes/FXColorOverLifeNode.js';
-export { FXStaticTextureNode } from './materials/color-nodes/FXStaticTextureNode.js';
 export { FXDiffuseMaterial } from './materials/FXDiffuseMaterial/FXDiffuseMaterial.js';
-export { FXMaterial } from './materials/FXMaterial.js';
+export { FXMaterial } from './materials/FXMaterial/FXMaterial.js';
 export { FXUnlitMaterial } from './materials/FXUnlitMaterial/FXUnlitMaterial.js';
 export { FXColor } from './miscellaneous/color/FXColor.js';
-export { FXParticleNormalsMode } from './materials/FXDiffuseMaterial/FXDiffuseMaterial.Internal.js';
+export { FXColorNode } from './nodes/color/FXColorNode.js';
+export { FXColorOverLifeNode } from './nodes/color/FXColorOverLifeNode.js';
+export { FXFlatNormalNode } from './nodes/normal/FXFlatNormalNode.js';
+export { FXNormalNode } from './nodes/normal/FXNormalNode.js';
+export { FXSphericalNormalNode } from './nodes/normal/FXSphericalNormalNode.js';
+export { FXAnimatedTextureNode } from './nodes/texture/FXAnimatedTextureNode.js';
+export { FXStaticTextureNode } from './nodes/texture/FXStaticTextureNode.js';
+export { FXTextureNode } from './nodes/texture/FXTextureNode.js';

package/dist/instancedParticle/FXInstancedParticle.Internal.d.ts

@@ -1,6 +1,2 @@
 import { InstancedBufferGeometry } from "three";
-import type { FXPropertyName, GLTypeInfo } from "./shared";
 export declare const INSTANCED_PARTICLE_GEOMETRY: InstancedBufferGeometry;
-export declare function collectProperties(keeper: Record<string, GLTypeInfo>, modules: readonly {
-    requiredProperties?: Record<string, FXPropertyName>;
-}[], debugContext: string): void;

package/dist/instancedParticle/FXInstancedParticle.Internal.js

@@ -1,5 +1,4 @@
 import { InstancedBufferGeometry, BufferAttribute, Float32BufferAttribute } from 'three';
-import { resolveGLSLTypeInfo } from './shared.js';
 
 const INSTANCED_PARTICLE_GEOMETRY = (() => {
     const geometry = new InstancedBufferGeometry();
@@ -11,22 +10,5 @@ const INSTANCED_PARTICLE_GEOMETRY = (() => {
     geometry.setAttribute("uv", new Float32BufferAttribute(uvs, 2));
     return geometry;
 })();
-function collectProperties(keeper, modules, debugContext) {
-    for (const module of modules) {
-        if (module.requiredProperties === undefined) {
-            continue;
-        }
-        for (const key in module.requiredProperties) {
-            const existingTypeInfo = keeper[key];
-            const newTypeInfo = resolveGLSLTypeInfo(module.requiredProperties[key]);
-            if (existingTypeInfo === undefined) {
-                keeper[key] = newTypeInfo;
-            }
-            else if (existingTypeInfo.glslTypeName !== newTypeInfo.glslTypeName) {
-                throw new Error(`${debugContext}: property conflict for "${key}"`);
-            }
-        }
-    }
-}
 
-export { INSTANCED_PARTICLE_GEOMETRY, collectProperties };
+export { INSTANCED_PARTICLE_GEOMETRY };

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

@@ -1,9 +1,7 @@
-import { MeshLambertMaterial, type Blending } from "three";
+import type { Blending } from "three";
+import { MeshLambertMaterial } from "three";
 import type { GLTypeInfo } from "../../instancedParticle/shared";
-import type { FXColorNode } from "../color-nodes/FXColorNode";
-export declare enum FXParticleNormalsMode {
-    FLAT = 0,
-    SPHERICAL = 1,
-    TOWARDS_LIGHT = 2
-}
-export declare function buildFXDiffuseMaterial(varyings: Record<string, GLTypeInfo>, blending: Blending, useAlphaHashing: boolean, normalsMode: FXParticleNormalsMode, colorNodes: readonly FXColorNode[]): MeshLambertMaterial;
+import type { FXColorNode } from "../../nodes/color/FXColorNode";
+import type { FXNormalNode } from "../../nodes/normal/FXNormalNode";
+import { FXTextureNode } from "../../nodes/texture/FXTextureNode";
+export declare function buildFXDiffuseMaterial(varyings: Record<string, GLTypeInfo>, blending: Blending, useAlphaHashing: boolean, alphaTest: number, albedoNodes: readonly (FXColorNode | FXTextureNode)[], normalNodes: readonly (FXTextureNode | FXNormalNode)[], emissionNodes: readonly (FXColorNode | FXTextureNode)[]): MeshLambertMaterial;

package/dist/materials/FXDiffuseMaterial/FXDiffuseMaterial.Internal.js

@@ -1,13 +1,8 @@
-import { MeshLambertMaterial, DoubleSide } from 'three';
-import { PARTICLE_DEFINES } from '../miscellaneous.js';
+import { MeshLambertMaterial, Color, DoubleSide } from 'three';
+import { PARTICLE_DEFINES } from '../../miscellaneous/miscellaneous.js';
+import { FXTextureNode } from '../../nodes/texture/FXTextureNode.js';
 
-var FXParticleNormalsMode;
-(function (FXParticleNormalsMode) {
-    FXParticleNormalsMode[FXParticleNormalsMode["FLAT"] = 0] = "FLAT";
-    FXParticleNormalsMode[FXParticleNormalsMode["SPHERICAL"] = 1] = "SPHERICAL";
-    FXParticleNormalsMode[FXParticleNormalsMode["TOWARDS_LIGHT"] = 2] = "TOWARDS_LIGHT";
-})(FXParticleNormalsMode || (FXParticleNormalsMode = {}));
-function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, normalsMode, colorNodes) {
+function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, alphaTest, albedoNodes, normalNodes, emissionNodes) {
     const attributeDeclarations = [];
     const varyingDeclarations = [];
     const vertexAssignments = [];
@@ -25,7 +20,8 @@ function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, normalsMode
         blending,
         side: DoubleSide,
         forceSinglePass: true,
-        alphaTest: 1 / 255,
+        alphaTest,
+        emissive: emissionNodes.length > 0 ? new Color(1, 1, 1) : new Color(0, 0, 0),
     });
     material.onBeforeCompile = (shader) => {
         const vertexPreamble = [
@@ -49,60 +45,108 @@ function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, normalsMode
                     "#endif",
                 ].join("\n"))
                     .replace("#include <project_vertex>", `
-          vec2 p_bp = position.xy;
-          p_bp.x *= PARTICLE_SCALE_X;
-          p_bp.y *= PARTICLE_SCALE_Y;
-          float p_cosR = cos(PARTICLE_ROTATION);
-          float p_sinR = sin(PARTICLE_ROTATION);
-          p_bp = vec2(
-            p_bp.x * p_cosR - p_bp.y * p_sinR,
-            p_bp.x * p_sinR + p_bp.y * p_cosR
+          // Scale and rotate the billboard offset in camera space
+          vec2 billboardOffset = position.xy;
+          billboardOffset.x *= PARTICLE_SCALE_X;
+          billboardOffset.y *= PARTICLE_SCALE_Y;
+
+          float cosRotation = cos(PARTICLE_ROTATION);
+          float sinRotation = sin(PARTICLE_ROTATION);
+          billboardOffset = vec2(
+            billboardOffset.x * cosRotation - billboardOffset.y * sinRotation,
+            billboardOffset.x * sinRotation + billboardOffset.y * cosRotation
           );
-          vec3 p_c = vec3(PARTICLE_POSITION_X, PARTICLE_POSITION_Y, PARTICLE_POSITION_Z);
-          vec4 mvPosition = modelViewMatrix * vec4(p_c, 1.0);
-          mvPosition.xy += p_bp;
+
+          // Move particle center to view space, then apply the billboard offset
+          vec3 particleCenter = vec3(PARTICLE_POSITION_X, PARTICLE_POSITION_Y, PARTICLE_POSITION_Z);
+          vec4 mvPosition = modelViewMatrix * vec4(particleCenter, 1.0);
+          mvPosition.xy += billboardOffset;
           gl_Position = projectionMatrix * mvPosition;
           `)
                     .replace("#include <worldpos_vertex>", `
           #if defined(USE_SHADOWMAP) || defined(USE_ENVMAP) || defined(DISTANCE) || (NUM_SPOT_LIGHT_COORDS > 0)
-            vec3 p_cr = vec3(viewMatrix[0][0], viewMatrix[1][0], viewMatrix[2][0]);
-            vec3 p_cu = vec3(viewMatrix[0][1], viewMatrix[1][1], viewMatrix[2][1]);
+            // Reconstruct world-space position for shadow/environment maps.
+            // Camera right and up are the first two rows of the view matrix rotation (transposed).
+            vec3 cameraRight = vec3(viewMatrix[0][0], viewMatrix[1][0], viewMatrix[2][0]);
+            vec3 cameraUp    = vec3(viewMatrix[0][1], viewMatrix[1][1], viewMatrix[2][1]);
             vec4 worldPosition = vec4(
-              (modelMatrix * vec4(p_c, 1.0)).xyz + p_cr * p_bp.x + p_cu * p_bp.y,
+              (modelMatrix * vec4(particleCenter, 1.0)).xyz + cameraRight * billboardOffset.x + cameraUp * billboardOffset.y,
               1.0
             );
           #endif
           `);
+        const blendReorientedNormalsHelper = normalNodes.length > 1
+            ? `
+          vec3 blendReorientedNormals(vec3 base, vec3 detail) {
+            base += vec3(0.0, 0.0, 1.0);
+            detail *= vec3(-1.0, -1.0, 1.0);
+            return normalize(base * dot(base, detail) / base.z - detail);
+          }
+        `
+            : "";
+        const seenCacheKeys = new Set();
+        const uniqueHelpers = (nodes) => nodes
+            .filter((n) => {
+            if (seenCacheKeys.has(n.cacheKey)) {
+                return false;
+            }
+            seenCacheKeys.add(n.cacheKey);
+            return true;
+        })
+            .map((n) => n.helperFunctions)
+            .join("\n");
         const fragmentPreamble = [
             PARTICLE_DEFINES,
             "varying vec2 p_uv;",
             varyingDeclarations.join("\n"),
-            colorNodes.flatMap((n) => n.uniformDeclarations).join("\n"),
-            colorNodes.map((n) => n.helperFunctions).join("\n"),
+            albedoNodes.flatMap((n) => n.uniformDeclarations).join("\n"),
+            uniqueHelpers(albedoNodes),
+            normalNodes.flatMap((n) => n.uniformDeclarations).join("\n"),
+            uniqueHelpers(normalNodes),
+            blendReorientedNormalsHelper,
+            emissionNodes.flatMap((n) => n.uniformDeclarations).join("\n"),
+            uniqueHelpers(emissionNodes),
         ].join("\n");
-        for (const node of colorNodes) {
+        for (const node of albedoNodes) {
             Object.assign(shader.uniforms, node.uniforms);
         }
-        let fragmentShader = shader.fragmentShader;
-        if (normalsMode === FXParticleNormalsMode.SPHERICAL) {
-            fragmentShader = fragmentShader.replace("#include <normal_fragment_begin>", `
-        float faceDirection = gl_FrontFacing ? 1.0 : -1.0;
-        vec2 p_sn = p_uv * 2.0 - 1.0;
-        vec3 normal = normalize(vec3(p_sn, sqrt(max(0.0, 1.0 - dot(p_sn, p_sn)))));
-        `);
+        for (const node of normalNodes) {
+            Object.assign(shader.uniforms, node.uniforms);
         }
-        else if (normalsMode === FXParticleNormalsMode.TOWARDS_LIGHT) {
-            fragmentShader = fragmentShader.replace("float dotNL = saturate( dot( geometryNormal, directLight.direction ) );", "float dotNL = 1.0;");
+        for (const node of emissionNodes) {
+            Object.assign(shader.uniforms, node.uniforms);
+        }
+        let fragmentShader = shader.fragmentShader;
+        if (normalNodes.length > 0) {
+            const normalExpressions = normalNodes.map((node) => {
+                if (node instanceof FXTextureNode) {
+                    return `normalize(${node.colorExpression}.rgb * 2.0 - 1.0)`;
+                }
+                return node.normalExpression;
+            });
+            const blendLines = normalExpressions
+                .slice(1)
+                .map((expression) => `normal = blendReorientedNormals(normal, ${expression});`);
+            const normalCode = [
+                "float faceDirection = gl_FrontFacing ? 1.0 : -1.0;",
+                `vec3 normal = ${normalExpressions[0]};`,
+                ...blendLines,
+            ].join("\n");
+            fragmentShader = fragmentShader.replace("#include <normal_fragment_begin>", normalCode);
         }
-        if (colorNodes.length > 0) {
-            const combinedExpression = colorNodes.map((n) => n.colorExpression).join(" * ");
+        if (albedoNodes.length > 0) {
+            const combinedExpression = albedoNodes.map((n) => n.colorExpression).join(" * ");
             const discardLine = useAlphaHashing ? "" : "if (diffuseColor.a < 0.0035) discard;";
             fragmentShader = fragmentShader.replace("#include <map_fragment>", `diffuseColor = ${combinedExpression}; ${discardLine}`);
         }
+        if (emissionNodes.length > 0) {
+            const combinedExpression = emissionNodes.map((n) => n.colorExpression).join(" * ");
+            fragmentShader = fragmentShader.replace("#include <emissivemap_fragment>", `totalEmissiveRadiance = (${combinedExpression}).rgb;`);
+        }
         shader.fragmentShader = fragmentPreamble + "\n" + fragmentShader;
     };
-    material.customProgramCacheKey = () => `fx-diffuse-${normalsMode}-${colorNodes.map((n) => n.cacheKey).join("-") || "none"}`;
+    material.customProgramCacheKey = () => `fx-diffuse-${albedoNodes.map((n) => n.cacheKey).join("-") || "none"}-${normalNodes.map((n) => n.cacheKey).join("-") || "none"}-${emissionNodes.map((n) => n.cacheKey).join("-") || "none"}`;
     return material;
 }
 
-export { FXParticleNormalsMode, buildFXDiffuseMaterial };
+export { buildFXDiffuseMaterial };

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

@@ -1,15 +1,15 @@
-import { type Blending } from "three";
-import { FXMaterial, type FXMaterialOptions } from "../FXMaterial";
-import { FXParticleNormalsMode } from "./FXDiffuseMaterial.Internal";
-export { FXParticleNormalsMode };
+import type { FXColorNode } from "../../nodes/color/FXColorNode";
+import type { FXNormalNode } from "../../nodes/normal/FXNormalNode";
+import type { FXTextureNode } from "../../nodes/texture/FXTextureNode";
+import type { FXMaterialOptions } from "../FXMaterial/FXMaterial";
+import { FXMaterial } from "../FXMaterial/FXMaterial";
 export interface FXDiffuseMaterialOptions extends FXMaterialOptions {
-    blending: Blending;
-    useAlphaHashing: boolean;
-    normalsMode: FXParticleNormalsMode;
+    normalNodes?: (FXTextureNode | FXNormalNode)[];
+    emissionNodes?: (FXColorNode | FXTextureNode)[];
 }
 export declare class FXDiffuseMaterial extends FXMaterial {
-    private readonly blending;
-    private readonly useAlphaHashing;
-    private readonly normalsMode;
-    constructor(options?: Partial<FXDiffuseMaterialOptions>);
+    private readonly normalNodes;
+    private readonly emissionNodes;
+    constructor(options?: FXDiffuseMaterialOptions);
+    destroy(): void;
 }

package/dist/materials/FXDiffuseMaterial/FXDiffuseMaterial.js

@@ -1,18 +1,26 @@
-import { NormalBlending } from 'three';
-import { FXMaterial } from '../FXMaterial.js';
-import { FXParticleNormalsMode, buildFXDiffuseMaterial } from './FXDiffuseMaterial.Internal.js';
+import { FXSphericalNormalNode } from '../../nodes/normal/FXSphericalNormalNode.js';
+import { FXMaterial } from '../FXMaterial/FXMaterial.js';
+import { buildFXDiffuseMaterial } from './FXDiffuseMaterial.Internal.js';
 
 class FXDiffuseMaterial extends FXMaterial {
     constructor(options = {}) {
         super(options);
-        this._private_blending = options.blending ?? NormalBlending;
-        this._private_useAlphaHashing = options.useAlphaHashing ?? false;
-        this._private_normalsMode = options.normalsMode ?? FXParticleNormalsMode.SPHERICAL;
+        this._private_normalNodes = options.normalNodes ?? [new FXSphericalNormalNode()];
+        this._private_emissionNodes = options.emissionNodes ?? [];
+    }
+    destroy() {
+        super.destroy();
+        for (const node of this._private_normalNodes) {
+            node.destroy?.();
+        }
+        for (const node of this._private_emissionNodes) {
+            node.destroy?.();
+        }
     }
     /** @internal */
     buildThreeMaterial(varyings) {
-        return buildFXDiffuseMaterial(varyings, this._private_blending, this._private_useAlphaHashing, this._private_normalsMode, this.colorNodes);
+        return buildFXDiffuseMaterial(varyings, this.blending, this.useAlphaHashing, this.alphaTest, this.albedoNodes, this._private_normalNodes, this._private_emissionNodes);
     }
 }
 
-export { FXDiffuseMaterial, FXParticleNormalsMode };
+export { FXDiffuseMaterial };

package/dist/materials/{FXMaterial.Internal.d.ts → FXMaterial/FXMaterial.Internal.d.ts}

@@ -1,4 +1,5 @@
 import { MeshDepthMaterial } from "three";
-import type { FXColorNode } from "./color-nodes/FXColorNode";
+import type { FXColorNode } from "../../nodes/color/FXColorNode";
+import type { FXTextureNode } from "../../nodes/texture/FXTextureNode";
 export declare const DEPTH_VERTEX_SHADER = "\n  #define PARTICLE_POSITION_X a_builtin[0][0]\n  #define PARTICLE_POSITION_Y a_builtin[0][1]\n  #define PARTICLE_POSITION_Z a_builtin[0][2]\n\n  #define PARTICLE_SCALE_X a_builtin[1][2]\n  #define PARTICLE_SCALE_Y a_builtin[1][3]\n\n  #define PARTICLE_ROTATION a_builtin[2][1]\n\n  attribute mat4 a_builtin;\n  varying mat4 p_builtin;\n  varying vec2 p_uv;\n  varying vec2 vHighPrecisionZW;\n  varying float v_viewZ;\n  #ifdef USE_ALPHAHASH\n    varying vec3 vPosition;\n  #endif\n\n  void main() {\n    p_builtin = a_builtin;\n    p_uv = uv;\n    #ifdef USE_ALPHAHASH\n      vPosition = vec3(PARTICLE_POSITION_X, PARTICLE_POSITION_Y, PARTICLE_POSITION_Z) + vec3(position.xy, 0.0);\n    #endif\n\n    vec2 transformedPosition = position.xy;\n    transformedPosition.x *= PARTICLE_SCALE_X;\n    transformedPosition.y *= PARTICLE_SCALE_Y;\n\n    float cosR = cos(PARTICLE_ROTATION);\n    float sinR = sin(PARTICLE_ROTATION);\n    transformedPosition = vec2(\n      transformedPosition.x * cosR - transformedPosition.y * sinR,\n      transformedPosition.x * sinR + transformedPosition.y * cosR\n    );\n\n    vec3 center = vec3(PARTICLE_POSITION_X, PARTICLE_POSITION_Y, PARTICLE_POSITION_Z);\n    vec4 modelViewCenter = modelViewMatrix * vec4(center, 1.0);\n    v_viewZ = modelViewCenter.z;\n    modelViewCenter.xy += transformedPosition;\n    gl_Position = projectionMatrix * modelViewCenter;\n    vHighPrecisionZW = gl_Position.zw;\n  }\n";
-export declare function buildDepthMaterial(colorNodes: readonly FXColorNode[], depthAlphaTest: number, useDepthAlphaHash: boolean, useSphericalDepth: boolean): MeshDepthMaterial;
+export declare function buildDepthMaterial(albedoNodes: readonly (FXColorNode | FXTextureNode)[], depthAlphaTest: number, useDepthAlphaHash: boolean, useSphericalDepth: boolean): MeshDepthMaterial;

package/dist/materials/{FXMaterial.Internal.js → FXMaterial/FXMaterial.Internal.js}

@@ -1,5 +1,5 @@
 import { MeshDepthMaterial, DoubleSide, RGBADepthPacking } from 'three';
-import { PARTICLE_DEFINES } from './miscellaneous.js';
+import { PARTICLE_DEFINES } from '../../miscellaneous/miscellaneous.js';
 
 const DEPTH_VERTEX_SHADER = `
   #define PARTICLE_POSITION_X a_builtin[0][0]
@@ -62,8 +62,8 @@ const DEPTH_SPHERICAL_FRAG_COORD_Z = `
     float fragCoordZ = 0.5 * _ndc_z + 0.5;
   #endif
 `;
-function buildDepthMaterial(colorNodes, depthAlphaTest, useDepthAlphaHash, useSphericalDepth) {
-    const depthNodes = colorNodes.filter((n) => n.affectsDepth);
+function buildDepthMaterial(albedoNodes, depthAlphaTest, useDepthAlphaHash, useSphericalDepth) {
+    const depthNodes = albedoNodes.filter((n) => n.affectsDepth);
     const needsFragmentMod = depthNodes.length > 0 || useSphericalDepth;
     const material = new MeshDepthMaterial({
         depthPacking: RGBADepthPacking,

package/dist/materials/{FXMaterial.d.ts → FXMaterial/FXMaterial.d.ts}

@@ -1,6 +1,11 @@
-import type { FXColorNode } from "./color-nodes/FXColorNode";
+import type { Blending } from "three";
+import type { FXColorNode } from "../../nodes/color/FXColorNode";
+import type { FXTextureNode } from "../../nodes/texture/FXTextureNode";
 export interface FXMaterialOptions {
-    colorNodes?: FXColorNode[];
+    albedoNodes?: (FXColorNode | FXTextureNode)[];
+    blending?: Blending;
+    useAlphaHashing?: boolean;
+    alphaTest?: number;
     depthAlphaTest?: number;
     useDepthAlphaHash?: boolean;
     useSphericalDepth?: boolean;

package/dist/materials/FXMaterial/FXMaterial.js

@@ -0,0 +1,25 @@
+import { NormalBlending } from 'three';
+import { buildDepthMaterial } from './FXMaterial.Internal.js';
+
+class FXMaterial {
+    constructor(options = {}) {
+        this.albedoNodes = options.albedoNodes ?? [];
+        this.blending = options.blending ?? NormalBlending;
+        this.useAlphaHashing = options.useAlphaHashing ?? false;
+        this.alphaTest = options.alphaTest ?? 1 / 255;
+        this._private_depthAlphaTest = options.depthAlphaTest ?? 0.5;
+        this._private_useDepthAlphaHash = options.useDepthAlphaHash ?? false;
+        this._private_useSphericalDepth = options.useSphericalDepth ?? true;
+    }
+    destroy() {
+        for (const node of this.albedoNodes) {
+            node.destroy?.();
+        }
+    }
+    /** @internal */
+    buildDepthMaterial() {
+        return buildDepthMaterial(this.albedoNodes, this._private_depthAlphaTest, this._private_useDepthAlphaHash, this._private_useSphericalDepth);
+    }
+}
+
+export { FXMaterial };

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

@@ -1,4 +1,6 @@
-import { MeshBasicMaterial, type Blending } from "three";
+import type { Blending } from "three";
+import { MeshBasicMaterial } from "three";
 import type { GLTypeInfo } from "../../instancedParticle/shared";
-import type { FXColorNode } from "../color-nodes/FXColorNode";
-export declare function buildFXUnlitMaterial(varyings: Record<string, GLTypeInfo>, blending: Blending, useAlphaHashing: boolean, colorNodes: readonly FXColorNode[]): MeshBasicMaterial;
+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, albedoNodes: readonly (FXColorNode | FXTextureNode)[]): MeshBasicMaterial;

package/dist/materials/FXUnlitMaterial/FXUnlitMaterial.Internal.js

@@ -1,7 +1,7 @@
 import { MeshBasicMaterial, DoubleSide } from 'three';
-import { PARTICLE_DEFINES } from '../miscellaneous.js';
+import { PARTICLE_DEFINES } from '../../miscellaneous/miscellaneous.js';
 
-function buildFXUnlitMaterial(varyings, blending, useAlphaHashing, colorNodes) {
+function buildFXUnlitMaterial(varyings, blending, useAlphaHashing, alphaTest, albedoNodes) {
     const attributeDeclarations = [];
     const varyingDeclarations = [];
     const vertexAssignments = [];
@@ -19,7 +19,7 @@ function buildFXUnlitMaterial(varyings, blending, useAlphaHashing, colorNodes) {
         blending,
         side: DoubleSide,
         forceSinglePass: true,
-        alphaTest: 1 / 255,
+        alphaTest,
     });
     material.onBeforeCompile = (shader) => {
         const vertexPreamble = [
@@ -41,39 +41,54 @@ function buildFXUnlitMaterial(varyings, blending, useAlphaHashing, colorNodes) {
                     "#endif",
                 ].join("\n"))
                     .replace("#include <project_vertex>", `
-          vec2 p_bp = position.xy;
-          p_bp.x *= PARTICLE_SCALE_X;
-          p_bp.y *= PARTICLE_SCALE_Y;
-          float p_cosR = cos(PARTICLE_ROTATION);
-          float p_sinR = sin(PARTICLE_ROTATION);
-          p_bp = vec2(
-            p_bp.x * p_cosR - p_bp.y * p_sinR,
-            p_bp.x * p_sinR + p_bp.y * p_cosR
+          // Scale and rotate the billboard offset in camera space
+          vec2 billboardOffset = position.xy;
+          billboardOffset.x *= PARTICLE_SCALE_X;
+          billboardOffset.y *= PARTICLE_SCALE_Y;
+
+          float cosRotation = cos(PARTICLE_ROTATION);
+          float sinRotation = sin(PARTICLE_ROTATION);
+          billboardOffset = vec2(
+            billboardOffset.x * cosRotation - billboardOffset.y * sinRotation,
+            billboardOffset.x * sinRotation + billboardOffset.y * cosRotation
           );
-          vec3 p_c = vec3(PARTICLE_POSITION_X, PARTICLE_POSITION_Y, PARTICLE_POSITION_Z);
-          vec4 mvPosition = modelViewMatrix * vec4(p_c, 1.0);
-          mvPosition.xy += p_bp;
+
+          // Move particle center to view space, then apply the billboard offset
+          vec3 particleCenter = vec3(PARTICLE_POSITION_X, PARTICLE_POSITION_Y, PARTICLE_POSITION_Z);
+          vec4 mvPosition = modelViewMatrix * vec4(particleCenter, 1.0);
+          mvPosition.xy += billboardOffset;
           gl_Position = projectionMatrix * mvPosition;
           `);
+        const seenCacheKeys = new Set();
+        const uniqueHelpers = (nodes) => nodes
+            .filter((n) => {
+            if (seenCacheKeys.has(n.cacheKey)) {
+                return false;
+            }
+            seenCacheKeys.add(n.cacheKey);
+            return true;
+        })
+            .map((n) => n.helperFunctions)
+            .join("\n");
         const fragmentPreamble = [
             PARTICLE_DEFINES,
             "varying vec2 p_uv;",
             varyingDeclarations.join("\n"),
-            colorNodes.flatMap((n) => n.uniformDeclarations).join("\n"),
-            colorNodes.map((n) => n.helperFunctions).join("\n"),
+            albedoNodes.flatMap((n) => n.uniformDeclarations).join("\n"),
+            uniqueHelpers(albedoNodes),
         ].join("\n");
-        for (const node of colorNodes) {
+        for (const node of albedoNodes) {
             Object.assign(shader.uniforms, node.uniforms);
         }
         let fragmentShader = shader.fragmentShader;
-        if (colorNodes.length > 0) {
-            const combinedExpression = colorNodes.map((n) => n.colorExpression).join(" * ");
+        if (albedoNodes.length > 0) {
+            const combinedExpression = albedoNodes.map((n) => n.colorExpression).join(" * ");
             const discardLine = useAlphaHashing ? "" : "if (diffuseColor.a < 0.0035) discard;";
             fragmentShader = fragmentShader.replace("#include <map_fragment>", `diffuseColor = ${combinedExpression}; ${discardLine}`);
         }
         shader.fragmentShader = fragmentPreamble + "\n" + fragmentShader;
     };
-    material.customProgramCacheKey = () => `fx-unlit-${colorNodes.map((n) => n.cacheKey).join("-") || "none"}`;
+    material.customProgramCacheKey = () => `fx-unlit-${albedoNodes.map((n) => n.cacheKey).join("-") || "none"}`;
     return material;
 }
 

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

@@ -1,11 +1,6 @@
-import { type Blending } from "three";
-import { FXMaterial, type FXMaterialOptions } from "../FXMaterial";
-export interface FXUnlitMaterialOptions extends FXMaterialOptions {
-    blending: Blending;
-    useAlphaHashing: boolean;
-}
+import type { FXMaterialOptions } from "../FXMaterial/FXMaterial";
+import { FXMaterial } from "../FXMaterial/FXMaterial";
+export type FXUnlitMaterialOptions = FXMaterialOptions;
 export declare class FXUnlitMaterial extends FXMaterial {
-    private readonly blending;
-    private readonly useAlphaHashing;
-    constructor(options?: Partial<FXUnlitMaterialOptions>);
+    constructor(options?: FXUnlitMaterialOptions);
 }

package/dist/materials/FXUnlitMaterial/FXUnlitMaterial.js

@@ -1,16 +1,13 @@
-import { NormalBlending } from 'three';
-import { FXMaterial } from '../FXMaterial.js';
+import { FXMaterial } from '../FXMaterial/FXMaterial.js';
 import { buildFXUnlitMaterial } from './FXUnlitMaterial.Internal.js';
 
 class FXUnlitMaterial extends FXMaterial {
     constructor(options = {}) {
         super(options);
-        this._private_blending = options.blending ?? NormalBlending;
-        this._private_useAlphaHashing = options.useAlphaHashing ?? false;
     }
     /** @internal */
     buildThreeMaterial(varyings) {
-        return buildFXUnlitMaterial(varyings, this._private_blending, this._private_useAlphaHashing, this.colorNodes);
+        return buildFXUnlitMaterial(varyings, this.blending, this.useAlphaHashing, this.alphaTest, this.albedoNodes);
     }
 }
 

package/dist/miscellaneous/miscellaneous.d.ts

@@ -30,3 +30,4 @@ export declare const BUILTIN_OFFSET_AGE = 12;
 export declare const BUILTIN_OFFSET_RANDOM_A = 13;
 export declare const BUILTIN_OFFSET_RANDOM_B = 14;
 export declare const BUILTIN_OFFSET_RANDOM_C = 15;
+export declare const PARTICLE_DEFINES = "\n  #define PARTICLE_POSITION_X p_builtin[0][0]\n  #define PARTICLE_POSITION_Y p_builtin[0][1]\n  #define PARTICLE_POSITION_Z p_builtin[0][2]\n\n  #define PARTICLE_VELOCITY_X p_builtin[0][3]\n  #define PARTICLE_VELOCITY_Y p_builtin[1][0]\n  #define PARTICLE_VELOCITY_Z p_builtin[1][1]\n\n  #define PARTICLE_SCALE_X p_builtin[1][2]\n  #define PARTICLE_SCALE_Y p_builtin[1][3]\n  #define PARTICLE_SCALE_Z p_builtin[2][0]\n\n  #define PARTICLE_ROTATION p_builtin[2][1]\n  #define PARTICLE_TORQUE p_builtin[2][2]\n\n  #define PARTICLE_LIFETIME p_builtin[2][3]\n  #define PARTICLE_AGE p_builtin[3][0]\n\n  #define PARTICLE_RANDOM_A p_builtin[3][1]\n  #define PARTICLE_RANDOM_B p_builtin[3][2]\n  #define PARTICLE_RANDOM_C p_builtin[3][3]\n";

package/dist/miscellaneous/miscellaneous.js

@@ -58,5 +58,28 @@ const BUILTIN_OFFSET_AGE = 12;
 const BUILTIN_OFFSET_RANDOM_A = 13;
 const BUILTIN_OFFSET_RANDOM_B = 14;
 const BUILTIN_OFFSET_RANDOM_C = 15;
+const PARTICLE_DEFINES = `
+  #define PARTICLE_POSITION_X p_builtin[0][0]
+  #define PARTICLE_POSITION_Y p_builtin[0][1]
+  #define PARTICLE_POSITION_Z p_builtin[0][2]
 
-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, buildGradientTexture, resolveAspect, resolveFXRangeConfig, resolveFXVector3Config };
+  #define PARTICLE_VELOCITY_X p_builtin[0][3]
+  #define PARTICLE_VELOCITY_Y p_builtin[1][0]
+  #define PARTICLE_VELOCITY_Z p_builtin[1][1]
+
+  #define PARTICLE_SCALE_X p_builtin[1][2]
+  #define PARTICLE_SCALE_Y p_builtin[1][3]
+  #define PARTICLE_SCALE_Z p_builtin[2][0]
+
+  #define PARTICLE_ROTATION p_builtin[2][1]
+  #define PARTICLE_TORQUE p_builtin[2][2]
+
+  #define PARTICLE_LIFETIME p_builtin[2][3]
+  #define PARTICLE_AGE p_builtin[3][0]
+
+  #define PARTICLE_RANDOM_A p_builtin[3][1]
+  #define PARTICLE_RANDOM_B p_builtin[3][2]
+  #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 };

package/dist/{materials/color-nodes → nodes/color}/FXColorOverLifeNode.d.ts

@@ -1,7 +1,6 @@
 import type { FXColor } from "../../miscellaneous/color/FXColor";
 import { FXColorNode } from "./FXColorNode";
 export declare class FXColorOverLifeNode extends FXColorNode {
-    private readonly gradientTexture;
     constructor(colors: FXColor[]);
     destroy(): void;
 }