sparcoon 0.9.0 → 0.9.2

package/README.md

@@ -13,7 +13,8 @@ ships to your app.
 ## Features
 
 - Instanced billboard and 3D-mesh particles in a single draw call.
-- Per-particle simulation from a precompiled kernel -- no `eval`, no codegen.
+- Per-particle simulation from a precompiled kernel, on the CPU or -- on a
+  WebGL2 renderer -- the GPU (transform feedback); no `eval`, no codegen either way.
 - Whole-project playback: an editor module subclasses `FXEffect`.
 - One `FXWorld.update` per frame drives every effect.
 - Optional depth sorting, shadows, and custom-geometry particles.
@@ -102,10 +103,14 @@ give it its own world. `world.dispose()` disposes every effect in it.
 
 The **Sparcoon Editor** compiles a node graph into a plain ES module exporting
 a render artifact (GLSL, uniforms, textures) and a behavior artifact (authored
-spawn/update functions). This runtime executes them -- your bundler compiles
-the authored functions like any other source, so nothing is evaluated at
-runtime. The editor/runtime boundary is a frozen ABI: two core per-particle
-buffers, `position` and `lifecycle` (`[age, lifetime]`).
+spawn/update functions), plus -- when the graph opts into GPU simulation -- a
+fused WebGL2 transform-feedback kernel. This runtime executes them: your bundler
+compiles the authored functions like any other source and the behavior runs on
+the CPU, or, when you pass a WebGL2 `renderer` in the effect options, the
+precompiled kernel runs the simulation on the GPU instead (falling back to the
+CPU behavior if GPU setup fails). Nothing is evaluated at runtime either way.
+The editor/runtime boundary is a frozen ABI: two core per-particle buffers,
+`position` and `lifecycle` (`[age, lifetime, id]`).
 
 ## Requirements
 
@@ -126,7 +131,7 @@ buffers, `position` and `lifecycle` (`[age, lifetime]`).
 - `FXWorld` -- the tick domain. `FXWorld.update(deltaTime)` per frame drives the
   default world; `new FXWorld()` is an isolated clock and pool.
 - Artifact contract types, the `FX_*` core-layout constants, CPU math helpers
-  (`fxMix`, `fxSnoise3`, ...), and `fxDataTexture`.
+  (`fxMix`, `fxNoise3`, ...), and `fxDataTexture`.
 
 ## License
 

package/dist/artifact/FXArtifact.d.ts

@@ -3,9 +3,11 @@ import type { FXGraphLambertMaterialOptions, FXGraphUnlitMaterialOptions } from
 /**
  * Frozen editor<->runtime boundary. The editor compiles a graph into a plain ESM module that
  * exports an {@link FXRenderArtifact} (GLSL + uniforms + textures) and an {@link FXBehaviorArtifact}
- * (authored spawn/update functions + bindings + buffer layout); the runtime only executes them.
- * Runtime-owned and exported; no code generation, no eval (the app's bundler compiles the authored
- * functions). Every value scrub must no-op on an unknown name so a name drift never corrupts values.
+ * (authored spawn/update functions + bindings + buffer layout), plus an optional
+ * {@link FXParticleKernelArtifact} (a fused GPU transform-feedback program) when the graph opts into
+ * GPU simulation; the runtime only executes them. Runtime-owned and exported; no code generation, no
+ * eval (the app's bundler compiles the authored JS functions, the editor precompiles the GLSL).
+ * Every value scrub must no-op on an unknown name so a name drift never corrupts values.
  */
 /** One state buffer: name + per-particle stride in floats. */
 export interface FXBufferLayout {
@@ -98,6 +100,23 @@ export interface FXRenderArtifact {
     /** Attributes the shader reads (`p_fx_<name>`); the emitter merges these with the sim's write set. */
     readonly attributeReads: readonly FXAttributeDecl[];
 }
+/**
+ * Which GLSL-family compiler tier produced a compiled {@link FXRenderArtifact}: `"baseline"` is
+ * the WebGL1/GLSL-ES-1.00-style compiler; `"standard"` is the WebGL2/GLSL-ES-3.00-only compiler
+ * (may use int/ivec and other standard-only capabilities a `"baseline"` graph cannot). Both
+ * compile to the same GLSL-text artifact shape and splice through the same material builders
+ * unchanged - Three already upgrades any material to `#version 300 es` (with full
+ * `attribute`/`varying`/`gl_FragColor` backward-compat macros) on an actual WebGL2 context,
+ * regardless of tier, so the runtime needs no declaration-style distinction between the two.
+ *
+ * Deliberately scoped to the GLSL family in its name: a structurally different family (the future
+ * advanced tier - a WGSL/WebGPU compiler, whose artifact has no vertex/fragment GLSL text at all)
+ * would need its own sibling type and its own field on the emitter/mesh spec, never a third member
+ * of this union or a third key in {@link FXRenderArtifactsByGLSLTier}.
+ */
+export type FXGLSLRenderTier = "baseline" | "standard";
+/** One emitter/mesh's render artifact, precompiled once per GLSL tier the editor supports. */
+export type FXRenderArtifactsByGLSLTier = Readonly<Record<FXGLSLRenderTier, FXRenderArtifact>>;
 /**
  * Behavior half of an emitted effect: authored spawn/update functions mutating the packed state
  * buffers, plus buffer layout and live bindings. Math helpers are inlined, so the artifact carries
@@ -118,3 +137,32 @@ export interface FXBehaviorArtifact {
     /** Advances all live particles `[0, count)`. */
     update(buffers: FXKernelBuffers, count: number, deltaTime: number, bindings: Record<string, FXValueSlot<number | Float32Array>>, emitter?: FXEmitterTransform): void;
 }
+/**
+ * Standard-tier (WebGL2, transform-feedback) behavior half of an emitted effect - a sibling of
+ * {@link FXBehaviorArtifact}, not a variant of it: a compiled GLSL program has no JS function
+ * shape to reuse. One fused GLSL ES 3.00 vertex-shader program handles both spawn and update in a
+ * single draw, branching per-invocation on the runtime-supplied spawn range (see
+ * `behaviorTransformFeedbackLayout.ts`'s uniform-name contract) - never two separate programs,
+ * since transform feedback cannot read and write the same buffer in one pass, and splitting the
+ * update range around a wrapping spawn cursor compounds badly with GPU-side buffer offsets.
+ *
+ * Optional per emitter/mesh spec: present only when the graph's spawn node had "Try GPU
+ * simulation" on and the graph actually compiled to GLSL; every emitter always has a matching
+ * {@link FXBehaviorArtifact} too (the mandatory JS fallback, including for the WebGL2->WebGL1
+ * emergency downgrade), so the runtime is never left with only this artifact and no JS twin.
+ */
+export interface FXParticleKernelArtifact {
+    readonly vertexSource: string;
+    readonly fragmentSource: string;
+    /** State buffers this program's `in`/`out` pairs cover, in declaration order - a buffer's index
+     *  here IS its `layout(location = N)` attribute index in {@link vertexSource}; the runtime binds
+     *  by that index, never by looking an attribute up by name. */
+    readonly buffers: readonly FXBufferLayout[];
+    /** Varying names for `gl.transformFeedbackVaryings`, one per {@link buffers} entry, same order. */
+    readonly transformFeedbackVaryings: readonly string[];
+    /** Live-tunable uniform values (graph-authored params only - the fixed contract uniforms in
+     *  `behaviorTransformFeedbackLayout.ts` are always declared and are the runtime's own
+     *  responsibility to set every tick, not part of this map). Float32Array is reserved for a
+     *  future sampler2D-backed (LUT) uniform; no standard-tier node produces one yet. */
+    readonly bindings: Record<string, FXValueSlot<number | Float32Array>>;
+}

package/dist/behaviorTransformFeedbackLayout.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Frozen transform-feedback (WebGL2, standard-tier behavior) uniform-name contract, shared by the
+ * editor's standard-tier behavior assembler (`FXKernelBuildStandard.Internal.ts`) and the
+ * runtime's transform-feedback driver. Every fused spawn+update program declares all of these
+ * uniforms unconditionally, regardless of whether a given graph actually reads them - fixed,
+ * literal names both sides import instead of independently deriving, the same reasoning as
+ * `coreLayout.ts`'s `PARTICLE_AGE`-style macros. Dependency-free (the editor imports this too), so
+ * keep it three-free and portable.
+ *
+ * Buffer-backed `in` attributes and `out` (transform-feedback) varyings are NOT listed here: a
+ * compiled program binds attributes by explicit `layout(location = N)` index (N = the buffer's
+ * position in the artifact's own `buffers` array), and transform-feedback varying names travel
+ * with the artifact itself (`FXParticleKernelArtifact.transformFeedbackVaryings`) - neither needs
+ * a shared naming scheme, only these truly fixed, graph-independent uniforms do.
+ */
+export declare const FX_TRANSFORM_FEEDBACK_SPAWN_RANGE_START_UNIFORM = "u_fxSpawnRangeStart";
+export declare const FX_TRANSFORM_FEEDBACK_SPAWN_RANGE_COUNT_UNIFORM = "u_fxSpawnRangeCount";
+export declare const FX_TRANSFORM_FEEDBACK_SPAWN_ID_BASE_UNIFORM = "u_fxSpawnIdBase";
+export declare const FX_TRANSFORM_FEEDBACK_CAPACITY_UNIFORM = "u_fxCapacity";
+export declare const FX_TRANSFORM_FEEDBACK_RAND_SEED_UNIFORM = "u_fxRandSeed";
+export declare const FX_TRANSFORM_FEEDBACK_DELTA_TIME_UNIFORM = "u_fxDt";
+export declare const FX_TRANSFORM_FEEDBACK_MODEL_MATRIX_UNIFORM = "u_fxModelMatrix";
+export declare const FX_TRANSFORM_FEEDBACK_OBJECT_VELOCITY_UNIFORM = "u_fxObjectVelocity";
+export declare const FX_TRANSFORM_FEEDBACK_OBJECT_ANGULAR_VELOCITY_UNIFORM = "u_fxObjectAngularVelocity";

package/dist/behaviorTransformFeedbackLayout.js

@@ -0,0 +1,24 @@
+/**
+ * Frozen transform-feedback (WebGL2, standard-tier behavior) uniform-name contract, shared by the
+ * editor's standard-tier behavior assembler (`FXKernelBuildStandard.Internal.ts`) and the
+ * runtime's transform-feedback driver. Every fused spawn+update program declares all of these
+ * uniforms unconditionally, regardless of whether a given graph actually reads them - fixed,
+ * literal names both sides import instead of independently deriving, the same reasoning as
+ * `coreLayout.ts`'s `PARTICLE_AGE`-style macros. Dependency-free (the editor imports this too), so
+ * keep it three-free and portable.
+ *
+ * Buffer-backed `in` attributes and `out` (transform-feedback) varyings are NOT listed here: a
+ * compiled program binds attributes by explicit `layout(location = N)` index (N = the buffer's
+ * position in the artifact's own `buffers` array), and transform-feedback varying names travel
+ * with the artifact itself (`FXParticleKernelArtifact.transformFeedbackVaryings`) - neither needs
+ * a shared naming scheme, only these truly fixed, graph-independent uniforms do.
+ */
+export const FX_TRANSFORM_FEEDBACK_SPAWN_RANGE_START_UNIFORM = "u_fxSpawnRangeStart";
+export const FX_TRANSFORM_FEEDBACK_SPAWN_RANGE_COUNT_UNIFORM = "u_fxSpawnRangeCount";
+export const FX_TRANSFORM_FEEDBACK_SPAWN_ID_BASE_UNIFORM = "u_fxSpawnIdBase";
+export const FX_TRANSFORM_FEEDBACK_CAPACITY_UNIFORM = "u_fxCapacity";
+export const FX_TRANSFORM_FEEDBACK_RAND_SEED_UNIFORM = "u_fxRandSeed";
+export const FX_TRANSFORM_FEEDBACK_DELTA_TIME_UNIFORM = "u_fxDt";
+export const FX_TRANSFORM_FEEDBACK_MODEL_MATRIX_UNIFORM = "u_fxModelMatrix";
+export const FX_TRANSFORM_FEEDBACK_OBJECT_VELOCITY_UNIFORM = "u_fxObjectVelocity";
+export const FX_TRANSFORM_FEEDBACK_OBJECT_ANGULAR_VELOCITY_UNIFORM = "u_fxObjectAngularVelocity";

package/dist/coreLayout.d.ts

@@ -1,22 +1,26 @@
 /**
  * Frozen per-particle ABI shared by the runtime loop and every editor-emitted module.
- * Two GPU-mirrored core buffers only: `position` (vec3) and `lifecycle` (vec2 [age, lifetime]);
+ * Two GPU-mirrored core buffers only: `position` (vec3) and `lifecycle` (vec3 [age, lifetime, id]);
  * a particle is dead once `age >= lifetime`. Everything else (velocity, scale, ...) is an ordinary
  * node-declared `a_fx_<name>` attribute, not core.
  *
- * Split into two buffers because a Three instanced attribute is at most a vec4 - a 5-float core
- * cannot be one attribute, whereas vec3 + vec2 are two clean varyings. Dependency-free (the editor's
+ * Split into two buffers because a Three instanced attribute is at most a vec4 - a 6-float core
+ * cannot be one attribute, whereas vec3 + vec3 are two clean varyings. Dependency-free (the editor's
  * module emitter imports this too), so keep it three-free and portable.
  */
 export declare const FX_CORE_POSITION = "position";
 export declare const FX_CORE_LIFECYCLE = "lifecycle";
 export declare const FX_CORE_POSITION_STRIDE = 3;
-export declare const FX_CORE_LIFECYCLE_STRIDE = 2;
+export declare const FX_CORE_LIFECYCLE_STRIDE = 3;
 export declare const FX_POSITION_X = 0;
 export declare const FX_POSITION_Y = 1;
 export declare const FX_POSITION_Z = 2;
 export declare const FX_AGE = 0;
 export declare const FX_LIFETIME = 1;
+export declare const FX_ID = 2;
 export declare const FX_CORE_POSITION_VARYING = "p_position";
 export declare const FX_CORE_LIFECYCLE_VARYING = "p_lifecycle";
-export declare const FX_CORE_PARTICLE_DEFINES = "\n  #define PARTICLE_POSITION_X p_position.x\n  #define PARTICLE_POSITION_Y p_position.y\n  #define PARTICLE_POSITION_Z p_position.z\n  #define PARTICLE_POSITION p_position\n\n  #define PARTICLE_AGE p_lifecycle.x\n  #define PARTICLE_LIFETIME p_lifecycle.y\n";
+export declare const ATTRIBUTE_BUFFER_PREFIX = "fx_";
+export declare function isCoreBufferName(bufferName: string): boolean;
+export declare function meshPropertyKeyFor(bufferName: string): string;
+export declare const FX_CORE_PARTICLE_DEFINES = "\n  #define PARTICLE_POSITION_X p_position.x\n  #define PARTICLE_POSITION_Y p_position.y\n  #define PARTICLE_POSITION_Z p_position.z\n  #define PARTICLE_POSITION p_position\n\n  #define PARTICLE_AGE p_lifecycle.x\n  #define PARTICLE_LIFETIME p_lifecycle.y\n  #define PARTICLE_ID p_lifecycle.z\n";

package/dist/coreLayout.js

@@ -1,24 +1,36 @@
 /**
  * Frozen per-particle ABI shared by the runtime loop and every editor-emitted module.
- * Two GPU-mirrored core buffers only: `position` (vec3) and `lifecycle` (vec2 [age, lifetime]);
+ * Two GPU-mirrored core buffers only: `position` (vec3) and `lifecycle` (vec3 [age, lifetime, id]);
  * a particle is dead once `age >= lifetime`. Everything else (velocity, scale, ...) is an ordinary
  * node-declared `a_fx_<name>` attribute, not core.
  *
- * Split into two buffers because a Three instanced attribute is at most a vec4 - a 5-float core
- * cannot be one attribute, whereas vec3 + vec2 are two clean varyings. Dependency-free (the editor's
+ * Split into two buffers because a Three instanced attribute is at most a vec4 - a 6-float core
+ * cannot be one attribute, whereas vec3 + vec3 are two clean varyings. Dependency-free (the editor's
  * module emitter imports this too), so keep it three-free and portable.
  */
 export const FX_CORE_POSITION = "position";
 export const FX_CORE_LIFECYCLE = "lifecycle";
 export const FX_CORE_POSITION_STRIDE = 3;
-export const FX_CORE_LIFECYCLE_STRIDE = 2;
+export const FX_CORE_LIFECYCLE_STRIDE = 3;
 export const FX_POSITION_X = 0;
 export const FX_POSITION_Y = 1;
 export const FX_POSITION_Z = 2;
 export const FX_AGE = 0;
 export const FX_LIFETIME = 1;
+export const FX_ID = 2;
 export const FX_CORE_POSITION_VARYING = "p_position";
 export const FX_CORE_LIFECYCLE_VARYING = "p_lifecycle";
+// A kernel-compiled buffer name (e.g. "velocity", as authored/compiled - always unprefixed) to its
+// mesh property-buffer key: unchanged for the two core buffers, `fx_<name>` for every attribute.
+// The one place this mapping is defined - every mesh/simulation-holder pairing (JS or GPU) must
+// go through this, not re-derive the prefix locally, or the two sides can silently drift apart.
+export const ATTRIBUTE_BUFFER_PREFIX = "fx_";
+export function isCoreBufferName(bufferName) {
+    return bufferName === FX_CORE_POSITION || bufferName === FX_CORE_LIFECYCLE;
+}
+export function meshPropertyKeyFor(bufferName) {
+    return isCoreBufferName(bufferName) ? bufferName : `${ATTRIBUTE_BUFFER_PREFIX}${bufferName}`;
+}
 // Stable macro names so emitted render GLSL reads PARTICLE_POSITION_X / PARTICLE_AGE etc. instead
 // of hardcoding the varying names this module owns.
 export const FX_CORE_PARTICLE_DEFINES = `
@@ -29,4 +41,5 @@ export const FX_CORE_PARTICLE_DEFINES = `
 
   #define PARTICLE_AGE ${FX_CORE_LIFECYCLE_VARYING}.x
   #define PARTICLE_LIFETIME ${FX_CORE_LIFECYCLE_VARYING}.y
+  #define PARTICLE_ID ${FX_CORE_LIFECYCLE_VARYING}.z
 `;

package/dist/editor/index.d.ts

@@ -0,0 +1,9 @@
+export { FXEmitter } from "../emitter/FXEmitter.js";
+export type { FXFromArtifactsOptions } from "../emitter/FXFromArtifactsOptions.js";
+export type { FXApplyRenderArtifactOptions } from "../emitter/FXApplyRenderArtifactOptions.js";
+export type { FXApplyValues, FXEmitterOptions, FXEmitterBurstOptions, FXEmitterPlayOptions, } from "../emitter/FXEmitter.Internal.js";
+export { FXMesh } from "../render/FXMesh.js";
+export type { FXFromMeshArtifactOptions } from "../render/FXMesh.js";
+export { FXMeshMaterial } from "../render/FXMeshMaterial.js";
+export { resolveGeometrySource } from "../instancedParticle/primitiveGeometry.js";
+export { frameOfTime, keyframeSegment, normalizeQuaternion, quaternionFromValue, sampleTrack, sampleTracks, sampleTransform, slerpQuaternion, timeOfFrame, vectorFromValue, } from "../effect/FXEffectSampling.Internal.js";

package/dist/editor/index.js

@@ -0,0 +1,17 @@
+// Editor-tooling surface: `import ... from "sparcoon/editor"`.
+//
+// UNSTABLE - no semver guarantees. These are the low-level building blocks the Sparcoon Editor's
+// live preview needs (rebuild a single emitter/mesh from freshly compiled artifacts on every graph
+// edit), plus the keyframe-sampling math the editor and runtime must share so a baked preview and
+// runtime playback never drift. Regular game/scene hosts use the main "sparcoon" entry
+// (FXEffect + FXWorld); they should not reach for anything here.
+export { FXEmitter } from "../emitter/FXEmitter.js";
+// Self-contained VFX mesh (the mesh twin of FXEmitter): build one from a render artifact and let
+// FXWorld.update drive it, including the object velocity/angular velocity a mesh render graph reads.
+export { FXMesh } from "../render/FXMesh.js";
+// Lower-level pieces FXMesh is built from - kept for tooling that assembles a mesh by hand.
+export { FXMeshMaterial } from "../render/FXMeshMaterial.js";
+export { resolveGeometrySource } from "../instancedParticle/primitiveGeometry.js";
+// Shared keyframe/transform sampling: the editor bakes keyframes and the runtime samples them, so
+// both sides must sample identically - a frozen contract, never a one-sided edit.
+export { frameOfTime, keyframeSegment, normalizeQuaternion, quaternionFromValue, sampleTrack, sampleTracks, sampleTransform, slerpQuaternion, timeOfFrame, vectorFromValue, } from "../effect/FXEffectSampling.Internal.js";

package/dist/effect/FXEffect.d.ts

@@ -18,6 +18,8 @@ export declare abstract class FXEffect extends Group {
     private readonly specification;
     private readonly world;
     private readonly emitters;
+    private readonly emitterRenders;
+    private readonly meshRenders;
     private readonly meshMaterials;
     private readonly meshes;
     private readonly meshMotionTrackers;

package/dist/effect/FXEffect.js

@@ -29,6 +29,10 @@ function applyTransform(object, transform, liveChannels) {
 function materializeValue(value) {
     return typeof value === "number" ? value : [...value];
 }
+/** Picks one emitter/mesh's compiled artifact by render target (see {@link FXEffectOptions.renderer}). */
+function resolveRenderArtifact(render, isWebGL2) {
+    return render[isWebGL2 ? "standard" : "baseline"];
+}
 // Duck-typed, not `instanceof`: the app's `three` and this package's peer-dep `three` can be two
 // separate module instances (e.g. hoisted differently across a workspace), which would make
 // `instanceof Texture`/`instanceof BufferGeometry` false for a perfectly good asset. Every `three`
@@ -115,6 +119,11 @@ export class FXEffect extends Group {
     constructor(specification, assets, options = {}) {
         super();
         this.emitters = [];
+        // The single artifact resolved (by render target) from each emitter/mesh spec's
+        // FXRenderArtifactsByGLSLTier - parallel to `emitters`/`meshes`, read by the parameter-drive path
+        // instead of re-resolving the spec's map on every call.
+        this.emitterRenders = [];
+        this.meshRenders = [];
         this.meshMaterials = [];
         this.meshes = [];
         // World-space velocity/angular-velocity tracker per mesh, parallel to `meshes`.
@@ -140,14 +149,22 @@ export class FXEffect extends Group {
         this.world = options.world ?? FXWorld.getDefault();
         applyTransform(this, specification.transform);
         const geometries = geometriesFromAssets(assets);
+        const isWebGL2 = options.renderer?.capabilities.isWebGL2 ?? false;
         for (const emitterSpec of specification.emitters) {
             const textures = texturesForSlots(emitterSpec.externalSlots, assets);
-            const emitter = FXEmitter.fromArtifacts(emitterSpec.render, emitterSpec.behavior, {
+            const render = resolveRenderArtifact(emitterSpec.render, isWebGL2);
+            const emitter = FXEmitter.fromArtifacts(render, emitterSpec.behavior, {
                 textures,
                 geometries,
                 expectedCapacity: emitterSpec.expectedCapacity,
                 castShadow: emitterSpec.castShadow ?? false,
                 receiveShadow: emitterSpec.receiveShadow ?? false,
+                // Only offered on an actual WebGL2 negotiation - the same `isWebGL2` signal already
+                // picking `render`'s "standard" tier above. FXEmitter itself decides whether GPU setup
+                // then actually succeeds, falling back to `emitterSpec.behavior` in place if not - this
+                // effect never needs to know which one ends up driving a given emitter.
+                gpuKernel: isWebGL2 ? emitterSpec.gpuBehavior : undefined,
+                renderer: options.renderer,
             }, this.world);
             if (options.camera !== undefined && emitterSpec.sortInterval > 0) {
                 emitter.sortCamera = options.camera;
@@ -157,11 +174,13 @@ export class FXEffect extends Group {
             this.add(emitter);
             this.emitterIndexByName.set(emitterSpec.name, this.emitters.length);
             this.emitters.push(emitter);
+            this.emitterRenders.push(render);
             this.emitterDriven.push(new Set());
         }
         for (const meshSpec of specification.meshes) {
             const textures = texturesForSlots(meshSpec.externalSlots, assets);
-            const material = new FXMeshMaterial(meshSpec.render, textures);
+            const render = resolveRenderArtifact(meshSpec.render, isWebGL2);
+            const material = new FXMeshMaterial(render, textures);
             const mesh = new Mesh(resolveGeometrySource(meshSpec.geometry, geometries), material.buildThreeMaterial());
             if (meshSpec.receiveShadow ?? false) {
                 mesh.receiveShadow = true;
@@ -174,6 +193,7 @@ export class FXEffect extends Group {
             this.add(mesh);
             this.meshIndexByName.set(meshSpec.name, this.meshes.length);
             this.meshes.push(mesh);
+            this.meshRenders.push(render);
             this.meshMaterials.push(material);
             this.meshMotionTrackers.push(new FXObjectMotionTracker());
             this.meshDriven.push(new Set());
@@ -283,7 +303,7 @@ export class FXEffect extends Group {
         const specification = this.specification.emitters[index];
         const uniforms = {};
         const bindings = {};
-        writeParameterSlots(specification.render, specification.behavior, parameter, materializeValue(value), uniforms, bindings);
+        writeParameterSlots(this.emitterRenders[index], specification.behavior, parameter, materializeValue(value), uniforms, bindings);
         if (Object.keys(uniforms).length > 0 || Object.keys(bindings).length > 0) {
             this.emitters[index].applyValues({ uniforms, bindings });
         }
@@ -297,10 +317,9 @@ export class FXEffect extends Group {
         if (index === undefined) {
             return;
         }
-        const specification = this.specification.meshes[index];
         const uniforms = {};
         const bindings = {};
-        writeParameterSlots(specification.render, NO_BEHAVIOR_BINDINGS, parameter, materializeValue(value), uniforms, bindings);
+        writeParameterSlots(this.meshRenders[index], NO_BEHAVIOR_BINDINGS, parameter, materializeValue(value), uniforms, bindings);
         if (Object.keys(uniforms).length > 0) {
             this.meshMaterials[index].applyUniformValues(uniforms);
         }
@@ -415,16 +434,17 @@ export class FXEffect extends Group {
     }
     driveEmitterValues(index, values) {
         const specification = this.specification.emitters[index];
+        const render = this.emitterRenders[index];
         const driven = this.emitterDriven[index];
         const uniforms = {};
         const bindings = {};
         for (const [name, value] of values) {
-            writeParameterSlots(specification.render, specification.behavior, name, value, uniforms, bindings);
+            writeParameterSlots(render, specification.behavior, name, value, uniforms, bindings);
             driven.add(name);
         }
         for (const name of [...driven]) {
             if (!values.has(name)) {
-                writeParameterBaseline(specification.render, specification.behavior, name, uniforms, bindings);
+                writeParameterBaseline(render, specification.behavior, name, uniforms, bindings);
                 driven.delete(name);
             }
         }
@@ -433,17 +453,17 @@ export class FXEffect extends Group {
         }
     }
     driveMeshValues(index, values) {
-        const specification = this.specification.meshes[index];
+        const render = this.meshRenders[index];
         const driven = this.meshDriven[index];
         const uniforms = {};
         const bindings = {};
         for (const [name, value] of values) {
-            writeParameterSlots(specification.render, NO_BEHAVIOR_BINDINGS, name, value, uniforms, bindings);
+            writeParameterSlots(render, NO_BEHAVIOR_BINDINGS, name, value, uniforms, bindings);
             driven.add(name);
         }
         for (const name of [...driven]) {
             if (!values.has(name)) {
-                writeParameterBaseline(specification.render, NO_BEHAVIOR_BINDINGS, name, uniforms, bindings);
+                writeParameterBaseline(render, NO_BEHAVIOR_BINDINGS, name, uniforms, bindings);
                 driven.delete(name);
             }
         }

package/dist/effect/FXEffectSpec.d.ts

@@ -1,5 +1,5 @@
-import type { Camera } from "three";
-import type { FXBehaviorArtifact, FXGeometrySource, FXRenderArtifact } from "../artifact/FXArtifact.js";
+import type { Camera, WebGLRenderer } from "three";
+import type { FXBehaviorArtifact, FXGeometrySource, FXParticleKernelArtifact, FXRenderArtifactsByGLSLTier } from "../artifact/FXArtifact.js";
 import type { FXWorld } from "../world/FXWorld.js";
 /**
  * Data shapes for {@link FXEffect}: a whole exported project (every emitter + VFX mesh, its
@@ -48,8 +48,19 @@ export type FXEffectEvent = {
 export interface FXEffectEmitterSpec {
     /** The editor-authored name, addressing this emitter through {@link FXEffect.getEmitter} etc. */
     readonly name: string;
-    readonly render: FXRenderArtifact;
+    readonly render: FXRenderArtifactsByGLSLTier;
     readonly behavior: FXBehaviorArtifact;
+    /**
+     * The standard-tier (WebGL2, transform-feedback) behavior artifact - present only when this
+     * emitter's spawn node had "Try GPU simulation" on and the graph compiled to GLSL. `behavior`
+     * above is always present regardless - the mandatory JS fallback, including for the
+     * WebGL2->WebGL1 emergency downgrade - so a spec is never left with only this field and no JS
+     * twin. {@link FXEffect} passes this to
+     * `FXEmitter.fromArtifacts` only when the live renderer actually negotiated WebGL2 (the same
+     * `isWebGL2` signal that already picks `render`'s "standard" tier); the runtime decides for
+     * itself whether GPU setup then actually succeeds, falling back to `behavior` in place if not.
+     */
+    readonly gpuBehavior?: FXParticleKernelArtifact;
     readonly expectedCapacity: number;
     readonly sortInterval: number;
     /** Casts a shape-aware shadow; omitted (treated as false) by pre-shadow exports. */
@@ -72,7 +83,7 @@ export interface FXEffectEmitterSpec {
 export interface FXEffectMeshSpec {
     /** The editor-authored name, addressing this mesh through {@link FXEffect.getMesh} etc. */
     readonly name: string;
-    readonly render: FXRenderArtifact;
+    readonly render: FXRenderArtifactsByGLSLTier;
     readonly geometry: FXGeometrySource;
     /** See {@link FXEffectEmitterSpec.castShadow}. */
     readonly castShadow?: boolean;
@@ -112,4 +123,10 @@ export interface FXEffectOptions {
      * own clock and particle pool (an independent time scale, or a group you tick separately).
      */
     readonly world?: FXWorld;
+    /**
+     * The renderer this effect will draw through: `renderer.capabilities.isWebGL2` picks each
+     * emitter/mesh's `"standard"` or `"baseline"` artifact (see {@link FXRenderArtifactsByGLSLTier}).
+     * Omit to get the `"baseline"` artifact unconditionally (the pre-split behavior).
+     */
+    readonly renderer?: WebGLRenderer;
 }

package/dist/emitter/FXApplyRenderArtifactOptions.d.ts

@@ -0,0 +1,15 @@
+import type { BufferGeometry, Texture } from "three";
+/**
+ * Options for {@link FXEmitter.applyRenderArtifact}: the render-only subset of
+ * {@link FXFromArtifactsOptions} - no `expectedCapacity`/`capacityStep`/`gpuKernel`/`renderer`,
+ * since none of those can change without a full {@link FXEmitter.fromArtifacts} rebuild. The app
+ * owns `textures`/`geometries`' lifecycle; the runtime never disposes them.
+ */
+export interface FXApplyRenderArtifactOptions {
+    readonly textures?: Record<string, Texture>;
+    readonly geometries?: Record<string, BufferGeometry>;
+    /** default false */
+    readonly receiveShadow?: boolean;
+    /** Casts a shape-aware shadow (a customDepthMaterial built from the new render artifact). default false */
+    readonly castShadow?: boolean;
+}

package/dist/emitter/FXApplyRenderArtifactOptions.js

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

package/dist/emitter/FXEmitter.d.ts

@@ -1,5 +1,9 @@
 import type { Camera } from "three";
 import { Object3D } from "three";
+import type { FXBehaviorArtifact, FXRenderArtifact } from "../artifact/FXArtifact.js";
+import type { FXApplyRenderArtifactOptions } from "./FXApplyRenderArtifactOptions.js";
+import type { FXFromArtifactsOptions } from "./FXFromArtifactsOptions.js";
+import { FXWorld } from "../world/FXWorld.js";
 import type { FXApplyValues, FXEmitterBurstOptions, FXEmitterPlayOptions } from "./FXEmitter.Internal.js";
 /**
  * Particle emitter - one instanced billboard/mesh draw call, per-particle state driven by a
@@ -7,6 +11,12 @@ import type { FXApplyValues, FXEmitterBurstOptions, FXEmitterPlayOptions } from
  * Three material. Built and ticked by {@link FXEffect} through an {@link FXWorld}. Not exported from
  * the package (the runtime path is running artifacts, not hand-building emitters); reached only as
  * the live handle returned by {@link FXEffect.getEmitter}.
+ *
+ * A thin facade over one {@link FXEmitterDriver} (JS or GPU - see `FXEmitterDriver.Internal.ts`),
+ * chosen once by {@link fromArtifacts} and never switched mid-playback. This class itself owns only
+ * what is genuinely backend-independent: play/burst/stop/prewarm scheduling, sort-fraction timing,
+ * object motion tracking, and the render material - the material itself CAN be replaced in place,
+ * by {@link applyRenderArtifact}, without touching the driver or its particle state.
  */
 export declare class FXEmitter extends Object3D {
     /** Camera for back-to-front depth sorting; `undefined` disables it. Distances are world-space, so any emitter/ancestor transform is handled correctly. */
@@ -14,10 +24,8 @@ export declare class FXEmitter extends Object3D {
     /** Fraction of frames sorting runs on (`1` = every frame, `0.1` = ~every 10th); defaults to `0.1`. */
     sortFraction: number;
     private readonly world;
-    private readonly mesh;
-    private readonly material;
-    private readonly simulation?;
-    private readonly collectedProperties;
+    private readonly driver;
+    private material;
     private nextHandler;
     private readonly pendingBursts;
     private readonly activePlays;
@@ -29,10 +37,20 @@ export declare class FXEmitter extends Object3D {
     private readonly motionScaleScratch;
     private readonly motionTracker;
     private destroyed;
-    private kernelBuffersCache?;
-    private kernelBuffersCacheVersion;
+    /** Exact live count for a JS-driven emitter; for a GPU-driven one, there is no CPU-visible live
+     *  count to report - `capacity` is the honest upper bound reported instead. */
     get particleCount(): number;
+    /** The buffer's current allocated size - grows over time for a JS-driven emitter, fixed at
+     *  construction for a GPU-driven one (no capacityStep growth path there). */
     get particleCapacity(): number;
+    private get mesh();
+    /**
+     * Builds an emitter into `world` from a precompiled effect - the low-level building block behind
+     * {@link FXEffect}. Exposed for editor tooling through the `sparcoon/editor` entry (live preview
+     * rebuilds a single emitter per graph edit); not part of the main package surface, where the
+     * runtime path is running whole projects through `FXEffect`.
+     */
+    static fromArtifacts(render: FXRenderArtifact, behavior: FXBehaviorArtifact, options?: FXFromArtifactsOptions, world?: FXWorld): FXEmitter;
     /** Unregisters, removes from the scene, disposes mesh and material. Idempotent. */
     destroy(): void;
     /**
@@ -55,7 +73,13 @@ export declare class FXEmitter extends Object3D {
      * @param stepDuration - Maximum step size in seconds. Defaults to `1/60`.
      */
     prewarm(duration: number, stepDuration?: number): void;
-    /** Kills all live particles and cancels all active plays and pending bursts. */
+    /**
+     * Kills all live particles and cancels all active plays and pending bursts. For a GPU-driven
+     * emitter this is a known-narrower reset (see the mesh's own `drop()` doc comment): there is no
+     * CPU-visible per-particle state to instantly zero, so already-alive particles keep aging out
+     * naturally rather than vanishing on this call's own frame - only the spawn cursor and pending
+     * schedule reset immediately.
+     */
     reset(): void;
     /**
      * Scrubs live parameter values into uniform/binding slots by name, picked up next frame - the
@@ -64,16 +88,21 @@ export declare class FXEmitter extends Object3D {
      */
     applyValues(values: FXApplyValues): void;
     /**
-     * Merged attribute set (name -> component count): union of the behavior's writes and the render's
-     * reads. Throws on a cross-artifact width disagreement rather than sizing a buffer wrong.
+     * Swaps only this emitter's render half in place - a new shader, geometry primitive/mesh, or
+     * shadow flags - leaving the behavior driver, particle buffers, instance count, and playback
+     * schedule completely untouched (unlike a structural edit that reaches {@link fromArtifacts},
+     * this never resets a running effect). The editor calls this instead of rebuilding whenever a
+     * graph edit only changed the render half.
+     *
+     * @throws If the new render artifact's attribute reads disagree with this emitter's already-
+     * allocated buffers (a genuine layout change - see {@link FXEmitterDriver.applyRenderArtifact}).
+     * This emitter is left exactly as it was before the call in that case; the caller must fall back
+     * to a fresh {@link fromArtifacts} instead, since only a new driver can safely resize buffers.
      */
-    private attributeComponents;
-    private buildCollectedProperties;
+    applyRenderArtifact(render: FXRenderArtifact, options?: FXApplyRenderArtifactOptions): void;
     private setSortFraction;
     private assertCanSpawn;
-    private kernelBuffers;
     private worldTransform;
-    private markBuffersNeedUpdate;
     private tick;
     private readonly onRendering;
     private spawnBurst;