sparcoon 0.9.0 → 0.9.2

package/dist/emitter/FXEmitter.js

@@ -1,37 +1,28 @@
 import { Object3D, Quaternion, Vector3 } from "three";
 import { FXWorld } from "../world/FXWorld.js";
 import { FXObjectMotionTracker } from "./FXObjectMotion.Internal.js";
-import { FX_AGE, FX_CORE_LIFECYCLE, FX_CORE_LIFECYCLE_STRIDE, FX_CORE_POSITION, FX_CORE_POSITION_STRIDE, } from "../coreLayout.js";
-import { FXInstancedParticle } from "../instancedParticle/FXInstancedParticle.js";
 import { resolveGeometrySource } from "../instancedParticle/primitiveGeometry.js";
 import { assertValidNonNegativeNumber, assertValidPositiveInteger, assertValidPositiveNumber, } from "../miscellaneous/asserts.js";
 import { FXArtifactMaterial } from "../render/FXArtifactMaterial.js";
-import { FXSimulationHolder } from "./FXSimulationHolder.js";
+import { FXGPUEmitterDriver } from "./FXGPUEmitterDriver.Internal.js";
+import { FXJSEmitterDriver } from "./FXJSEmitterDriver.Internal.js";
 import { EMITTER_DEFAULT_CAPACITY_STEP, EMITTER_DEFAULT_CAST_SHADOW, EMITTER_DEFAULT_EXPECTED_CAPACITY, EMITTER_DEFAULT_PREWARM_MAX_STEP_COUNT, EMITTER_DEFAULT_PREWARM_MIN_STEP_DURATION, EMITTER_DEFAULT_RECEIVE_SHADOW, EMITTER_DEFAULT_SORT_FRACTION, } from "./FXEmitter.Internal.js";
-// User attribute `name` -> mesh property-buffer key `fx_<name>`.
-const ATTRIBUTE_BUFFER_PREFIX = "fx_";
-// GLSL type of a float attribute, indexed by component count.
-const GLSL_TYPE_BY_COMPONENTS = ["", "float", "vec2", "vec3", "vec4"];
-const CORE_POSITION_TYPE = {
-    glslTypeName: "vec3",
-    bufferSize: FX_CORE_POSITION_STRIDE,
-    instantiable: true,
-};
-const CORE_LIFECYCLE_TYPE = {
-    glslTypeName: "vec2",
-    bufferSize: FX_CORE_LIFECYCLE_STRIDE,
-    instantiable: true,
-};
 /**
  * Particle emitter - one instanced billboard/mesh draw call, per-particle state driven by a
  * precompiled behavior artifact and appearance by a precompiled render artifact spliced into a
  * Three material. Built and ticked by {@link FXEffect} through an {@link FXWorld}. Not exported from
  * the package (the runtime path is running artifacts, not hand-building emitters); reached only as
  * the live handle returned by {@link FXEffect.getEmitter}.
+ *
+ * A thin facade over one {@link FXEmitterDriver} (JS or GPU - see `FXEmitterDriver.Internal.ts`),
+ * chosen once by {@link fromArtifacts} and never switched mid-playback. This class itself owns only
+ * what is genuinely backend-independent: play/burst/stop/prewarm scheduling, sort-fraction timing,
+ * object motion tracking, and the render material - the material itself CAN be replaced in place,
+ * by {@link applyRenderArtifact}, without touching the driver or its particle state.
  */
 export class FXEmitter extends Object3D {
     /** @internal Use {@link FXEmitter.fromArtifacts}. */
-    constructor(material, simulation, options = {}, baseGeometry, world) {
+    constructor(driver, material, options, world) {
         super();
         this.nextHandler = 0;
         this.pendingBursts = [];
@@ -52,38 +43,22 @@ export class FXEmitter extends Object3D {
         this.motionScaleScratch = new Vector3();
         this.motionTracker = new FXObjectMotionTracker();
         this.destroyed = false;
-        this.kernelBuffersCacheVersion = -1;
         this.onRendering = (deltaTime) => {
             this.tick(deltaTime);
-            if (this.sortCamera !== undefined && this.mesh.instanceCount > 0) {
-                // `sortFraction` is public, so clamp here too: a direct assignment above 1 would grow the accumulator unbounded.
-                this.sortingAccumulator += Math.min(Math.max(this.sortFraction, 0), 1);
-                if (this.sortingAccumulator >= 1) {
-                    this.sortingAccumulator -= 1;
-                    // Sort in world space to match the shader's `p_cameraDistance`, correct under any transform.
-                    this.sortCamera.getWorldPosition(this.sortingCameraWorldPosition);
-                    this.mesh.updateWorldMatrix(true, false);
-                    this.mesh.sortByDistance(this.sortingCameraWorldPosition, this.mesh.matrixWorld);
-                }
+            if (this.sortCamera === undefined) {
+                return;
+            }
+            // `sortFraction` is public, so clamp here too: a direct assignment above 1 would grow the accumulator unbounded.
+            this.sortingAccumulator += Math.min(Math.max(this.sortFraction, 0), 1);
+            if (this.sortingAccumulator >= 1) {
+                this.sortingAccumulator -= 1;
+                this.sortCamera.getWorldPosition(this.sortingCameraWorldPosition);
+                this.driver.sortByDistance(this.sortingCameraWorldPosition);
             }
         };
         this.world = world;
-        if (options.expectedCapacity !== undefined) {
-            // Sizes the Float32Array buffers - a fractional length is a RangeError.
-            assertValidPositiveInteger(options.expectedCapacity, "FXEmitter.constructor.options.expectedCapacity");
-        }
-        if (options.capacityStep !== undefined) {
-            assertValidPositiveInteger(options.capacityStep, "FXEmitter.constructor.options.capacityStep");
-        }
+        this.driver = driver;
         this.material = material;
-        this.simulation = simulation;
-        // Property set = the two core buffers plus one `fx_<name>` per attribute, known before the mesh
-        // and Three material are built so `a_<name>`/`p_<name>` are declared up front. A cross-artifact
-        // width disagreement fails fast here.
-        const components = this.attributeComponents();
-        this.collectedProperties = this.buildCollectedProperties(components);
-        const threeMaterial = material.buildThreeMaterial(this.collectedProperties);
-        this.mesh = new FXInstancedParticle(this.collectedProperties, options.expectedCapacity ?? EMITTER_DEFAULT_EXPECTED_CAPACITY, options.capacityStep ?? EMITTER_DEFAULT_CAPACITY_STEP, threeMaterial, baseGeometry);
         if (options.receiveShadow ?? EMITTER_DEFAULT_RECEIVE_SHADOW) {
             this.mesh.receiveShadow = true;
         }
@@ -92,7 +67,7 @@ export class FXEmitter extends Object3D {
         // false on the mesh, so the shadow pass's frustum check is a no-op just like the color pass.
         if (options.castShadow ?? EMITTER_DEFAULT_CAST_SHADOW) {
             this.mesh.castShadow = true;
-            this.mesh.customDepthMaterial = material.buildThreeDepthMaterial(this.collectedProperties);
+            this.mesh.customDepthMaterial = material.buildThreeDepthMaterial(this.driver.varyings);
         }
         this.sortCamera = options.sortCamera;
         this.sortFraction = EMITTER_DEFAULT_SORT_FRACTION;
@@ -101,23 +76,58 @@ export class FXEmitter extends Object3D {
         }
         this.assertCanSpawn("FXEmitter.constructor");
         this.add(this.mesh);
-        this.world.registerEmitter(this);
+        this.world.registerObject(this);
     }
+    /** Exact live count for a JS-driven emitter; for a GPU-driven one, there is no CPU-visible live
+     *  count to report - `capacity` is the honest upper bound reported instead. */
     get particleCount() {
-        return this.mesh.instanceCount;
+        return this.driver.particleCount;
     }
+    /** The buffer's current allocated size - grows over time for a JS-driven emitter, fixed at
+     *  construction for a GPU-driven one (no capacityStep growth path there). */
     get particleCapacity() {
-        return this.mesh.instanceCapacity;
+        return this.driver.particleCapacity;
+    }
+    // The active driver's own mesh - a thin passthrough, not a second source of truth (this.driver.mesh
+    // is authoritative; nothing caches or duplicates it here).
+    get mesh() {
+        return this.driver.mesh;
     }
     /**
-     * @internal Builds an emitter into `world` from a precompiled effect. Called by {@link FXEffect};
-     * the editor emits the two artifacts as an ESM module and the effect hands them here.
+     * Builds an emitter into `world` from a precompiled effect - the low-level building block behind
+     * {@link FXEffect}. Exposed for editor tooling through the `sparcoon/editor` entry (live preview
+     * rebuilds a single emitter per graph edit); not part of the main package surface, where the
+     * runtime path is running whole projects through `FXEffect`.
      */
     static fromArtifacts(render, behavior, options = {}, world = FXWorld.getDefault()) {
+        if (options.expectedCapacity !== undefined) {
+            // Sizes the Float32Array buffers - a fractional length is a RangeError. Doubles as the
+            // fixed GPU capacity when a GPU kernel is present (no capacityStep growth for that path).
+            assertValidPositiveInteger(options.expectedCapacity, "FXEmitter.constructor.options.expectedCapacity");
+        }
+        if (options.capacityStep !== undefined) {
+            assertValidPositiveInteger(options.capacityStep, "FXEmitter.constructor.options.capacityStep");
+        }
         const material = new FXArtifactMaterial(render, options.textures);
-        const holder = new FXSimulationHolder(behavior);
         const baseGeometry = resolveGeometrySource(render.geometry, options.geometries ?? {});
-        return new FXEmitter(material, holder, options, baseGeometry, world);
+        const capacity = options.expectedCapacity ?? EMITTER_DEFAULT_EXPECTED_CAPACITY;
+        // The one place this emitter's backend is chosen, ever (never switched mid-playback). A real
+        // driver-level failure (program link, buffer/VAO setup) despite "Try GPU simulation" having
+        // compiled and the live render tier already being "standard" falls back to the mandatory JS
+        // artifact in place, no reload loop, matching the editor's sceneCoordinator.ts own forced-
+        // WebGL1-creation-failure fallback shape on the render side.
+        let driver;
+        if (options.gpuKernel !== undefined && options.renderer !== undefined) {
+            try {
+                driver = new FXGPUEmitterDriver(options.gpuKernel, options.renderer, material, capacity, baseGeometry);
+            }
+            catch (error) {
+                console.warn("FXEmitter: GPU (transform-feedback) behavior setup failed at runtime; falling back " +
+                    "to the JS behavior artifact for this emitter.", error);
+            }
+        }
+        driver ?? (driver = new FXJSEmitterDriver(behavior, material, capacity, options.capacityStep ?? EMITTER_DEFAULT_CAPACITY_STEP, baseGeometry));
+        return new FXEmitter(driver, material, options, world);
     }
     /**
      * @internal Ticks this emitter one frame. Driven by {@link FXWorld.update}, which advances the
@@ -138,15 +148,14 @@ export class FXEmitter extends Object3D {
             return;
         }
         this.destroyed = true;
-        this.world.unregisterEmitter(this);
-        // Drop scheduled work and the buffer cache so nothing references the mesh's buffers after teardown.
+        this.world.unregisterObject(this);
+        // Drop scheduled work so nothing references the driver's buffers after teardown.
         this.pendingBursts.length = 0;
         this.activePlays.length = 0;
-        this.kernelBuffersCache = undefined;
-        // The material owns no per-emitter GPU resources; the mesh teardown disposes the instanced
-        // geometry and the mounted material.
+        // The material owns no per-emitter GPU resources; the driver teardown disposes the instanced
+        // geometry and the mounted material (plus, for a GPU-driven emitter, the compiled program+VAO).
         this.material.destroy();
-        this.mesh.destroy();
+        this.driver.destroy();
         this.removeFromParent();
     }
     /**
@@ -241,14 +250,20 @@ export class FXEmitter extends Object3D {
             remaining -= deltaTime;
         }
     }
-    /** Kills all live particles and cancels all active plays and pending bursts. */
+    /**
+     * Kills all live particles and cancels all active plays and pending bursts. For a GPU-driven
+     * emitter this is a known-narrower reset (see the mesh's own `drop()` doc comment): there is no
+     * CPU-visible per-particle state to instantly zero, so already-alive particles keep aging out
+     * naturally rather than vanishing on this call's own frame - only the spawn cursor and pending
+     * schedule reset immediately.
+     */
     reset() {
         if (this.destroyed) {
             return;
         }
         this.pendingBursts.length = 0;
         this.activePlays.length = 0;
-        this.mesh.drop();
+        this.driver.reset();
         // A restarted effect should not report a teleport spike from wherever the emitter was last
         // posed - drop the velocity/angular-velocity baseline along with the particles.
         this.motionTracker.reset();
@@ -266,45 +281,42 @@ export class FXEmitter extends Object3D {
             this.material.applyUniformValues(values.uniforms);
         }
         if (values.bindings !== undefined) {
-            this.simulation?.applyBindingValues(values.bindings);
+            this.driver.applyBindingValues(values.bindings);
         }
     }
     /**
-     * Merged attribute set (name -> component count): union of the behavior's writes and the render's
-     * reads. Throws on a cross-artifact width disagreement rather than sizing a buffer wrong.
+     * Swaps only this emitter's render half in place - a new shader, geometry primitive/mesh, or
+     * shadow flags - leaving the behavior driver, particle buffers, instance count, and playback
+     * schedule completely untouched (unlike a structural edit that reaches {@link fromArtifacts},
+     * this never resets a running effect). The editor calls this instead of rebuilding whenever a
+     * graph edit only changed the render half.
+     *
+     * @throws If the new render artifact's attribute reads disagree with this emitter's already-
+     * allocated buffers (a genuine layout change - see {@link FXEmitterDriver.applyRenderArtifact}).
+     * This emitter is left exactly as it was before the call in that case; the caller must fall back
+     * to a fresh {@link fromArtifacts} instead, since only a new driver can safely resize buffers.
      */
-    attributeComponents() {
-        const components = new Map();
-        const add = (name, count) => {
-            const existing = components.get(name);
-            if (existing !== undefined && existing !== count) {
-                throw new Error(`FXEmitter: attribute "${name}" is written and read with conflicting widths ` +
-                    `(${existing.toString()} vs ${count.toString()}); the behavior attributeWrites and ` +
-                    `the render attributeReads must agree`);
-            }
-            components.set(name, count);
-        };
-        for (const write of this.simulation?.attributeWrites ?? []) {
-            add(write.name, write.components);
+    applyRenderArtifact(render, options = {}) {
+        if (this.destroyed) {
+            return;
         }
-        for (const read of this.material.attributeReads) {
-            add(read.name, read.components);
+        const material = new FXArtifactMaterial(render, options.textures);
+        const baseGeometry = resolveGeometrySource(render.geometry, options.geometries ?? {});
+        // Throws (leaving this emitter untouched) before anything below mutates it - see this
+        // method's own @throws doc.
+        this.driver.applyRenderArtifact(material, baseGeometry);
+        this.material = material;
+        this.mesh.receiveShadow = options.receiveShadow ?? EMITTER_DEFAULT_RECEIVE_SHADOW;
+        const previousDepthMaterial = this.mesh.customDepthMaterial;
+        if (options.castShadow ?? EMITTER_DEFAULT_CAST_SHADOW) {
+            this.mesh.castShadow = true;
+            this.mesh.customDepthMaterial = material.buildThreeDepthMaterial(this.driver.varyings);
         }
-        return components;
-    }
-    buildCollectedProperties(components) {
-        const properties = {
-            [FX_CORE_POSITION]: CORE_POSITION_TYPE,
-            [FX_CORE_LIFECYCLE]: CORE_LIFECYCLE_TYPE,
-        };
-        for (const [name, count] of components) {
-            properties[`${ATTRIBUTE_BUFFER_PREFIX}${name}`] = {
-                glslTypeName: GLSL_TYPE_BY_COMPONENTS[count],
-                bufferSize: count,
-                instantiable: true,
-            };
+        else {
+            this.mesh.castShadow = false;
+            this.mesh.customDepthMaterial = undefined;
         }
-        return properties;
+        previousDepthMaterial?.dispose();
     }
     setSortFraction(value, context) {
         assertValidNonNegativeNumber(value, context);
@@ -314,31 +326,10 @@ export class FXEmitter extends Object3D {
     // Throws when the behavior artifact cannot seed births. Checked at the scheduling points, NOT in
     // the frame tick - a throw from the world tick would take the host's render loop down.
     assertCanSpawn(context) {
-        if (this.simulation !== undefined && !this.simulation.canSpawn) {
+        if (!this.driver.canSpawn) {
             throw new Error(`${context}: this behavior artifact cannot seed births (update-only)`);
         }
     }
-    // Maps each kernel state-buffer name to its backing Float32Array. Cached across ticks/bursts and
-    // rebuilt only when the mesh's buffer set changes (`bufferVersion` - capacity growth).
-    kernelBuffers() {
-        const version = this.mesh.bufferVersion;
-        if (this.kernelBuffersCache !== undefined && this.kernelBuffersCacheVersion === version) {
-            return this.kernelBuffersCache;
-        }
-        const buffers = {
-            [FX_CORE_POSITION]: this.mesh.propertyBuffers[FX_CORE_POSITION].array,
-            [FX_CORE_LIFECYCLE]: this.mesh.propertyBuffers[FX_CORE_LIFECYCLE].array,
-        };
-        for (const buffer of this.simulation?.attributeBuffers ?? []) {
-            const attribute = this.mesh.propertyBuffers[`${ATTRIBUTE_BUFFER_PREFIX}${buffer.name}`];
-            if (attribute !== undefined) {
-                buffers[buffer.name] = attribute.array;
-            }
-        }
-        this.kernelBuffersCache = buffers;
-        this.kernelBuffersCacheVersion = version;
-        return buffers;
-    }
     // The emitter's world matrix as the reused snapshot the kernel reads. It is the mesh's
     // `matrixWorld` (same matrix the shader and depth sort see), so a world-space graph stays
     // consistent under any transform. `Matrix4.elements` is already column-major.
@@ -351,16 +342,6 @@ export class FXEmitter extends Object3D {
         }
         return transform;
     }
-    markBuffersNeedUpdate(names) {
-        for (const name of names) {
-            const isCore = name === FX_CORE_POSITION || name === FX_CORE_LIFECYCLE;
-            const key = isCore ? name : `${ATTRIBUTE_BUFFER_PREFIX}${name}`;
-            const attribute = this.mesh.propertyBuffers[key];
-            if (attribute !== undefined) {
-                attribute.needsUpdate = true;
-            }
-        }
-    }
     tick(deltaTime) {
         // World-space velocity/angular velocity since the previous tick, computed once here and not
         // inside worldTransform() - the burst/play loops below and the update phase can each call
@@ -388,16 +369,13 @@ export class FXEmitter extends Object3D {
         this.emitterTransform.angularVelocity[0] = motion.angularVelocity[0];
         this.emitterTransform.angularVelocity[1] = motion.angularVelocity[1];
         this.emitterTransform.angularVelocity[2] = motion.angularVelocity[2];
-        // Age increment + cull. Age is owned by this fixed loop, not the graph - same for every effect.
-        {
-            const lifecycle = this.mesh.propertyBuffers[FX_CORE_LIFECYCLE];
-            const { array, itemSize } = lifecycle;
-            const instanceCount = this.mesh.instanceCount;
-            for (let i = 0; i < instanceCount; i++) {
-                array[i * itemSize + FX_AGE] += deltaTime;
-            }
+        // Paused (dt == 0): skip the simulation step entirely - no JS age/kernel update, no GPU
+        // transform-feedback dispatch, no schedule advance - the emitter keeps rendering whatever
+        // particle state the last active tick left behind.
+        if (deltaTime <= 0) {
+            return;
         }
-        this.mesh.removeDeadParticles();
+        this.driver.beginTick(deltaTime);
         for (let i = this.pendingBursts.length - 1; i >= 0; i--) {
             const pending = this.pendingBursts[i];
             pending.delay -= deltaTime;
@@ -436,27 +414,10 @@ export class FXEmitter extends Object3D {
                 this.activePlays.splice(i, 1);
             }
         }
-        if (this.mesh.instanceCount === 0) {
-            return;
-        }
-        if (this.simulation !== undefined) {
-            // Motion integration lives in the graph (an `integrate-motion` node writes
-            // `position += velocity * dt`), not in this host loop.
-            this.simulation.update(this.kernelBuffers(), this.mesh.instanceCount, deltaTime, this.worldTransform());
-            this.markBuffersNeedUpdate(this.simulation.updateWrittenBuffers);
-        }
-        // Age (written above) must reach the GPU this frame; the update phase's buffers were flagged already.
-        this.mesh.propertyBuffers[FX_CORE_LIFECYCLE].needsUpdate = true;
+        this.driver.endTick(deltaTime, this.worldTransform());
     }
     spawnBurst(count) {
-        const instanceBegin = this.mesh.instanceCount;
-        this.mesh.createInstances(count);
-        const instanceEnd = this.mesh.instanceCount;
-        // Re-checked (defensive): no spawn function would leave the freshly zeroed rows born dead.
-        if (this.simulation?.canSpawn === true) {
-            this.simulation.spawn(this.kernelBuffers(), instanceBegin, instanceEnd - instanceBegin, this.worldTransform());
-            this.markBuffersNeedUpdate(this.simulation.spawnWrittenBuffers);
-        }
+        this.driver.spawn(count, this.worldTransform());
     }
 }
 // Returned by post-destroy `burst`/`play` - never matches a scheduled handler.

package/dist/emitter/FXEmitterDriver.Internal.d.ts

@@ -0,0 +1,26 @@
+import type { GLTypeInfo } from "../instancedParticle/glTypeInfo.js";
+/** A named width declaration - shape shared by `FXAttributeDecl` (`components`) and a mapped
+ *  `FXBufferLayout` (`stride`), the two concrete lists {@link mergeAttributeWidths} merges. */
+interface FXNamedWidth {
+    readonly name: string;
+    readonly components: number;
+}
+/**
+ * Merges width-declaring attribute lists (a driver's own state buffers, the render artifact's
+ * `attributeReads`) into one name -> component-count map, throwing on a genuine cross-source
+ * disagreement rather than sizing a buffer wrong. Shared by both drivers' constructors so the
+ * validation itself never drifts between them, even though each driver's own input list does not.
+ */
+export declare function mergeAttributeWidths(...sources: readonly (readonly FXNamedWidth[])[]): ReadonlyMap<string, number>;
+/** Builds a driver's full varyings map (the two core buffers plus one `fx_<name>` per attribute)
+ *  from a merged width map - the input to both `FXArtifactMaterial.buildThreeMaterial` and either
+ *  mesh class's constructor. */
+export declare function varyingsFromComponents(components: ReadonlyMap<string, number>): Record<string, GLTypeInfo>;
+/**
+ * Whether two varyings maps declare the exact same names at the exact same width - the guard
+ * `applyRenderArtifact` needs before reusing already-allocated buffers in place: a new render
+ * artifact whose attribute reads disagree with what is already allocated (a new name, or an
+ * existing name at a different width) cannot be applied without a full rebuild.
+ */
+export declare function sameVaryings(current: Record<string, GLTypeInfo>, next: Record<string, GLTypeInfo>): boolean;
+export {};

package/dist/emitter/FXEmitterDriver.Internal.js

@@ -0,0 +1,70 @@
+import { FX_CORE_LIFECYCLE, FX_CORE_LIFECYCLE_STRIDE, FX_CORE_POSITION, FX_CORE_POSITION_STRIDE, meshPropertyKeyFor, } from "../coreLayout.js";
+const CORE_POSITION_TYPE = {
+    glslTypeName: "vec3",
+    bufferSize: FX_CORE_POSITION_STRIDE,
+    instantiable: true,
+};
+const CORE_LIFECYCLE_TYPE = {
+    glslTypeName: "vec3",
+    bufferSize: FX_CORE_LIFECYCLE_STRIDE,
+    instantiable: true,
+};
+// GLSL type of a float attribute, indexed by component count.
+const GLSL_TYPE_BY_COMPONENTS = ["", "float", "vec2", "vec3", "vec4"];
+/**
+ * Merges width-declaring attribute lists (a driver's own state buffers, the render artifact's
+ * `attributeReads`) into one name -> component-count map, throwing on a genuine cross-source
+ * disagreement rather than sizing a buffer wrong. Shared by both drivers' constructors so the
+ * validation itself never drifts between them, even though each driver's own input list does not.
+ */
+export function mergeAttributeWidths(...sources) {
+    const components = new Map();
+    for (const source of sources) {
+        for (const decl of source) {
+            const existing = components.get(decl.name);
+            if (existing !== undefined && existing !== decl.components) {
+                throw new Error(`FXEmitter: attribute "${decl.name}" is declared with conflicting widths ` +
+                    `(${existing.toString()} vs ${decl.components.toString()}) across its sources`);
+            }
+            components.set(decl.name, decl.components);
+        }
+    }
+    return components;
+}
+/** Builds a driver's full varyings map (the two core buffers plus one `fx_<name>` per attribute)
+ *  from a merged width map - the input to both `FXArtifactMaterial.buildThreeMaterial` and either
+ *  mesh class's constructor. */
+export function varyingsFromComponents(components) {
+    const varyings = {
+        [FX_CORE_POSITION]: CORE_POSITION_TYPE,
+        [FX_CORE_LIFECYCLE]: CORE_LIFECYCLE_TYPE,
+    };
+    for (const [name, count] of components) {
+        varyings[meshPropertyKeyFor(name)] = {
+            glslTypeName: GLSL_TYPE_BY_COMPONENTS[count],
+            bufferSize: count,
+            instantiable: true,
+        };
+    }
+    return varyings;
+}
+/**
+ * Whether two varyings maps declare the exact same names at the exact same width - the guard
+ * `applyRenderArtifact` needs before reusing already-allocated buffers in place: a new render
+ * artifact whose attribute reads disagree with what is already allocated (a new name, or an
+ * existing name at a different width) cannot be applied without a full rebuild.
+ */
+export function sameVaryings(current, next) {
+    const currentNames = Object.keys(current);
+    if (currentNames.length !== Object.keys(next).length) {
+        return false;
+    }
+    return currentNames.every((name) => {
+        if (!Object.prototype.hasOwnProperty.call(next, name)) {
+            return false;
+        }
+        const nextEntry = next[name];
+        return (nextEntry.glslTypeName === current[name].glslTypeName &&
+            nextEntry.bufferSize === current[name].bufferSize);
+    });
+}

package/dist/emitter/FXFromArtifactsOptions.d.ts

@@ -1,4 +1,5 @@
-import type { BufferGeometry, Texture } from "three";
+import type { BufferGeometry, Texture, WebGLRenderer } from "three";
+import type { FXParticleKernelArtifact } from "../artifact/FXArtifact.js";
 import type { FXEmitterOptions } from "./FXEmitter.Internal.js";
 /**
  * Options for {@link FXEmitter.fromArtifacts}: the emitter options plus external textures by slot -
@@ -10,4 +11,14 @@ import type { FXEmitterOptions } from "./FXEmitter.Internal.js";
 export interface FXFromArtifactsOptions extends Partial<FXEmitterOptions> {
     readonly textures?: Record<string, Texture>;
     readonly geometries?: Record<string, BufferGeometry>;
+    /**
+     * The standard-tier (WebGL2, transform-feedback) behavior artifact, present only when the
+     * graph's spawn node had "Try GPU simulation" on and the graph compiled to GLSL. `renderer` is
+     * required alongside it - without one, or if GPU program setup itself throws (a real
+     * driver-level failure), the emitter falls back to the mandatory JS `behavior` artifact in
+     * place, never a hard error. `expectedCapacity` becomes this emitter's fixed GPU particle
+     * capacity (no growth); `capacityStep` is meaningless for a GPU-driven emitter and is ignored.
+     */
+    readonly gpuKernel?: FXParticleKernelArtifact;
+    readonly renderer?: WebGLRenderer;
 }

package/dist/emitter/FXGPUEmitterDriver.Internal.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/emitter/FXGPUEmitterDriver.Internal.js

@@ -0,0 +1,137 @@
+import { isCoreBufferName } from "../coreLayout.js";
+import { FXTransformFeedbackParticle } from "../instancedParticle/FXTransformFeedbackParticle.js";
+import { mergeAttributeWidths, sameVaryings, varyingsFromComponents, } from "./FXEmitterDriver.Internal.js";
+import { FXTransformFeedbackSimulationHolder } from "./FXTransformFeedbackSimulationHolder.js";
+/**
+ * @internal The GPU (WebGL2 transform-feedback) particle-simulation backend: a fixed-capacity
+ * `FXTransformFeedbackParticle` mesh driven by a precompiled `FXParticleKernelArtifact` through
+ * `FXTransformFeedbackSimulationHolder`. Self-sufficient from its own artifact - its varyings come
+ * from `gpu.kernel.buffers` (+ the render artifact's `attributeReads`), never from a JS behavior
+ * artifact's `attributeWrites`.
+ *
+ * No sorting or dead-particle compaction: every particle slot is always drawn at the fixed
+ * `capacity`, and `particleCount`/`particleCapacity` both report that capacity rather than an
+ * exact live count, which there is no cheap way to know.
+ */
+export class FXGPUEmitterDriver {
+    constructor(kernel, renderer, material, capacity, baseGeometry) {
+        // Cursor/overwrite bookkeeping: `gpuSpawnCursor` is the next write position (mod
+        // capacity); `gpuSpawnRangeStart`/`gpuPendingSpawnCount` accumulate every spawn() call since the
+        // last endTick() into one contiguous range, since the GPU can only run one transform-feedback pass
+        // per tick (unlike the JS backend, which can grow its array once per call with no such constraint) -
+        // "since the last endTick()", not "since the start of this tick": an immediate `burst()` between
+        // ticks must not lose its contribution (see endTick()'s own doc comment).
+        this.gpuSpawnCursor = 0;
+        this.gpuSpawnRangeStart = 0;
+        this.gpuPendingSpawnCount = 0;
+        // Depth sorting has no GPU-driven form - warned once, not every tick, if a host sets
+        // sortCamera on one anyway.
+        this.warnedAboutSortCamera = false;
+        const attributeBuffers = kernel.buffers.filter((buffer) => !isCoreBufferName(buffer.name));
+        this.behaviorAttributeWidths = attributeBuffers.map((buffer) => ({
+            name: buffer.name,
+            components: buffer.stride,
+        }));
+        const components = mergeAttributeWidths(this.behaviorAttributeWidths, material.attributeReads);
+        this.varyings = varyingsFromComponents(components);
+        const threeMaterial = material.buildThreeMaterial(this.varyings);
+        let mesh;
+        try {
+            mesh = new FXTransformFeedbackParticle(renderer.getContext(), this.varyings, capacity, threeMaterial, baseGeometry);
+            this.simulation = new FXTransformFeedbackSimulationHolder(renderer, kernel);
+        }
+        catch (error) {
+            // `mesh` can have already succeeded (real WebGL buffers/VAO-backing state allocated) when the
+            // simulation holder construction right after it is what actually throws - release those
+            // before re-throwing, or they leak for the GL context's lifetime. The caller (FXEmitter.
+            // fromArtifacts) decides what happens next - falling back to FXJSEmitterDriver.
+            mesh?.destroy();
+            throw error;
+        }
+        this.mesh = mesh;
+    }
+    get particleCount() {
+        return this.mesh.capacity;
+    }
+    get particleCapacity() {
+        return this.mesh.capacity;
+    }
+    // A fused transform-feedback program always has a spawn branch - assembleTransformFeedbackProgram
+    // (the editor's assembler) refuses to build one without it, so a constructed FXParticleKernelArtifact
+    // is this guarantee already checked, not something to re-derive here.
+    get canSpawn() {
+        return true;
+    }
+    spawn(count) {
+        // Cursor advances by `count`, wrapping at capacity - the buffer slots this claims may already
+        // be occupied by still-alive particles, which are simply overwritten (the scheme's cheapness is
+        // not checking occupancy at all). Accumulates into
+        // `gpuPendingSpawnCount` regardless of whether this call happens during a tick's own scheduling
+        // (a delayed burst/play firing) or entirely between ticks (an immediate `burst()` call from host
+        // code) - endTick() is the only place that range is ever consumed and reset (see its own doc
+        // comment for why beginTick() must NOT also reset it).
+        this.gpuSpawnCursor = (this.gpuSpawnCursor + count) % this.mesh.capacity;
+        this.gpuPendingSpawnCount += count;
+    }
+    beginTick() {
+        // No begin-of-tick bookkeeping needed: unlike the range/count fields (reset only once consumed,
+        // in endTick()), there is nothing here that must happen before this tick's scheduled bursts run.
+    }
+    endTick(deltaTime, transform) {
+        // Every particle slot is always processed - there is no CPU-visible live count to skip on;
+        // the render shader hides dead slots (FXArtifactMaterial.Internal.ts's
+        // projectFromModelPos degenerate-position injection).
+        this.simulation.tick(this.mesh, deltaTime, { start: this.gpuSpawnRangeStart, count: this.gpuPendingSpawnCount }, transform);
+        // Consumed - reset for the NEXT accumulation window, starting from wherever the cursor now sits.
+        // Must NOT happen in beginTick() instead: an immediate `burst()` call between two ticks (the
+        // ordinary way to spawn a one-shot effect, never touching pendingBursts/activePlays at all)
+        // already advances the cursor and this count the moment it is called - resetting at the START of
+        // the NEXT tick would silently discard that count before it was ever reported as a birth range,
+        // leaving those slots' data one full transform-feedback pass behind their real cursor claim.
+        this.gpuSpawnRangeStart = this.gpuSpawnCursor;
+        this.gpuPendingSpawnCount = 0;
+    }
+    sortByDistance() {
+        // No CPU-visible particle positions to sort, and no cheap way to sort GPU-resident data without
+        // a readback that would defeat the point of running on the GPU at all (an accepted loss, not a
+        // bug to work around). Never thrown - a host that sets sortCamera on a GPU
+        // emitter out of habit should not crash the world tick over it.
+        if (!this.warnedAboutSortCamera) {
+            this.warnedAboutSortCamera = true;
+            console.warn("FXEmitter: sortCamera has no effect on a GPU-driven (transform-feedback) emitter - " +
+                "back-to-front depth sorting is not supported for that backend.");
+        }
+    }
+    applyBindingValues(values) {
+        this.simulation.applyBindingValues(values);
+    }
+    reset() {
+        this.mesh.drop();
+        this.gpuSpawnCursor = 0;
+        // Must also clear any not-yet-consumed spawn accumulation (endTick() only resets it AFTER
+        // consuming it - see that method's own doc comment), or a burst() that ran earlier this same
+        // accumulation window would still spawn on the next tick despite reset() having just cancelled
+        // it - a stale range left over from before the cursor was zeroed here.
+        this.gpuSpawnRangeStart = 0;
+        this.gpuPendingSpawnCount = 0;
+    }
+    applyRenderArtifact(material, baseGeometry) {
+        // Recomputed exactly as the constructor does, against this driver's OWN kernel buffers (never
+        // a JS behavior artifact's attributeWrites) - a stale merge here would wrongly pass a real
+        // layout change.
+        const components = mergeAttributeWidths(this.behaviorAttributeWidths, material.attributeReads);
+        const nextVaryings = varyingsFromComponents(components);
+        if (!sameVaryings(this.varyings, nextVaryings)) {
+            throw new Error("FXGPUEmitterDriver.applyRenderArtifact: the new render artifact's attribute reads no " +
+                "longer match this emitter's allocated buffers - a full rebuild (fromArtifacts) is required");
+        }
+        // this.varyings is value-equal to nextVaryings (just proved by sameVaryings above) - built
+        // from nextVaryings so a future reader never has to re-derive that equivalence to trust this.
+        const threeMaterial = material.buildThreeMaterial(nextVaryings);
+        this.mesh.replaceMaterialAndBaseGeometry(threeMaterial, baseGeometry);
+    }
+    destroy() {
+        this.mesh.destroy();
+        this.simulation.destroy();
+    }
+}