sparcoon 0.9.0 → 0.9.2

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,181 @@
+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;
+        // 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 resetState() at the end of this method.
+        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);
+        });
+        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);
+        // A bound TRANSFORM_FEEDBACK_BUFFER base is otherwise still "active" for this binding point;
+        // release it rather than leave a stale reference around between ticks.
+        for (let index = 0; index < this.bufferNames.length; index += 1) {
+            gl.bindBufferBase(gl.TRANSFORM_FEEDBACK_BUFFER, index, null);
+        }
+        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();
+    }
+    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];
+            }
+        }
+    }
+    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,10 +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 {};

package/dist/instancedParticle/FXTransformFeedbackParticle.js

@@ -0,0 +1,169 @@
+import { GLBufferAttribute, InstancedBufferGeometry, Mesh } from "three";
+/**
+ * @internal A `GLBufferAttribute` additionally declared instanced (divisor 1, one value per drawn
+ * particle instead of per vertex). Confirmed by reading `WebGLBindingStates.js:432-444`: the
+ * per-instance vertex-attribute divisor is driven by `isInstancedBufferAttribute`/
+ * `meshPerAttribute` on the attribute object itself - a plain `GLBufferAttribute` never sets
+ * either, so without this every particle's state would be read as per-VERTEX (one value shared
+ * by the whole base primitive) instead of per-INSTANCE.
+ */
+class FXGLInstancedBufferAttribute extends GLBufferAttribute {
+    constructor() {
+        super(...arguments);
+        this.isInstancedBufferAttribute = true;
+        this.meshPerAttribute = 1;
+    }
+}
+/**
+ * `InstancedBufferGeometry.setAttribute` is typed only for `BufferAttribute`/
+ * `InterleavedBufferAttribute` - its `Attributes` generic defaults to `NormalBufferAttributes`,
+ * and `InstancedBufferGeometry` itself is declared non-generic, so the wider
+ * `NormalOrGLBufferAttributes` union (which DOES include `GLBufferAttribute`) is unreachable
+ * through it at the type level, even though `GLBufferAttribute` is a real, three.js-documented
+ * attribute type for exactly this GPGPU use case. Narrow, isolated escape hatch - matches the
+ * existing three.js-typing-gap precedent in `FXInstancedParticle.invalidateInstanceCap`.
+ */
+function setInstancedGLAttribute(geometry, name, attribute) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    geometry.setAttribute(name, attribute);
+}
+/**
+ * @internal GPU-resident sibling of `FXInstancedParticle`: same instanced-mesh shape (one base
+ * primitive drawn `capacity` times, one property buffer per declared varying), but every property
+ * buffer is a **ping-pong pair** of raw `WebGLBuffer`s the transform-feedback simulation holder
+ * writes directly - never a `Float32Array`-backed `InstancedBufferAttribute` three.js uploads
+ * itself (`FXInstancedParticle`'s own mechanism, untouched). Capacity is fixed at construction, no
+ * growth: this class is never resized, unlike `FXInstancedParticle.ensureCapacity` (a deferred
+ * future extension, not required for correctness today). Every
+ * particle slot is always drawn (`instanceCount` is always `capacity`) - the CPU never knows the
+ * true live count for a GPU-driven emitter, so dead slots are hidden by the render shader's own
+ * age/lifetime test, not by shrinking the draw range.
+ */
+export class FXTransformFeedbackParticle extends Mesh {
+    constructor(gl, varyings, capacity, material, baseGeometry) {
+        const instancedGeometry = new InstancedBufferGeometry();
+        // Copy the base geometry's position/uv/normal + index onto the instanced geometry, same as
+        // FXInstancedParticle - these stay real, CPU-readable BufferAttributes (the base primitive's
+        // own shape, not per-particle state), borrowed by reference, never disposed here.
+        const baseIndex = baseGeometry.getIndex();
+        if (baseIndex !== null) {
+            instancedGeometry.setIndex(baseIndex);
+        }
+        instancedGeometry.setAttribute("position", baseGeometry.getAttribute("position"));
+        instancedGeometry.setAttribute("uv", baseGeometry.getAttribute("uv"));
+        instancedGeometry.setAttribute("normal", baseGeometry.getAttribute("normal"));
+        super(instancedGeometry, material);
+        this.propertyBuffers = {};
+        // Per-buffer-name ping-pong pair; `currentIndex[name]` (0 or 1) is which half is the currently
+        // valid, renderable side - the other half is what the transform-feedback pass writes into this
+        // tick. Never read and written by name in the same pass (see `readBuffer`/`writeBuffer`).
+        this.rawBufferPairs = {};
+        this.currentIndex = {};
+        this.strides = {};
+        this.frustumCulled = false;
+        this.gl = gl;
+        this.instancedGeometry = instancedGeometry;
+        this.capacity = capacity;
+        this.instancedGeometry.instanceCount = capacity;
+        for (const name in varyings) {
+            const { bufferSize } = varyings[name];
+            this.strides[name] = bufferSize;
+            const bufferA = this.createSizedBuffer(bufferSize, capacity);
+            const bufferB = this.createSizedBuffer(bufferSize, capacity);
+            this.rawBufferPairs[name] = [bufferA, bufferB];
+            this.currentIndex[name] = 0;
+            const attribute = new FXGLInstancedBufferAttribute(bufferA, gl.FLOAT, bufferSize, 4, capacity);
+            setInstancedGLAttribute(this.instancedGeometry, `a_${name}`, attribute);
+            this.propertyBuffers[name] = attribute;
+        }
+    }
+    /** The buffer transform feedback should bind as its `in` (read) source this tick - last tick's
+     *  result, or uninitialized garbage on the very first tick (safe: the assembled program's spawn
+     *  branch always zero-defaults every buffer before the graph's own writes, so a freshly claimed
+     *  slot never actually reads it before being overwritten). */
+    readBuffer(name) {
+        return this.rawBufferPairs[name][this.currentIndex[name]];
+    }
+    /** The buffer transform feedback should bind as its transform-feedback (write) target this tick
+     *  - the stale half of the pair, about to become current once `swapBuffers` runs. */
+    writeBuffer(name) {
+        return this.rawBufferPairs[name][this.currentIndex[name] === 0 ? 1 : 0];
+    }
+    /**
+     * Call once per state buffer after a tick's transform-feedback pass has finished writing
+     * `writeBuffer(name)`: flips which half is current, and replaces the whole attribute object on
+     * the geometry - never just `.setBuffer()` + `.needsUpdate` on the existing one. Confirmed by
+     * reading `WebGLBindingStates.needsUpdate()` (`WebGLBindingStates.js:166-209`): it decides
+     * whether to rebind a cached VAO's vertex-attribute pointers purely by comparing attribute
+     * OBJECT identity, never `.version`/`.buffer` - reusing the same attribute instance across a
+     * swap would leave the render draw silently bound to the FIRST buffer forever (independently
+     * confirmed against three.js issue #22843, which describes the identical root cause). Mirrors
+     * `FXInstancedParticle.ensureCapacity`, which replaces the whole `InstancedBufferAttribute` for
+     * the same reason - there discovered as an array-reallocation side effect, here load-bearing on
+     * its own since nothing about capacity itself ever changes.
+     */
+    swapBuffers(name) {
+        const nextIndex = this.currentIndex[name] === 0 ? 1 : 0;
+        this.currentIndex[name] = nextIndex;
+        const stride = this.strides[name];
+        const attribute = new FXGLInstancedBufferAttribute(this.rawBufferPairs[name][nextIndex], this.gl.FLOAT, stride, 4, this.capacity);
+        setInstancedGLAttribute(this.instancedGeometry, `a_${name}`, attribute);
+        this.propertyBuffers[name] = attribute;
+    }
+    drop() {
+        // No live-particle count to reset for a GPU-driven emitter (instanceCount is always
+        // `capacity`) - a reset instead means "everything currently alive should read as dead", which
+        // is the simulation holder's job (it owns dt/age, not this buffer-holding class).
+    }
+    /**
+     * Swaps the mounted material and base geometry in place for a render-only structural edit -
+     * every ping-pong state buffer and `capacity` are left completely untouched, so playback never
+     * resets. 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, the currently mounted material, and every raw ping-pong
+    // buffer this instance owns - never the base geometry's borrowed position/uv/normal/index.
+    destroy() {
+        this.instancedGeometry.deleteAttribute("position");
+        this.instancedGeometry.deleteAttribute("uv");
+        this.instancedGeometry.deleteAttribute("normal");
+        this.instancedGeometry.setIndex(null);
+        this.instancedGeometry.dispose();
+        this.material?.dispose();
+        for (const name in this.rawBufferPairs) {
+            const [bufferA, bufferB] = this.rawBufferPairs[name];
+            this.gl.deleteBuffer(bufferA);
+            this.gl.deleteBuffer(bufferB);
+        }
+    }
+    createSizedBuffer(itemSize, count) {
+        const buffer = this.gl.createBuffer();
+        this.gl.bindBuffer(this.gl.ARRAY_BUFFER, buffer);
+        // Sized but uninitialized (garbage) - the spawn branch's zero-default (see the constructor
+        // doc) makes this safe for every buffer, core and attribute alike.
+        this.gl.bufferData(this.gl.ARRAY_BUFFER, itemSize * count * Float32Array.BYTES_PER_ELEMENT, this.gl.DYNAMIC_DRAW);
+        this.gl.bindBuffer(this.gl.ARRAY_BUFFER, null);
+        return buffer;
+    }
+}

package/dist/instancedParticle/primitiveGeometry.d.ts

@@ -1 +1,10 @@
-export {};
+import type { BufferGeometry } from "three";
+import type { FXGeometrySource } from "../artifact/FXArtifact.js";
+/**
+ * Resolves an artifact's {@link FXGeometrySource} to a concrete `BufferGeometry`: a
+ * built-in primitive is built fresh; a `"custom"` slot is looked up by name in `customGeometries`
+ * (app-supplied, e.g. from the exported module's `assets` or the editor's own live content
+ * library) - falling back to the `"plane"` primitive when the name is unbound, the same graceful
+ * degradation an unbound external texture slot gets.
+ */
+export declare function resolveGeometrySource(source: FXGeometrySource | undefined, customGeometries: Readonly<Record<string, BufferGeometry>>): BufferGeometry;

package/dist/instancedParticle/primitiveGeometry.js

@@ -16,7 +16,7 @@ export function buildPrimitiveGeometry(primitive) {
     }
 }
 /**
- * @internal Resolves an artifact's {@link FXGeometrySource} to a concrete `BufferGeometry`: a
+ * Resolves an artifact's {@link FXGeometrySource} to a concrete `BufferGeometry`: a
  * built-in primitive is built fresh; a `"custom"` slot is looked up by name in `customGeometries`
  * (app-supplied, e.g. from the exported module's `assets` or the editor's own live content
  * library) - falling back to the `"plane"` primitive when the name is unbound, the same graceful