sparcoon 0.3.1 → 0.4.1

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

@@ -7,6 +7,7 @@ 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;
 export declare function collectProperties(keeper: Record<string, GLTypeInfo>, modules: readonly {
     requiredProperties?: Record<string, FXPropertyName>;
 }[], debugContext: string): void;

package/dist/emitter/FXEmitter.Internal.js

@@ -5,6 +5,7 @@ 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;
 function collectProperties(keeper, modules, debugContext) {
     for (const module of modules) {
         if (module.requiredProperties === undefined) {
@@ -23,4 +24,4 @@ function collectProperties(keeper, modules, debugContext) {
     }
 }
 
-export { EMITTER_DEFAULT_AUTOMATICALLY_DESTROY_MODULES, EMITTER_DEFAULT_CAPACITY_STEP, EMITTER_DEFAULT_CAST_SHADOW, EMITTER_DEFAULT_EXPECTED_CAPACITY, EMITTER_DEFAULT_RECEIVE_SHADOW, collectProperties };
+export { EMITTER_DEFAULT_AUTOMATICALLY_DESTROY_MODULES, EMITTER_DEFAULT_CAPACITY_STEP, EMITTER_DEFAULT_CAST_SHADOW, EMITTER_DEFAULT_EXPECTED_CAPACITY, EMITTER_DEFAULT_RECEIVE_SHADOW, EMITTER_DEFAULT_SORT_FRACTION, collectProperties };

package/dist/emitter/FXEmitter.d.ts

@@ -1,3 +1,4 @@
+import type { Camera } from "three";
 import { Object3D } from "three";
 import type { FXMaterial } from "../materials/FXMaterial/FXMaterial";
 import type { FXBehavior } from "./behavior/FXBehavior";
@@ -9,17 +10,23 @@ export interface FXEmitterOptions {
     automaticallyDestroyModules: boolean;
     castShadow: boolean;
     receiveShadow: boolean;
+    sortCamera: Camera;
+    sortFraction: number;
 }
 export declare class FXEmitter extends Object3D {
     private readonly spawnSequence;
     private readonly behaviorSequence;
     automaticallyDestroyModules: boolean;
+    sortCamera: Camera | undefined;
+    sortFraction: number;
     private readonly mesh;
     private readonly material;
     private emissionRate;
     private emissionAccumulator;
     private emissionDuration;
     private emissionElapsed;
+    private sortingAccumulator;
+    private readonly sortingCameraWorldPosition;
     constructor(spawnSequence: FXSpawn[], behaviorSequence: readonly FXBehavior[], material: FXMaterial, options?: Partial<FXEmitterOptions>);
     static onWillRender: (deltaTime: number) => void;
     destroy(): void;

package/dist/emitter/FXEmitter.js

@@ -1,8 +1,8 @@
-import { Object3D } from 'three';
+import { Object3D, Vector3 } from 'three';
 import { FXInstancedParticle } from '../instancedParticle/FXInstancedParticle.js';
 import { resolveGLSLTypeInfo } from '../instancedParticle/shared.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 { collectProperties, EMITTER_DEFAULT_EXPECTED_CAPACITY, EMITTER_DEFAULT_CAPACITY_STEP, EMITTER_DEFAULT_CAST_SHADOW, EMITTER_DEFAULT_RECEIVE_SHADOW, EMITTER_DEFAULT_AUTOMATICALLY_DESTROY_MODULES } from './FXEmitter.Internal.js';
+import { 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 } from './FXEmitter.Internal.js';
 
 const EMITTERS = new Array();
 class FXEmitter extends Object3D {
@@ -14,6 +14,8 @@ class FXEmitter extends Object3D {
         this._private_emissionAccumulator = 0;
         this._private_emissionDuration = Infinity;
         this._private_emissionElapsed = 0;
+        this._private_sortingAccumulator = 0;
+        this._private_sortingCameraWorldPosition = new Vector3();
         this._private_onRendering = (deltaTime) => {
             {
                 const { builtin } = this._private_mesh.propertyBuffers;
@@ -69,6 +71,14 @@ class FXEmitter extends Object3D {
                 }
                 builtin.needsUpdate = true;
             }
+            if (this.sortCamera !== undefined) {
+                this._private_sortingAccumulator += this.sortFraction;
+                if (this._private_sortingAccumulator >= 1) {
+                    this._private_sortingAccumulator -= 1;
+                    this.sortCamera.getWorldPosition(this._private_sortingCameraWorldPosition);
+                    this._private_mesh.sortByDistance(this._private_sortingCameraWorldPosition);
+                }
+            }
         };
         const collectedProperties = {
             builtin: resolveGLSLTypeInfo("Matrix4"),
@@ -80,12 +90,15 @@ class FXEmitter extends Object3D {
         if (options.castShadow ?? EMITTER_DEFAULT_CAST_SHADOW) {
             this._private_mesh.castShadow = true;
             this._private_mesh.customDepthMaterial = material.buildDepthMaterial();
+            this._private_mesh.customDistanceMaterial = material.buildDistanceMaterial();
         }
         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);

package/dist/instancedParticle/FXInstancedParticle.d.ts

@@ -1,4 +1,4 @@
-import type { Material } from "three";
+import type { Material, Vector3 } from "three";
 import { InstancedBufferAttribute, Mesh } from "three";
 import type { GLTypeInfo } from "./shared";
 export declare class FXInstancedParticle extends Mesh {
@@ -7,10 +7,14 @@ export declare class FXInstancedParticle extends Mesh {
     private readonly instancedGeometry;
     private readonly particleMaterial;
     private capacity;
+    private sortingIndices;
+    private sortingSquaredDistances;
+    private sortingTemporaryBuffer;
     constructor(varyings: Record<string, GLTypeInfo>, expectedCapacity: number, capacityStep: number, material: Material);
     get instanceCount(): number;
     createInstances(count: number): void;
     removeDeadParticles(): void;
+    sortByDistance(cameraWorldPosition: Vector3): void;
     drop(): void;
     destroy(): void;
     private ensureCapacity;

package/dist/instancedParticle/FXInstancedParticle.js

@@ -1,5 +1,5 @@
 import { Mesh, InstancedBufferAttribute, StreamDrawUsage } from 'three';
-import { BUILTIN_OFFSET_AGE, BUILTIN_OFFSET_LIFETIME } from '../miscellaneous/miscellaneous.js';
+import { BUILTIN_OFFSET_AGE, BUILTIN_OFFSET_LIFETIME, BUILTIN_OFFSET_POSITION_X, BUILTIN_OFFSET_POSITION_Y, BUILTIN_OFFSET_POSITION_Z } from '../miscellaneous/miscellaneous.js';
 import { INSTANCED_PARTICLE_GEOMETRY } from './FXInstancedParticle.Internal.js';
 
 class FXInstancedParticle extends Mesh {
@@ -8,6 +8,9 @@ class FXInstancedParticle extends Mesh {
         super(instancedGeometry, material);
         this._private_capacityStep = _private_capacityStep;
         this.propertyBuffers = {};
+        this._private_sortingIndices = new Int32Array(0);
+        this._private_sortingSquaredDistances = new Float64Array(0);
+        this._private_sortingTemporaryBuffer = new Float32Array(0);
         this.frustumCulled = false;
         this._private_instancedGeometry = instancedGeometry;
         this._private_instancedGeometry.instanceCount = 0;
@@ -37,6 +40,7 @@ class FXInstancedParticle extends Mesh {
         const { array: builtinArray, itemSize: builtinItemSize } = builtinBuffer;
         const { instanceCount } = this._private_instancedGeometry;
         let writeIndex = 0;
+        let didCompact = false;
         for (let readIndex = 0; readIndex < instanceCount; readIndex++) {
             const offset = readIndex * builtinItemSize;
             if (builtinArray[offset + BUILTIN_OFFSET_AGE] < builtinArray[offset + BUILTIN_OFFSET_LIFETIME]) {
@@ -47,14 +51,72 @@ class FXInstancedParticle extends Mesh {
                         const srcOffset = readIndex * dataItemSize;
                         const dstOffset = writeIndex * dataItemSize;
                         dataArray.copyWithin(dstOffset, srcOffset, srcOffset + dataItemSize);
-                        attribute.needsUpdate = true;
                     }
+                    didCompact = true;
                 }
                 writeIndex++;
             }
         }
+        if (didCompact) {
+            for (const name in this.propertyBuffers) {
+                this.propertyBuffers[name].needsUpdate = true;
+            }
+        }
         this._private_instancedGeometry.instanceCount = writeIndex;
     }
+    sortByDistance(cameraWorldPosition) {
+        const { instanceCount } = this._private_instancedGeometry;
+        if (instanceCount < 2) {
+            return;
+        }
+        const builtinBuffer = this.propertyBuffers.builtin;
+        if (builtinBuffer === undefined) {
+            return;
+        }
+        if (this._private_sortingIndices.length < instanceCount) {
+            this._private_sortingIndices = new Int32Array(this._private_capacity);
+            this._private_sortingSquaredDistances = new Float64Array(this._private_capacity);
+        }
+        const { array: builtinArray, itemSize: builtinItemSize } = builtinBuffer;
+        for (let particleIndex = 0; particleIndex < instanceCount; particleIndex++) {
+            this._private_sortingIndices[particleIndex] = particleIndex;
+            const itemOffset = particleIndex * builtinItemSize;
+            const dx = builtinArray[itemOffset + BUILTIN_OFFSET_POSITION_X] - cameraWorldPosition.x;
+            const dy = builtinArray[itemOffset + BUILTIN_OFFSET_POSITION_Y] - cameraWorldPosition.y;
+            const dz = builtinArray[itemOffset + BUILTIN_OFFSET_POSITION_Z] - cameraWorldPosition.z;
+            this._private_sortingSquaredDistances[particleIndex] = dx * dx + dy * dy + dz * dz;
+        }
+        const sortingSquaredDistances = this._private_sortingSquaredDistances;
+        const sortingIndices = this._private_sortingIndices.subarray(0, instanceCount);
+        sortingIndices.sort((indexA, indexB) => sortingSquaredDistances[indexB] - sortingSquaredDistances[indexA]);
+        let maximumItemSize = 0;
+        for (const name in this.propertyBuffers) {
+            if (this.propertyBuffers[name].itemSize > maximumItemSize) {
+                maximumItemSize = this.propertyBuffers[name].itemSize;
+            }
+        }
+        const requiredTemporaryBufferSize = instanceCount * maximumItemSize;
+        if (this._private_sortingTemporaryBuffer.length < requiredTemporaryBufferSize) {
+            this._private_sortingTemporaryBuffer = new Float32Array(this._private_capacity * maximumItemSize);
+        }
+        for (const name in this.propertyBuffers) {
+            const attribute = this.propertyBuffers[name];
+            const { array, itemSize } = attribute;
+            for (let newIndex = 0; newIndex < instanceCount; newIndex++) {
+                const originalIndex = sortingIndices[newIndex];
+                const sourceOffset = originalIndex * itemSize;
+                const destinationOffset = newIndex * itemSize;
+                for (let componentIndex = 0; componentIndex < itemSize; componentIndex++) {
+                    this._private_sortingTemporaryBuffer[destinationOffset + componentIndex] =
+                        array[sourceOffset + componentIndex];
+                }
+            }
+            for (let i = 0; i < instanceCount * itemSize; i++) {
+                array[i] = this._private_sortingTemporaryBuffer[i];
+            }
+            attribute.needsUpdate = true;
+        }
+    }
     drop() {
         this._private_instancedGeometry.instanceCount = 0;
     }
@@ -68,17 +130,32 @@ class FXInstancedParticle extends Mesh {
         }
         const newCapacity = Math.ceil(requiredCapacity / this._private_capacityStep) * this._private_capacityStep;
         for (const name in this.propertyBuffers) {
-            const { itemSize, array, usage } = this.propertyBuffers[name];
+            const oldAttribute = this.propertyBuffers[name];
+            const { itemSize, array, usage } = oldAttribute;
             const newArray = new Float32Array(newCapacity * itemSize);
             newArray.set(array);
             const newAttribute = new InstancedBufferAttribute(newArray, itemSize);
             newAttribute.setUsage(usage);
             this._private_instancedGeometry.setAttribute(`a_${name}`, newAttribute);
             this.propertyBuffers[name] = newAttribute;
+            // Detach old typed array to help GC release GPU-side memory sooner.
+            // Three.js does not expose dispose() on BufferAttribute directly,
+            // but clearing the array reference prevents the old data from lingering.
+            oldAttribute.array = null;
         }
         this._private_capacity = newCapacity;
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- old three.js compatibility fix
-        this._private_instancedGeometry._maxInstanceCount = newCapacity;
+        // Force the renderer to recalculate _maxInstanceCount on the next
+        // setupVertexAttributes pass. The new InstancedBufferAttributes will
+        // trigger a VAO rebind, at which point _maxInstanceCount is recomputed
+        // from the current attribute sizes.
+        //
+        // _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
+        // the Three.js ecosystem (see #19706, #26363, #27205).
+        //
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        delete this._private_instancedGeometry._maxInstanceCount;
     }
 }
 

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

@@ -1,7 +1,23 @@
 import type { Blending } from "three";
-import { MeshLambertMaterial } from "three";
+import { Color, MeshLambertMaterial } from "three";
 import type { GLTypeInfo } from "../../instancedParticle/shared";
 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;
+export interface FXScatterUniforms {
+    u_ScatterTint: {
+        value: Color;
+    };
+    u_ScatterPower: {
+        value: number;
+    };
+    u_ForwardScatterStrength: {
+        value: number;
+    };
+    u_BackScatterStrength: {
+        value: number;
+    };
+}
+export declare function buildFXDiffuseMaterial(varyings: Record<string, GLTypeInfo>, blending: Blending, useAlphaHashing: boolean, alphaTest: number, premultipliedAlpha: boolean, albedoNodes: readonly (FXColorNode | FXTextureNode)[], normalNodes: readonly (FXTextureNode | FXNormalNode)[], emissionNodes: readonly (FXColorNode | FXTextureNode)[], scatterUniforms?: FXScatterUniforms, shadowSensitivity?: {
+    value: number;
+}): MeshLambertMaterial;

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

@@ -2,7 +2,44 @@ import { MeshLambertMaterial, Color, DoubleSide } from 'three';
 import { PARTICLE_DEFINES } from '../../miscellaneous/miscellaneous.js';
 import { FXTextureNode } from '../../nodes/texture/FXTextureNode.js';
 
-function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, alphaTest, albedoNodes, normalNodes, emissionNodes) {
+/**
+ * Wraps every `getShadow(...)` call in the shader source with
+ * `mix(1.0, getShadow(...), <uniformName>)` so that a uniform
+ * can scale shadow influence from 0 (no shadows) to 1 (full shadows).
+ */
+function wrapShadowCalls(source, uniformName) {
+    const target = "getShadow(";
+    let result = "";
+    let position = 0;
+    while (position < source.length) {
+        const callStart = source.indexOf(target, position);
+        if (callStart === -1) {
+            result += source.slice(position);
+            break;
+        }
+        result += source.slice(position, callStart);
+        let depth = 0;
+        let cursor = callStart + target.length - 1;
+        for (; cursor < source.length; cursor++) {
+            if (source[cursor] === "(") {
+                depth++;
+            }
+            if (source[cursor] === ")") {
+                depth--;
+            }
+            if (depth === 0) {
+                break;
+            }
+        }
+        const originalCall = source.slice(callStart, cursor + 1);
+        result += `mix(1.0, ${originalCall}, ${uniformName})`;
+        position = cursor + 1;
+    }
+    return result;
+}
+function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, alphaTest, premultipliedAlpha, albedoNodes, normalNodes, emissionNodes, scatterUniforms, shadowSensitivity) {
+    const useScatter = scatterUniforms !== undefined;
+    const useShadowSensitivity = shadowSensitivity !== undefined;
     const attributeDeclarations = [];
     const varyingDeclarations = [];
     const vertexAssignments = [];
@@ -13,6 +50,7 @@ function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, alphaTest,
         vertexAssignments.push(`p_${name} = a_${name};`);
     }
     const material = new MeshLambertMaterial({
+        name: "FXDiffuseMaterial",
         transparent: !useAlphaHashing,
         depthWrite: useAlphaHashing,
         depthTest: true,
@@ -22,12 +60,14 @@ function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, alphaTest,
         forceSinglePass: true,
         alphaTest,
         emissive: emissionNodes.length > 0 ? new Color(1, 1, 1) : new Color(0, 0, 0),
+        premultipliedAlpha,
     });
     material.onBeforeCompile = (shader) => {
         const vertexPreamble = [
             PARTICLE_DEFINES,
             attributeDeclarations.join("\n"),
             "varying vec2 p_uv;",
+            useScatter ? "varying vec3 v_viewPosition;" : "",
             varyingDeclarations.join("\n"),
         ].join("\n");
         shader.vertexShader =
@@ -44,29 +84,26 @@ function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, alphaTest,
                     "  vPosition = vec3(PARTICLE_POSITION_X, PARTICLE_POSITION_Y, PARTICLE_POSITION_Z) + vec3(position.xy, 0.0);",
                     "#endif",
                 ].join("\n"))
-                    .replace("#include <project_vertex>", `
-          // 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
-          );
-
-          // 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 <project_vertex>", [
+                    "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 particleCenter = vec3(PARTICLE_POSITION_X, PARTICLE_POSITION_Y, PARTICLE_POSITION_Z);",
+                    "vec4 mvPosition = modelViewMatrix * vec4(particleCenter, 1.0);",
+                    "mvPosition.xy += billboardOffset;",
+                    useScatter ? "v_viewPosition = mvPosition.xyz;" : "",
+                    "gl_Position = projectionMatrix * mvPosition;",
+                ].join("\n"))
                     .replace("#include <worldpos_vertex>", `
           #if defined(USE_SHADOWMAP) || defined(USE_ENVMAP) || defined(DISTANCE) || (NUM_SPOT_LIGHT_COORDS > 0)
-            // 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(
@@ -95,6 +132,24 @@ function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, alphaTest,
         })
             .map((n) => n.helperFunctions)
             .join("\n");
+        const scatterDeclarations = useScatter
+            ? [
+                "varying vec3 v_viewPosition;",
+                "uniform vec3 u_ScatterTint;",
+                "uniform float u_ScatterPower;",
+                "uniform float u_ForwardScatterStrength;",
+                "uniform float u_BackScatterStrength;",
+                `vec3 calculateScatter(vec3 viewDirection, vec3 lightDirection, vec3 lightColor, float alpha) {
+            float viewDotLight = dot(viewDirection, lightDirection);
+            float scatterForward  = pow(max(-viewDotLight, 0.0), u_ScatterPower) * u_ForwardScatterStrength;
+            float scatterBackward = pow(max( viewDotLight, 0.0), 2.0) * u_BackScatterStrength;
+            return lightColor * u_ScatterTint * (scatterForward + scatterBackward) * alpha;
+          }`,
+            ]
+            : [];
+        const shadowSensitivityDeclarations = useShadowSensitivity
+            ? ["uniform float u_shadowSensitivity;"]
+            : [];
         const fragmentPreamble = [
             PARTICLE_DEFINES,
             "varying vec2 p_uv;",
@@ -106,7 +161,18 @@ function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, alphaTest,
             blendReorientedNormalsHelper,
             emissionNodes.flatMap((n) => n.uniformDeclarations).join("\n"),
             uniqueHelpers(emissionNodes),
+            ...scatterDeclarations,
+            ...shadowSensitivityDeclarations,
         ].join("\n");
+        if (useScatter) {
+            shader.uniforms["u_ScatterTint"] = scatterUniforms.u_ScatterTint;
+            shader.uniforms["u_ScatterPower"] = scatterUniforms.u_ScatterPower;
+            shader.uniforms["u_ForwardScatterStrength"] = scatterUniforms.u_ForwardScatterStrength;
+            shader.uniforms["u_BackScatterStrength"] = scatterUniforms.u_BackScatterStrength;
+        }
+        if (useShadowSensitivity) {
+            shader.uniforms["u_shadowSensitivity"] = shadowSensitivity;
+        }
         for (const node of albedoNodes) {
             Object.assign(shader.uniforms, node.uniforms);
         }
@@ -131,6 +197,7 @@ function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, alphaTest,
                 "float faceDirection = gl_FrontFacing ? 1.0 : -1.0;",
                 `vec3 normal = ${normalExpressions[0]};`,
                 ...blendLines,
+                "normal *= faceDirection;",
             ].join("\n");
             fragmentShader = fragmentShader.replace("#include <normal_fragment_begin>", normalCode);
         }
@@ -143,9 +210,71 @@ function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, alphaTest,
             const combinedExpression = emissionNodes.map((n) => n.colorExpression).join(" * ");
             fragmentShader = fragmentShader.replace("#include <emissivemap_fragment>", `totalEmissiveRadiance = (${combinedExpression}).rgb;`);
         }
+        if (useScatter) {
+            // Per-fragment Mie scatter for all light types.
+            // viewDirection and all light directions/positions are in view space.
+            fragmentShader = fragmentShader.replace("#include <opaque_fragment>", `
+        #ifdef OPAQUE
+          diffuseColor.a = 1.0;
+        #endif
+
+        vec3 viewDirection = normalize(-v_viewPosition);
+        vec3 totalScatter = vec3(0.0);
+
+        #if NUM_DIR_LIGHTS > 0
+          for (int i = 0; i < NUM_DIR_LIGHTS; i++) {
+            totalScatter += calculateScatter(viewDirection, directionalLights[i].direction, directionalLights[i].color, diffuseColor.a);
+          }
+        #endif
+
+        #if NUM_POINT_LIGHTS > 0
+          for (int i = 0; i < NUM_POINT_LIGHTS; i++) {
+            vec3 toLightDirection = normalize(pointLights[i].position - v_viewPosition);
+            float lightDistance = length(pointLights[i].position - v_viewPosition);
+            float attenuation = 1.0 / (1.0 + 0.09 * lightDistance + 0.032 * lightDistance * lightDistance);
+            totalScatter += calculateScatter(viewDirection, toLightDirection, pointLights[i].color, diffuseColor.a) * attenuation;
+          }
+        #endif
+
+        #if NUM_SPOT_LIGHTS > 0
+          for (int i = 0; i < NUM_SPOT_LIGHTS; i++) {
+            vec3 toLightDirection = normalize(spotLights[i].position - v_viewPosition);
+            float lightDistance = length(spotLights[i].position - v_viewPosition);
+            float attenuation = 1.0 / (1.0 + 0.09 * lightDistance + 0.032 * lightDistance * lightDistance);
+            float spotCosine = dot(normalize(spotLights[i].direction), -toLightDirection);
+            float spotFalloff = smoothstep(spotLights[i].coneCos, spotLights[i].penumbraCos, spotCosine);
+            totalScatter += calculateScatter(viewDirection, toLightDirection, spotLights[i].color, diffuseColor.a) * attenuation * spotFalloff;
+          }
+        #endif
+
+        // calculateScatter() includes a "* alpha" density factor. Compositing
+        // will apply another "* alpha" (via blend equation in straight mode,
+        // or via premultiplied_alpha_fragment + One/OneMinusSrcAlpha blend).
+        // Without correction, scatter would get alpha² while diffuse lighting
+        // only gets alpha¹. Dividing diffuseColor.rgb by alpha cancels the
+        // extra factor, so scatter composites at the same alpha power as
+        // the rest of outgoingLight.
+        vec3 albedo = diffuseColor.a > 0.001
+            ? diffuseColor.rgb / diffuseColor.a
+            : vec3(0.0);
+        gl_FragColor = vec4(outgoingLight + totalScatter * albedo, diffuseColor.a);
+        `);
+        }
+        if (useShadowSensitivity) {
+            fragmentShader = wrapShadowCalls(fragmentShader, "u_shadowSensitivity");
+        }
         shader.fragmentShader = fragmentPreamble + "\n" + fragmentShader;
     };
-    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"}`;
+    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",
+        scatterKey,
+        shadowKey,
+    ].join("_");
     return material;
 }
 

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

@@ -1,15 +1,24 @@
+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 { FXMaterialOptions } from "../FXMaterial/FXMaterial";
 import { FXMaterial } from "../FXMaterial/FXMaterial";
 export interface FXDiffuseMaterialOptions extends FXMaterialOptions {
-    normalNodes?: (FXTextureNode | FXNormalNode)[];
-    emissionNodes?: (FXColorNode | FXTextureNode)[];
+    normalNodes: (FXTextureNode | FXNormalNode)[];
+    emissionNodes: (FXColorNode | FXTextureNode)[];
+    enableScatter: boolean;
+    scatterTint: ColorRepresentation;
+    scatterPower: number;
+    forwardScatterStrength: number;
+    backScatterStrength: number;
+    shadowSensitivity: number;
 }
 export declare class FXDiffuseMaterial extends FXMaterial {
     private readonly normalNodes;
     private readonly emissionNodes;
-    constructor(options?: FXDiffuseMaterialOptions);
+    private readonly scatterUniforms;
+    private readonly shadowSensitivity;
+    constructor(options?: Partial<FXDiffuseMaterialOptions>);
     destroy(): void;
 }

package/dist/materials/FXDiffuseMaterial/FXDiffuseMaterial.js

@@ -1,3 +1,4 @@
+import { FXColor } from '../../miscellaneous/color/FXColor.js';
 import { FXSphericalNormalNode } from '../../nodes/normal/FXSphericalNormalNode.js';
 import { FXMaterial } from '../FXMaterial/FXMaterial.js';
 import { buildFXDiffuseMaterial } from './FXDiffuseMaterial.Internal.js';
@@ -7,6 +8,20 @@ class FXDiffuseMaterial extends FXMaterial {
         super(options);
         this._private_normalNodes = options.normalNodes ?? [new FXSphericalNormalNode()];
         this._private_emissionNodes = options.emissionNodes ?? [];
+        this._private_scatterUniforms =
+            options.enableScatter === true
+                ? {
+                    // eslint-disable-next-line @typescript-eslint/naming-convention
+                    u_ScatterTint: { value: new FXColor(options.scatterTint ?? 0xffd999).toThreeColor() },
+                    // eslint-disable-next-line @typescript-eslint/naming-convention
+                    u_ScatterPower: { value: options.scatterPower ?? 10 },
+                    // eslint-disable-next-line @typescript-eslint/naming-convention
+                    u_ForwardScatterStrength: { value: options.forwardScatterStrength ?? 1 },
+                    // eslint-disable-next-line @typescript-eslint/naming-convention
+                    u_BackScatterStrength: { value: options.backScatterStrength ?? 1 },
+                }
+                : undefined;
+        this._private_shadowSensitivity = { value: options.shadowSensitivity ?? 1 };
     }
     destroy() {
         super.destroy();
@@ -19,7 +34,7 @@ class FXDiffuseMaterial extends FXMaterial {
     }
     /** @internal */
     buildThreeMaterial(varyings) {
-        return buildFXDiffuseMaterial(varyings, this.blending, this.useAlphaHashing, this.alphaTest, this.albedoNodes, this._private_normalNodes, this._private_emissionNodes);
+        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);
     }
 }
 

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

@@ -0,0 +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;

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

@@ -0,0 +1,139 @@
+import { MeshDepthMaterial, DoubleSide, RGBADepthPacking } from 'three';
+import { PARTICLE_DEFINES } from '../../miscellaneous/miscellaneous.js';
+
+const DEPTH_VERTEX_SHADER = `
+  #define PARTICLE_POSITION_X a_builtin[0][0]
+  #define PARTICLE_POSITION_Y a_builtin[0][1]
+  #define PARTICLE_POSITION_Z a_builtin[0][2]
+
+  #define PARTICLE_SCALE_X a_builtin[1][2]
+  #define PARTICLE_SCALE_Y a_builtin[1][3]
+
+  #define PARTICLE_ROTATION a_builtin[2][1]
+
+  attribute mat4 a_builtin;
+  varying mat4 p_builtin;
+  varying vec2 p_uv;
+  varying vec2 vHighPrecisionZW;
+  varying float vCenterViewZ;
+
+  #ifdef USE_ALPHAHASH
+    varying vec3 vPosition;
+  #endif
+
+  void main() {
+    p_builtin = a_builtin;
+    p_uv = uv;
+
+    #ifdef USE_ALPHAHASH
+      vPosition = vec3(PARTICLE_POSITION_X, PARTICLE_POSITION_Y, PARTICLE_POSITION_Z) + vec3(position.xy, 0.0);
+    #endif
+
+    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 particleCenter = vec3(PARTICLE_POSITION_X, PARTICLE_POSITION_Y, PARTICLE_POSITION_Z);
+    vec4 modelViewPosition = modelViewMatrix * vec4(particleCenter, 1.0);
+    vCenterViewZ = modelViewPosition.z;
+    modelViewPosition.xy += billboardOffset;
+    gl_Position = projectionMatrix * modelViewPosition;
+    vHighPrecisionZW = gl_Position.zw;
+  }
+`;
+/**
+ * GLSL snippet that replaces the flat `fragCoordZ` with a spherical depth
+ * approximation. Treats each billboard as the front hemisphere of a sphere
+ * whose radius equals half the smaller particle scale dimension. Fragments
+ * outside that radius are discarded, producing a circular silhouette.
+ *
+ * Expects `vCenterViewZ` (view-space Z of the particle center), `p_uv`,
+ * `PARTICLE_SCALE_X / Y`, and `projectionMatrix` to be available.
+ */
+const SPHERICAL_DEPTH_FRAG_COORD_Z = `
+  float sphereOffsetX = (p_uv.x - 0.5) * PARTICLE_SCALE_X;
+  float sphereOffsetY = (p_uv.y - 0.5) * PARTICLE_SCALE_Y;
+  float sphereRadius = min(PARTICLE_SCALE_X, PARTICLE_SCALE_Y) * 0.5;
+  float squaredDistanceFromCenter = sphereOffsetX * sphereOffsetX + sphereOffsetY * sphereOffsetY;
+  if (squaredDistanceFromCenter > sphereRadius * sphereRadius) discard;
+
+  float sphereViewZ = vCenterViewZ + sqrt(sphereRadius * sphereRadius - squaredDistanceFromCenter);
+  float projectedZ = projectionMatrix[2][2] * sphereViewZ + projectionMatrix[3][2];
+  float projectedW = projectionMatrix[2][3] * sphereViewZ + projectionMatrix[3][3];
+  float normalizedDeviceZ = projectedZ / projectedW;
+
+  #ifdef USE_REVERSEDEPTHBUF
+    float fragCoordZ = normalizedDeviceZ;
+  #else
+    float fragCoordZ = 0.5 * normalizedDeviceZ + 0.5;
+  #endif
+`;
+const FRAG_COORD_Z_PATTERN = /float fragCoordZ\b[^;]*;/;
+function buildDepthMaterial(albedoNodes, depthAlphaTest, useDepthAlphaHash, useSphericalDepth) {
+    const depthNodes = albedoNodes.filter((node) => node.affectsDepth);
+    const needsFragmentPatch = depthNodes.length > 0 || useSphericalDepth;
+    const material = new MeshDepthMaterial({
+        name: "FXDepthMaterial",
+        depthPacking: RGBADepthPacking,
+        side: DoubleSide,
+        forceSinglePass: true,
+        alphaHash: useDepthAlphaHash,
+    });
+    material.onBeforeCompile = (shader) => {
+        shader.vertexShader = DEPTH_VERTEX_SHADER;
+        if (!needsFragmentPatch) {
+            return;
+        }
+        const seenCacheKeys = new Set();
+        const uniqueHelpers = depthNodes
+            .filter((node) => {
+            if (seenCacheKeys.has(node.cacheKey)) {
+                return false;
+            }
+            seenCacheKeys.add(node.cacheKey);
+            return true;
+        })
+            .map((node) => node.helperFunctions)
+            .join("\n");
+        const fragmentPreamble = [
+            PARTICLE_DEFINES,
+            "varying mat4 p_builtin;",
+            "varying vec2 p_uv;",
+            "varying float vCenterViewZ;",
+            useSphericalDepth ? "uniform mat4 projectionMatrix;" : "",
+            depthNodes.flatMap((node) => node.uniformDeclarations).join("\n"),
+            uniqueHelpers,
+        ].join("\n");
+        for (const node of depthNodes) {
+            Object.assign(shader.uniforms, node.uniforms);
+        }
+        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;`);
+        }
+        if (useSphericalDepth) {
+            if (!FRAG_COORD_Z_PATTERN.test(fragmentShader)) {
+                console.warn("FXDepthMaterial: could not find 'float fragCoordZ' in the depth fragment shader. " +
+                    "Spherical depth will not be applied. " +
+                    "This may indicate a Three.js version mismatch.");
+            }
+            else {
+                fragmentShader = fragmentShader.replace(FRAG_COORD_Z_PATTERN, SPHERICAL_DEPTH_FRAG_COORD_Z);
+            }
+        }
+        shader.fragmentShader = fragmentPreamble + "\n" + fragmentShader;
+    };
+    material.customProgramCacheKey = () => `fx-depth-${useDepthAlphaHash ? "alphaHash" : "alphaTest"}-${useSphericalDepth ? "spherical" : "flat"}-${depthNodes.map((node) => node.cacheKey).join("-") || "none"}`;
+    return material;
+}
+
+export { buildDepthMaterial };

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

@@ -0,0 +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;

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

@@ -0,0 +1,171 @@
+import { MeshDistanceMaterial, DoubleSide } from 'three';
+import { PARTICLE_DEFINES } from '../../miscellaneous/miscellaneous.js';
+
+/**
+ * Custom vertex shader for point/spot light shadow maps.
+ *
+ * Unlike the depth material (which writes clip-space Z for directional light
+ * shadows), the distance material writes the world-space distance from each
+ * fragment to the light position. This means we need to reconstruct world
+ * position for each billboarded vertex.
+ *
+ * `vWorldPosition` is a Three.js convention consumed by the distance fragment
+ * shader. `viewMatrix` here is the shadow camera's view matrix, so the
+ * billboard faces the light — which is correct for shadow shape.
+ */
+const DISTANCE_VERTEX_SHADER = `
+  #define DISTANCE
+
+  #define PARTICLE_POSITION_X a_builtin[0][0]
+  #define PARTICLE_POSITION_Y a_builtin[0][1]
+  #define PARTICLE_POSITION_Z a_builtin[0][2]
+
+  #define PARTICLE_SCALE_X a_builtin[1][2]
+  #define PARTICLE_SCALE_Y a_builtin[1][3]
+
+  #define PARTICLE_ROTATION a_builtin[2][1]
+
+  attribute mat4 a_builtin;
+  varying mat4 p_builtin;
+  varying vec2 p_uv;
+  varying vec3 vWorldPosition;
+
+  #ifdef USE_ALPHAHASH
+    varying vec3 vPosition;
+  #endif
+
+  void main() {
+    p_builtin = a_builtin;
+    p_uv = uv;
+
+    #ifdef USE_ALPHAHASH
+      vPosition = vec3(PARTICLE_POSITION_X, PARTICLE_POSITION_Y, PARTICLE_POSITION_Z) + vec3(position.xy, 0.0);
+    #endif
+
+    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 particleCenter = vec3(PARTICLE_POSITION_X, PARTICLE_POSITION_Y, PARTICLE_POSITION_Z);
+
+    // Reconstruct world-space position for the billboarded vertex.
+    // Camera axes are extracted from the shadow camera's view matrix (transposed
+    // rotation part), then scaled by the billboard offset.
+    vec3 cameraRight = vec3(viewMatrix[0][0], viewMatrix[1][0], viewMatrix[2][0]);
+    vec3 cameraUp    = vec3(viewMatrix[0][1], viewMatrix[1][1], viewMatrix[2][1]);
+    vec3 worldCenter = (modelMatrix * vec4(particleCenter, 1.0)).xyz;
+    vWorldPosition = worldCenter + cameraRight * billboardOffset.x + cameraUp * billboardOffset.y;
+
+    // Standard clip-space projection via the shadow camera.
+    vec4 modelViewPosition = modelViewMatrix * vec4(particleCenter, 1.0);
+    modelViewPosition.xy += billboardOffset;
+    gl_Position = projectionMatrix * modelViewPosition;
+  }
+`;
+/**
+ * GLSL snippet for spherical distance adjustment.
+ *
+ * Instead of measuring distance from the flat billboard surface, this
+ * approximates the front hemisphere of a sphere. The sphere radius is half
+ * the smaller scale dimension. Fragments outside the sphere are discarded.
+ *
+ * The depth offset is subtracted from the flat distance, bringing the
+ * perceived surface closer to the light. This is an approximation — the
+ * true offset direction depends on the light-to-fragment vector, not the
+ * camera-to-fragment vector — but for smoke particles the error is
+ * negligible.
+ */
+const SPHERICAL_DISTANCE_SNIPPET = `
+  {
+    float sphereOffsetX = (p_uv.x - 0.5) * PARTICLE_SCALE_X;
+    float sphereOffsetY = (p_uv.y - 0.5) * PARTICLE_SCALE_Y;
+    float sphereRadius = min(PARTICLE_SCALE_X, PARTICLE_SCALE_Y) * 0.5;
+    float squaredDistanceFromCenter = sphereOffsetX * sphereOffsetX + sphereOffsetY * sphereOffsetY;
+    if (squaredDistanceFromCenter > sphereRadius * sphereRadius) discard;
+    float sphereDepthOffset = sqrt(sphereRadius * sphereRadius - squaredDistanceFromCenter);
+    dist = max(0.0, dist - sphereDepthOffset);
+  }
+`;
+const DISTANCE_CALCULATION_PATTERN = /float\s+dist\s*=\s*length\s*\(\s*vWorldPosition\s*-\s*referencePosition\s*\)\s*;/;
+function buildDistanceMaterial(albedoNodes, distanceAlphaTest, useDistanceAlphaHash, useSphericalDepth) {
+    const distanceNodes = albedoNodes.filter((node) => node.affectsDepth);
+    const needsFragmentPatch = distanceNodes.length > 0 || useSphericalDepth;
+    const material = new MeshDistanceMaterial({
+        name: "FXDistanceMaterial",
+        side: DoubleSide,
+        forceSinglePass: true,
+        alphaHash: useDistanceAlphaHash,
+    });
+    material.onBeforeCompile = (shader) => {
+        shader.vertexShader = DISTANCE_VERTEX_SHADER;
+        if (!needsFragmentPatch) {
+            return;
+        }
+        const seenCacheKeys = new Set();
+        const uniqueHelpers = distanceNodes
+            .filter((node) => {
+            if (seenCacheKeys.has(node.cacheKey)) {
+                return false;
+            }
+            seenCacheKeys.add(node.cacheKey);
+            return true;
+        })
+            .map((node) => node.helperFunctions)
+            .join("\n");
+        const fragmentPreamble = [
+            PARTICLE_DEFINES,
+            "varying mat4 p_builtin;",
+            "varying vec2 p_uv;",
+            distanceNodes.flatMap((node) => node.uniformDeclarations).join("\n"),
+            uniqueHelpers,
+        ].join("\n");
+        for (const node of distanceNodes) {
+            Object.assign(shader.uniforms, node.uniforms);
+        }
+        let fragmentShader = shader.fragmentShader;
+        // Alpha from nodes — MeshDistanceMaterial may or may not include
+        // <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;`;
+            if (fragmentShader.includes("#include <map_fragment>")) {
+                fragmentShader = fragmentShader.replace("#include <map_fragment>", alphaDiscardCode);
+            }
+            else if (DISTANCE_CALCULATION_PATTERN.test(fragmentShader)) {
+                // Fallback: inject alpha discard just before the distance calculation.
+                fragmentShader = fragmentShader.replace(DISTANCE_CALCULATION_PATTERN, (match) => alphaDiscardCode + "\n" + match);
+            }
+            else {
+                console.warn("FXDistanceMaterial: could not find a suitable injection point for alpha discard. " +
+                    "This may indicate a Three.js version mismatch.");
+            }
+        }
+        // Spherical distance adjustment — offset the flat-billboard distance by
+        // the sphere's front surface depth.
+        if (useSphericalDepth) {
+            if (!DISTANCE_CALCULATION_PATTERN.test(fragmentShader)) {
+                console.warn("FXDistanceMaterial: could not find the distance calculation line. " +
+                    "Spherical depth will not be applied. " +
+                    "This may indicate a Three.js version mismatch.");
+            }
+            else {
+                // Inject the spherical adjustment right after the distance calculation.
+                fragmentShader = fragmentShader.replace(DISTANCE_CALCULATION_PATTERN, (match) => match + "\n" + SPHERICAL_DISTANCE_SNIPPET);
+            }
+        }
+        shader.fragmentShader = fragmentPreamble + "\n" + fragmentShader;
+    };
+    material.customProgramCacheKey = () => `fx-distance-${useDistanceAlphaHash ? "alphaHash" : "alphaTest"}-${useSphericalDepth ? "spherical" : "flat"}-${distanceNodes.map((node) => node.cacheKey).join("-") || "none"}`;
+    return material;
+}
+
+export { buildDistanceMaterial };

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

@@ -1,19 +1,21 @@
-import type { Blending } from "three";
+import type { Blending, MeshDistanceMaterial } from "three";
 import type { FXColorNode } from "../../nodes/color/FXColorNode";
 import type { FXTextureNode } from "../../nodes/texture/FXTextureNode";
 export interface FXMaterialOptions {
-    albedoNodes?: (FXColorNode | FXTextureNode)[];
-    blending?: Blending;
-    useAlphaHashing?: boolean;
-    alphaTest?: number;
-    depthAlphaTest?: number;
-    useDepthAlphaHash?: boolean;
-    useSphericalDepth?: boolean;
+    albedoNodes: (FXColorNode | FXTextureNode)[];
+    blending: Blending;
+    useAlphaHashing: boolean;
+    alphaTest: number;
+    depthAlphaTest: number;
+    useDepthAlphaHash: boolean;
+    useSphericalDepth: boolean;
+    premultipliedAlpha: boolean;
 }
 export declare abstract class FXMaterial {
     private readonly depthAlphaTest;
     private readonly useDepthAlphaHash;
     private readonly useSphericalDepth;
-    constructor(options?: FXMaterialOptions);
+    constructor(options?: Partial<FXMaterialOptions>);
     destroy(): void;
+    buildDistanceMaterial(): MeshDistanceMaterial;
 }

package/dist/materials/FXMaterial/FXMaterial.js

@@ -1,12 +1,15 @@
 import { NormalBlending } from 'three';
-import { buildDepthMaterial } from './FXMaterial.Internal.js';
+import { buildDepthMaterial } from './FXDepthMaterial.Internal.js';
+import { buildDistanceMaterial } from './FXDistanceMaterial.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.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;
@@ -20,6 +23,9 @@ class FXMaterial {
     buildDepthMaterial() {
         return buildDepthMaterial(this.albedoNodes, this._private_depthAlphaTest, this._private_useDepthAlphaHash, this._private_useSphericalDepth);
     }
+    buildDistanceMaterial() {
+        return buildDistanceMaterial(this.albedoNodes, this._private_depthAlphaTest, this._private_useDepthAlphaHash, this._private_useSphericalDepth);
+    }
 }
 
 export { FXMaterial };

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

@@ -3,4 +3,4 @@ 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, albedoNodes: readonly (FXColorNode | FXTextureNode)[]): MeshBasicMaterial;
+export declare function buildFXUnlitMaterial(varyings: Record<string, GLTypeInfo>, blending: Blending, useAlphaHashing: boolean, alphaTest: number, premultipliedAlpha: boolean, 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/miscellaneous.js';
 
-function buildFXUnlitMaterial(varyings, blending, useAlphaHashing, alphaTest, albedoNodes) {
+function buildFXUnlitMaterial(varyings, blending, useAlphaHashing, alphaTest, premultipliedAlpha, albedoNodes) {
     const attributeDeclarations = [];
     const varyingDeclarations = [];
     const vertexAssignments = [];
@@ -12,6 +12,7 @@ function buildFXUnlitMaterial(varyings, blending, useAlphaHashing, alphaTest, al
         vertexAssignments.push(`p_${name} = a_${name};`);
     }
     const material = new MeshBasicMaterial({
+        name: "FXUnlitMaterial",
         transparent: !useAlphaHashing,
         depthWrite: useAlphaHashing,
         depthTest: true,
@@ -20,6 +21,7 @@ function buildFXUnlitMaterial(varyings, blending, useAlphaHashing, alphaTest, al
         side: DoubleSide,
         forceSinglePass: true,
         alphaTest,
+        premultipliedAlpha,
     });
     material.onBeforeCompile = (shader) => {
         const vertexPreamble = [

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

@@ -2,5 +2,5 @@ import type { FXMaterialOptions } from "../FXMaterial/FXMaterial";
 import { FXMaterial } from "../FXMaterial/FXMaterial";
 export type FXUnlitMaterialOptions = FXMaterialOptions;
 export declare class FXUnlitMaterial extends FXMaterial {
-    constructor(options?: FXUnlitMaterialOptions);
+    constructor(options?: Partial<FXUnlitMaterialOptions>);
 }

package/dist/materials/FXUnlitMaterial/FXUnlitMaterial.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparcoon",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "",
   "keywords": [
     "particles",

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

@@ -1,5 +0,0 @@
-import { MeshDepthMaterial } from "three";
-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(albedoNodes: readonly (FXColorNode | FXTextureNode)[], depthAlphaTest: number, useDepthAlphaHash: boolean, useSphericalDepth: boolean): MeshDepthMaterial;

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

@@ -1,106 +0,0 @@
-import { MeshDepthMaterial, DoubleSide, RGBADepthPacking } from 'three';
-import { PARTICLE_DEFINES } from '../../miscellaneous/miscellaneous.js';
-
-const DEPTH_VERTEX_SHADER = `
-  #define PARTICLE_POSITION_X a_builtin[0][0]
-  #define PARTICLE_POSITION_Y a_builtin[0][1]
-  #define PARTICLE_POSITION_Z a_builtin[0][2]
-
-  #define PARTICLE_SCALE_X a_builtin[1][2]
-  #define PARTICLE_SCALE_Y a_builtin[1][3]
-
-  #define PARTICLE_ROTATION a_builtin[2][1]
-
-  attribute mat4 a_builtin;
-  varying mat4 p_builtin;
-  varying vec2 p_uv;
-  varying vec2 vHighPrecisionZW;
-  varying float v_viewZ;
-  #ifdef USE_ALPHAHASH
-    varying vec3 vPosition;
-  #endif
-
-  void main() {
-    p_builtin = a_builtin;
-    p_uv = uv;
-    #ifdef USE_ALPHAHASH
-      vPosition = vec3(PARTICLE_POSITION_X, PARTICLE_POSITION_Y, PARTICLE_POSITION_Z) + vec3(position.xy, 0.0);
-    #endif
-
-    vec2 transformedPosition = position.xy;
-    transformedPosition.x *= PARTICLE_SCALE_X;
-    transformedPosition.y *= PARTICLE_SCALE_Y;
-
-    float cosR = cos(PARTICLE_ROTATION);
-    float sinR = sin(PARTICLE_ROTATION);
-    transformedPosition = vec2(
-      transformedPosition.x * cosR - transformedPosition.y * sinR,
-      transformedPosition.x * sinR + transformedPosition.y * cosR
-    );
-
-    vec3 center = vec3(PARTICLE_POSITION_X, PARTICLE_POSITION_Y, PARTICLE_POSITION_Z);
-    vec4 modelViewCenter = modelViewMatrix * vec4(center, 1.0);
-    v_viewZ = modelViewCenter.z;
-    modelViewCenter.xy += transformedPosition;
-    gl_Position = projectionMatrix * modelViewCenter;
-    vHighPrecisionZW = gl_Position.zw;
-  }
-`;
-const DEPTH_SPHERICAL_FRAG_COORD_Z = `
-  float _dx = (p_uv.x - 0.5) * PARTICLE_SCALE_X;
-  float _dy = (p_uv.y - 0.5) * PARTICLE_SCALE_Y;
-  float _r = min(PARTICLE_SCALE_X, PARTICLE_SCALE_Y) * 0.5;
-  float _d2 = _dx * _dx + _dy * _dy;
-  if (_d2 > _r * _r) discard;
-  float _sphereZ = v_viewZ + sqrt(_r * _r - _d2);
-  float _pz = projectionMatrix[2][2] * _sphereZ + projectionMatrix[3][2];
-  float _pw = projectionMatrix[2][3] * _sphereZ + projectionMatrix[3][3];
-  float _ndc_z = _pz / _pw;
-  #ifdef USE_REVERSEDEPTHBUF
-    float fragCoordZ = _ndc_z;
-  #else
-    float fragCoordZ = 0.5 * _ndc_z + 0.5;
-  #endif
-`;
-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,
-        side: DoubleSide,
-        forceSinglePass: true,
-        alphaHash: useDepthAlphaHash,
-    });
-    material.onBeforeCompile = (shader) => {
-        shader.vertexShader = DEPTH_VERTEX_SHADER;
-        if (!needsFragmentMod) {
-            return;
-        }
-        const fragmentPreamble = [
-            PARTICLE_DEFINES,
-            "varying mat4 p_builtin;",
-            "varying vec2 p_uv;",
-            "varying float v_viewZ;",
-            useSphericalDepth ? "uniform mat4 projectionMatrix;" : "",
-            depthNodes.flatMap((n) => n.uniformDeclarations).join("\n"),
-            depthNodes.map((n) => n.helperFunctions).join("\n"),
-        ].join("\n");
-        for (const node of depthNodes) {
-            Object.assign(shader.uniforms, node.uniforms);
-        }
-        let fs = shader.fragmentShader;
-        if (depthNodes.length > 0) {
-            const combinedAlpha = depthNodes.map((n) => n.colorExpression).join(" * ");
-            fs = fs.replace("#include <map_fragment>", `diffuseColor.a = (${combinedAlpha}).a;
-         if (diffuseColor.a < ${depthAlphaTest.toFixed(4)}) discard;`);
-        }
-        if (useSphericalDepth) {
-            fs = fs.replace(/float fragCoordZ\b[^;]*;/, DEPTH_SPHERICAL_FRAG_COORD_Z);
-        }
-        shader.fragmentShader = fragmentPreamble + "\n" + fs;
-    };
-    material.customProgramCacheKey = () => `fx-depth-${useDepthAlphaHash ? "ah" : "at"}-${useSphericalDepth ? "sd" : "flat"}-${depthNodes.map((n) => n.cacheKey).join("-") || "none"}`;
-    return material;
-}
-
-export { DEPTH_VERTEX_SHADER, buildDepthMaterial };