sparcoon 0.9.0 → 0.9.2

package/dist/miscellaneous/fxMath.d.ts

@@ -1,5 +1,5 @@
 /**
- * CPU-side twins of the compiler's math/noise builtins (`fxMix`, `fxSnoise3`, ...). A behavior
+ * CPU-side twins of the compiler's math/noise builtins (`fxMix`, `fxNoise3`, ...). A behavior
  * kernel's authored `spawn`/`update` body calls these by name - the editor's compiler prints those
  * exact calls - so every exported name here is a frozen contract with already-compiled kernels,
  * like the `a_`/`p_` buffer prefixes. Never rename one without updating the compiler side in
@@ -9,18 +9,25 @@ export declare function fxFract(x: number): number;
 export declare function fxMod(a: number, b: number): number;
 export declare function fxMix(a: number, b: number, t: number): number;
 export declare function fxSmoothstep(edge0: number, edge1: number, x: number): number;
-export declare function fxHash(n: number): number;
-/** Cheap deterministic 1D value-noise (smoothed hash interpolation), range [-1, 1]. */
-export declare function fxValueNoise(x: number): number;
-/** Fractal Brownian motion over {@link fxValueNoise} (gain 0.5, lacunarity 2). */
+/** Fractal Brownian motion over {@link fxNoise1} (gain 0.5, lacunarity 2). */
 export declare function fxFbm(x: number, octaves: number): number;
+/**
+ * Fractal Brownian motion over the full {@link fxNoise3} domain (gain 0.5, lacunarity 2) - unlike
+ * {@link fxFbm}, which walks a single scalar axis, this samples all three input components
+ * together so the field varies with the whole position, not just one of its axes.
+ */
+export declare function fxFbm3(x: number, y: number, z: number, octaves: number): number;
 /** Linearly samples a curve LUT at `t` in [0, 1] (clamped), interpolating between entries. */
 export declare function fxSampleLut(lut: ArrayLike<number>, t: number): number;
 /**
- * Ashima/Gustavson "webgl-noise" simplex noise, 2D - the CPU twin of the compiler's GLSL `snoise`
- * helper. Component arguments (rather than a vector) so it mirrors how the scalarized JS backend calls
- * it; the arithmetic tracks the GLSL version op-for-op. Output is roughly `[-1, 1]`.
+ * Cheap deterministic 1D value-noise (smoothed integer-hash interpolation), range [-1, 1]. The
+ * CPU twin of the compiler's GLSL `noise(float)` standard-tier form - see {@link fxIntHash1}.
+ */
+export declare function fxNoise1(x: number): number;
+/**
+ * 2D twin of {@link fxNoise1}, mirroring the GLSL `noise(vec2)` standard-tier overload op-for-op.
+ * Component arguments (rather than a vector) so it mirrors how the scalarized JS backend calls it.
  */
-export declare function fxSnoise2(vx: number, vy: number): number;
-/** 3D twin of {@link fxSnoise2}, mirroring the GLSL `snoise(vec3)` overload op-for-op. */
-export declare function fxSnoise3(vx: number, vy: number, vz: number): number;
+export declare function fxNoise2(vx: number, vy: number): number;
+/** 3D twin of {@link fxNoise1}, mirroring the GLSL `noise(vec3)` standard-tier overload op-for-op. */
+export declare function fxNoise3(vx: number, vy: number, vz: number): number;

package/dist/miscellaneous/fxMath.js

@@ -1,5 +1,5 @@
 /**
- * CPU-side twins of the compiler's math/noise builtins (`fxMix`, `fxSnoise3`, ...). A behavior
+ * CPU-side twins of the compiler's math/noise builtins (`fxMix`, `fxNoise3`, ...). A behavior
  * kernel's authored `spawn`/`update` body calls these by name - the editor's compiler prints those
  * exact calls - so every exported name here is a frozen contract with already-compiled kernels,
  * like the `a_`/`p_` buffer prefixes. Never rename one without updating the compiler side in
@@ -18,28 +18,34 @@ export function fxSmoothstep(edge0, edge1, x) {
     const t = Math.min(Math.max((x - edge0) / (edge1 - edge0), 0.0), 1.0);
     return t * t * (3.0 - 2.0 * t);
 }
-export function fxHash(n) {
-    const s = Math.sin(n * 127.1) * 43758.5453123;
-    return s - Math.floor(s);
-}
-/** Cheap deterministic 1D value-noise (smoothed hash interpolation), range [-1, 1]. */
-export function fxValueNoise(x) {
-    const i = Math.floor(x);
-    const fractional = x - i;
-    const u = fractional * fractional * (3 - 2 * fractional);
-    return (fxHash(i) * (1 - u) + fxHash(i + 1) * u) * 2 - 1;
-}
 // Mirrors FBM_MAX_OCTAVES in the editor engine: clamps a runaway octave count (a
 // value parameter rebinds with no recompile/sanity gate) so it cannot blow up the update kernel.
 const FBM_MAX_OCTAVES = 8;
-/** Fractal Brownian motion over {@link fxValueNoise} (gain 0.5, lacunarity 2). */
+/** Fractal Brownian motion over {@link fxNoise1} (gain 0.5, lacunarity 2). */
 export function fxFbm(x, octaves) {
     const octaveCount = Math.min(Math.max(Math.floor(octaves), 0), FBM_MAX_OCTAVES);
     let sum = 0;
     let amplitude = 1;
     let frequency = 1;
     for (let i = 0; i < octaveCount; i += 1) {
-        sum += fxValueNoise(x * frequency) * amplitude;
+        sum += fxNoise1(x * frequency) * amplitude;
+        amplitude *= 0.5;
+        frequency *= 2;
+    }
+    return sum;
+}
+/**
+ * Fractal Brownian motion over the full {@link fxNoise3} domain (gain 0.5, lacunarity 2) - unlike
+ * {@link fxFbm}, which walks a single scalar axis, this samples all three input components
+ * together so the field varies with the whole position, not just one of its axes.
+ */
+export function fxFbm3(x, y, z, octaves) {
+    const octaveCount = Math.min(Math.max(Math.floor(octaves), 0), FBM_MAX_OCTAVES);
+    let sum = 0;
+    let amplitude = 1;
+    let frequency = 1;
+    for (let i = 0; i < octaveCount; i += 1) {
+        sum += fxNoise3(x * frequency, y * frequency, z * frequency) * amplitude;
         amplitude *= 0.5;
         frequency *= 2;
     }
@@ -57,205 +63,79 @@ export function fxSampleLut(lut, t) {
     const upperValue = lut[i + 1 < length ? i + 1 : last];
     return lowerValue + (upperValue - lowerValue) * fraction;
 }
-// Ashima/Gustavson simplex-noise sub-helpers (mod289/permute/fract), private to fxSnoise2/3.
-function fxsnMod289(x) {
-    return x - Math.floor(x * (1.0 / 289.0)) * 289.0;
+/**
+ * Integer-hash sub-primitive, private to `fxNoise1/2/3` - Ken Perlin's classic `IntNoise` bit
+ * scramble. `Math.imul` plus `| 0` truncation at each step forces genuine 32-bit wraparound so
+ * this tracks the compiler's GLSL `int` version bit-for-bit (see the `noise` case in the editor's
+ * `FXFunctions.Internal.ts` standard-tier helper).
+ */
+function fxIntHash1(n) {
+    const shifted = (n << 13) | 0;
+    const mixed = (shifted ^ n) | 0;
+    const squared = Math.imul(mixed, mixed);
+    const step1 = (Math.imul(squared, 15731) + Math.imul(mixed, 789221)) | 0;
+    const step2 = (Math.imul(step1, step1) + 1376312589) | 0;
+    return (step2 & 0x00ffffff) / 16777216.0;
 }
-function fxsnPermute(x) {
-    return fxsnMod289((x * 34.0 + 1.0) * x);
+function fxIntHash2(ix, iy) {
+    return fxIntHash1((ix + Math.imul(iy, 57)) | 0);
 }
-function fxsnFract(x) {
-    return x - Math.floor(x);
+function fxIntHash3(ix, iy, iz) {
+    return fxIntHash1((ix + Math.imul(iy, 57) + Math.imul(iz, 113)) | 0);
 }
 /**
- * Ashima/Gustavson "webgl-noise" simplex noise, 2D - the CPU twin of the compiler's GLSL `snoise`
- * helper. Component arguments (rather than a vector) so it mirrors how the scalarized JS backend calls
- * it; the arithmetic tracks the GLSL version op-for-op. Output is roughly `[-1, 1]`.
+ * Cheap deterministic 1D value-noise (smoothed integer-hash interpolation), range [-1, 1]. The
+ * CPU twin of the compiler's GLSL `noise(float)` standard-tier form - see {@link fxIntHash1}.
  */
-export function fxSnoise2(vx, vy) {
-    const cx = 0.211324865405187;
-    const cy = 0.366025403784439;
-    const cz = -0.577350269189626;
-    const cw = 0.024390243902439;
-    const s = (vx + vy) * cy;
-    let ix = Math.floor(vx + s);
-    let iy = Math.floor(vy + s);
-    const t = (ix + iy) * cx;
-    const x0x = vx - ix + t;
-    const x0y = vy - iy + t;
-    let i1x;
-    let i1y;
-    if (x0x > x0y) {
-        i1x = 1.0;
-        i1y = 0.0;
-    }
-    else {
-        i1x = 0.0;
-        i1y = 1.0;
-    }
-    const x1x = x0x - i1x + cx;
-    const x1y = x0y - i1y + cx;
-    const x2x = x0x + cz;
-    const x2y = x0y + cz;
-    ix = fxsnMod289(ix);
-    iy = fxsnMod289(iy);
-    const p0 = fxsnPermute(fxsnPermute(iy + 0.0) + ix + 0.0);
-    const p1 = fxsnPermute(fxsnPermute(iy + i1y) + ix + i1x);
-    const p2 = fxsnPermute(fxsnPermute(iy + 1.0) + ix + 1.0);
-    let m0 = Math.max(0.5 - (x0x * x0x + x0y * x0y), 0.0);
-    let m1 = Math.max(0.5 - (x1x * x1x + x1y * x1y), 0.0);
-    let m2 = Math.max(0.5 - (x2x * x2x + x2y * x2y), 0.0);
-    m0 = m0 * m0;
-    m0 = m0 * m0;
-    m1 = m1 * m1;
-    m1 = m1 * m1;
-    m2 = m2 * m2;
-    m2 = m2 * m2;
-    const gx0 = 2.0 * fxsnFract(p0 * cw) - 1.0;
-    const gx1 = 2.0 * fxsnFract(p1 * cw) - 1.0;
-    const gx2 = 2.0 * fxsnFract(p2 * cw) - 1.0;
-    const h0 = Math.abs(gx0) - 0.5;
-    const h1 = Math.abs(gx1) - 0.5;
-    const h2 = Math.abs(gx2) - 0.5;
-    const ox0 = Math.floor(gx0 + 0.5);
-    const ox1 = Math.floor(gx1 + 0.5);
-    const ox2 = Math.floor(gx2 + 0.5);
-    const a0 = gx0 - ox0;
-    const a1 = gx1 - ox1;
-    const a2 = gx2 - ox2;
-    m0 *= 1.79284291400159 - 0.85373472095314 * (a0 * a0 + h0 * h0);
-    m1 *= 1.79284291400159 - 0.85373472095314 * (a1 * a1 + h1 * h1);
-    m2 *= 1.79284291400159 - 0.85373472095314 * (a2 * a2 + h2 * h2);
-    const g0 = a0 * x0x + h0 * x0y;
-    const g1 = a1 * x1x + h1 * x1y;
-    const g2 = a2 * x2x + h2 * x2y;
-    return 130.0 * (m0 * g0 + m1 * g1 + m2 * g2);
+export function fxNoise1(x) {
+    const i = Math.floor(x);
+    const f = x - i;
+    const u = f * f * (3 - 2 * f);
+    return (fxIntHash1(i) * (1 - u) + fxIntHash1(i + 1) * u) * 2 - 1;
 }
-/** 3D twin of {@link fxSnoise2}, mirroring the GLSL `snoise(vec3)` overload op-for-op. */
-export function fxSnoise3(vx, vy, vz) {
-    const cx = 1.0 / 6.0;
-    const cy = 1.0 / 3.0;
-    const s = (vx + vy + vz) * cy;
-    let ix = Math.floor(vx + s);
-    let iy = Math.floor(vy + s);
-    let iz = Math.floor(vz + s);
-    const t = (ix + iy + iz) * cx;
-    const x0x = vx - ix + t;
-    const x0y = vy - iy + t;
-    const x0z = vz - iz + t;
-    const gx = x0x >= x0y ? 1.0 : 0.0;
-    const gy = x0y >= x0z ? 1.0 : 0.0;
-    const gz = x0z >= x0x ? 1.0 : 0.0;
-    const lx = 1.0 - gx;
-    const ly = 1.0 - gy;
-    const lz = 1.0 - gz;
-    const i1x = Math.min(gx, lz);
-    const i1y = Math.min(gy, lx);
-    const i1z = Math.min(gz, ly);
-    const i2x = Math.max(gx, lz);
-    const i2y = Math.max(gy, lx);
-    const i2z = Math.max(gz, ly);
-    const x1x = x0x - i1x + cx;
-    const x1y = x0y - i1y + cx;
-    const x1z = x0z - i1z + cx;
-    const x2x = x0x - i2x + cy;
-    const x2y = x0y - i2y + cy;
-    const x2z = x0z - i2z + cy;
-    const x3x = x0x - 0.5;
-    const x3y = x0y - 0.5;
-    const x3z = x0z - 0.5;
-    ix = fxsnMod289(ix);
-    iy = fxsnMod289(iy);
-    iz = fxsnMod289(iz);
-    const offz = [0.0, i1z, i2z, 1.0];
-    const offy = [0.0, i1y, i2y, 1.0];
-    const offx = [0.0, i1x, i2x, 1.0];
-    const p = [0.0, 0.0, 0.0, 0.0];
-    for (let k = 0; k < 4; k += 1) {
-        p[k] = fxsnPermute(fxsnPermute(fxsnPermute(iz + offz[k]) + iy + offy[k]) + ix + offx[k]);
-    }
-    const oneOverSeven = 1.0 / 7.0;
-    const nsx = oneOverSeven * 2.0;
-    const nsy = oneOverSeven * 0.5 - 1.0;
-    const nsz = oneOverSeven;
-    const xx = [0.0, 0.0, 0.0, 0.0];
-    const yy = [0.0, 0.0, 0.0, 0.0];
-    const hh = [0.0, 0.0, 0.0, 0.0];
-    for (let k = 0; k < 4; k += 1) {
-        const j = p[k] - 49.0 * Math.floor(p[k] * nsz * nsz);
-        const xf = Math.floor(j * nsz);
-        const yf = Math.floor(j - 7.0 * xf);
-        xx[k] = xf * nsx + nsy;
-        yy[k] = yf * nsx + nsy;
-        hh[k] = 1.0 - Math.abs(xx[k]) - Math.abs(yy[k]);
-    }
-    const b0 = [xx[0], xx[1], yy[0], yy[1]];
-    const b1 = [xx[2], xx[3], yy[2], yy[3]];
-    const s0 = [
-        Math.floor(b0[0]) * 2.0 + 1.0,
-        Math.floor(b0[1]) * 2.0 + 1.0,
-        Math.floor(b0[2]) * 2.0 + 1.0,
-        Math.floor(b0[3]) * 2.0 + 1.0,
-    ];
-    const s1 = [
-        Math.floor(b1[0]) * 2.0 + 1.0,
-        Math.floor(b1[1]) * 2.0 + 1.0,
-        Math.floor(b1[2]) * 2.0 + 1.0,
-        Math.floor(b1[3]) * 2.0 + 1.0,
-    ];
-    const sh = [
-        -(hh[0] <= 0.0 ? 1.0 : 0.0),
-        -(hh[1] <= 0.0 ? 1.0 : 0.0),
-        -(hh[2] <= 0.0 ? 1.0 : 0.0),
-        -(hh[3] <= 0.0 ? 1.0 : 0.0),
-    ];
-    const a00 = b0[0] + s0[0] * sh[0];
-    const a01 = b0[2] + s0[2] * sh[0];
-    const a02 = b0[1] + s0[1] * sh[1];
-    const a03 = b0[3] + s0[3] * sh[1];
-    const a10 = b1[0] + s1[0] * sh[2];
-    const a11 = b1[2] + s1[2] * sh[2];
-    const a12 = b1[1] + s1[1] * sh[3];
-    const a13 = b1[3] + s1[3] * sh[3];
-    let p0x = a00;
-    let p0y = a01;
-    let p0z = hh[0];
-    let p1x = a02;
-    let p1y = a03;
-    let p1z = hh[1];
-    let p2x = a10;
-    let p2y = a11;
-    let p2z = hh[2];
-    let p3x = a12;
-    let p3y = a13;
-    let p3z = hh[3];
-    const nrm0 = 1.79284291400159 - 0.85373472095314 * (p0x * p0x + p0y * p0y + p0z * p0z);
-    const nrm1 = 1.79284291400159 - 0.85373472095314 * (p1x * p1x + p1y * p1y + p1z * p1z);
-    const nrm2 = 1.79284291400159 - 0.85373472095314 * (p2x * p2x + p2y * p2y + p2z * p2z);
-    const nrm3 = 1.79284291400159 - 0.85373472095314 * (p3x * p3x + p3y * p3y + p3z * p3z);
-    p0x *= nrm0;
-    p0y *= nrm0;
-    p0z *= nrm0;
-    p1x *= nrm1;
-    p1y *= nrm1;
-    p1z *= nrm1;
-    p2x *= nrm2;
-    p2y *= nrm2;
-    p2z *= nrm2;
-    p3x *= nrm3;
-    p3y *= nrm3;
-    p3z *= nrm3;
-    let m0 = Math.max(0.6 - (x0x * x0x + x0y * x0y + x0z * x0z), 0.0);
-    let m1 = Math.max(0.6 - (x1x * x1x + x1y * x1y + x1z * x1z), 0.0);
-    let m2 = Math.max(0.6 - (x2x * x2x + x2y * x2y + x2z * x2z), 0.0);
-    let m3 = Math.max(0.6 - (x3x * x3x + x3y * x3y + x3z * x3z), 0.0);
-    m0 = m0 * m0;
-    m1 = m1 * m1;
-    m2 = m2 * m2;
-    m3 = m3 * m3;
-    const dp0 = p0x * x0x + p0y * x0y + p0z * x0z;
-    const dp1 = p1x * x1x + p1y * x1y + p1z * x1z;
-    const dp2 = p2x * x2x + p2y * x2y + p2z * x2z;
-    const dp3 = p3x * x3x + p3y * x3y + p3z * x3z;
-    return 42.0 * (m0 * m0 * dp0 + m1 * m1 * dp1 + m2 * m2 * dp2 + m3 * m3 * dp3);
+/**
+ * 2D twin of {@link fxNoise1}, mirroring the GLSL `noise(vec2)` standard-tier overload op-for-op.
+ * Component arguments (rather than a vector) so it mirrors how the scalarized JS backend calls it.
+ */
+export function fxNoise2(vx, vy) {
+    const ix = Math.floor(vx);
+    const iy = Math.floor(vy);
+    const fx = vx - ix;
+    const fy = vy - iy;
+    const ux = fx * fx * (3 - 2 * fx);
+    const uy = fy * fy * (3 - 2 * fy);
+    const a = fxIntHash2(ix, iy);
+    const b = fxIntHash2(ix + 1, iy);
+    const c = fxIntHash2(ix, iy + 1);
+    const d = fxIntHash2(ix + 1, iy + 1);
+    const ab = a + (b - a) * ux;
+    const cd = c + (d - c) * ux;
+    return (ab + (cd - ab) * uy) * 2 - 1;
+}
+/** 3D twin of {@link fxNoise1}, mirroring the GLSL `noise(vec3)` standard-tier overload op-for-op. */
+export function fxNoise3(vx, vy, vz) {
+    const ix = Math.floor(vx);
+    const iy = Math.floor(vy);
+    const iz = Math.floor(vz);
+    const fx = vx - ix;
+    const fy = vy - iy;
+    const fz = vz - iz;
+    const ux = fx * fx * (3 - 2 * fx);
+    const uy = fy * fy * (3 - 2 * fy);
+    const uz = fz * fz * (3 - 2 * fz);
+    const a = fxIntHash3(ix, iy, iz);
+    const b = fxIntHash3(ix + 1, iy, iz);
+    const c = fxIntHash3(ix, iy + 1, iz);
+    const d = fxIntHash3(ix + 1, iy + 1, iz);
+    const e = fxIntHash3(ix, iy, iz + 1);
+    const f = fxIntHash3(ix + 1, iy, iz + 1);
+    const g = fxIntHash3(ix, iy + 1, iz + 1);
+    const h = fxIntHash3(ix + 1, iy + 1, iz + 1);
+    const ab = a + (b - a) * ux;
+    const cd = c + (d - c) * ux;
+    const abcd = ab + (cd - ab) * uy;
+    const ef = e + (f - e) * ux;
+    const gh = g + (h - g) * ux;
+    const efgh = ef + (gh - ef) * uy;
+    return (abcd + (efgh - abcd) * uz) * 2 - 1;
 }

package/dist/render/FXArtifactMaterial.Internal.js

@@ -48,11 +48,23 @@ function transformPreamble(outputs, withNormal) {
     return lines.join("\n");
 }
 // `#include <project_vertex>` replacement: projects `fxModelPos`, records camera distance, feeds alpha-hash.
+// World -> view via `viewMatrix` only, deliberately skipping `modelMatrix`: particle simulation
+// authors `fxModelPos` directly in world space (reference space == world by convention), so the
+// emitter's own scene transform must never re-enter here - see fxWorldMatrix for the explicit
+// opt-in a graph uses when it wants particles attached to the emitter instead.
 function projectFromModelPos() {
     return [
-        "vec4 mvPosition = modelViewMatrix * vec4(fxModelPos, 1.0);",
+        "vec4 mvPosition = viewMatrix * vec4(fxModelPos, 1.0);",
         "p_cameraDistance = length(mvPosition.xyz);",
         "gl_Position = projectionMatrix * mvPosition;",
+        // A dead particle (age >= lifetime, coreLayout.ts's convention) is pushed outside the clip
+        // volume on every axis so the GPU's trivial-reject clip test drops the whole primitive before
+        // rasterization - a fragment discard would defeat opaque mode's early-Z instead (see
+        // alphaDiscardLines, which already skips discard for that reason). A JS-driven emitter never
+        // draws a dead particle at all (removeDeadParticles keeps it out of the instance range), so
+        // this is a no-op there; a GPU-driven emitter always draws its full fixed capacity with no
+        // such compaction (FXTransformFeedbackParticle), which is what this actually guards.
+        "if (PARTICLE_AGE >= PARTICLE_LIFETIME) { gl_Position = vec4(2.0, 2.0, 2.0, 1.0); }",
         "#ifdef USE_ALPHAHASH",
         "  vPosition = fxModelPos;",
         "#endif",
@@ -161,7 +173,7 @@ export function buildUnlitArtifactMaterial(render, varyings, timeUniform, deltaU
         "uniform vec3 objectVelocity;",
         "uniform vec3 objectAngularVelocity;",
         "varying float p_cameraDistance;",
-        // World-space surface frame + position (NORMAL_SPACE_PLAN): the canonical author space for
+        // World-space surface frame + position: the canonical author space for
         // normals. Written in the vertex stage, read as the geometryNormal/geometryTangent/worldPosition
         // builtins in the fragment stage.
         "varying vec3 vWorldNormal;",
@@ -185,12 +197,13 @@ export function buildUnlitArtifactMaterial(render, varyings, timeUniform, deltaU
         "vec3 objectNormal = fxNormalXform * normal;",
         "#include <defaultnormal_vertex>",
         "#include <normal_vertex>",
-        // World-space surface frame + position (NORMAL_SPACE_PLAN): mat3(modelMatrix) is exact for a
-        // plane's frame under uniform scale; the tangent is the plane's local +X (the u axis), so billboard
-        // roll/orientation is baked in here ONCE for every consumer (normal maps, spherical normal, fresnel).
-        "vWorldNormal  = normalize( mat3( modelMatrix ) * objectNormal );",
-        "vWorldTangent = normalize( mat3( modelMatrix ) * ( fxNormalXform * vec3( 1.0, 0.0, 0.0 ) ) );",
-        "vWorldPos     = ( modelMatrix * vec4( fxModelPos, 1.0 ) ).xyz;",
+        // World-space surface frame + position: fxModelPos/objectNormal are already world space (no
+        // modelMatrix step - see fxWorldMatrix for the explicit emitter-attach opt-in). The tangent is
+        // the plane's local +X (the u axis), so billboard roll/orientation is baked in here ONCE for
+        // every consumer (normal maps, spherical normal, fresnel).
+        "vWorldNormal  = normalize( objectNormal );",
+        "vWorldTangent = normalize( fxNormalXform * vec3( 1.0, 0.0, 0.0 ) );",
+        "vWorldPos     = fxModelPos;",
         projectFromModelPos(),
         "#include <fog_vertex>",
         "}",
@@ -205,7 +218,7 @@ export function buildUnlitArtifactMaterial(render, varyings, timeUniform, deltaU
         "uniform vec3 objectVelocity;",
         "uniform vec3 objectAngularVelocity;",
         "varying float p_cameraDistance;",
-        // World-space surface frame + position (NORMAL_SPACE_PLAN): the canonical author space for
+        // World-space surface frame + position: the canonical author space for
         // normals. Written in the vertex stage, read as the geometryNormal/geometryTangent/worldPosition
         // builtins in the fragment stage.
         "varying vec3 vWorldNormal;",
@@ -223,7 +236,7 @@ export function buildUnlitArtifactMaterial(render, varyings, timeUniform, deltaU
         "void main() {",
         // Front-facing sign for the surface frame below (a back-facing fragment flips the normal).
         "float fxFaceDirection = gl_FrontFacing ? 1.0 : - 1.0;",
-        // World-space surface frame + position - the canonical author space (NORMAL_SPACE_PLAN). The
+        // World-space surface frame + position - the canonical author space. The
         // lighting intrinsics convert world->view at their own boundary; geometryTangent/worldPosition feed
         // normal maps and camera-correct fresnel. Declared before the node body so any reader resolves.
         "vec3 geometryNormal  = normalize( vWorldNormal ) * fxFaceDirection;",
@@ -258,13 +271,18 @@ export function buildUnlitArtifactMaterial(render, varyings, timeUniform, deltaU
         forceSinglePass: true,
         premultipliedAlpha: true,
     });
+    // `alphaHash` pulls in Three's own alphahash_pars_fragment chunk, which calls dFdx/dFdy - under
+    // a real WebGL1 context those need an explicit extension request or the shader fails to
+    // compile ("extension is disabled"); under WebGL2 this is a no-op (dFdx/dFdy are core there,
+    // and three skips extension generation entirely for a WebGL2 context either way).
+    material.extensions.derivatives = materialFlags(renderMode).alphaHash;
     material.customProgramCacheKey = () => `fx-unlit_${cacheKey}`;
     return material;
 }
 // The lighting-node intrinsics the graph calls by name (`fn.raw(... "fxLambertShade" ...)`) but never
 // defines - the frozen `fx_` cross-repo ABI. Each wraps the exact stock Lambert light sequence in a
-// function of (color, WORLD-space normal) -> shaded color: the graph authors normals in world space
-// (NORMAL_SPACE_PLAN), and each intrinsic converts world->view on its first line before Three's
+// function of (color, WORLD-space normal) -> shaded color: the graph authors normals in world
+// space, and each intrinsic converts world->view on its first line before Three's
 // view-space light chain runs, so view space stays a private detail behind this ABI. A node emits a
 // plain expression that can sit anywhere in the graph (mid-graph mix included). Placed AFTER the pars chunks (which supply the
 // `ReflectedLight`/`LambertMaterial` types, the `RE_*` macros, `vViewPosition`, the light uniforms) and
@@ -330,7 +348,7 @@ function buildLitArtifactMaterial(render, varyings, timeUniform, deltaUniform, v
         "uniform vec3 objectVelocity;",
         "uniform vec3 objectAngularVelocity;",
         "varying float p_cameraDistance;",
-        // World-space surface frame + position (NORMAL_SPACE_PLAN): the canonical author space for
+        // World-space surface frame + position: the canonical author space for
         // normals. Written in the vertex stage, read as the geometryNormal/geometryTangent/worldPosition
         // builtins in the fragment stage.
         "varying vec3 vWorldNormal;",
@@ -353,17 +371,18 @@ function buildLitArtifactMaterial(render, varyings, timeUniform, deltaUniform, v
         "vec3 objectNormal = fxNormalXform * normal;",
         "#include <defaultnormal_vertex>",
         "#include <normal_vertex>",
-        // World-space surface frame + position (NORMAL_SPACE_PLAN): mat3(modelMatrix) is exact for a
-        // plane's frame under uniform scale; the tangent is the plane's local +X (the u axis), so billboard
-        // roll/orientation is baked in here ONCE for every consumer (normal maps, spherical normal, fresnel).
-        "vWorldNormal  = normalize( mat3( modelMatrix ) * objectNormal );",
-        "vWorldTangent = normalize( mat3( modelMatrix ) * ( fxNormalXform * vec3( 1.0, 0.0, 0.0 ) ) );",
-        "vWorldPos     = ( modelMatrix * vec4( fxModelPos, 1.0 ) ).xyz;",
+        // World-space surface frame + position: fxModelPos/objectNormal are already world space (no
+        // modelMatrix step - see fxWorldMatrix for the explicit emitter-attach opt-in). The tangent is
+        // the plane's local +X (the u axis), so billboard roll/orientation is baked in here ONCE for
+        // every consumer (normal maps, spherical normal, fresnel).
+        "vWorldNormal  = normalize( objectNormal );",
+        "vWorldTangent = normalize( fxNormalXform * vec3( 1.0, 0.0, 0.0 ) );",
+        "vWorldPos     = fxModelPos;",
         "vec3 transformed = position;",
         projectFromModelPos(),
         "vViewPosition = - mvPosition.xyz;",
         "#if defined( USE_ENVMAP ) || defined( DISTANCE ) || defined( USE_SHADOWMAP ) || defined( USE_TRANSMISSION ) || NUM_SPOT_LIGHT_COORDS > 0",
-        "  vec4 worldPosition = modelMatrix * vec4(particleCenter, 1.0);",
+        "  vec4 worldPosition = vec4(particleCenter, 1.0);",
         "#endif",
         "#include <shadowmap_vertex>",
         "#include <fog_vertex>",
@@ -378,7 +397,7 @@ function buildLitArtifactMaterial(render, varyings, timeUniform, deltaUniform, v
         "uniform vec3 objectVelocity;",
         "uniform vec3 objectAngularVelocity;",
         "varying float p_cameraDistance;",
-        // World-space surface frame + position (NORMAL_SPACE_PLAN): the canonical author space for
+        // World-space surface frame + position: the canonical author space for
         // normals. Written in the vertex stage, read as the geometryNormal/geometryTangent/worldPosition
         // builtins in the fragment stage.
         "varying vec3 vWorldNormal;",
@@ -402,7 +421,7 @@ function buildLitArtifactMaterial(render, varyings, timeUniform, deltaUniform, v
         // Front-facing sign (matching `normal_fragment_begin` under DOUBLE_SIDED): a back-facing fragment
         // flips the surface frame below.
         "float fxFaceDirection = gl_FrontFacing ? 1.0 : - 1.0;",
-        // World-space surface frame + position - the canonical author space (NORMAL_SPACE_PLAN). The
+        // World-space surface frame + position - the canonical author space. The
         // lighting intrinsics convert world->view at their own boundary; geometryTangent/worldPosition feed
         // normal maps and camera-correct fresnel. Declared before the node body so any reader resolves.
         "vec3 geometryNormal  = normalize( vWorldNormal ) * fxFaceDirection;",
@@ -439,6 +458,8 @@ function buildLitArtifactMaterial(render, varyings, timeUniform, deltaUniform, v
         forceSinglePass: true,
         premultipliedAlpha: true,
     });
+    // See buildUnlitArtifactMaterial's identical line for why this is needed.
+    material.extensions.derivatives = materialFlags(renderMode).alphaHash;
     material.customProgramCacheKey = () => `fx-lit-nodes_${cacheKey}`;
     return material;
 }
@@ -471,11 +492,12 @@ function meshTransformPreamble(outputs, withNormal) {
     }
     return lines.join("\n");
 }
-// Mesh `#include <project_vertex>` replacement: plain object-space projection. No `p_cameraDistance`
-// (a mesh has no per-particle camera-distance builtin); still feeds alpha-hash `vPosition`.
+// Mesh `#include <project_vertex>` replacement: plain world-space projection (`viewMatrix` only,
+// no `modelMatrix` - see {@link projectFromModelPos}). No `p_cameraDistance` (a mesh has no
+// per-particle camera-distance builtin); still feeds alpha-hash `vPosition`.
 function meshProjectFromModelPos() {
     return [
-        "vec4 mvPosition = modelViewMatrix * vec4(fxModelPos, 1.0);",
+        "vec4 mvPosition = viewMatrix * vec4(fxModelPos, 1.0);",
         "gl_Position = projectionMatrix * mvPosition;",
         "#ifdef USE_ALPHAHASH",
         "  vPosition = fxModelPos;",
@@ -516,9 +538,9 @@ function buildMeshUnlitArtifactMaterial(render, timeUniform, deltaUniform, veloc
         "vec3 objectNormal = fxNormalXform * normal;",
         "#include <defaultnormal_vertex>",
         "#include <normal_vertex>",
-        "vWorldNormal  = normalize( mat3( modelMatrix ) * objectNormal );",
-        "vWorldTangent = normalize( mat3( modelMatrix ) * ( fxNormalXform * vec3( 1.0, 0.0, 0.0 ) ) );",
-        "vWorldPos     = ( modelMatrix * vec4( fxModelPos, 1.0 ) ).xyz;",
+        "vWorldNormal  = normalize( objectNormal );",
+        "vWorldTangent = normalize( fxNormalXform * vec3( 1.0, 0.0, 0.0 ) );",
+        "vWorldPos     = fxModelPos;",
         meshProjectFromModelPos(),
         "#include <fog_vertex>",
         "}",
@@ -571,6 +593,8 @@ function buildMeshUnlitArtifactMaterial(render, timeUniform, deltaUniform, veloc
         forceSinglePass: true,
         premultipliedAlpha: true,
     });
+    // See buildUnlitArtifactMaterial's identical line for why this is needed.
+    material.extensions.derivatives = materialFlags(renderMode).alphaHash;
     material.customProgramCacheKey = () => `fx-mesh-unlit_${cacheKey}`;
     return material;
 }
@@ -611,14 +635,14 @@ function buildMeshLitArtifactMaterial(render, timeUniform, deltaUniform, velocit
         "vec3 objectNormal = fxNormalXform * normal;",
         "#include <defaultnormal_vertex>",
         "#include <normal_vertex>",
-        "vWorldNormal  = normalize( mat3( modelMatrix ) * objectNormal );",
-        "vWorldTangent = normalize( mat3( modelMatrix ) * ( fxNormalXform * vec3( 1.0, 0.0, 0.0 ) ) );",
-        "vWorldPos     = ( modelMatrix * vec4( fxModelPos, 1.0 ) ).xyz;",
+        "vWorldNormal  = normalize( objectNormal );",
+        "vWorldTangent = normalize( fxNormalXform * vec3( 1.0, 0.0, 0.0 ) );",
+        "vWorldPos     = fxModelPos;",
         "vec3 transformed = position;",
         meshProjectFromModelPos(),
         "vViewPosition = - mvPosition.xyz;",
         "#if defined( USE_ENVMAP ) || defined( DISTANCE ) || defined( USE_SHADOWMAP ) || defined( USE_TRANSMISSION ) || NUM_SPOT_LIGHT_COORDS > 0",
-        "  vec4 worldPosition = modelMatrix * vec4(fxModelPos, 1.0);",
+        "  vec4 worldPosition = vec4(fxModelPos, 1.0);",
         "#endif",
         "#include <shadowmap_vertex>",
         "#include <fog_vertex>",
@@ -683,6 +707,8 @@ function buildMeshLitArtifactMaterial(render, timeUniform, deltaUniform, velocit
         forceSinglePass: true,
         premultipliedAlpha: true,
     });
+    // See buildUnlitArtifactMaterial's identical line for why this is needed.
+    material.extensions.derivatives = materialFlags(renderMode).alphaHash;
     material.customProgramCacheKey = () => `fx-mesh-lit-nodes_${cacheKey}`;
     return material;
 }
@@ -753,16 +779,16 @@ export function buildArtifactDepthMaterial(render, varyings, timeUniform, deltaU
         "vec3 objectNormal = fxNormalXform * normal;",
         "#include <defaultnormal_vertex>",
         "#include <normal_vertex>",
-        "vWorldNormal  = normalize( mat3( modelMatrix ) * objectNormal );",
-        "vWorldTangent = normalize( mat3( modelMatrix ) * ( fxNormalXform * vec3( 1.0, 0.0, 0.0 ) ) );",
-        "vWorldPos     = ( modelMatrix * vec4( fxModelPos, 1.0 ) ).xyz;",
+        "vWorldNormal  = normalize( objectNormal );",
+        "vWorldTangent = normalize( fxNormalXform * vec3( 1.0, 0.0, 0.0 ) );",
+        "vWorldPos     = fxModelPos;",
         ...(lit ? ["vec3 transformed = position;"] : []),
         projectFromModelPos(),
         ...(lit
             ? [
                 "vViewPosition = - mvPosition.xyz;",
                 "#if defined( USE_ENVMAP ) || defined( DISTANCE ) || defined( USE_SHADOWMAP ) || defined( USE_TRANSMISSION ) || NUM_SPOT_LIGHT_COORDS > 0",
-                "  vec4 worldPosition = modelMatrix * vec4(particleCenter, 1.0);",
+                "  vec4 worldPosition = vec4(particleCenter, 1.0);",
                 "#endif",
                 "#include <shadowmap_vertex>",
             ]
@@ -870,16 +896,16 @@ export function buildMeshArtifactDepthMaterial(render, timeUniform, deltaUniform
         "vec3 objectNormal = fxNormalXform * normal;",
         "#include <defaultnormal_vertex>",
         "#include <normal_vertex>",
-        "vWorldNormal  = normalize( mat3( modelMatrix ) * objectNormal );",
-        "vWorldTangent = normalize( mat3( modelMatrix ) * ( fxNormalXform * vec3( 1.0, 0.0, 0.0 ) ) );",
-        "vWorldPos     = ( modelMatrix * vec4( fxModelPos, 1.0 ) ).xyz;",
+        "vWorldNormal  = normalize( objectNormal );",
+        "vWorldTangent = normalize( fxNormalXform * vec3( 1.0, 0.0, 0.0 ) );",
+        "vWorldPos     = fxModelPos;",
         ...(lit ? ["vec3 transformed = position;"] : []),
         meshProjectFromModelPos(),
         ...(lit
             ? [
                 "vViewPosition = - mvPosition.xyz;",
                 "#if defined( USE_ENVMAP ) || defined( DISTANCE ) || defined( USE_SHADOWMAP ) || defined( USE_TRANSMISSION ) || NUM_SPOT_LIGHT_COORDS > 0",
-                "  vec4 worldPosition = modelMatrix * vec4(fxModelPos, 1.0);",
+                "  vec4 worldPosition = vec4(fxModelPos, 1.0);",
                 "#endif",
                 "#include <shadowmap_vertex>",
             ]

package/dist/render/FXArtifactMaterial.js

@@ -1,4 +1,4 @@
-import { buildArtifactDepthMaterial, buildArtifactMaterial } from "./FXArtifactMaterial.Internal.js";
+import { buildArtifactDepthMaterial, buildArtifactMaterial, } from "./FXArtifactMaterial.Internal.js";
 /**
  * @internal Runtime material driver: wraps a precompiled {@link FXRenderArtifact} and builds the
  * concrete self-contained `ShaderMaterial` via {@link buildArtifactMaterial}, which picks the flat or