sparcoon 0.7.2 → 0.9.0

package/dist/emitter/FXEmitter.js

@@ -1,135 +1,191 @@
-import { Object3D, Vector3 } from 'three';
-import { FXInstancedParticle } from '../instancedParticle/FXInstancedParticle.js';
-import { resolveGLSLTypeInfo } from '../instancedParticle/shared.js';
-import { assertValidPositiveNumber, assertValidNonNegativeNumber } from '../miscellaneous/asserts.js';
-import { BUILTIN_OFFSET_AGE, BUILTIN_OFFSET_POSITION_X, BUILTIN_OFFSET_VELOCITY_X, BUILTIN_OFFSET_POSITION_Y, BUILTIN_OFFSET_VELOCITY_Y, BUILTIN_OFFSET_POSITION_Z, BUILTIN_OFFSET_VELOCITY_Z, BUILTIN_OFFSET_ROTATION, BUILTIN_OFFSET_TORQUE, BUILTIN_OFFSET_RANDOM_A, BUILTIN_OFFSET_RANDOM_B, BUILTIN_OFFSET_RANDOM_C } from '../miscellaneous/miscellaneous.js';
-import { EMITTERS, collectProperties, EMITTER_DEFAULT_EXPECTED_CAPACITY, EMITTER_DEFAULT_CAPACITY_STEP, EMITTER_DEFAULT_CAST_SHADOW, EMITTER_DEFAULT_RECEIVE_SHADOW, EMITTER_DEFAULT_SORT_FRACTION, EMITTER_DEFAULT_PREWARM_MIN_STEP_DURATION, EMITTER_DEFAULT_PREWARM_MAX_STEP_COUNT } from './FXEmitter.Internal.js';
-
+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 { 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 - add to a scene to make particles visible
- *
- * @remarks
- * Drives a pipeline of spawn modules (run once at particle birth) and behavior modules
- * (run every frame). Call {@link FXEmitter.onWillRender} each frame to tick the system.
+ * 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}.
  */
-class FXEmitter extends Object3D {
-    /**
-     * @param spawnSequence - Modules executed in order when particles are born
-     * @param behaviorSequence - Modules executed in order every frame for all live particles
-     * @param material - Particle material
-     * @param options - Emitter configuration
-     */
-    constructor(_private_spawnSequence, _private_behaviorSequence, material, options = {}) {
+export class FXEmitter extends Object3D {
+    /** @internal Use {@link FXEmitter.fromArtifacts}. */
+    constructor(material, simulation, options = {}, baseGeometry, world) {
         super();
-        this._private_spawnSequence = _private_spawnSequence;
-        this._private_behaviorSequence = _private_behaviorSequence;
-        this._private_nextHandler = 0;
-        this._private_pendingBursts = [];
-        this._private_activePlays = [];
-        this._private_sortingAccumulator = 0;
-        this._private_sortingCameraWorldPosition = new Vector3();
-        this._private_onRendering = (deltaTime) => {
-            this._private_tick(deltaTime);
-            if (this.sortCamera !== undefined && this._private_mesh.instanceCount > 0) {
-                this._private_sortingAccumulator += this.sortFraction;
-                if (this._private_sortingAccumulator >= 1) {
-                    this._private_sortingAccumulator -= 1;
-                    this.sortCamera.getWorldPosition(this._private_sortingCameraWorldPosition);
-                    this._private_mesh.sortByDistance(this._private_sortingCameraWorldPosition);
+        this.nextHandler = 0;
+        this.pendingBursts = [];
+        this.activePlays = [];
+        this.sortingAccumulator = 0;
+        this.sortingCameraWorldPosition = new Vector3();
+        // The emitter's `matrixWorld` as a column-major mat4, plus its world-space velocity/angular
+        // velocity, handed to the behavior kernel each spawn/update. Mutated in place - never
+        // reallocated per frame.
+        this.emitterTransform = {
+            worldMatrix: new Array(16).fill(0),
+            velocity: [0, 0, 0],
+            angularVelocity: [0, 0, 0],
+        };
+        // Reused decompose scratch (avoids a per-tick allocation); scale is discarded.
+        this.motionPositionScratch = new Vector3();
+        this.motionQuaternionScratch = new Quaternion();
+        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);
                 }
             }
         };
+        this.world = world;
         if (options.expectedCapacity !== undefined) {
-            assertValidPositiveNumber(options.expectedCapacity, "FXEmitter.constructor.options.expectedCapacity");
+            // Sizes the Float32Array buffers - a fractional length is a RangeError.
+            assertValidPositiveInteger(options.expectedCapacity, "FXEmitter.constructor.options.expectedCapacity");
         }
         if (options.capacityStep !== undefined) {
-            assertValidPositiveNumber(options.capacityStep, "FXEmitter.constructor.options.capacityStep");
+            assertValidPositiveInteger(options.capacityStep, "FXEmitter.constructor.options.capacityStep");
         }
-        if (options.sortFraction !== undefined) {
-            assertValidNonNegativeNumber(options.sortFraction, "FXEmitter.constructor.options.sortFraction");
+        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;
         }
-        const collectedProperties = {
-            builtin: resolveGLSLTypeInfo("Matrix4"),
-        };
-        collectProperties(collectedProperties, _private_spawnSequence, "FXEmitter.constructor.spawnSequence");
-        collectProperties(collectedProperties, _private_behaviorSequence, "FXEmitter.constructor.behaviorSequence");
-        material.prepare();
-        const threeMaterial = material.buildThreeMaterial(collectedProperties);
-        this._private_mesh = new FXInstancedParticle(collectedProperties, options.expectedCapacity ?? EMITTER_DEFAULT_EXPECTED_CAPACITY, options.capacityStep ?? EMITTER_DEFAULT_CAPACITY_STEP, threeMaterial);
+        // Pay for the second (depth) ShaderMaterial only when a cast shadow is actually requested.
+        // `castShadow`/`customDepthMaterial` are inherited Object3D members; `frustumCulled` is already
+        // 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._private_mesh.castShadow = true;
-            this._private_mesh.customDepthMaterial = material.buildDepthMaterial();
-            this._private_mesh.customDistanceMaterial = material.buildDistanceMaterial();
-        }
-        if (options.receiveShadow ?? EMITTER_DEFAULT_RECEIVE_SHADOW) {
-            this._private_mesh.receiveShadow = true;
+            this.mesh.castShadow = true;
+            this.mesh.customDepthMaterial = material.buildThreeDepthMaterial(this.collectedProperties);
         }
         this.sortCamera = options.sortCamera;
-        this.sortFraction = options.sortFraction ?? EMITTER_DEFAULT_SORT_FRACTION;
-        this._private_material = material;
-        this.add(this._private_mesh);
-        EMITTERS.push(this);
+        this.sortFraction = EMITTER_DEFAULT_SORT_FRACTION;
+        if (options.sortFraction !== undefined) {
+            this.setSortFraction(options.sortFraction, "FXEmitter.constructor.options.sortFraction");
+        }
+        this.assertCanSpawn("FXEmitter.constructor");
+        this.add(this.mesh);
+        this.world.registerEmitter(this);
     }
-    /** Number of currently alive particles */
     get particleCount() {
-        return this._private_mesh.instanceCount;
+        return this.mesh.instanceCount;
     }
-    /** Maximum number of particles that fit in the currently allocated buffers */
     get particleCapacity() {
-        return this._private_mesh.instanceCapacity;
+        return this.mesh.instanceCapacity;
+    }
+    /**
+     * @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.
+     */
+    static fromArtifacts(render, behavior, options = {}, world = FXWorld.getDefault()) {
+        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);
+    }
+    /**
+     * @internal Ticks this emitter one frame. Driven by {@link FXWorld.update}, which advances the
+     * shared clock once and passes it in as `elapsedTime`.
+     */
+    onWorldTick(deltaTime, elapsedTime) {
+        this.onRendering(deltaTime);
+        this.material.setElapsedTime(elapsedTime);
+        this.material.setDeltaTime(deltaTime);
+        // emitterTransform.velocity/angularVelocity are always length 3 (see its declaration) -
+        // computed once per tick in onRendering -> tick.
+        this.material.setObjectVelocity(this.emitterTransform.velocity);
+        this.material.setObjectAngularVelocity(this.emitterTransform.angularVelocity);
     }
-    /** Unregisters the emitter, removes it from the scene, and disposes modules and material */
+    /** Unregisters, removes from the scene, disposes mesh and material. Idempotent. */
     destroy() {
-        const index = EMITTERS.indexOf(this);
-        if (index !== -1) {
-            EMITTERS.splice(index, 1);
-        }
-        for (const module of this._private_spawnSequence) {
-            module.destroy?.();
-        }
-        for (const module of this._private_behaviorSequence) {
-            module.destroy?.();
+        if (this.destroyed) {
+            return;
         }
-        this._private_material.destroy();
-        this._private_mesh.material?.dispose();
-        this._private_mesh.customDepthMaterial?.dispose();
-        this._private_mesh.customDistanceMaterial?.dispose();
+        this.destroyed = true;
+        this.world.unregisterEmitter(this);
+        // Drop scheduled work and the buffer cache so nothing references the mesh'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.
+        this.material.destroy();
+        this.mesh.destroy();
         this.removeFromParent();
     }
     /**
-     * Spawns `count` particles immediately, or after a delay when `options.delay` is set
-     *
-     * @param count - Number of particles to spawn
-     * @param options - Burst options
-     * @returns Handler that can be passed to {@link stop} to cancel a pending delayed burst
+     * Spawns `count` particles immediately, or after `options.delay`.
+     * @returns Handler for {@link stop} to cancel a pending delayed burst.
      */
     burst(count, options = {}) {
-        assertValidPositiveNumber(count, "FXEmitter.burst.count");
-        const handler = this._private_nextHandler++;
+        // Whole particles only: a fractional count sets a fractional `instanceCount`.
+        assertValidPositiveInteger(count, "FXEmitter.burst.count");
+        this.assertCanSpawn("FXEmitter.burst");
+        if (this.destroyed) {
+            return DEAD_HANDLER;
+        }
+        const handler = this.nextHandler++;
         const delay = options.delay ?? 0;
         assertValidNonNegativeNumber(delay, "FXEmitter.burst.options.delay");
         if (delay <= 0) {
-            this._private_spawnBurst(count);
+            this.spawnBurst(count);
         }
         else {
-            this._private_pendingBursts.push({ handler, count, delay });
+            this.pendingBursts.push({ handler, count, delay });
         }
         return handler;
     }
     /**
-     * Starts continuous emission at the given rate
-     *
-     * @param rate - Particles per second
-     * @param options - Play options
-     * @returns Handler that can be passed to {@link stop} to cancel
+     * Starts continuous emission at `rate` particles/second.
+     * @returns Handler for {@link stop} to cancel.
      */
     play(rate, options = {}) {
         assertValidPositiveNumber(rate, "FXEmitter.play.rate");
         if (options.delay !== undefined) {
             assertValidNonNegativeNumber(options.delay, "FXEmitter.play.options.delay");
         }
-        const handler = this._private_nextHandler++;
-        this._private_activePlays.push({
+        this.assertCanSpawn("FXEmitter.play");
+        if (this.destroyed) {
+            return DEAD_HANDLER;
+        }
+        const handler = this.nextHandler++;
+        this.activePlays.push({
             handler,
             rate,
             duration: options.duration ?? Infinity,
@@ -140,155 +196,268 @@ class FXEmitter extends Object3D {
         return handler;
     }
     /**
-     * Stops an active play or pending burst by handler; stops all when called with no arguments
-     *
-     * @param handler - Handler returned by {@link play} or {@link burst}; omit to stop everything
-     * @returns `true` if anything was stopped
+     * Stops an active play or pending burst by handler; stops all when called with no arguments.
+     * @returns `true` if anything was stopped.
      */
     stop(handler) {
+        if (this.destroyed) {
+            return false;
+        }
         if (handler === undefined) {
-            const hadAnything = this._private_pendingBursts.length > 0 || this._private_activePlays.length > 0;
-            this._private_pendingBursts.length = 0;
-            this._private_activePlays.length = 0;
+            const hadAnything = this.pendingBursts.length > 0 || this.activePlays.length > 0;
+            this.pendingBursts.length = 0;
+            this.activePlays.length = 0;
             return hadAnything;
         }
-        const burstIndex = this._private_pendingBursts.findIndex((b) => b.handler === handler);
+        const burstIndex = this.pendingBursts.findIndex((b) => b.handler === handler);
         if (burstIndex !== -1) {
-            this._private_pendingBursts.splice(burstIndex, 1);
+            this.pendingBursts.splice(burstIndex, 1);
             return true;
         }
-        const playIndex = this._private_activePlays.findIndex((p) => p.handler === handler);
+        const playIndex = this.activePlays.findIndex((play) => play.handler === handler);
         if (playIndex !== -1) {
-            this._private_activePlays.splice(playIndex, 1);
+            this.activePlays.splice(playIndex, 1);
             return true;
         }
         return false;
     }
     /**
-     * Simulates the emitter forward in time to avoid a cold-start on frame 0
-     *
-     * @param duration - Total time to simulate in seconds
-     * @param stepDuration - Maximum simulation step size in seconds. Defaults to `1/60`
+     * Simulates forward in time to avoid a cold-start on frame 0.
+     * @param stepDuration - Maximum step size in seconds. Defaults to `1/60`.
      */
     prewarm(duration, stepDuration = EMITTER_DEFAULT_PREWARM_MIN_STEP_DURATION) {
         assertValidPositiveNumber(duration, "FXEmitter.prewarm.duration");
         assertValidPositiveNumber(stepDuration, "FXEmitter.prewarm.stepDuration");
+        if (this.destroyed) {
+            // Ticking a destroyed emitter would fire pending bursts and mutate disposed geometry.
+            return;
+        }
         const stepCount = Math.min(duration / Math.max(stepDuration, EMITTER_DEFAULT_PREWARM_MIN_STEP_DURATION), EMITTER_DEFAULT_PREWARM_MAX_STEP_COUNT);
         const step = duration / stepCount;
         let remaining = duration;
         while (remaining > 0) {
             const deltaTime = Math.min(remaining, step);
-            this._private_tick(deltaTime);
+            this.tick(deltaTime);
             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. */
     reset() {
-        this._private_pendingBursts.length = 0;
-        this._private_activePlays.length = 0;
-        this._private_mesh.drop();
+        if (this.destroyed) {
+            return;
+        }
+        this.pendingBursts.length = 0;
+        this.activePlays.length = 0;
+        this.mesh.drop();
+        // 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();
+    }
+    /**
+     * Scrubs live parameter values into uniform/binding slots by name, picked up next frame - the
+     * runtime's value channel for a non-structural edit. Unknown name = safe no-op; never recompiles.
+     * A structural edit is instead a fresh {@link fromArtifacts} (the editor decides which).
+     */
+    applyValues(values) {
+        if (this.destroyed) {
+            return;
+        }
+        if (values.uniforms !== undefined) {
+            this.material.applyUniformValues(values.uniforms);
+        }
+        if (values.bindings !== undefined) {
+            this.simulation?.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.
+     */
+    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);
+        }
+        for (const read of this.material.attributeReads) {
+            add(read.name, read.components);
+        }
+        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,
+            };
+        }
+        return properties;
+    }
+    setSortFraction(value, context) {
+        assertValidNonNegativeNumber(value, context);
+        // Clamp to [0, 1]: a value > 1 would grow `sortingAccumulator` without bound.
+        this.sortFraction = Math.min(value, 1);
+    }
+    // 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) {
+            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.
+    worldTransform() {
+        this.mesh.updateWorldMatrix(true, false);
+        const world = this.mesh.matrixWorld.elements;
+        const transform = this.emitterTransform;
+        for (let i = 0; i < 16; i += 1) {
+            transform.worldMatrix[i] = world[i];
+        }
+        return transform;
     }
-    _private_tick(deltaTime) {
-        // Age increment & cull dead particles
+    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
+        // worldTransform() several times this tick, and diffing per-call instead of per-tick would
+        // corrupt the value on a frame with more than one of those (each call would diff against a
+        // baseline the previous call already advanced).
+        this.mesh.updateWorldMatrix(true, false);
+        this.mesh.matrixWorld.decompose(this.motionPositionScratch, this.motionQuaternionScratch, this.motionScaleScratch);
+        const motion = this.motionTracker.sample({
+            position: [
+                this.motionPositionScratch.x,
+                this.motionPositionScratch.y,
+                this.motionPositionScratch.z,
+            ],
+            quaternion: [
+                this.motionQuaternionScratch.x,
+                this.motionQuaternionScratch.y,
+                this.motionQuaternionScratch.z,
+                this.motionQuaternionScratch.w,
+            ],
+        }, deltaTime);
+        this.emitterTransform.velocity[0] = motion.velocity[0];
+        this.emitterTransform.velocity[1] = motion.velocity[1];
+        this.emitterTransform.velocity[2] = motion.velocity[2];
+        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 { builtin } = this._private_mesh.propertyBuffers;
-            const { array, itemSize } = builtin;
-            for (let i = 0; i < this._private_mesh.instanceCount; i++) {
-                array[i * itemSize + BUILTIN_OFFSET_AGE] += deltaTime;
+            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;
             }
         }
-        this._private_mesh.removeDeadParticles();
-        // Pending bursts (delayed)
-        for (let i = this._private_pendingBursts.length - 1; i >= 0; i--) {
-            const pending = this._private_pendingBursts[i];
+        this.mesh.removeDeadParticles();
+        for (let i = this.pendingBursts.length - 1; i >= 0; i--) {
+            const pending = this.pendingBursts[i];
             pending.delay -= deltaTime;
             if (pending.delay <= 0) {
-                this._private_pendingBursts.splice(i, 1);
-                this._private_spawnBurst(pending.count);
+                this.pendingBursts.splice(i, 1);
+                this.spawnBurst(pending.count);
             }
         }
-        // Active plays
-        for (let i = this._private_activePlays.length - 1; i >= 0; i--) {
-            const play = this._private_activePlays[i];
+        for (let i = this.activePlays.length - 1; i >= 0; i--) {
+            const play = this.activePlays[i];
             let effectiveDeltaTime = deltaTime;
             if (play.delay > 0) {
                 play.delay -= deltaTime;
                 if (play.delay > 0) {
                     continue;
                 }
-                // Delay just expired - use the overshoot as effective dt this tick
+                // Delay just expired - use the overshoot as effective dt this tick.
                 effectiveDeltaTime = -play.delay;
                 play.delay = 0;
             }
+            const previousElapsed = play.elapsed;
             play.elapsed += effectiveDeltaTime;
-            if (play.elapsed >= play.duration) {
-                this._private_activePlays.splice(i, 1);
-                continue;
-            }
-            play.accumulator += play.rate * effectiveDeltaTime;
+            const expired = play.elapsed >= play.duration;
+            // On the final (partial) tick, emit only for the slice inside the play's duration, so the last
+            // fraction and the accumulator remainder still spawn instead of being dropped on removal.
+            const emitDeltaTime = expired
+                ? Math.max(0, play.duration - previousElapsed)
+                : effectiveDeltaTime;
+            play.accumulator += play.rate * emitDeltaTime;
             const particlesToSpawn = Math.floor(play.accumulator);
             if (particlesToSpawn > 0) {
-                this._private_spawnBurst(particlesToSpawn);
+                this.spawnBurst(particlesToSpawn);
                 play.accumulator -= particlesToSpawn;
             }
+            if (expired) {
+                this.activePlays.splice(i, 1);
+            }
         }
-        if (this._private_mesh.instanceCount === 0) {
+        if (this.mesh.instanceCount === 0) {
             return;
         }
-        {
-            const { propertyBuffers, instanceCount } = this._private_mesh;
-            for (const module of this._private_behaviorSequence) {
-                module.update(propertyBuffers, instanceCount, deltaTime);
-            }
-        }
-        {
-            const { builtin } = this._private_mesh.propertyBuffers;
-            const { array, itemSize } = builtin;
-            for (let i = 0; i < this._private_mesh.instanceCount; i++) {
-                const offset = i * itemSize;
-                // Position += velocity * dt
-                array[offset + BUILTIN_OFFSET_POSITION_X] +=
-                    array[offset + BUILTIN_OFFSET_VELOCITY_X] * deltaTime;
-                array[offset + BUILTIN_OFFSET_POSITION_Y] +=
-                    array[offset + BUILTIN_OFFSET_VELOCITY_Y] * deltaTime;
-                array[offset + BUILTIN_OFFSET_POSITION_Z] +=
-                    array[offset + BUILTIN_OFFSET_VELOCITY_Z] * deltaTime;
-                // Rotation += torque * dt
-                array[offset + BUILTIN_OFFSET_ROTATION] +=
-                    array[offset + BUILTIN_OFFSET_TORQUE] * deltaTime;
-            }
-            builtin.needsUpdate = true;
+        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;
     }
-    _private_spawnBurst(count) {
-        const instanceBegin = this._private_mesh.instanceCount;
-        this._private_mesh.createInstances(count);
-        const instanceEnd = this._private_mesh.instanceCount;
-        {
-            const { builtin } = this._private_mesh.propertyBuffers;
-            const { array, itemSize } = builtin;
-            for (let i = instanceBegin; i < instanceEnd; i++) {
-                const itemOffset = i * itemSize;
-                array[itemOffset + BUILTIN_OFFSET_RANDOM_A] = Math.random();
-                array[itemOffset + BUILTIN_OFFSET_RANDOM_B] = Math.random();
-                array[itemOffset + BUILTIN_OFFSET_RANDOM_C] = Math.random();
-            }
-            builtin.needsUpdate = true;
-        }
-        for (const spawnModule of this._private_spawnSequence) {
-            spawnModule.spawn(this._private_mesh.propertyBuffers, instanceBegin, instanceEnd);
+    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);
         }
     }
 }
-/**
- * Ticks all active emitters; call once per frame before rendering
- *
- * @param deltaTime - Elapsed time in seconds since the last frame
- */
-FXEmitter.onWillRender = (deltaTime) => {
-    for (const instance of EMITTERS) {
-        instance._private_onRendering(deltaTime);
-    }
-};
-
-export { FXEmitter };
+// Returned by post-destroy `burst`/`play` - never matches a scheduled handler.
+const DEAD_HANDLER = -1;