sparcoon 0.6.1 → 0.7.0

package/dist/instancedParticle/FXInstancedParticle.js

@@ -27,6 +27,9 @@ class FXInstancedParticle extends Mesh {
     get instanceCount() {
         return this._private_instancedGeometry.instanceCount;
     }
+    get instanceCapacity() {
+        return this._private_capacity;
+    }
     createInstances(count) {
         const currentInstanceCount = this._private_instancedGeometry.instanceCount;
         this._private_ensureCapacity(currentInstanceCount + count);
@@ -151,7 +154,7 @@ class FXInstancedParticle extends Mesh {
         //
         // _maxInstanceCount is an internal renderer cache field set by
         // WebGLBindingStates.js. It was never promoted to a public API in the
-        // r157–r180 range. Deleting it is the standard workaround used across
+        // r157-r180 range. Deleting it is the standard workaround used across
         // the Three.js ecosystem (see #19706, #26363, #27205).
         //
         // eslint-disable-next-line @typescript-eslint/no-explicit-any

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

@@ -1,9 +1,10 @@
-import type { Blending } from "three";
 import { Color, MeshLambertMaterial } from "three";
 import type { GLTypeInfo } from "../../instancedParticle/shared";
-import type { FXNodeColor } from "../../nodes/color/FXNodeColor";
+import type { FXNodeBlending } from "../../nodes/blending/FXNodeBlending";
+import { FXNodeColor } from "../../nodes/color/FXNodeColor";
 import type { FXNodeNormal } from "../../nodes/normal/FXNodeNormal";
 import { FXNodeTexture } from "../../nodes/texture/FXNodeTexture";
+import { FXBlending } from "../FXMaterial/FXMaterial";
 export interface FXScatterUniforms {
     u_ScatterTint: {
         value: Color;
@@ -18,6 +19,6 @@ export interface FXScatterUniforms {
         value: number;
     };
 }
-export declare function buildFXDiffuseMaterial(varyings: Record<string, GLTypeInfo>, blending: Blending, useAlphaHashing: boolean, alphaTest: number, premultipliedAlpha: boolean, albedoNodes: readonly (FXNodeColor | FXNodeTexture)[], normalNodes: readonly (FXNodeTexture | FXNodeNormal)[], emissionNodes: readonly (FXNodeColor | FXNodeTexture)[], scatterUniforms?: FXScatterUniforms, shadowSensitivity?: {
+export declare function buildFXDiffuseMaterial(varyings: Record<string, GLTypeInfo>, blending: FXBlending, useAlphaHashing: boolean, alphaTest: number, albedoNodes: readonly (FXNodeColor | FXNodeTexture | FXNodeBlending)[], normalNodes: readonly (FXNodeTexture | FXNodeNormal)[], emissionNodes: readonly (FXNodeColor | FXNodeTexture)[], scatterUniforms?: FXScatterUniforms, shadowSensitivity?: {
     value: number;
 }): MeshLambertMaterial;

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

@@ -1,6 +1,10 @@
-import { MeshLambertMaterial, Color, DoubleSide } from 'three';
+import { MeshLambertMaterial, Color, DoubleSide, NormalBlending } from 'three';
 import { PARTICLE_DEFINES } from '../../miscellaneous/miscellaneous.js';
+import { FXNodeColor } from '../../nodes/color/FXNodeColor.js';
+import { CURRENT_EXPRESSION_VALUE_PLACEHOLDER } from '../../nodes/FXNode.js';
 import { FXNodeTexture } from '../../nodes/texture/FXNodeTexture.js';
+import { buildAlbedoAndBlendingCode } from '../FXMaterial/FXBlending.Internal.js';
+import { FXBlending } from '../FXMaterial/FXMaterial.js';
 
 /**
  * Wraps every `getShadow(...)` call in the shader source with
@@ -37,7 +41,7 @@ function wrapShadowCalls(source, uniformName) {
     }
     return result;
 }
-function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, alphaTest, premultipliedAlpha, albedoNodes, normalNodes, emissionNodes, scatterUniforms, shadowSensitivity) {
+function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, alphaTest, albedoNodes, normalNodes, emissionNodes, scatterUniforms, shadowSensitivity) {
     const useScatter = scatterUniforms !== undefined;
     const useShadowSensitivity = shadowSensitivity !== undefined;
     const useNormals = normalNodes.length > 0;
@@ -56,12 +60,12 @@ function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, alphaTest,
         depthWrite: useAlphaHashing,
         depthTest: true,
         alphaHash: useAlphaHashing,
-        blending,
+        blending: NormalBlending,
         side: DoubleSide,
         forceSinglePass: true,
         alphaTest,
         emissive: emissionNodes.length > 0 ? new Color(1, 1, 1) : new Color(0, 0, 0),
-        premultipliedAlpha,
+        premultipliedAlpha: true,
     });
     material.onBeforeCompile = (shader) => {
         const vertexPreamble = [
@@ -117,25 +121,16 @@ function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, alphaTest,
             );
           #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)) {
+            .filter((node) => {
+            if (seenCacheKeys.has(node.cacheKey)) {
                 return false;
             }
-            seenCacheKeys.add(n.cacheKey);
+            seenCacheKeys.add(node.cacheKey);
             return true;
         })
-            .map((n) => n.helperFunctions)
+            .map((node) => node.helperFunctions)
             .join("\n");
         const scatterDeclarations = useScatter
             ? [
@@ -160,12 +155,11 @@ function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, alphaTest,
             "varying vec2 p_uv;",
             useNormals ? "varying vec2 p_billboardSinCos;" : "",
             varyingDeclarations.join("\n"),
-            albedoNodes.flatMap((n) => n.uniformDeclarations).join("\n"),
+            albedoNodes.flatMap((node) => node.uniformDeclarations).join("\n"),
             uniqueHelpers(albedoNodes),
-            normalNodes.flatMap((n) => n.uniformDeclarations).join("\n"),
+            normalNodes.flatMap((node) => node.uniformDeclarations).join("\n"),
             uniqueHelpers(normalNodes),
-            blendReorientedNormalsHelper,
-            emissionNodes.flatMap((n) => n.uniformDeclarations).join("\n"),
+            emissionNodes.flatMap((node) => node.uniformDeclarations).join("\n"),
             uniqueHelpers(emissionNodes),
             ...scatterDeclarations,
             ...shadowSensitivityDeclarations,
@@ -190,42 +184,32 @@ function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, alphaTest,
         }
         let fragmentShader = shader.fragmentShader;
         if (useNormals) {
-            const normalExpressions = normalNodes.map((node) => {
-                if (node instanceof FXNodeTexture) {
-                    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 = [
+            const normalLines = [
                 "float faceDirection = gl_FrontFacing ? 1.0 : -1.0;",
-                `vec3 normal = ${normalExpressions[0]};`,
-                ...blendLines,
-                "",
-                "// Rotate tangent-space normal XY into view space to match billboard rotation.",
-                "// p_billboardSinCos carries the exact sin/cos that rotated the quad vertices.",
-                "float sinR = p_billboardSinCos.x;",
-                "float cosR = p_billboardSinCos.y;",
-                "normal = vec3(",
-                "  normal.x * cosR - normal.y * sinR,",
-                "  normal.x * sinR + normal.y * cosR,",
-                "  normal.z",
-                ");",
-                "",
-                "normal *= faceDirection;",
-            ].join("\n");
-            fragmentShader = fragmentShader.replace("#include <normal_fragment_begin>", normalCode);
+                "vec3 fxNormal = vec3(0.0, 0.0, 1.0);",
+            ];
+            for (const node of normalNodes) {
+                if (node instanceof FXNodeTexture || node instanceof FXNodeColor) {
+                    normalLines.push(`fxNormal = normalize((${node.colorExpression.replace(CURRENT_EXPRESSION_VALUE_PLACEHOLDER, "vec4(fxNormal, 1.0)")}).rgb * 2.0 - 1.0);`);
+                }
+                else {
+                    normalLines.push(`fxNormal = ${node.normalExpression.replace(CURRENT_EXPRESSION_VALUE_PLACEHOLDER, "fxNormal")};`);
+                }
+            }
+            normalLines.push("", "float sinR = p_billboardSinCos.x;", "float cosR = p_billboardSinCos.y;", "vec3 normal = vec3(", "  fxNormal.x * cosR - fxNormal.y * sinR,", "  fxNormal.x * sinR + fxNormal.y * cosR,", "  fxNormal.z", ");", "", "normal *= faceDirection;");
+            fragmentShader = fragmentShader.replace("#include <normal_fragment_begin>", normalLines.join("\n"));
         }
-        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}`);
+        const albedoCode = buildAlbedoAndBlendingCode(albedoNodes, blending, useAlphaHashing);
+        if (albedoCode.mapFragment !== null) {
+            fragmentShader = fragmentShader.replace("#include <map_fragment>", albedoCode.mapFragment);
         }
         if (emissionNodes.length > 0) {
-            const combinedExpression = emissionNodes.map((n) => n.colorExpression).join(" * ");
-            fragmentShader = fragmentShader.replace("#include <emissivemap_fragment>", `totalEmissiveRadiance = (${combinedExpression}).rgb;`);
+            const emissiveLines = ["vec4 fxEmissive = vec4(1.0);"];
+            for (const node of emissionNodes) {
+                emissiveLines.push(`fxEmissive = ${node.colorExpression.replace(CURRENT_EXPRESSION_VALUE_PLACEHOLDER, "fxEmissive")};`);
+            }
+            emissiveLines.push("totalEmissiveRadiance = fxEmissive.rgb;");
+            fragmentShader = fragmentShader.replace("#include <emissivemap_fragment>", emissiveLines.join("\n"));
         }
         if (useScatter) {
             fragmentShader = fragmentShader.replace("#include <opaque_fragment>", `
@@ -271,15 +255,17 @@ function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, alphaTest,
         if (useShadowSensitivity) {
             fragmentShader = wrapShadowCalls(fragmentShader, "u_shadowSensitivity");
         }
+        fragmentShader = fragmentShader.replace("#include <premultiplied_alpha_fragment>", albedoCode.premultChunk);
         shader.fragmentShader = fragmentPreamble + "\n" + fragmentShader;
     };
     const scatterKey = useScatter ? `scatter(${scatterUniforms.u_ScatterPower.value})` : "no-scatter";
     const shadowKey = useShadowSensitivity ? "shadow-sens" : "no-shadow-sens";
     material.customProgramCacheKey = () => [
         "fx",
-        albedoNodes.map((n) => n.cacheKey).join("-") || "none",
-        normalNodes.map((n) => n.cacheKey).join("-") || "none",
-        emissionNodes.map((n) => n.cacheKey).join("-") || "none",
+        albedoNodes.map((node) => node.cacheKey).join("-") || "none",
+        normalNodes.map((node) => node.cacheKey).join("-") || "none",
+        emissionNodes.map((node) => node.cacheKey).join("-") || "none",
+        FXBlending[blending],
         scatterKey,
         shadowKey,
     ].join("_");

package/dist/materials/FXDiffuseMaterial/FXDiffuseMaterial.js

@@ -41,7 +41,7 @@ class FXDiffuseMaterial extends FXMaterial {
     }
     /** @internal */
     buildThreeMaterial(varyings) {
-        return buildFXDiffuseMaterial(varyings, this.blending, this.useAlphaHashing, this.alphaTest, this.premultipliedAlpha, this.albedoNodes, this._private_normalNodes, this._private_emissionNodes, this._private_scatterUniforms, this._private_shadowSensitivity);
+        return buildFXDiffuseMaterial(varyings, this.blending, this.useAlphaHashing, this.alphaTest, this.albedoNodes, this._private_normalNodes, this._private_emissionNodes, this._private_scatterUniforms, this._private_shadowSensitivity);
     }
 }
 

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

@@ -0,0 +1,24 @@
+import { FXNodeBlending } from "../../nodes/blending/FXNodeBlending";
+import type { FXNodeColor } from "../../nodes/color/FXNodeColor";
+import type { FXNodeTexture } from "../../nodes/texture/FXNodeTexture";
+import { FXBlending } from "./FXMaterial";
+export interface AlbedoBlendingCode {
+    /** Replacement for #include <map_fragment>. null means: leave the include as-is */
+    mapFragment: string | null;
+    /** Replacement for #include <premultiplied_alpha_fragment> */
+    premultChunk: string;
+}
+/**
+ * Processes albedoNodes in order to produce shader code for both the color assignment
+ * and the per-pixel blending mode.
+ *
+ * Nodes are composed sequentially: each node receives the current accumulated value via
+ * EXPRESSION_CURRENT_VALUE_PLACEHOLDER and returns a new value. Nodes that do not use
+ * the placeholder act as sources and replace the current value entirely.
+ *
+ * When a FXNodeBlending appears, it receives both the current mask (via
+ * EXPRESSION_CURRENT_VALUE_PLACEHOLDER) and the current color (via
+ * EXPRESSION_CURRENT_COLOR_PLACEHOLDER), and returns the new mask value. Color nodes
+ * that follow a blending node do not affect the mask.
+ */
+export declare function buildAlbedoAndBlendingCode(albedoNodes: readonly (FXNodeColor | FXNodeTexture | FXNodeBlending)[], blending: FXBlending, useAlphaHashing: boolean): AlbedoBlendingCode;

package/dist/materials/FXMaterial/FXBlending.Internal.js

@@ -0,0 +1,64 @@
+import { CURRENT_EXPRESSION_VALUE_PLACEHOLDER, BLENDING_EXPRESSION_CURRENT_COLOR_PLACEHOLDER } from '../../nodes/FXNode.js';
+import { FXNodeBlending } from '../../nodes/blending/FXNodeBlending.js';
+import { FXBlending } from './FXMaterial.js';
+
+/**
+ * Processes albedoNodes in order to produce shader code for both the color assignment
+ * and the per-pixel blending mode.
+ *
+ * Nodes are composed sequentially: each node receives the current accumulated value via
+ * EXPRESSION_CURRENT_VALUE_PLACEHOLDER and returns a new value. Nodes that do not use
+ * the placeholder act as sources and replace the current value entirely.
+ *
+ * When a FXNodeBlending appears, it receives both the current mask (via
+ * EXPRESSION_CURRENT_VALUE_PLACEHOLDER) and the current color (via
+ * EXPRESSION_CURRENT_COLOR_PLACEHOLDER), and returns the new mask value. Color nodes
+ * that follow a blending node do not affect the mask.
+ */
+function buildAlbedoAndBlendingCode(albedoNodes, blending, useAlphaHashing) {
+    if (albedoNodes.length === 0) {
+        return { mapFragment: null, premultChunk: buildPremultChunk(blending, false) };
+    }
+    const hasBlendingNodes = albedoNodes.some((node) => node instanceof FXNodeBlending);
+    const lines = [];
+    lines.push("vec4 fxAlbedo = vec4(1.0);");
+    if (hasBlendingNodes) {
+        lines.push("float fxBlendMask = 1.0;");
+    }
+    for (const node of albedoNodes) {
+        if (node instanceof FXNodeBlending) {
+            lines.push(`fxBlendMask = ${node.blendingExpression
+                .replace(CURRENT_EXPRESSION_VALUE_PLACEHOLDER, "fxBlendMask")
+                .replace(BLENDING_EXPRESSION_CURRENT_COLOR_PLACEHOLDER, "fxAlbedo")};`);
+        }
+        else {
+            lines.push(`fxAlbedo = ${node.colorExpression.replace(CURRENT_EXPRESSION_VALUE_PLACEHOLDER, "fxAlbedo")};`);
+        }
+    }
+    const discardLine = useAlphaHashing ? "" : "if (diffuseColor.a < 0.0035) discard;";
+    lines.push(`diffuseColor = fxAlbedo; ${discardLine}`);
+    return {
+        mapFragment: lines.join("\n"),
+        premultChunk: buildPremultChunk(blending, hasBlendingNodes),
+    };
+}
+function buildPremultChunk(blending, hasBlendingNodes) {
+    if (!hasBlendingNodes) {
+        return `gl_FragColor.rgb *= gl_FragColor.a;`;
+    }
+    if (blending === FXBlending.MASKED_ADDITIVE) {
+        return `
+      gl_FragColor.rgb *= gl_FragColor.a;
+      gl_FragColor.a *= (1.0 - clamp(fxBlendMask, 0.0, 1.0));
+    `;
+    }
+    // MASKED_MULTIPLY: dark areas darken destination, bright areas normal-blend
+    return `
+    gl_FragColor.rgb *= gl_FragColor.a;
+    float fxLumPremult = dot(gl_FragColor.rgb, vec3(0.2126, 0.7152, 0.0722));
+    vec4 fxMultiply = vec4(0.0, 0.0, 0.0, gl_FragColor.a - fxLumPremult);
+    gl_FragColor = mix(gl_FragColor, fxMultiply, clamp(fxBlendMask, 0.0, 1.0));
+  `;
+}
+
+export { buildAlbedoAndBlendingCode };

package/dist/materials/FXMaterial/FXDepthMaterial.Internal.js

@@ -1,5 +1,6 @@
 import { MeshDepthMaterial, DoubleSide, RGBADepthPacking } from 'three';
 import { PARTICLE_DEFINES } from '../../miscellaneous/miscellaneous.js';
+import { CURRENT_EXPRESSION_VALUE_PLACEHOLDER } from '../../nodes/FXNode.js';
 
 const DEPTH_VERTEX_SHADER = `
   #define PARTICLE_POSITION_X a_builtin[0][0]
@@ -116,9 +117,13 @@ function buildDepthMaterial(albedoNodes, depthAlphaTest, useDepthAlphaHash, useS
         }
         let fragmentShader = shader.fragmentShader;
         if (depthNodes.length > 0) {
-            const combinedAlphaExpression = depthNodes.map((node) => node.colorExpression).join(" * ");
-            fragmentShader = fragmentShader.replace("#include <map_fragment>", `diffuseColor.a = (${combinedAlphaExpression}).a;
-         if (diffuseColor.a < ${depthAlphaTest.toFixed(4)}) discard;`);
+            const albedoLines = ["vec4 fxDepthAlbedo = vec4(1.0);"];
+            for (const node of depthNodes) {
+                albedoLines.push(`fxDepthAlbedo = ${node.colorExpression.replace(CURRENT_EXPRESSION_VALUE_PLACEHOLDER, "fxDepthAlbedo")};`);
+            }
+            albedoLines.push(`diffuseColor.a = fxDepthAlbedo.a;`);
+            albedoLines.push(`if (diffuseColor.a < ${depthAlphaTest.toFixed(4)}) discard;`);
+            fragmentShader = fragmentShader.replace("#include <map_fragment>", albedoLines.join("\n"));
         }
         if (useSphericalDepth) {
             if (!FRAG_COORD_Z_PATTERN.test(fragmentShader)) {

package/dist/materials/FXMaterial/FXDistanceMaterial.Internal.js

@@ -1,5 +1,6 @@
 import { MeshDistanceMaterial, DoubleSide } from 'three';
 import { PARTICLE_DEFINES } from '../../miscellaneous/miscellaneous.js';
+import { CURRENT_EXPRESSION_VALUE_PLACEHOLDER } from '../../nodes/FXNode.js';
 
 /**
  * Custom vertex shader for point/spot light shadow maps.
@@ -134,9 +135,12 @@ function buildDistanceMaterial(albedoNodes, distanceAlphaTest, useDistanceAlphaH
         // <map_fragment> depending on the Three.js version. If the chunk is
         // absent, insert the alpha discard before the distance calculation.
         if (distanceNodes.length > 0) {
-            const combinedAlphaExpression = distanceNodes.map((node) => node.colorExpression).join(" * ");
-            const alphaDiscardCode = `float nodeAlpha = (${combinedAlphaExpression}).a;\n` +
-                `if (nodeAlpha < ${distanceAlphaTest.toFixed(4)}) discard;`;
+            const albedoLines = ["vec4 fxDistAlbedo = vec4(1.0);"];
+            for (const node of distanceNodes) {
+                albedoLines.push(`fxDistAlbedo = ${node.colorExpression.replace(CURRENT_EXPRESSION_VALUE_PLACEHOLDER, "fxDistAlbedo")};`);
+            }
+            albedoLines.push(`float nodeAlpha = fxDistAlbedo.a;`);
+            const alphaDiscardCode = albedoLines.join("\n") + `\nif (nodeAlpha < ${distanceAlphaTest.toFixed(4)}) discard;`;
             if (fragmentShader.includes("#include <map_fragment>")) {
                 fragmentShader = fragmentShader.replace("#include <map_fragment>", alphaDiscardCode);
             }

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

@@ -1,6 +1,20 @@
-import type { Blending } from "three";
-import type { FXNodeColor } from "../../nodes/color/FXNodeColor";
-import type { FXNodeTexture } from "../../nodes/texture/FXNodeTexture";
+import { FXNodeColor } from "../../nodes/color/FXNodeColor";
+import { FXNodeTexture } from "../../nodes/texture/FXNodeTexture";
+/**
+ * Per-particle blend mode used when compositing particles into the scene
+ */
+export declare enum FXBlending {
+    /**
+     * Premultiplied additive blend - particle color is pre-multiplied by alpha and added to the
+     * destination with zero alpha contribution
+     */
+    MASKED_ADDITIVE = 0,
+    /**
+     * Luminance-aware multiply blend - dark areas darken the destination while bright areas
+     * normal-blend through a mask
+     */
+    MASKED_MULTIPLY = 1
+}
 /**
  * Configuration options shared by all {@link FXMaterial} subclasses
  */
@@ -11,12 +25,7 @@ export interface FXMaterialOptions {
      * @defaultValue `[]`
      */
     albedoNodes: (FXNodeColor | FXNodeTexture)[];
-    /**
-     * Three.js blending mode
-     *
-     * @defaultValue `NormalBlending`
-     */
-    blending: Blending;
+    blending: FXBlending;
     /**
      * Use alpha hashing instead of standard transparency
      *
@@ -47,12 +56,6 @@ export interface FXMaterialOptions {
      * @defaultValue `true`
      */
     useSphericalDepth: boolean;
-    /**
-     * Use premultiplied alpha blending
-     *
-     * @defaultValue `true`
-     */
-    premultipliedAlpha: boolean;
 }
 /**
  * Abstract base class for particle materials

package/dist/materials/FXMaterial/FXMaterial.js

@@ -1,18 +1,33 @@
-import { NormalBlending } from 'three';
+import { FXNodeColor } from '../../nodes/color/FXNodeColor.js';
+import { FXNodeTexture } from '../../nodes/texture/FXNodeTexture.js';
 import { buildDepthMaterial } from './FXDepthMaterial.Internal.js';
 import { buildDistanceMaterial } from './FXDistanceMaterial.Internal.js';
 
+/**
+ * Per-particle blend mode used when compositing particles into the scene
+ */
+var FXBlending;
+(function (FXBlending) {
+    /**
+     * Premultiplied additive blend - particle color is pre-multiplied by alpha and added to the
+     * destination with zero alpha contribution
+     */
+    FXBlending[FXBlending["MASKED_ADDITIVE"] = 0] = "MASKED_ADDITIVE";
+    /**
+     * Luminance-aware multiply blend - dark areas darken the destination while bright areas
+     * normal-blend through a mask
+     */
+    FXBlending[FXBlending["MASKED_MULTIPLY"] = 1] = "MASKED_MULTIPLY";
+})(FXBlending || (FXBlending = {}));
 /**
  * Abstract base class for particle materials
  */
 class FXMaterial {
     constructor(options = {}) {
         this.albedoNodes = options.albedoNodes ?? [];
-        this.blending = options.blending ?? NormalBlending;
+        this.blending = options.blending ?? FXBlending.MASKED_ADDITIVE;
         this.useAlphaHashing = options.useAlphaHashing ?? false;
         this.alphaTest = options.alphaTest ?? 0.0075;
-        this.premultipliedAlpha =
-            (options.useAlphaHashing === undefined && options.premultipliedAlpha) ?? true;
         this._private_depthAlphaTest = options.depthAlphaTest ?? 0.5;
         this._private_useDepthAlphaHash = options.useDepthAlphaHash ?? false;
         this._private_useSphericalDepth = options.useSphericalDepth ?? true;
@@ -25,12 +40,12 @@ class FXMaterial {
     }
     /** @internal */
     buildDepthMaterial() {
-        return buildDepthMaterial(this.albedoNodes, this._private_depthAlphaTest, this._private_useDepthAlphaHash, this._private_useSphericalDepth);
+        return buildDepthMaterial(this.albedoNodes.filter((node) => node instanceof FXNodeColor || node instanceof FXNodeTexture), this._private_depthAlphaTest, this._private_useDepthAlphaHash, this._private_useSphericalDepth);
     }
     /** @internal */
     buildDistanceMaterial() {
-        return buildDistanceMaterial(this.albedoNodes, this._private_depthAlphaTest, this._private_useDepthAlphaHash, this._private_useSphericalDepth);
+        return buildDistanceMaterial(this.albedoNodes.filter((node) => node instanceof FXNodeColor || node instanceof FXNodeTexture), this._private_depthAlphaTest, this._private_useDepthAlphaHash, this._private_useSphericalDepth);
     }
 }
 
-export { FXMaterial };
+export { FXBlending, FXMaterial };

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

@@ -1,6 +1,7 @@
-import type { Blending } from "three";
 import { MeshBasicMaterial } from "three";
 import type { GLTypeInfo } from "../../instancedParticle/shared";
+import type { FXNodeBlending } from "../../nodes/blending/FXNodeBlending";
 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;
+import { FXBlending } from "../FXMaterial/FXMaterial";
+export declare function buildFXUnlitMaterial(varyings: Record<string, GLTypeInfo>, blending: FXBlending, useAlphaHashing: boolean, alphaTest: number, albedoNodes: readonly (FXNodeColor | FXNodeTexture | FXNodeBlending)[]): MeshBasicMaterial;

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

@@ -1,7 +1,9 @@
-import { MeshBasicMaterial, DoubleSide } from 'three';
+import { MeshBasicMaterial, DoubleSide, NormalBlending } from 'three';
 import { PARTICLE_DEFINES } from '../../miscellaneous/miscellaneous.js';
+import { buildAlbedoAndBlendingCode } from '../FXMaterial/FXBlending.Internal.js';
+import { FXBlending } from '../FXMaterial/FXMaterial.js';
 
-function buildFXUnlitMaterial(varyings, blending, useAlphaHashing, alphaTest, premultipliedAlpha, albedoNodes) {
+function buildFXUnlitMaterial(varyings, blending, useAlphaHashing, alphaTest, albedoNodes) {
     const attributeDeclarations = [];
     const varyingDeclarations = [];
     const vertexAssignments = [];
@@ -17,11 +19,11 @@ function buildFXUnlitMaterial(varyings, blending, useAlphaHashing, alphaTest, pr
         depthWrite: useAlphaHashing,
         depthTest: true,
         alphaHash: useAlphaHashing,
-        blending,
+        blending: NormalBlending,
         side: DoubleSide,
         forceSinglePass: true,
         alphaTest,
-        premultipliedAlpha,
+        premultipliedAlpha: true,
     });
     material.onBeforeCompile = (shader) => {
         const vertexPreamble = [
@@ -63,34 +65,34 @@ function buildFXUnlitMaterial(varyings, blending, useAlphaHashing, alphaTest, pr
           `);
         const seenCacheKeys = new Set();
         const uniqueHelpers = (nodes) => nodes
-            .filter((n) => {
-            if (seenCacheKeys.has(n.cacheKey)) {
+            .filter((node) => {
+            if (seenCacheKeys.has(node.cacheKey)) {
                 return false;
             }
-            seenCacheKeys.add(n.cacheKey);
+            seenCacheKeys.add(node.cacheKey);
             return true;
         })
-            .map((n) => n.helperFunctions)
+            .map((node) => node.helperFunctions)
             .join("\n");
         const fragmentPreamble = [
             PARTICLE_DEFINES,
             "varying vec2 p_uv;",
             varyingDeclarations.join("\n"),
-            albedoNodes.flatMap((n) => n.uniformDeclarations).join("\n"),
+            albedoNodes.flatMap((node) => node.uniformDeclarations).join("\n"),
             uniqueHelpers(albedoNodes),
         ].join("\n");
         for (const node of albedoNodes) {
             Object.assign(shader.uniforms, node.uniforms);
         }
+        const albedoCode = buildAlbedoAndBlendingCode(albedoNodes, blending, useAlphaHashing);
         let fragmentShader = shader.fragmentShader;
-        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 (albedoCode.mapFragment !== null) {
+            fragmentShader = fragmentShader.replace("#include <map_fragment>", albedoCode.mapFragment);
         }
+        fragmentShader = fragmentShader.replace("#include <premultiplied_alpha_fragment>", albedoCode.premultChunk);
         shader.fragmentShader = fragmentPreamble + "\n" + fragmentShader;
     };
-    material.customProgramCacheKey = () => `fx-unlit-${albedoNodes.map((n) => n.cacheKey).join("-") || "none"}`;
+    material.customProgramCacheKey = () => ["fx-unlit", albedoNodes.map((node) => node.cacheKey).join("-") || "none", FXBlending[blending]].join("_");
     return material;
 }
 

package/dist/materials/FXUnlitMaterial/FXUnlitMaterial.js

@@ -7,7 +7,7 @@ import { buildFXUnlitMaterial } from './FXUnlitMaterial.Internal.js';
 class FXUnlitMaterial extends FXMaterial {
     /** @internal */
     buildThreeMaterial(varyings) {
-        return buildFXUnlitMaterial(varyings, this.blending, this.useAlphaHashing, this.alphaTest, this.premultipliedAlpha, this.albedoNodes);
+        return buildFXUnlitMaterial(varyings, this.blending, this.useAlphaHashing, this.alphaTest, this.albedoNodes);
     }
 }
 

package/dist/nodes/FXNode.d.ts

@@ -0,0 +1,5 @@
+export declare const CURRENT_EXPRESSION_VALUE_PLACEHOLDER = "CURRENT_EXPRESSION_VALUE_PLACEHOLDER";
+export declare const BLENDING_EXPRESSION_CURRENT_COLOR_PLACEHOLDER = "BLENDING_EXPRESSION_CURRENT_COLOR_PLACEHOLDER";
+export declare abstract class FXNode {
+    destroy?(): void;
+}

package/dist/nodes/FXNode.js

@@ -0,0 +1,10 @@
+const CURRENT_EXPRESSION_VALUE_PLACEHOLDER = "CURRENT_EXPRESSION_VALUE_PLACEHOLDER";
+const BLENDING_EXPRESSION_CURRENT_COLOR_PLACEHOLDER = "BLENDING_EXPRESSION_CURRENT_COLOR_PLACEHOLDER";
+class FXNode {
+    constructor() {
+        /** @internal */
+        this.affectsDepth = false;
+    }
+}
+
+export { BLENDING_EXPRESSION_CURRENT_COLOR_PLACEHOLDER, CURRENT_EXPRESSION_VALUE_PLACEHOLDER, FXNode };

package/dist/nodes/blending/FXNodeBlending.d.ts

@@ -0,0 +1,6 @@
+import { FXNode } from "../FXNode";
+/**
+ * Abstract base class for particle color nodes
+ */
+export declare abstract class FXNodeBlending extends FXNode {
+}

package/dist/nodes/blending/FXNodeBlending.js

@@ -0,0 +1,9 @@
+import { FXNode } from '../FXNode.js';
+
+/**
+ * Abstract base class for particle color nodes
+ */
+class FXNodeBlending extends FXNode {
+}
+
+export { FXNodeBlending };

package/dist/nodes/blending/FXNodeLightnessBlendingMask.d.ts

@@ -0,0 +1,16 @@
+import { FXNodeBlending } from "./FXNodeBlending";
+export declare class FXNodeLightnessBlendingMask extends FXNodeBlending {
+    private readonly uniformEdge0;
+    private readonly uniformEdge1;
+    /**
+     * @param edge0 - brightness threshold where mask starts (below this: NormalBlending). Defaults to `0.3`
+     * @param edge1 - brightness threshold where mask is fully active (above this: full FXBlending effect). Defaults to `0.7`
+     */
+    constructor(edge0?: number, edge1?: number);
+    /** Brightness threshold where mask starts (below this: NormalBlending) */
+    get edge0(): number;
+    /** Brightness threshold where mask is fully active (above this: full FXBlending effect) */
+    get edge1(): number;
+    set edge0(value: number);
+    set edge1(value: number);
+}