sparcoon 0.4.0 → 0.4.2

package/README.md

@@ -0,0 +1,79 @@
+# sparcoon
+
+[![npm](https://img.shields.io/npm/v/sparcoon.svg)](https://www.npmjs.com/package/sparcoon)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Instanced-mesh particle system for Three.js. WebGL 1 compatible. **[EDITOR](https://jango-git.github.io/sparcoon/)**
+
+## API
+
+- **FXEmitter** extends `Object3D`. Manages emission, lifetime, pooling, rendering. One draw call per emitter. Optional back-to-front sorting.
+- **Spawn modules** set initial particle state: position (box/sphere/point), velocity (cone), rotation, scale, lifetime. Numeric params accept ranges.
+- **Behavior modules** update particles per frame: directional/point gravity, velocity/torque damping, simplex noise, scale-over-life.
+- **Materials**: `FXUnlitMaterial` (MeshBasicMaterial), `FXDiffuseMaterial` (MeshLambertMaterial + optional subsurface scatter). Shadow support.
+- **Nodes** are composable material inputs: color-over-life, static/animated textures, normals (flat/spherical/map).
+
+## Example
+
+Smoke volume with animated sprite sheet, subsurface scattering, and shadow receiving:
+
+```typescript
+const RATE = 10;
+const LIFETIME = 6;
+
+const smoke = new FXEmitter(
+  [
+    new FXSpawnBox(areaMin, areaMax),
+    new FXSpawnRandomLifetime({ min: LIFETIME * 0.5, max: LIFETIME }),
+    new FXSpawnRandomScale({ min: 8, max: 16 }),
+    new FXSpawnRandomRotation(),
+  ],
+  [],
+  new FXDiffuseMaterial({
+    enableScatter: true,
+    scatterPower: 10,
+    forwardScatterStrength: 1,
+    backScatterStrength: 0.25,
+    shadowSensitivity: 0.25,
+    premultipliedAlpha: true,
+    albedoNodes: [
+      new FXAnimatedTextureNode({
+        texture: smokeAtlas,
+        rows: 8,
+        columns: 8,
+        interpolate: true,
+      }),
+      new FXColorOverLifeNode([
+        new FXColor(0xffffff, 0),
+        new FXColor(0xffffff, 0.4),
+        new FXColor(0xffffff, 0.4),
+        new FXColor(0xffffff, 0),
+      ]),
+    ],
+  }),
+  {
+    expectedCapacity: Math.ceil(LIFETIME * RATE) + 1,
+    receiveShadow: true,
+    sortCamera: camera,
+    sortFraction: 0.25,
+  },
+);
+
+scene.add(smoke);
+smoke.play(RATE);
+
+// render loop
+FXEmitter.onWillRender(delta);
+```
+
+## Install
+
+```
+npm install sparcoon
+```
+
+Peer dep: `three` >=0.157.0 <0.180.0
+
+## License
+
+MIT

package/dist/emitter/FXEmitter.d.ts

@@ -17,7 +17,7 @@ export declare class FXEmitter extends Object3D {
     private readonly spawnSequence;
     private readonly behaviorSequence;
     automaticallyDestroyModules: boolean;
-    sortCamera: Camera | undefined;
+    sortCamera?: Camera;
     sortFraction: number;
     private readonly mesh;
     private readonly material;

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

@@ -18,6 +18,6 @@ export interface FXScatterUniforms {
         value: number;
     };
 }
-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)[], scatterUniforms?: FXScatterUniforms, shadowSensitivity?: {
+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;
-}, premultipliedAlpha?: boolean): MeshLambertMaterial;
+}): MeshLambertMaterial;

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

@@ -37,7 +37,7 @@ function wrapShadowCalls(source, uniformName) {
     }
     return result;
 }
-function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, alphaTest, albedoNodes, normalNodes, emissionNodes, scatterUniforms, shadowSensitivity, premultipliedAlpha) {
+function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, alphaTest, premultipliedAlpha, albedoNodes, normalNodes, emissionNodes, scatterUniforms, shadowSensitivity) {
     const useScatter = scatterUniforms !== undefined;
     const useShadowSensitivity = shadowSensitivity !== undefined;
     const attributeDeclarations = [];
@@ -67,6 +67,7 @@ function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, alphaTest,
             PARTICLE_DEFINES,
             attributeDeclarations.join("\n"),
             "varying vec2 p_uv;",
+            "varying float p_rotation;",
             useScatter ? "varying vec3 v_viewPosition;" : "",
             varyingDeclarations.join("\n"),
         ].join("\n");
@@ -78,6 +79,7 @@ function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, alphaTest,
                     .replace("#include <defaultnormal_vertex>", "vec3 transformedNormal = vec3(0.0, 0.0, 1.0);")
                     .replace("#include <begin_vertex>", [
                     "p_uv = uv;",
+                    "p_rotation = PARTICLE_ROTATION;",
                     vertexAssignments.join("\n"),
                     "vec3 transformed = position;",
                     "#ifdef USE_ALPHAHASH",
@@ -153,6 +155,7 @@ function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, alphaTest,
         const fragmentPreamble = [
             PARTICLE_DEFINES,
             "varying vec2 p_uv;",
+            "varying float p_rotation;",
             varyingDeclarations.join("\n"),
             albedoNodes.flatMap((n) => n.uniformDeclarations).join("\n"),
             uniqueHelpers(albedoNodes),
@@ -197,6 +200,10 @@ function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, alphaTest,
                 "float faceDirection = gl_FrontFacing ? 1.0 : -1.0;",
                 `vec3 normal = ${normalExpressions[0]};`,
                 ...blendLines,
+                "// Rotate normal xy to match billboard PARTICLE_ROTATION",
+                "float cosR = cos(p_rotation);",
+                "float sinR = sin(p_rotation);",
+                "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);
@@ -211,8 +218,6 @@ function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, alphaTest,
             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;

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

@@ -13,14 +13,12 @@ export interface FXDiffuseMaterialOptions extends FXMaterialOptions {
     forwardScatterStrength: number;
     backScatterStrength: number;
     shadowSensitivity: number;
-    premultipliedAlpha: boolean;
 }
 export declare class FXDiffuseMaterial extends FXMaterial {
     private readonly normalNodes;
     private readonly emissionNodes;
     private readonly scatterUniforms;
     private readonly shadowSensitivity;
-    private readonly premultipliedAlpha;
     constructor(options?: Partial<FXDiffuseMaterialOptions>);
     destroy(): void;
 }

package/dist/materials/FXDiffuseMaterial/FXDiffuseMaterial.js

@@ -22,7 +22,6 @@ class FXDiffuseMaterial extends FXMaterial {
                 }
                 : undefined;
         this._private_shadowSensitivity = { value: options.shadowSensitivity ?? 1 };
-        this._private_premultipliedAlpha = options.premultipliedAlpha ?? false;
     }
     destroy() {
         super.destroy();
@@ -35,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, this._private_scatterUniforms, this._private_shadowSensitivity, this._private_premultipliedAlpha);
+        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/FXMaterial.d.ts

@@ -2,19 +2,20 @@ 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

@@ -8,6 +8,8 @@ class FXMaterial {
         this.blending = options.blending ?? NormalBlending;
         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;

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 = [];
@@ -21,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.4.0",
+  "version": "0.4.2",
   "description": "",
   "keywords": [
     "particles",