sparcoon 0.5.0 → 0.6.1

package/dist/miscellaneous/texture/FXTextureView.js

@@ -0,0 +1,234 @@
+import { Ferrsign3 } from 'ferrsign';
+import { Matrix3, Vector2, Texture } from 'three';
+import { assertValidPositiveNumber, assertValidNonNegativeNumber } from '../asserts.js';
+import { TEXTURE_DEFAULT_TEXTURE, TEXTURE_DEFAULT_SIZE } from './FXTextureView.Internal.js';
+
+/** Wrapper for Three.js texture with atlas and trim support. Does not own the underlying texture; user must dispose it. */
+class FXTextureView {
+    /** @param config Texture or atlas configuration */
+    constructor(config) {
+        this._private_textureInternal = TEXTURE_DEFAULT_TEXTURE;
+        this._private_sourceWidth = TEXTURE_DEFAULT_SIZE;
+        this._private_sourceHeight = TEXTURE_DEFAULT_SIZE;
+        this._private_frameX = 0;
+        this._private_frameY = 0;
+        this._private_frameWidth = TEXTURE_DEFAULT_SIZE;
+        this._private_frameHeight = TEXTURE_DEFAULT_SIZE;
+        this._private_rotatedInternal = false;
+        this._private_scaleInternal = 1;
+        this._private_trimLeft = 0;
+        this._private_trimRight = 0;
+        this._private_trimTop = 0;
+        this._private_trimBottom = 0;
+        this._private_textureDirtyInternal = false;
+        this._private_uvTransformDirtyInternal = false;
+        this._private_trimDirtyInternal = false;
+        this._private_signalDiminsionsChangedInternal = new Ferrsign3();
+        if (config !== undefined) {
+            this.set(config);
+        }
+    }
+    /** Original width before trimming in world units */
+    get width() {
+        return this._private_sourceWidth / this._private_scaleInternal;
+    }
+    /** Original height before trimming in world units */
+    get height() {
+        return this._private_sourceHeight / this._private_scaleInternal;
+    }
+    /** Visible width after trimming in world units */
+    get trimmedWidth() {
+        const frameSize = this._private_rotatedInternal ? this._private_frameHeight : this._private_frameWidth;
+        return frameSize / this._private_scaleInternal;
+    }
+    /** Visible height after trimming in world units */
+    get trimmedHeight() {
+        const frameSize = this._private_rotatedInternal ? this._private_frameWidth : this._private_frameHeight;
+        return frameSize / this._private_scaleInternal;
+    }
+    /** Underlying Three.js texture */
+    get texture() {
+        return this._private_textureInternal;
+    }
+    /** Whether sprite is rotated in atlas */
+    get rotated() {
+        return this._private_rotatedInternal;
+    }
+    /** Scale factor for resolution independence */
+    get scale() {
+        return this._private_scaleInternal;
+    }
+    /** Transparent padding around visible content */
+    get trim() {
+        const scale = this._private_scaleInternal;
+        return {
+            left: this._private_trimLeft / scale,
+            right: this._private_trimRight / scale,
+            top: this._private_trimTop / scale,
+            bottom: this._private_trimBottom / scale,
+        };
+    }
+    get textureDirty() {
+        return this._private_textureDirtyInternal;
+    }
+    /** Whether UV transform inputs changed since last check */
+    get uvTransformDirty() {
+        return this._private_uvTransformDirtyInternal;
+    }
+    /** Whether trim values changed since last check */
+    get trimDirty() {
+        return this._private_trimDirtyInternal;
+    }
+    get signalDiminsionsChanged() {
+        return this._private_signalDiminsionsChangedInternal;
+    }
+    setTextureDirtyFalse() {
+        this._private_textureDirtyInternal = false;
+    }
+    /** Marks UV transform as clean. @internal */
+    setUVTransformDirtyFalse() {
+        this._private_uvTransformDirtyInternal = false;
+    }
+    /** Marks trim as clean. @internal */
+    setTrimDirtyFalse() {
+        this._private_trimDirtyInternal = false;
+    }
+    /**
+     * Calculates UV transform matrix for shader sampling.
+     * @param result Matrix to store result in
+     * @returns UV transform matrix
+     */
+    calculateUVTransform(result = new Matrix3()) {
+        const atlasWidth = this._private_textureInternal.image?.naturalWidth ?? TEXTURE_DEFAULT_SIZE;
+        const atlasHeight = this._private_textureInternal.image?.naturalHeight ?? TEXTURE_DEFAULT_SIZE;
+        if (this._private_rotatedInternal) {
+            const physicalWidth = this._private_frameHeight;
+            const physicalHeight = this._private_frameWidth;
+            const u0 = this._private_frameX / atlasWidth;
+            const v0 = (atlasHeight - this._private_frameY - physicalHeight) / atlasHeight;
+            const uSize = physicalWidth / atlasWidth;
+            const vSize = physicalHeight / atlasHeight;
+            result.set(0, uSize, u0, -vSize, 0, v0 + vSize, 0, 0, 1);
+        }
+        else {
+            const u0 = this._private_frameX / atlasWidth;
+            const v0 = (atlasHeight - this._private_frameY - this._private_frameHeight) / atlasHeight;
+            const uSize = this._private_frameWidth / atlasWidth;
+            const vSize = this._private_frameHeight / atlasHeight;
+            result.set(uSize, 0, u0, 0, vSize, v0, 0, 0, 1);
+        }
+        return result;
+    }
+    /**
+     * Gets original dimensions before trimming.
+     * @param result Vector to store result in
+     * @returns Width and height in world units
+     */
+    getResolution(result = new Vector2()) {
+        return result.set(this.width, this.height);
+    }
+    /**
+     * Replaces texture with new configuration.
+     * @param config Texture or atlas configuration
+     */
+    set(config) {
+        const lastWidth = this.width;
+        const lastHeight = this.height;
+        if (config instanceof Texture) {
+            this._private_setFromTexture(config);
+        }
+        else {
+            this._private_setFromAtlasConfig(config);
+        }
+        if (this.width !== lastWidth || this.height !== lastHeight) {
+            this._private_signalDiminsionsChangedInternal.emit(this.width, this.height, this);
+        }
+    }
+    _private_setFromTexture(texture) {
+        const width = texture.image?.naturalWidth ?? TEXTURE_DEFAULT_SIZE;
+        const height = texture.image?.naturalHeight ?? TEXTURE_DEFAULT_SIZE;
+        this._private_sourceWidth = width;
+        this._private_sourceHeight = height;
+        if (this.texture !== texture) {
+            this._private_textureInternal = texture;
+            this._private_textureDirtyInternal = true;
+        }
+        if (this._private_frameX !== 0 ||
+            this._private_frameY !== 0 ||
+            this._private_frameWidth !== width ||
+            this._private_frameHeight !== height ||
+            this._private_scaleInternal !== 1 || this._private_rotatedInternal) {
+            this._private_frameX = 0;
+            this._private_frameY = 0;
+            this._private_frameWidth = width;
+            this._private_frameHeight = height;
+            this._private_rotatedInternal = false;
+            this._private_scaleInternal = 1;
+            this._private_uvTransformDirtyInternal = true;
+        }
+        if (this._private_trimLeft !== 0 ||
+            this._private_trimRight !== 0 ||
+            this._private_trimTop !== 0 ||
+            this._private_trimBottom !== 0) {
+            this._private_trimLeft = 0;
+            this._private_trimRight = 0;
+            this._private_trimTop = 0;
+            this._private_trimBottom = 0;
+            this._private_trimDirtyInternal = true;
+        }
+    }
+    _private_setFromAtlasConfig(config) {
+        assertValidPositiveNumber(config.sourceSize.w, "FXTextureView.setFromAtlasConfig.config.sourceSize.w");
+        assertValidPositiveNumber(config.sourceSize.h, "FXTextureView.setFromAtlasConfig.config.sourceSize.h");
+        assertValidNonNegativeNumber(config.frame.x, "FXTextureView.setFromAtlasConfig.config.frame.x");
+        assertValidNonNegativeNumber(config.frame.y, "FXTextureView.setFromAtlasConfig.config.frame.y");
+        assertValidPositiveNumber(config.frame.w, "FXTextureView.setFromAtlasConfig.config.frame.w");
+        assertValidPositiveNumber(config.frame.h, "FXTextureView.setFromAtlasConfig.config.frame.h");
+        assertValidNonNegativeNumber(config.spriteSourceSize.x, "FXTextureView.setFromAtlasConfig.config.spriteSourceSize.x");
+        assertValidNonNegativeNumber(config.spriteSourceSize.y, "FXTextureView.setFromAtlasConfig.config.spriteSourceSize.y");
+        assertValidPositiveNumber(config.spriteSourceSize.w, "FXTextureView.setFromAtlasConfig.config.spriteSourceSize.w");
+        assertValidPositiveNumber(config.spriteSourceSize.h, "FXTextureView.setFromAtlasConfig.config.spriteSourceSize.h");
+        if (config.scale !== undefined) {
+            assertValidPositiveNumber(config.scale, "FXTextureView.setFromAtlasConfig.config.scale");
+        }
+        this._private_sourceWidth = config.sourceSize.w;
+        this._private_sourceHeight = config.sourceSize.h;
+        if (this.texture !== config.texture) {
+            this._private_textureInternal = config.texture;
+            this._private_textureDirtyInternal = true;
+        }
+        const scale = config.scale ?? 1;
+        const rotated = config.rotated ?? false;
+        if (this._private_frameX !== 0 ||
+            this._private_frameY !== 0 ||
+            this._private_frameWidth !== config.frame.w ||
+            this._private_frameHeight !== config.frame.h ||
+            this._private_scaleInternal !== scale ||
+            this._private_rotatedInternal !== rotated) {
+            this._private_frameX = config.frame.x;
+            this._private_frameY = config.frame.y;
+            this._private_frameWidth = config.frame.w;
+            this._private_frameHeight = config.frame.h;
+            this._private_scaleInternal = scale;
+            this._private_rotatedInternal = rotated;
+            this._private_uvTransformDirtyInternal = true;
+        }
+        const spriteSource = config.spriteSourceSize;
+        const trimLeft = spriteSource.x;
+        const trimTop = spriteSource.y;
+        const trimRight = this._private_sourceWidth - spriteSource.x - spriteSource.w;
+        const trimBottom = this._private_sourceHeight - spriteSource.y - spriteSource.h;
+        if (this._private_trimLeft !== trimLeft ||
+            this._private_trimRight !== trimRight ||
+            this._private_trimTop !== trimTop ||
+            this._private_trimBottom !== trimBottom) {
+            this._private_trimLeft = trimLeft;
+            this._private_trimRight = trimRight;
+            this._private_trimTop = trimTop;
+            this._private_trimBottom = trimBottom;
+            this._private_trimDirtyInternal = true;
+        }
+    }
+}
+
+export { FXTextureView };

package/dist/nodes/color/FXNodeColor.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Abstract base class for particle color nodes
+ */
+export declare abstract class FXNodeColor {
+    /** Releases any GPU resources held by this node */
+    destroy?(): void;
+}

package/dist/nodes/color/FXNodeColor.js

@@ -0,0 +1,11 @@
+/**
+ * Abstract base class for particle color nodes
+ */
+class FXNodeColor {
+    constructor() {
+        /** @internal */
+        this.affectsDepth = false;
+    }
+}
+
+export { FXNodeColor };

package/dist/nodes/color/FXNodeColorOverLife.d.ts

@@ -0,0 +1,25 @@
+import type { FXColor } from "../../miscellaneous/color/FXColor";
+import type { FXCurve1DConfig } from "../../miscellaneous/curve/FXCurve1D";
+import { FXCurve1D } from "../../miscellaneous/curve/FXCurve1D";
+import { FXNodeColor } from "./FXNodeColor";
+/**
+ * Color node that animates particle color along a gradient curve over its lifetime
+ */
+export declare class FXNodeColorOverLife extends FXNodeColor {
+    private readonly uniformName;
+    private curveInternal;
+    /**
+     * @param curve - Color gradient defining the animation over the particle lifetime
+     */
+    constructor(curve: FXCurve1DConfig<FXColor>);
+    /** Current color gradient curve */
+    get curve(): FXCurve1D<FXColor>;
+    /**
+     * Replaces the color gradient curve and rebuilds the backing texture
+     *
+     * @param value - New color gradient configuration
+     */
+    set curve(value: FXCurve1DConfig<FXColor>);
+    /** Releases the backing gradient texture */
+    destroy(): void;
+}

package/dist/nodes/color/FXNodeColorOverLife.js

@@ -0,0 +1,60 @@
+import { FXCurve1D } from '../../miscellaneous/curve/FXCurve1D.js';
+import { buildGradientTexture, getNextInstanceId } from '../../miscellaneous/miscellaneous.js';
+import { checkSRGBSupport } from '../../miscellaneous/webglCapabilities.js';
+import { FXNodeColor } from './FXNodeColor.js';
+
+/**
+ * Color node that animates particle color along a gradient curve over its lifetime
+ */
+class FXNodeColorOverLife extends FXNodeColor {
+    /**
+     * @param curve - Color gradient defining the animation over the particle lifetime
+     */
+    constructor(curve) {
+        super();
+        const id = getNextInstanceId();
+        this._private_uniformName = `u_ColorOverLife_${id}`;
+        this._private_curveInternal = new FXCurve1D(curve);
+        this._private_gradientTexture = buildGradientTexture(this._private_curveInternal);
+        this.affectsDepth = true;
+        this.cacheKey = "color-over-life";
+        this.uniformDeclarations = [`uniform sampler2D ${this._private_uniformName};`];
+        this.uniforms = {
+            [this._private_uniformName]: { value: this._private_gradientTexture },
+        };
+        this.helperFunctions = `
+      vec4 fxSampleColorOverLife(sampler2D gradientTexture) {
+        // Normalized particle age [0, 1] maps to the gradient texture's x-axis
+        float lifetimeRatio = clamp(PARTICLE_AGE / PARTICLE_LIFETIME, 0.0, 1.0);
+        vec4 color = texture2D(gradientTexture, vec2(lifetimeRatio, 0.5));
+
+        // Apply gamma correction when sRGB textures are not natively supported
+        ${checkSRGBSupport() ? "" : "color = vec4(pow(color.rgb, vec3(2.2)), color.a);"}
+
+        return color;
+      }
+    `;
+        this.colorExpression = `fxSampleColorOverLife(${this._private_uniformName})`;
+    }
+    /** Current color gradient curve */
+    get curve() {
+        return this._private_curveInternal;
+    }
+    /**
+     * Replaces the color gradient curve and rebuilds the backing texture
+     *
+     * @param value - New color gradient configuration
+     */
+    set curve(value) {
+        this._private_curveInternal = new FXCurve1D(value);
+        this._private_gradientTexture.dispose();
+        this._private_gradientTexture = buildGradientTexture(this._private_curveInternal);
+        this.uniforms[this._private_uniformName].value = this._private_gradientTexture;
+    }
+    /** Releases the backing gradient texture */
+    destroy() {
+        this._private_gradientTexture.dispose();
+    }
+}
+
+export { FXNodeColorOverLife };

package/dist/nodes/color/FXNodeSphericalClip.d.ts

@@ -0,0 +1,18 @@
+import { FXNodeColor } from "./FXNodeColor";
+/**
+ * Color node that clips a particle to a circle with a configurable soft edge
+ *
+ * @remarks
+ * Fades alpha from fully opaque at `innerRadius` to fully transparent at the billboard edge
+ * (UV radius `0.5`). An `innerRadius` of `0.5` produces a hard circular clip with no gradient.
+ */
+export declare class FXNodeSphericalClip extends FXNodeColor {
+    private readonly uniformInnerRadius;
+    /**
+     * @param innerRadius - UV radius where the fade begins; must be non-negative. Defaults to `0.5`
+     */
+    constructor(innerRadius?: number);
+    /** UV radius of the fully opaque inner area */
+    get innerRadius(): number;
+    set innerRadius(value: number);
+}

package/dist/nodes/color/FXNodeSphericalClip.js

@@ -0,0 +1,45 @@
+import { assertValidNonNegativeNumber } from '../../miscellaneous/asserts.js';
+import { getNextInstanceId } from '../../miscellaneous/miscellaneous.js';
+import { FXNodeColor } from './FXNodeColor.js';
+
+/**
+ * Color node that clips a particle to a circle with a configurable soft edge
+ *
+ * @remarks
+ * Fades alpha from fully opaque at `innerRadius` to fully transparent at the billboard edge
+ * (UV radius `0.5`). An `innerRadius` of `0.5` produces a hard circular clip with no gradient.
+ */
+class FXNodeSphericalClip extends FXNodeColor {
+    /**
+     * @param innerRadius - UV radius where the fade begins; must be non-negative. Defaults to `0.5`
+     */
+    constructor(innerRadius = 0.5) {
+        super();
+        assertValidNonNegativeNumber(innerRadius, "FXNodeSphericalClip.constructor.innerRadius");
+        const id = getNextInstanceId();
+        this._private_uniformInnerRadius = `u_SphericalClipInnerRadius_${id}`;
+        this.affectsDepth = true;
+        this.cacheKey = "spherical-clip";
+        this.uniformDeclarations = [`uniform float ${this._private_uniformInnerRadius};`];
+        this.uniforms = {
+            [this._private_uniformInnerRadius]: { value: innerRadius },
+        };
+        this.helperFunctions = `
+      vec4 fxApplySphericalClip(float innerRadius) {
+        float distanceToCenter = distance(p_uv, vec2(0.5, 0.5));
+        return vec4(1.0, 1.0, 1.0, 1.0 - smoothstep(innerRadius, 0.5, distanceToCenter));
+      }
+    `;
+        this.colorExpression = `fxApplySphericalClip(${this._private_uniformInnerRadius})`;
+    }
+    /** UV radius of the fully opaque inner area */
+    get innerRadius() {
+        return this.uniforms[this._private_uniformInnerRadius].value;
+    }
+    set innerRadius(value) {
+        assertValidNonNegativeNumber(value, "FXNodeSphericalClip.innerRadius");
+        this.uniforms[this._private_uniformInnerRadius].value = value;
+    }
+}
+
+export { FXNodeSphericalClip };

package/dist/nodes/normal/FXNodeFlatNormal.d.ts

@@ -0,0 +1,7 @@
+import { FXNodeNormal } from "./FXNodeNormal";
+/**
+ * Normal node that outputs a constant face-aligned normal pointing toward the camera
+ */
+export declare class FXNodeFlatNormal extends FXNodeNormal {
+    constructor();
+}

package/dist/nodes/normal/FXNodeFlatNormal.js

@@ -0,0 +1,17 @@
+import { FXNodeNormal } from './FXNodeNormal.js';
+
+/**
+ * Normal node that outputs a constant face-aligned normal pointing toward the camera
+ */
+class FXNodeFlatNormal extends FXNodeNormal {
+    constructor() {
+        super();
+        this.cacheKey = "flat-normal";
+        this.uniformDeclarations = [];
+        this.uniforms = {};
+        this.helperFunctions = "";
+        this.normalExpression = "vec3(0.0, 0.0, 1.0)";
+    }
+}
+
+export { FXNodeFlatNormal };

package/dist/nodes/normal/FXNodeNormal.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Abstract base class for particle normal nodes
+ */
+export declare abstract class FXNodeNormal {
+    /** Releases any GPU resources held by this node */
+    destroy?(): void;
+}

package/dist/nodes/normal/FXNodeNormal.js

@@ -0,0 +1,7 @@
+/**
+ * Abstract base class for particle normal nodes
+ */
+class FXNodeNormal {
+}
+
+export { FXNodeNormal };

package/dist/nodes/normal/FXNodeSphericalNormal.d.ts

@@ -0,0 +1,7 @@
+import { FXNodeNormal } from "./FXNodeNormal";
+/**
+ * Normal node that makes flat billboard particles appear as spheres under directional lighting
+ */
+export declare class FXNodeSphericalNormal extends FXNodeNormal {
+    constructor();
+}

package/dist/nodes/normal/{FXSphericalNormalNode.js → FXNodeSphericalNormal.js}

@@ -1,9 +1,12 @@
-import { FXNormalNode } from './FXNormalNode.js';
+import { FXNodeNormal } from './FXNodeNormal.js';
 
-class FXSphericalNormalNode extends FXNormalNode {
+/**
+ * Normal node that makes flat billboard particles appear as spheres under directional lighting
+ */
+class FXNodeSphericalNormal extends FXNodeNormal {
     constructor() {
         super();
-        this.cacheKey = "spherical";
+        this.cacheKey = "spherical-normal";
         this.uniformDeclarations = [];
         this.uniforms = {};
         this.helperFunctions = `
@@ -16,4 +19,4 @@ class FXSphericalNormalNode extends FXNormalNode {
     }
 }
 
-export { FXSphericalNormalNode };
+export { FXNodeSphericalNormal };

package/dist/nodes/texture/FXNodeAnimatedTexture.d.ts

@@ -0,0 +1,47 @@
+import { FXTextureView } from "../../miscellaneous/texture/FXTextureView";
+import type { FXTextureConfig } from "../../miscellaneous/texture/FXTextureView.Internal";
+import { FXNodeTexture } from "./FXNodeTexture";
+/**
+ * Options for {@link FXNodeAnimatedTexture}
+ */
+export interface FXNodeAnimatedTextureOptions {
+    /** Texture or atlas configuration containing all animation frames */
+    texture: FXTextureConfig;
+    /** Number of frame columns in the sprite sheet */
+    columns: number;
+    /** Number of frame rows in the sprite sheet */
+    rows: number;
+    /**
+     * If true, blends between adjacent frames for smoother animation
+     *
+     * @defaultValue `false`
+     */
+    interpolate?: boolean;
+}
+/**
+ * Texture node that animates through sprite sheet frames over a particle's lifetime
+ *
+ * @remarks
+ * Frames advance from the first to the last as the particle ages. The total frame count
+ * is `columns * rows`. Both `columns` and `rows` must be positive integers.
+ */
+export declare class FXNodeAnimatedTexture extends FXNodeTexture {
+    private readonly uniformTexture;
+    private readonly uniformUVTransform;
+    private readonly uniformColumns;
+    private readonly uniformRows;
+    private readonly textureViewInternal;
+    /**
+     * @param options - Sprite sheet configuration
+     */
+    constructor({ texture, columns, rows, interpolate }: FXNodeAnimatedTextureOptions);
+    /** View describing the texture and its atlas region */
+    get textureView(): FXTextureView;
+    /** Number of frame columns in the sprite sheet */
+    get columns(): number;
+    /** Number of frame rows in the sprite sheet */
+    get rows(): number;
+    set textureView(config: FXTextureConfig);
+    set columns(value: number);
+    set rows(value: number);
+}

package/dist/nodes/texture/FXNodeAnimatedTexture.js

@@ -0,0 +1,137 @@
+import { assertValidPositiveNumber } from '../../miscellaneous/asserts.js';
+import { getNextInstanceId } from '../../miscellaneous/miscellaneous.js';
+import { FXTextureView } from '../../miscellaneous/texture/FXTextureView.js';
+import { checkSRGBSupport } from '../../miscellaneous/webglCapabilities.js';
+import { FXNodeTexture } from './FXNodeTexture.js';
+
+/**
+ * Texture node that animates through sprite sheet frames over a particle's lifetime
+ *
+ * @remarks
+ * Frames advance from the first to the last as the particle ages. The total frame count
+ * is `columns * rows`. Both `columns` and `rows` must be positive integers.
+ */
+class FXNodeAnimatedTexture extends FXNodeTexture {
+    /**
+     * @param options - Sprite sheet configuration
+     */
+    constructor({ texture, columns, rows, interpolate = false }) {
+        super();
+        assertValidPositiveNumber(columns, "FXNodeAnimatedTexture.constructor.columns");
+        assertValidPositiveNumber(rows, "FXNodeAnimatedTexture.constructor.rows");
+        const idx = getNextInstanceId();
+        this._private_uniformTexture = `u_AnimatedTexture_${idx}`;
+        this._private_uniformUVTransform = `u_AnimatedTextureUVTransform_${idx}`;
+        this._private_uniformColumns = `u_AnimatedTextureColumns_${idx}`;
+        this._private_uniformRows = `u_AnimatedTextureRows_${idx}`;
+        this._private_textureViewInternal = new FXTextureView(texture);
+        const uvTransform = this._private_textureViewInternal.calculateUVTransform();
+        this._private_textureViewInternal.setTextureDirtyFalse();
+        this._private_textureViewInternal.setUVTransformDirtyFalse();
+        const gammaCorrection = checkSRGBSupport()
+            ? ""
+            : "color = vec4(pow(color.rgb, vec3(2.2)), color.a);";
+        this.affectsDepth = true;
+        this.cacheKey = interpolate ? "animated-texture-interpolated" : "animated-texture";
+        this.uniformDeclarations = [
+            `uniform sampler2D ${this._private_uniformTexture};`,
+            `uniform mat3 ${this._private_uniformUVTransform};`,
+            `uniform float ${this._private_uniformColumns};`,
+            `uniform float ${this._private_uniformRows};`,
+        ];
+        this.uniforms = {
+            [this._private_uniformTexture]: { value: this._private_textureViewInternal.texture },
+            [this._private_uniformUVTransform]: { value: uvTransform },
+            [this._private_uniformColumns]: { value: columns },
+            [this._private_uniformRows]: { value: rows },
+        };
+        this.helperFunctions = interpolate
+            ? `
+        vec2 fxFrameToUV(vec2 uv, float frame, float columns, float rows) {
+          float column = mod(frame, columns);
+          float row = floor(frame / columns);
+          return vec2((column + uv.x) / columns, 1.0 - (row + 1.0 - uv.y) / rows);
+        }
+
+        vec4 fxSampleAnimatedTexture(sampler2D spriteSheet, mat3 uvTransform, vec2 uv, float columns, float rows) {
+          float totalFrames = columns * rows;
+
+          // Fractional frame position drives both frame selection and blend weight
+          float exactFrame = PARTICLE_AGE / PARTICLE_LIFETIME * totalFrames;
+          float currentFrame = clamp(floor(exactFrame), 0.0, totalFrames - 1.0);
+          float nextFrame    = clamp(currentFrame + 1.0, 0.0, totalFrames - 1.0);
+          float blendWeight  = fract(exactFrame);
+
+          vec2 currentUV = (uvTransform * vec3(fxFrameToUV(uv, currentFrame, columns, rows), 1.0)).xy;
+          vec2 nextUV    = (uvTransform * vec3(fxFrameToUV(uv, nextFrame,    columns, rows), 1.0)).xy;
+
+          vec4 color = mix(
+            texture2D(spriteSheet, currentUV),
+            texture2D(spriteSheet, nextUV),
+            blendWeight
+          );
+
+          // Apply gamma correction when sRGB textures are not natively supported
+          ${gammaCorrection}
+
+          return color;
+        }
+      `
+            : `
+        vec4 fxSampleAnimatedTexture(sampler2D spriteSheet, mat3 uvTransform, vec2 uv, float columns, float rows) {
+          // Determine which frame to display based on normalized particle age
+          float totalFrames = columns * rows;
+          float frame = floor(PARTICLE_AGE / PARTICLE_LIFETIME * totalFrames);
+          frame = clamp(frame, 0.0, totalFrames - 1.0);
+
+          // Locate the frame's column and row in the sprite sheet grid
+          float column = mod(frame, columns);
+          float row = floor(frame / columns);
+
+          // Remap UV to the frame's tile region, then apply atlas transform
+          vec2 frameUV = vec2((column + uv.x) / columns, 1.0 - (row + 1.0 - uv.y) / rows);
+          vec2 atlasUV = (uvTransform * vec3(frameUV, 1.0)).xy;
+          vec4 color = texture2D(spriteSheet, atlasUV);
+
+          // Apply gamma correction when sRGB textures are not natively supported
+          ${gammaCorrection}
+
+          return color;
+        }
+      `;
+        this.colorExpression = `fxSampleAnimatedTexture(${this._private_uniformTexture}, ${this._private_uniformUVTransform}, p_uv, ${this._private_uniformColumns}, ${this._private_uniformRows})`;
+    }
+    /** View describing the texture and its atlas region */
+    get textureView() {
+        return this._private_textureViewInternal;
+    }
+    /** Number of frame columns in the sprite sheet */
+    get columns() {
+        return this.uniforms[this._private_uniformColumns].value;
+    }
+    /** Number of frame rows in the sprite sheet */
+    get rows() {
+        return this.uniforms[this._private_uniformRows].value;
+    }
+    set textureView(config) {
+        this._private_textureViewInternal.set(config);
+        if (this._private_textureViewInternal.textureDirty) {
+            this.uniforms[this._private_uniformTexture].value = this._private_textureViewInternal.texture;
+            this._private_textureViewInternal.setTextureDirtyFalse();
+        }
+        if (this._private_textureViewInternal.uvTransformDirty) {
+            this._private_textureViewInternal.calculateUVTransform(this.uniforms[this._private_uniformUVTransform].value);
+            this._private_textureViewInternal.setUVTransformDirtyFalse();
+        }
+    }
+    set columns(value) {
+        assertValidPositiveNumber(value, "FXNodeAnimatedTexture.columns");
+        this.uniforms[this._private_uniformColumns].value = value;
+    }
+    set rows(value) {
+        assertValidPositiveNumber(value, "FXNodeAnimatedTexture.rows");
+        this.uniforms[this._private_uniformRows].value = value;
+    }
+}
+
+export { FXNodeAnimatedTexture };