sparcoon 0.4.1 → 0.4.3

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.js

@@ -40,6 +40,7 @@ function wrapShadowCalls(source, uniformName) {
 function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, alphaTest, premultipliedAlpha, albedoNodes, normalNodes, emissionNodes, scatterUniforms, shadowSensitivity) {
     const useScatter = scatterUniforms !== undefined;
     const useShadowSensitivity = shadowSensitivity !== undefined;
+    const useNormals = normalNodes.length > 0;
     const attributeDeclarations = [];
     const varyingDeclarations = [];
     const vertexAssignments = [];
@@ -67,6 +68,7 @@ function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, alphaTest,
             PARTICLE_DEFINES,
             attributeDeclarations.join("\n"),
             "varying vec2 p_uv;",
+            useNormals ? "varying vec2 p_billboardSinCos;" : "",
             useScatter ? "varying vec3 v_viewPosition;" : "",
             varyingDeclarations.join("\n"),
         ].join("\n");
@@ -96,6 +98,9 @@ function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, alphaTest,
                     "  billboardOffset.x * sinRotation + billboardOffset.y * cosRotation",
                     ");",
                     "",
+                    // Pass the exact sin/cos that rotated the billboard to the fragment shader.
+                    useNormals ? "p_billboardSinCos = vec2(sinRotation, cosRotation);" : "",
+                    "",
                     "vec3 particleCenter = vec3(PARTICLE_POSITION_X, PARTICLE_POSITION_Y, PARTICLE_POSITION_Z);",
                     "vec4 mvPosition = modelViewMatrix * vec4(particleCenter, 1.0);",
                     "mvPosition.xy += billboardOffset;",
@@ -153,6 +158,7 @@ function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, alphaTest,
         const fragmentPreamble = [
             PARTICLE_DEFINES,
             "varying vec2 p_uv;",
+            useNormals ? "varying vec2 p_billboardSinCos;" : "",
             varyingDeclarations.join("\n"),
             albedoNodes.flatMap((n) => n.uniformDeclarations).join("\n"),
             uniqueHelpers(albedoNodes),
@@ -183,7 +189,7 @@ function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, alphaTest,
             Object.assign(shader.uniforms, node.uniforms);
         }
         let fragmentShader = shader.fragmentShader;
-        if (normalNodes.length > 0) {
+        if (useNormals) {
             const normalExpressions = normalNodes.map((node) => {
                 if (node instanceof FXTextureNode) {
                     return `normalize(${node.colorExpression}.rgb * 2.0 - 1.0)`;
@@ -197,6 +203,17 @@ function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, alphaTest,
                 "float faceDirection = gl_FrontFacing ? 1.0 : -1.0;",
                 `vec3 normal = ${normalExpressions[0]};`,
                 ...blendLines,
+                "",
+                "// Rotate tangent-space normal XY into view space to match billboard rotation.",
+                "// p_billboardSinCos carries the exact sin/cos that rotated the quad vertices.",
+                "float sinR = p_billboardSinCos.x;",
+                "float cosR = p_billboardSinCos.y;",
+                "normal = vec3(",
+                "  normal.x * cosR - normal.y * sinR,",
+                "  normal.x * sinR + normal.y * cosR,",
+                "  normal.z",
+                ");",
+                "",
                 "normal *= faceDirection;",
             ].join("\n");
             fragmentShader = fragmentShader.replace("#include <normal_fragment_begin>", normalCode);
@@ -211,8 +228,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;
@@ -247,13 +262,6 @@ function buildFXDiffuseMaterial(varyings, blending, useAlphaHashing, alphaTest,
           }
         #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);

package/package.json

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