sparcoon 0.7.3 → 0.9.1

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

@@ -1,175 +0,0 @@
-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.
- *
- * 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 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);
-            }
-            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,70 +0,0 @@
-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
- */
-export interface FXMaterialOptions {
-    /**
-     * Color and texture nodes composited for particle color
-     *
-     * @defaultValue `[]`
-     */
-    albedoNodes: (FXNodeColor | FXNodeTexture)[];
-    blending: FXBlending;
-    /**
-     * Use alpha hashing instead of standard transparency
-     *
-     * @defaultValue `false`
-     */
-    useAlphaHashing: boolean;
-    /**
-     * Alpha cutoff threshold for color passes
-     *
-     * @defaultValue `0.0075`
-     */
-    alphaTest: number;
-    /**
-     * Alpha cutoff threshold for depth and shadow passes
-     *
-     * @defaultValue `0.5`
-     */
-    depthAlphaTest: number;
-    /**
-     * Use alpha hashing in depth and shadow passes
-     *
-     * @defaultValue `false`
-     */
-    useDepthAlphaHash: boolean;
-    /**
-     * Approximate spherical depth for shadow maps
-     *
-     * @defaultValue `true`
-     */
-    useSphericalDepth: boolean;
-}
-/**
- * Abstract base class for particle materials
- */
-export declare abstract class FXMaterial {
-    private readonly depthAlphaTest;
-    private readonly useDepthAlphaHash;
-    private readonly useSphericalDepth;
-    constructor(options?: Partial<FXMaterialOptions>);
-    /** Releases resources held by all albedo nodes */
-    destroy(): void;
-}

package/dist/materials/FXMaterial/FXMaterial.js

@@ -1,51 +0,0 @@
-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 ?? FXBlending.MASKED_ADDITIVE;
-        this.useAlphaHashing = options.useAlphaHashing ?? false;
-        this.alphaTest = options.alphaTest ?? 0.0075;
-        this._private_depthAlphaTest = options.depthAlphaTest ?? 0.5;
-        this._private_useDepthAlphaHash = options.useDepthAlphaHash ?? false;
-        this._private_useSphericalDepth = options.useSphericalDepth ?? true;
-    }
-    /** Releases resources held by all albedo nodes */
-    destroy() {
-        for (const node of this.albedoNodes) {
-            node.destroy?.();
-        }
-    }
-    /** @internal */
-    buildDepthMaterial() {
-        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.filter((node) => node instanceof FXNodeColor || node instanceof FXNodeTexture), this._private_depthAlphaTest, this._private_useDepthAlphaHash, this._private_useSphericalDepth);
-    }
-}
-
-export { FXBlending, FXMaterial };

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

@@ -1,7 +0,0 @@
-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";
-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,103 +0,0 @@
-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, albedoNodes) {
-    const attributeDeclarations = [];
-    const varyingDeclarations = [];
-    const vertexAssignments = [];
-    for (const name in varyings) {
-        const { glslTypeName } = varyings[name];
-        attributeDeclarations.push(`attribute ${glslTypeName} a_${name};`);
-        varyingDeclarations.push(`varying ${glslTypeName} p_${name};`);
-        vertexAssignments.push(`p_${name} = a_${name};`);
-    }
-    const material = new MeshBasicMaterial({
-        name: "FXUnlitMaterial",
-        transparent: !useAlphaHashing,
-        depthWrite: useAlphaHashing,
-        depthTest: true,
-        alphaHash: useAlphaHashing,
-        blending: NormalBlending,
-        side: DoubleSide,
-        forceSinglePass: true,
-        alphaTest,
-        premultipliedAlpha: true,
-    });
-    material.onBeforeCompile = (shader) => {
-        const vertexPreamble = [
-            PARTICLE_DEFINES,
-            attributeDeclarations.join("\n"),
-            "varying vec2 p_uv;",
-            varyingDeclarations.join("\n"),
-        ].join("\n");
-        shader.vertexShader =
-            vertexPreamble +
-                "\n" +
-                shader.vertexShader
-                    .replace("#include <begin_vertex>", [
-                    "p_uv = uv;",
-                    vertexAssignments.join("\n"),
-                    "vec3 transformed = position;",
-                    "#ifdef USE_ALPHAHASH",
-                    "  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;
-          `);
-        const seenCacheKeys = new Set();
-        const uniqueHelpers = (nodes) => nodes
-            .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 vec2 p_uv;",
-            varyingDeclarations.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 (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((node) => node.cacheKey).join("-") || "none",
-        FXBlending[blending],
-    ].join("_");
-    return material;
-}
-
-export { buildFXUnlitMaterial };

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

@@ -1,7 +0,0 @@
-import { FXMaterial } from "../FXMaterial/FXMaterial";
-/**
- * Unlit particle material - renders particles without lighting or shadows
- */
-export declare class FXUnlitMaterial extends FXMaterial {
-    prepare(): void;
-}

package/dist/materials/FXUnlitMaterial/FXUnlitMaterial.js

@@ -1,21 +0,0 @@
-import { FXMaterial } from '../FXMaterial/FXMaterial.js';
-import { buildFXUnlitMaterial } from './FXUnlitMaterial.Internal.js';
-
-/**
- * Unlit particle material - renders particles without lighting or shadows
- */
-class FXUnlitMaterial extends FXMaterial {
-    /** @internal */
-    buildThreeMaterial(varyings) {
-        return buildFXUnlitMaterial(varyings, this.blending, this.useAlphaHashing, this.alphaTest, this.albedoNodes);
-    }
-    prepare() {
-        let i = 0;
-        for (const node of this.albedoNodes) {
-            node.prepare?.(i);
-            i += 1;
-        }
-    }
-}
-
-export { FXUnlitMaterial };

package/dist/miscellaneous/color/FXColor.Internal.d.ts

@@ -1,7 +0,0 @@
-import type { Color } from "three";
-import type { FXColor } from "./FXColor";
-/** Color configuration as Three.js Color, hex number, hex string, or FXColor */
-export type FXColorConfig = Color | number | string | FXColor;
-/** Predefined color names */
-export type FXColorName = "black" | "white" | "red" | "green" | "blue" | "yellow" | "cyan" | "magenta" | "gray" | "grey" | "silver" | "maroon" | "olive" | "lime" | "aqua" | "teal" | "navy" | "fuchsia" | "purple" | "orange" | "pink" | "brown" | "gold" | "violet" | "indigo" | "coral" | "salmon" | "khaki" | "plum" | "orchid" | "tan" | "beige" | "mint" | "lavender" | "crimson" | "azure" | "ivory" | "snow";
-export declare const COLORS: Record<string, number | undefined>;

package/dist/miscellaneous/color/FXColor.Internal.js

@@ -1,42 +0,0 @@
-const COLORS = {
-    black: 0x000000,
-    white: 0xffffff,
-    red: 0xff0000,
-    green: 0x008000,
-    blue: 0x0000ff,
-    yellow: 0xffff00,
-    cyan: 0x00ffff,
-    magenta: 0xff00ff,
-    gray: 0x808080,
-    grey: 0x808080,
-    silver: 0xc0c0c0,
-    maroon: 0x800000,
-    olive: 0x808000,
-    lime: 0x00ff00,
-    aqua: 0x00ffff,
-    teal: 0x008080,
-    navy: 0x000080,
-    fuchsia: 0xff00ff,
-    purple: 0x800080,
-    orange: 0xffa500,
-    pink: 0xffc0cb,
-    brown: 0xa52a2a,
-    gold: 0xffd700,
-    violet: 0xee82ee,
-    indigo: 0x4b0082,
-    coral: 0xff7f50,
-    salmon: 0xfa8072,
-    khaki: 0xf0e68c,
-    plum: 0xdda0dd,
-    orchid: 0xda70d6,
-    tan: 0xd2b48c,
-    beige: 0xf5f5dc,
-    mint: 0x98fb98,
-    lavender: 0xe6e6fa,
-    crimson: 0xdc143c,
-    azure: 0xf0ffff,
-    ivory: 0xfffff0,
-    snow: 0xfffafa,
-};
-
-export { COLORS };