sparcoon 0.9.1 → 0.9.3

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);
         }
@@ -353,20 +372,33 @@ export class FXEffect extends Group {
         const duration = this.specification.duration;
         let now = this.time + deltaSeconds;
         if (duration > 0 && now >= duration) {
-            // Loop wrap: finish this lap's tail, reset, then replay from the remainder.
+            // Loop wrap: finish this lap's tail from the lap's last pose, then run on into the next lap
+            // without clearing what is alive - a looping effect never pops at the seam. The pose jumps
+            // back to the start, which is no motion: every motion baseline is dropped, or the jump would
+            // read as a one-frame velocity spike.
+            this.poseAt(duration);
             this.fire(this.lastTime, duration);
             for (const emitter of this.emitters) {
-                emitter.stop();
-                emitter.reset();
+                emitter.loopTimeline();
+            }
+            for (const tracker of this.meshMotionTrackers) {
+                tracker.reset();
             }
             now = now % duration;
             this.lastTime = 0;
             this.lastFrame = -1;
         }
+        // Pose and values first, events second: a burst spawns from the emitter's pose and parameters
+        // at the moment it is called, so this frame's bursts must see this frame's pose - not the one
+        // the previous frame left behind.
+        this.poseAt(now);
         this.fire(this.lastTime, now);
         this.lastTime = now;
         this.time = now;
-        const frame = frameOfTime(now, this.specification.fps);
+    }
+    /** Poses every entity for the frame `time` falls in, unless it already is. */
+    poseAt(time) {
+        const frame = frameOfTime(time, this.specification.fps);
         if (frame !== this.lastFrame) {
             this.lastFrame = frame;
             this.driveFrame(timeOfFrame(frame, this.specification.fps));
@@ -415,16 +447,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 +466,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,6 +1,7 @@
 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";
@@ -10,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. */
@@ -17,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 artifactMaterial;
     private nextHandler;
     private readonly pendingBursts;
     private readonly activePlays;
@@ -32,10 +37,13 @@ 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
@@ -46,7 +54,10 @@ export declare class FXEmitter extends Object3D {
     /** Unregisters, removes from the scene, disposes mesh and material. Idempotent. */
     destroy(): void;
     /**
-     * Spawns `count` particles immediately, or after `options.delay`.
+     * Spawns `count` particles immediately, or after `options.delay`. An immediate burst seeds its
+     * particles from this emitter's pose and parameter values at the moment of the call, on either
+     * backend - so moving the emitter between two bursts of one frame spawns them in two places.
+     * A delayed burst spawns from the pose and values of the tick it expires on.
      * @returns Handler for {@link stop} to cancel a pending delayed burst.
      */
     burst(count: number, options?: Partial<FXEmitterBurstOptions>): number;
@@ -65,8 +76,22 @@ 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;
+    /**
+     * For a timeline that loops back to its start - {@link FXEffect}'s own, or a tool's that drives
+     * the emitter itself: cancels the active plays and pending bursts, as {@link stop} does, and
+     * forgets the motion baseline - the pose jumps from the lap's end to its start, which is no
+     * motion - but leaves live particles to finish their lives, so the loop runs on seamlessly.
+     * Unlike {@link reset}, which clears them.
+     */
+    loopTimeline(): void;
     /**
      * Scrubs live parameter values into uniform/binding slots by name, picked up next frame - the
      * runtime's value channel for a non-structural edit. Unknown name = safe no-op; never recompiles.
@@ -74,16 +99,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;