sparcoon 0.9.1 → 0.9.3

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).
+        // Spawns inside a tick (a delayed burst expiring, a play's rate accumulator) all share that
+        // tick's pose and parameters, so `gpuSpawnRangeStart`/`gpuPendingSpawnCount` gather them into
+        // one contiguous range the tick's own pass seeds. A spawn outside a tick - an immediate
+        // `burst()` from host code or from an effect's timeline - is seeded right away by a pass of its
+        // own instead (see spawn()), so the range is always empty between ticks.
+        this.gpuSpawnCursor = 0;
+        this.gpuSpawnRangeStart = 0;
+        this.gpuPendingSpawnCount = 0;
+        // Between beginTick() and endTick(): spawns join the tick's pass instead of running their own.
+        this.ticking = false;
+        // 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, transform) {
+        // 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).
+        const start = this.gpuSpawnCursor;
+        this.gpuSpawnCursor = (this.gpuSpawnCursor + count) % this.mesh.capacity;
+        if (this.ticking) {
+            this.gpuPendingSpawnCount += count;
+            return;
+        }
+        // Outside a tick, the emitter may be moved or re-parametrized before the next one (two
+        // bursts from two poses in one frame is an ordinary way to author an effect), so this spawn
+        // is seeded now, from the pose and bindings of this call. More than `capacity` at once
+        // overwrites the whole ring; the extra births would only overwrite each other.
+        this.simulation.spawn(this.mesh, { start, count: Math.min(count, this.mesh.capacity) }, transform);
+        this.gpuSpawnRangeStart = this.gpuSpawnCursor;
+    }
+    beginTick() {
+        this.ticking = true;
+    }
+    endTick(deltaTime, transform) {
+        this.ticking = false;
+        // 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 - the next tick's range starts wherever the cursor now sits.
+        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;
+        // Also drops a range gathered but not yet seeded, so nothing cancelled here spawns later.
+        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();
+    }
+}

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

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

package/dist/emitter/FXJSEmitterDriver.Internal.js

@@ -0,0 +1,133 @@
+import { FX_AGE, FX_CORE_LIFECYCLE, FX_CORE_POSITION, FX_ID, meshPropertyKeyFor, } from "../coreLayout.js";
+import { FXInstancedParticle } from "../instancedParticle/FXInstancedParticle.js";
+import { mergeAttributeWidths, sameVaryings, varyingsFromComponents, } from "./FXEmitterDriver.Internal.js";
+import { FXSimulationHolder } from "./FXSimulationHolder.js";
+/**
+ * @internal The CPU (JS) particle-simulation backend: a dense, compacting `FXInstancedParticle`
+ * mesh driven by a precompiled `FXBehaviorArtifact` through `FXSimulationHolder`. Self-sufficient
+ * from its own artifact - its varyings come from `behavior.attributeWrites` (+ the render
+ * artifact's `attributeReads`), never from a GPU kernel artifact.
+ */
+export class FXJSEmitterDriver {
+    constructor(behavior, material, capacity, capacityStep, baseGeometry) {
+        this.kernelBuffersCacheVersion = -1;
+        // Host-owned, monotonic per-emitter counter (like age, never touched by the compiled kernel/
+        // graph) - persists across reset() the same way FXTransformFeedbackSimulationHolder's
+        // randSeedCounter does, only restarting when this driver itself is rebuilt from artifacts.
+        this.nextParticleId = 0;
+        this.simulation = new FXSimulationHolder(behavior);
+        const components = mergeAttributeWidths(this.simulation.attributeWrites, material.attributeReads);
+        this.varyings = varyingsFromComponents(components);
+        const threeMaterial = material.buildThreeMaterial(this.varyings);
+        this.mesh = new FXInstancedParticle(this.varyings, capacity, capacityStep, threeMaterial, baseGeometry);
+    }
+    get particleCount() {
+        return this.mesh.instanceCount;
+    }
+    get particleCapacity() {
+        return this.mesh.instanceCapacity;
+    }
+    get canSpawn() {
+        return this.simulation.canSpawn;
+    }
+    spawn(count, transform) {
+        const instanceBegin = this.mesh.instanceCount;
+        this.mesh.createInstances(count);
+        const instanceEnd = this.mesh.instanceCount;
+        // Host-owned, like age: no write slot exists for id (the editor's FXParticleBehaviorTarget.ts
+        // scalarWriteSlots never lists it), so no graph can ever collide with this assignment.
+        const lifecycle = this.mesh.propertyBuffers[FX_CORE_LIFECYCLE];
+        const { array: lifecycleArray, itemSize: lifecycleItemSize } = lifecycle;
+        for (let i = instanceBegin; i < instanceEnd; i++) {
+            lifecycleArray[i * lifecycleItemSize + FX_ID] = this.nextParticleId++;
+        }
+        // Re-checked (defensive): no spawn function would leave the freshly zeroed rows born dead.
+        if (this.simulation.canSpawn) {
+            this.simulation.spawn(this.kernelBuffers(), instanceBegin, instanceEnd - instanceBegin, transform);
+            this.markBuffersNeedUpdate(this.simulation.spawnWrittenBuffers);
+        }
+    }
+    beginTick(deltaTime) {
+        // 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;
+        }
+        this.mesh.removeDeadParticles();
+    }
+    endTick(deltaTime, transform) {
+        if (this.mesh.instanceCount === 0) {
+            return;
+        }
+        // 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, transform);
+        this.markBuffersNeedUpdate(this.simulation.updateWrittenBuffers);
+        // Age (written in beginTick) must reach the GPU this frame; the update phase's buffers were
+        // flagged already.
+        this.mesh.propertyBuffers[FX_CORE_LIFECYCLE].needsUpdate = true;
+    }
+    sortByDistance(cameraWorldPosition) {
+        if (this.mesh.instanceCount === 0) {
+            return;
+        }
+        // Sort in world space to match the shader's `p_cameraDistance`, correct under any transform.
+        this.mesh.updateWorldMatrix(true, false);
+        this.mesh.sortByDistance(cameraWorldPosition, this.mesh.matrixWorld);
+    }
+    applyBindingValues(values) {
+        this.simulation.applyBindingValues(values);
+    }
+    reset() {
+        this.mesh.drop();
+    }
+    applyRenderArtifact(material, baseGeometry) {
+        // Recomputed exactly as the constructor does, against this driver's OWN behavior writes
+        // (never the other backend's) - a stale merge here would wrongly pass a real layout change.
+        const components = mergeAttributeWidths(this.simulation.attributeWrites, material.attributeReads);
+        const nextVaryings = varyingsFromComponents(components);
+        if (!sameVaryings(this.varyings, nextVaryings)) {
+            throw new Error("FXJSEmitterDriver.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.kernelBuffersCache = undefined;
+        this.mesh.destroy();
+    }
+    // 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[meshPropertyKeyFor(buffer.name)];
+            if (attribute !== undefined) {
+                buffers[buffer.name] = attribute.array;
+            }
+        }
+        this.kernelBuffersCache = buffers;
+        this.kernelBuffersCacheVersion = version;
+        return buffers;
+    }
+    markBuffersNeedUpdate(names) {
+        for (const name of names) {
+            const attribute = this.mesh.propertyBuffers[meshPropertyKeyFor(name)];
+            if (attribute !== undefined) {
+                attribute.needsUpdate = true;
+            }
+        }
+    }
+}

package/dist/emitter/FXSimulationHolder.js

@@ -1,7 +1,7 @@
-import { FX_CORE_LIFECYCLE, FX_CORE_POSITION } from "../coreLayout.js";
-const CORE_BUFFER_NAMES = new Set([FX_CORE_POSITION, FX_CORE_LIFECYCLE]);
+import { isCoreBufferName } from "../coreLayout.js";
 /**
- * @internal The runtime's behavior driver: holds a precompiled {@link FXBehaviorArtifact} and just
+ * @internal The runtime's JS (CPU) behavior driver - the GPU sibling is
+ * `FXTransformFeedbackSimulationHolder`. Holds a precompiled {@link FXBehaviorArtifact} and just
  * calls its `spawn`/`update` each tick (no graph, compiler, or `new Function`). The artifact's
  * `bindings` record is passed through on every call, so a value scrub is read next tick.
  */
@@ -11,7 +11,7 @@ export class FXSimulationHolder {
     }
     /** Declared buffers minus the fixed core `position`/`lifecycle` - one per user attribute. */
     get attributeBuffers() {
-        return this.artifact.buffers.filter((buffer) => !CORE_BUFFER_NAMES.has(buffer.name));
+        return this.artifact.buffers.filter((buffer) => !isCoreBufferName(buffer.name));
     }
     get attributeWrites() {
         return this.artifact.attributeWrites;
@@ -32,7 +32,9 @@ export class FXSimulationHolder {
     update(buffers, count, deltaTime, emitter) {
         this.artifact.update(buffers, count, deltaTime, this.artifact.bindings, emitter);
     }
-    /** Behavior half of {@link FXEmitter.applyValues}: mutate each named slot in place; unknown name = no-op. */
+    /** Behavior half of {@link FXEmitter.applyValues}: mutate each named slot in place; unknown name
+     *  = no-op. Mirrored by `FXTransformFeedbackSimulationHolder.applyBindingValues` for the GPU
+     *  tier - `FXEmitter.applyValues` scrubs both, since either backend may be the active one. */
     applyBindingValues(values) {
         for (const name in values) {
             if (name in this.artifact.bindings) {

package/dist/emitter/FXTransformFeedbackSimulationHolder.d.ts

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

package/dist/emitter/FXTransformFeedbackSimulationHolder.js

@@ -0,0 +1,249 @@
+import { meshPropertyKeyFor } from "../coreLayout.js";
+import { FX_TRANSFORM_FEEDBACK_CAPACITY_UNIFORM, FX_TRANSFORM_FEEDBACK_DELTA_TIME_UNIFORM, FX_TRANSFORM_FEEDBACK_MODEL_MATRIX_UNIFORM, FX_TRANSFORM_FEEDBACK_OBJECT_ANGULAR_VELOCITY_UNIFORM, FX_TRANSFORM_FEEDBACK_OBJECT_VELOCITY_UNIFORM, FX_TRANSFORM_FEEDBACK_RAND_SEED_UNIFORM, FX_TRANSFORM_FEEDBACK_SPAWN_ID_BASE_UNIFORM, FX_TRANSFORM_FEEDBACK_SPAWN_RANGE_COUNT_UNIFORM, FX_TRANSFORM_FEEDBACK_SPAWN_RANGE_START_UNIFORM, } from "../behaviorTransformFeedbackLayout.js";
+/**
+ * @internal The GPU sibling of `FXSimulationHolder`: holds a precompiled {@link FXParticleKernelArtifact}
+ * (one fused GLSL program covering both spawn and update) and drives it via raw WebGL2 transform
+ * feedback each tick. Bypasses three.js's `Material`/
+ * `WebGLProgram` machinery entirely - three has no transform-feedback support at all - the same
+ * way the render side never touches it either.
+ */
+export class FXTransformFeedbackSimulationHolder {
+    constructor(renderer, artifact) {
+        this.renderer = renderer;
+        this.artifact = artifact;
+        this.uniformLocations = {};
+        // A fresh, monotonic seed every tick - decorrelates `rand()` draws across ticks (and, crucially,
+        // across a buffer slot's successive rebirths under the cursor/overwrite scheme - see the `rand`
+        // registry entry's own doc comment in the editor's core/ir/FXFunctions.Internal.ts for why this
+        // matters). Wraparound is harmless: it only ever feeds a hash's bit-mixing, never arithmetic
+        // that needs exact precision.
+        this.randSeedCounter = 0;
+        // Running total of particles ever spawned by this emitter - the base a newborn's id offsets
+        // from this tick's relative spawn index. Never reset (no reset() exists on this class, only
+        // destroy()): a stop/replay must not reissue ids already handed out, same reasoning as
+        // randSeedCounter above.
+        this.spawnIdBase = 0;
+        // Every emitter driven by this class already required the live render tier to be "standard"
+        // (a real WebGL2 context) before this class is ever constructed (FXEmitter.fromArtifacts's
+        // driver-selection rule) - the cast reflects an already-established precondition, not a new
+        // capability check.
+        const gl = this.renderer.getContext();
+        this.gl = gl;
+        // `artifact.buffers[].name` is the raw, unprefixed kernel-compiled name (e.g. "velocity") -
+        // `mesh.readBuffer`/`writeBuffer`/`swapBuffers` key by the mesh's own property-buffer key
+        // instead (`fx_velocity`, matching `FXGPUEmitterDriver`'s own `varyings`), so every name must go
+        // through the same mapping the JS-driven path also uses (`meshPropertyKeyFor`) before reaching
+        // the mesh - the two core buffers pass through unchanged either way, which is why this only
+        // actually mattered for attribute-buffer emitters, not the position/lifetime-only fixtures this
+        // class's own tests use.
+        this.bufferNames = artifact.buffers.map((buffer) => meshPropertyKeyFor(buffer.name));
+        this.strides = artifact.buffers.map((buffer) => buffer.stride);
+        const vertexShader = compileShader(gl, gl.VERTEX_SHADER, artifact.vertexSource);
+        const fragmentShader = compileShader(gl, gl.FRAGMENT_SHADER, artifact.fragmentSource);
+        const program = gl.createProgram();
+        gl.attachShader(program, vertexShader);
+        gl.attachShader(program, fragmentShader);
+        // Must be called before linking (WebGL2 spec) - SEPARATE_ATTRIBS matches this class's one
+        // dedicated WebGLBuffer per state buffer (never one interleaved buffer for all of them).
+        gl.transformFeedbackVaryings(program, [...artifact.transformFeedbackVaryings], gl.SEPARATE_ATTRIBS);
+        gl.linkProgram(program);
+        // Shaders are safe to delete once linked - GL keeps them alive by refcount until the program
+        // itself is deleted, regardless of link success.
+        gl.deleteShader(vertexShader);
+        gl.deleteShader(fragmentShader);
+        if (gl.getProgramParameter(program, gl.LINK_STATUS) !== true) {
+            const info = gl.getProgramInfoLog(program);
+            gl.deleteProgram(program);
+            throw new Error(`FXTransformFeedbackSimulationHolder: program failed to link: ${info ?? ""}`);
+        }
+        this.program = program;
+        for (const name of FIXED_UNIFORM_NAMES) {
+            this.uniformLocations[name] = gl.getUniformLocation(program, name);
+        }
+        for (const name of Object.keys(artifact.bindings)) {
+            this.uniformLocations[name] = gl.getUniformLocation(program, name);
+        }
+        // A dedicated VAO for this simulation pass only - never one three.js's own WebGLBindingStates
+        // manages, so raw attribute setup here can never corrupt a mesh's cached vertex state. This
+        // is exactly the raw gl.bindVertexArray() call whose effect on three's VAO cache `tick()`'s
+        // closing `resetState()` call exists to correct (see that call site's own doc comment).
+        this.vao = gl.createVertexArray();
+    }
+    /**
+     * Runs one transform-feedback pass: reads `mesh`'s current buffers, writes the fused spawn+
+     * update program's result into the other half of each ping-pong pair, then swaps. `spawnRange`
+     * is this tick's birth range under the buffer's cursor/overwrite scheme - `count === 0` is a
+     * valid, ordinary "no births this tick" case, not skipped specially.
+     */
+    tick(mesh, deltaTime, spawnRange, emitter) {
+        const gl = this.gl;
+        this.randSeedCounter += 1;
+        this.bindProgramAndInputs(mesh);
+        this.bufferNames.forEach((name, index) => {
+            gl.bindBufferBase(gl.TRANSFORM_FEEDBACK_BUFFER, index, mesh.writeBuffer(name));
+        });
+        this.setUniforms(deltaTime, spawnRange, emitter, mesh.capacity);
+        gl.enable(gl.RASTERIZER_DISCARD);
+        gl.beginTransformFeedback(gl.POINTS);
+        gl.drawArrays(gl.POINTS, 0, mesh.capacity);
+        gl.endTransformFeedback();
+        gl.disable(gl.RASTERIZER_DISCARD);
+        this.releaseFeedbackBuffers();
+        for (const name of this.bufferNames) {
+            mesh.swapBuffers(name);
+        }
+        // Consumed - advance past every id this tick's spawn range just claimed.
+        this.spawnIdBase += spawnRange.count;
+        // Our raw gl.bindVertexArray() call above is invisible to three's own VAO-identity cache
+        // (WebGLBindingStates has no scoped, public way to invalidate just this mesh's entry) -
+        // resetState() is the only public lever, so it runs every tick. Per-emitter for now, not
+        // batched across every GPU-driven emitter into one call per frame - a real, deferred
+        // optimization, not required for correctness.
+        this.renderer.resetState();
+    }
+    /**
+     * Seeds the slots of `spawnRange` right now, from `emitter` and the current binding values, and
+     * touches no other slot: the spawn half of {@link tick}, run on its own. Lets every `burst()`
+     * outside the emitter's tick spawn from the pose and parameters of the moment it was called,
+     * instead of sharing one pass - and so one pose - with everything else spawned that frame.
+     *
+     * Transform feedback cannot write the buffer it reads, so the seeded range is drawn into the
+     * write half of each pair (`drawArrays(first, count)`: `gl_VertexID` is the slot index, which
+     * makes every drawn vertex a birth under the kernel's own range test) and then copied into the
+     * read half - the side the renderer draws and the next {@link tick} reads. No swap: every slot
+     * outside the range keeps its state untouched. A range that wraps past the end of the ring is
+     * drawn as two segments. `spawnRange.count` must not exceed the mesh's capacity.
+     */
+    spawn(mesh, spawnRange, emitter) {
+        if (spawnRange.count <= 0) {
+            return;
+        }
+        const gl = this.gl;
+        this.randSeedCounter += 1;
+        const capacity = mesh.capacity;
+        const head = Math.min(spawnRange.count, capacity - spawnRange.start);
+        const segments = head < spawnRange.count
+            ? [
+                [spawnRange.start, head],
+                [0, spawnRange.count - head],
+            ]
+            : [[spawnRange.start, spawnRange.count]];
+        this.bindProgramAndInputs(mesh);
+        // dt 0: the spawn branch has no use for it, and nothing else runs in this pass.
+        this.setUniforms(0, spawnRange, emitter, capacity);
+        gl.enable(gl.RASTERIZER_DISCARD);
+        for (const [first, count] of segments) {
+            this.bufferNames.forEach((name, index) => {
+                const bytesPerSlot = this.strides[index] * Float32Array.BYTES_PER_ELEMENT;
+                gl.bindBufferRange(gl.TRANSFORM_FEEDBACK_BUFFER, index, mesh.writeBuffer(name), first * bytesPerSlot, count * bytesPerSlot);
+            });
+            gl.beginTransformFeedback(gl.POINTS);
+            gl.drawArrays(gl.POINTS, first, count);
+            gl.endTransformFeedback();
+        }
+        gl.disable(gl.RASTERIZER_DISCARD);
+        // Released before the copy: a buffer still bound for transform feedback cannot be a copy
+        // source.
+        this.releaseFeedbackBuffers();
+        this.bufferNames.forEach((name, index) => {
+            const bytesPerSlot = this.strides[index] * Float32Array.BYTES_PER_ELEMENT;
+            gl.bindBuffer(gl.COPY_READ_BUFFER, mesh.writeBuffer(name));
+            gl.bindBuffer(gl.COPY_WRITE_BUFFER, mesh.readBuffer(name));
+            for (const [first, count] of segments) {
+                gl.copyBufferSubData(gl.COPY_READ_BUFFER, gl.COPY_WRITE_BUFFER, first * bytesPerSlot, first * bytesPerSlot, count * bytesPerSlot);
+            }
+        });
+        gl.bindBuffer(gl.COPY_READ_BUFFER, null);
+        gl.bindBuffer(gl.COPY_WRITE_BUFFER, null);
+        this.spawnIdBase += spawnRange.count;
+        // Same reason as in tick(): the raw VAO bind is invisible to three's caches.
+        this.renderer.resetState();
+    }
+    destroy() {
+        this.gl.deleteProgram(this.program);
+        this.gl.deleteVertexArray(this.vao);
+    }
+    /** GPU-tier mirror of `FXSimulationHolder.applyBindingValues`: mutate each named uniform's live
+     *  value in place; unknown name = no-op. `FXEmitter.applyValues` calls both mirrors, since
+     *  either backend may be the active one. */
+    applyBindingValues(values) {
+        for (const name in values) {
+            if (name in this.artifact.bindings) {
+                this.artifact.bindings[name].value = values[name];
+            }
+        }
+    }
+    /** Binds the program and wires every state buffer's read half as its vertex input. */
+    bindProgramAndInputs(mesh) {
+        const gl = this.gl;
+        // Routed through the renderer's own cache-aware setter (not raw gl.useProgram()) so three's
+        // `WebGLState.currentProgram` cache stays truthful - its own next draw then correctly detects
+        // the mismatch and re-binds, with no reset needed for this half of the state-hygiene problem.
+        // The other half (the VAO-identity cache) has no such setter - see the raw
+        // gl.bindVertexArray() call below and the resetState() that ends every pass.
+        this.renderer.state.useProgram(this.program);
+        gl.bindVertexArray(this.vao);
+        this.bufferNames.forEach((name, index) => {
+            gl.bindBuffer(gl.ARRAY_BUFFER, mesh.readBuffer(name));
+            gl.vertexAttribPointer(index, this.strides[index], gl.FLOAT, false, 0, 0);
+            gl.enableVertexAttribArray(index);
+        });
+    }
+    /**
+     * Unbinds every transform-feedback binding point. A bound base stays "active" for its point
+     * otherwise; released rather than left as a stale reference between passes.
+     */
+    releaseFeedbackBuffers() {
+        for (let index = 0; index < this.bufferNames.length; index += 1) {
+            this.gl.bindBufferBase(this.gl.TRANSFORM_FEEDBACK_BUFFER, index, null);
+        }
+    }
+    setUniforms(deltaTime, spawnRange, emitter, capacity) {
+        const gl = this.gl;
+        gl.uniform1i(this.uniformLocations[FX_TRANSFORM_FEEDBACK_RAND_SEED_UNIFORM], this.randSeedCounter);
+        gl.uniform1i(this.uniformLocations[FX_TRANSFORM_FEEDBACK_SPAWN_RANGE_START_UNIFORM], spawnRange.start);
+        gl.uniform1i(this.uniformLocations[FX_TRANSFORM_FEEDBACK_SPAWN_RANGE_COUNT_UNIFORM], spawnRange.count);
+        gl.uniform1i(this.uniformLocations[FX_TRANSFORM_FEEDBACK_SPAWN_ID_BASE_UNIFORM], this.spawnIdBase);
+        gl.uniform1i(this.uniformLocations[FX_TRANSFORM_FEEDBACK_CAPACITY_UNIFORM], capacity);
+        gl.uniform1f(this.uniformLocations[FX_TRANSFORM_FEEDBACK_DELTA_TIME_UNIFORM], deltaTime);
+        gl.uniformMatrix4fv(this.uniformLocations[FX_TRANSFORM_FEEDBACK_MODEL_MATRIX_UNIFORM], false, [
+            ...emitter.worldMatrix,
+        ]);
+        gl.uniform3fv(this.uniformLocations[FX_TRANSFORM_FEEDBACK_OBJECT_VELOCITY_UNIFORM], [
+            ...emitter.velocity,
+        ]);
+        gl.uniform3fv(this.uniformLocations[FX_TRANSFORM_FEEDBACK_OBJECT_ANGULAR_VELOCITY_UNIFORM], [
+            ...emitter.angularVelocity,
+        ]);
+        for (const [name, slot] of Object.entries(this.artifact.bindings)) {
+            // Float32Array-valued (sampler2D/LUT) bindings are reserved for a future node - see
+            // FXParticleKernelArtifact.bindings's own doc comment - never produced by any node today.
+            gl.uniform1f(this.uniformLocations[name], slot.value);
+        }
+    }
+}
+const FIXED_UNIFORM_NAMES = [
+    FX_TRANSFORM_FEEDBACK_RAND_SEED_UNIFORM,
+    FX_TRANSFORM_FEEDBACK_SPAWN_RANGE_START_UNIFORM,
+    FX_TRANSFORM_FEEDBACK_SPAWN_RANGE_COUNT_UNIFORM,
+    FX_TRANSFORM_FEEDBACK_SPAWN_ID_BASE_UNIFORM,
+    FX_TRANSFORM_FEEDBACK_CAPACITY_UNIFORM,
+    FX_TRANSFORM_FEEDBACK_DELTA_TIME_UNIFORM,
+    FX_TRANSFORM_FEEDBACK_MODEL_MATRIX_UNIFORM,
+    FX_TRANSFORM_FEEDBACK_OBJECT_VELOCITY_UNIFORM,
+    FX_TRANSFORM_FEEDBACK_OBJECT_ANGULAR_VELOCITY_UNIFORM,
+];
+function compileShader(gl, type, source) {
+    const shader = gl.createShader(type);
+    if (shader === null) {
+        throw new Error("FXTransformFeedbackSimulationHolder: gl.createShader() failed");
+    }
+    gl.shaderSource(shader, source);
+    gl.compileShader(shader);
+    if (gl.getShaderParameter(shader, gl.COMPILE_STATUS) !== true) {
+        const info = gl.getShaderInfoLog(shader);
+        gl.deleteShader(shader);
+        throw new Error(`FXTransformFeedbackSimulationHolder: shader failed to compile: ${info ?? ""}`);
+    }
+    return shader;
+}

package/dist/index.d.ts

@@ -1,11 +1,12 @@
-export type { FXAttributeDecl, FXBehaviorArtifact, FXBufferLayout, FXGeometrySource, FXKernelBuffers, FXRenderArtifact, FXShaderStageSource, FXUniformInit, FXValueSlot, } from "./artifact/FXArtifact.js";
-export { FX_AGE, FX_CORE_LIFECYCLE, FX_CORE_LIFECYCLE_STRIDE, FX_CORE_LIFECYCLE_VARYING, FX_CORE_PARTICLE_DEFINES, FX_CORE_POSITION, FX_CORE_POSITION_STRIDE, FX_CORE_POSITION_VARYING, FX_LIFETIME, FX_POSITION_X, FX_POSITION_Y, FX_POSITION_Z, } from "./coreLayout.js";
+export type { FXAttributeDecl, FXBehaviorArtifact, FXBufferLayout, FXGeometrySource, FXKernelBuffers, FXParticleKernelArtifact, FXRenderArtifact, FXShaderStageSource, FXUniformInit, FXValueSlot, } from "./artifact/FXArtifact.js";
+export { FX_AGE, FX_CORE_LIFECYCLE, FX_CORE_LIFECYCLE_STRIDE, FX_CORE_LIFECYCLE_VARYING, FX_CORE_PARTICLE_DEFINES, FX_CORE_POSITION, FX_CORE_POSITION_STRIDE, FX_CORE_POSITION_VARYING, FX_ID, FX_LIFETIME, FX_POSITION_X, FX_POSITION_Y, FX_POSITION_Z, } from "./coreLayout.js";
+export { FX_TRANSFORM_FEEDBACK_CAPACITY_UNIFORM, FX_TRANSFORM_FEEDBACK_DELTA_TIME_UNIFORM, FX_TRANSFORM_FEEDBACK_MODEL_MATRIX_UNIFORM, FX_TRANSFORM_FEEDBACK_OBJECT_ANGULAR_VELOCITY_UNIFORM, FX_TRANSFORM_FEEDBACK_OBJECT_VELOCITY_UNIFORM, FX_TRANSFORM_FEEDBACK_RAND_SEED_UNIFORM, FX_TRANSFORM_FEEDBACK_SPAWN_ID_BASE_UNIFORM, FX_TRANSFORM_FEEDBACK_SPAWN_RANGE_COUNT_UNIFORM, FX_TRANSFORM_FEEDBACK_SPAWN_RANGE_START_UNIFORM, } from "./behaviorTransformFeedbackLayout.js";
 export type { FXGraphLambertMaterialOptions, FXGraphUnlitMaterialOptions, FXRenderMode, } from "./render/FXMaterialOptions.js";
 export type { FXGeometryPrimitive } from "./artifact/FXArtifact.js";
 export { FXEffect } from "./effect/FXEffect.js";
 export type { FXEffectOptions, FXEffectSpec } from "./effect/FXEffectSpec.js";
 export type { FXEmitter } from "./emitter/FXEmitter.js";
 export { FXWorld } from "./world/FXWorld.js";
-export { fxFbm, fxFract, fxHash, fxMix, fxMod, fxSampleLut, fxSmoothstep, fxSnoise2, fxSnoise3, fxValueNoise, } from "./miscellaneous/fxMath.js";
+export { fxFbm, fxFbm3, fxFract, fxMix, fxMod, fxNoise1, fxNoise2, fxNoise3, fxSampleLut, fxSmoothstep, } from "./miscellaneous/fxMath.js";
 export { fxDataTexture } from "./miscellaneous/texture/fxDataTexture.js";
 export type { FXDataTextureOptions } from "./miscellaneous/texture/fxDataTexture.js";

package/dist/index.js

@@ -2,12 +2,13 @@
 // FXWorld, and is driven by a single FXWorld.update per frame - plus the runtime-owned types the
 // editor imports (artifact contracts and the core layout). No graph, compiler, validator, or live
 // protocol lives here.
-export { FX_AGE, FX_CORE_LIFECYCLE, FX_CORE_LIFECYCLE_STRIDE, FX_CORE_LIFECYCLE_VARYING, FX_CORE_PARTICLE_DEFINES, FX_CORE_POSITION, FX_CORE_POSITION_STRIDE, FX_CORE_POSITION_VARYING, FX_LIFETIME, FX_POSITION_X, FX_POSITION_Y, FX_POSITION_Z, } from "./coreLayout.js";
+export { FX_AGE, FX_CORE_LIFECYCLE, FX_CORE_LIFECYCLE_STRIDE, FX_CORE_LIFECYCLE_VARYING, FX_CORE_PARTICLE_DEFINES, FX_CORE_POSITION, FX_CORE_POSITION_STRIDE, FX_CORE_POSITION_VARYING, FX_ID, FX_LIFETIME, FX_POSITION_X, FX_POSITION_Y, FX_POSITION_Z, } from "./coreLayout.js";
+export { FX_TRANSFORM_FEEDBACK_CAPACITY_UNIFORM, FX_TRANSFORM_FEEDBACK_DELTA_TIME_UNIFORM, FX_TRANSFORM_FEEDBACK_MODEL_MATRIX_UNIFORM, FX_TRANSFORM_FEEDBACK_OBJECT_ANGULAR_VELOCITY_UNIFORM, FX_TRANSFORM_FEEDBACK_OBJECT_VELOCITY_UNIFORM, FX_TRANSFORM_FEEDBACK_RAND_SEED_UNIFORM, FX_TRANSFORM_FEEDBACK_SPAWN_ID_BASE_UNIFORM, FX_TRANSFORM_FEEDBACK_SPAWN_RANGE_COUNT_UNIFORM, FX_TRANSFORM_FEEDBACK_SPAWN_RANGE_START_UNIFORM, } from "./behaviorTransformFeedbackLayout.js";
 // Whole-project playback: the generic runtime behind every editor-emitted project module (base
 // class + scene specification). An emitted module supplies only its `FXEffectSpec` data and a thin subclass.
 export { FXEffect } from "./effect/FXEffect.js";
 // The tick domain: an effect joins one on construction; a single FXWorld.update per frame drives
 // every effect's timeline and the shared particle pool.
 export { FXWorld } from "./world/FXWorld.js";
-export { fxFbm, fxFract, fxHash, fxMix, fxMod, fxSampleLut, fxSmoothstep, fxSnoise2, fxSnoise3, fxValueNoise, } from "./miscellaneous/fxMath.js";
+export { fxFbm, fxFbm3, fxFract, fxMix, fxMod, fxNoise1, fxNoise2, fxNoise3, fxSampleLut, fxSmoothstep, } from "./miscellaneous/fxMath.js";
 export { fxDataTexture } from "./miscellaneous/texture/fxDataTexture.js";

package/dist/instancedParticle/FXInstancedParticle.js

@@ -68,7 +68,7 @@ export class FXInstancedParticle extends Mesh {
         this.instancedGeometry.instanceCount += count;
     }
     removeDeadParticles() {
-        // Cull against core `lifecycle` (vec2 [age, lifetime]); alive while `age < lifetime`. Rides the
+        // Cull against core `lifecycle` (vec3 [age, lifetime, id]); alive while `age < lifetime`. Rides the
         // same copy-down as every other property buffer.
         const lifecycleBuffer = this.propertyBuffers[FX_CORE_LIFECYCLE];
         if (lifecycleBuffer === undefined) {
@@ -183,6 +183,33 @@ export class FXInstancedParticle extends Mesh {
     drop() {
         this.instancedGeometry.instanceCount = 0;
     }
+    /**
+     * Swaps the mounted material and base geometry in place for a render-only structural edit -
+     * every per-particle buffer in {@link propertyBuffers} and the current instance count are left
+     * completely untouched, so live particles never reset. Never called when the varyings shape
+     * itself changed (the driver's own `applyRenderArtifact` guards that) - only the constructor
+     * path handles a real buffer-layout change.
+     */
+    replaceMaterialAndBaseGeometry(material, baseGeometry) {
+        // Detach the previous base attributes first, same as destroy()'s dance: they were borrowed by
+        // reference from a caller-owned geometry (possibly shared with other live consumers), so they
+        // must never be disposed here.
+        this.instancedGeometry.deleteAttribute("position");
+        this.instancedGeometry.deleteAttribute("uv");
+        this.instancedGeometry.deleteAttribute("normal");
+        this.instancedGeometry.setIndex(null);
+        const baseIndex = baseGeometry.getIndex();
+        if (baseIndex !== null) {
+            this.instancedGeometry.setIndex(baseIndex);
+        }
+        this.instancedGeometry.setAttribute("position", baseGeometry.getAttribute("position"));
+        this.instancedGeometry.setAttribute("uv", baseGeometry.getAttribute("uv"));
+        this.instancedGeometry.setAttribute("normal", baseGeometry.getAttribute("normal"));
+        // The mounted material IS disposable here (unlike the base geometry attributes above) - it was
+        // built exclusively for this mesh, never shared.
+        this.material?.dispose();
+        this.material = material;
+    }
     // Disposes the instanced geometry and the currently mounted material - not the constructor one,
     // which a live material hot-swap may have replaced and disposed.
     destroy() {

package/dist/instancedParticle/FXTransformFeedbackParticle.d.ts

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