sparcoon 0.9.2 → 0.9.3

package/README.md

@@ -1,138 +1,233 @@
-# Sparcoon
+# <img src="https://raw.githubusercontent.com/jango-git/sparcoon/experimental/assets/logo.svg" width="30" height="30" alt="" align="top" /> Sparcoon
 
-Three.js runtime for VFX authored in the Sparcoon Editor.
+A three.js runtime that plays visual effects authored in the
+[Sparcoon Editor](https://github.com/jango-git/sparcoon-editor). The editor compiles a node graph
+into a plain ES module of precompiled artifacts, and this package executes them: instanced particle
+rendering in one draw call plus a small timeline player. No graph, no compiler and no `eval` in your
+build.
 
-`sparcoon` plays back particle effects designed in the Sparcoon Editor: the
-editor compiles a node graph into a plain ES module of precompiled artifacts,
-and this thin runtime loads and runs it -- instanced-particle rendering in one
-draw call plus a small timeline player. No graph, compiler, or live protocol
-ships to your app.
+**[Open the editor](https://jango-git.github.io/sparcoon-editor/)** -
+[Editor source](https://github.com/jango-git/sparcoon-editor) -
+[npm](https://www.npmjs.com/package/sparcoon/v/0.9.3)
 
-> Editor: link coming soon.
+> **Pre-release.** The artifact format is not frozen yet - breaking changes are possible before the
+> first stable release. The package is published under the `experimental` tag: npm's `latest` holds
+> an older release that the current editor does not work with.
 
-## Features
+## Who this is for
 
-- Instanced billboard and 3D-mesh particles in a single draw call.
-- 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.
-- Tree-shakeable ESM with full TypeScript types.
+Someone sent you a `.ts` file exported from the editor and you need to play it in your three.js
+scene. This package is everything you have to add for that.
+
+What is worth knowing before you install:
+
+- **No code generation.** The exported module is ready GLSL plus ordinary JavaScript functions that
+  your bundler compiles like any other source. Neither `eval` nor `new Function` is called anywhere,
+  so the effect passes where runtime code generation is forbidden by policy.
+- **No dependencies.** The only peer dependency is `three`.
+- **One draw call per emitter.** Billboards and mesh particles are drawn instanced.
+- **Two GLSL tiers in every artifact.** Standard (WebGL2) and Baseline (WebGL1-compatible); the
+  runtime picks by the capabilities of the renderer you pass in.
+- **Optional GPU simulation** through transform feedback, with an automatic fallback to the
+  JavaScript kernel.
+- **Tree-shakeable ESM with full types**, unbundled and unminified: your bundler processes the
+  package like any other source, exactly the way three.js is consumed.
 
 ## Install
 
 ```sh
-npm install sparcoon three
+npm install sparcoon@experimental three
 ```
 
-`three` (>= 0.157) is a peer dependency.
+`three` is a peer dependency; the supported range is `>=0.157 <0.180`.
 
 ## Quick start
 
-An editor project exports an `FXEffect` subclass plus a typed map of the
-textures it needs. Construct it (it joins the default world automatically), add
-it to your scene, and call `FXWorld.update(deltaTime)` once per frame.
+A module from the editor exports a named `FXEffect` subclass and a typed interface for its assets.
+The runtime does not load assets: you prepare the textures and geometries and pass them to the
+constructor.
 
 ```ts
 import { TextureLoader } from "three";
 import { FXWorld } from "sparcoon";
-import { VFXDemo0 } from "./effects/VFXDemo_0"; // emitted by the editor
+import { MyEffect, type MyEffectAssets } from "./effects/MyEffect"; // emitted by the editor
 
 const loader = new TextureLoader();
-const assets = {
-  heart: loader.load("heart.png"),
-  fire: loader.load("fire.png"),
+const assets: MyEffectAssets = {
+  spark: loader.load("spark.png"),
 };
-const effect = new VFXDemo0(assets);
+
+// renderer picks the artifact tier (WebGL2 -> Standard) and enables GPU simulation.
+// camera is needed by emitters that were given a sort interval in the editor.
+const effect = new MyEffect(assets, { renderer, camera });
 
 scene.add(effect); // FXEffect is a THREE.Group
 effect.play();
 
-function frame(deltaTime: number): void {
-  FXWorld.update(deltaTime); // advances every effect's timeline and its particles
+function frame(deltaSeconds: number): void {
+  FXWorld.update(deltaSeconds); // advances the timeline and particles of every effect
   renderer.render(scene, camera);
 }
 ```
 
-The effect is an `Object3D` -- position, rotate, and scale it like any other.
-Call `effect.dispose()` to remove it, free its GPU resources, and unsubscribe it
-from the world.
+Straight after the constructor the effect sits on frame zero, in the state the artist authored.
+`play()` restarts the timeline from the top; `stop()` halts playback, clears live particles and
+returns the effect to frame zero. The timeline loops, and seamlessly: particles still alive at the
+end of a lap finish their lives in the next one.
+
+Without `renderer` the effect takes the Baseline tier unconditionally and runs on the JavaScript
+kernel. That is a working mode if you have no renderer at the point of construction.
 
-### Live parameters
+`effect.dispose()` unsubscribes the effect from its world, destroys its emitters and frees mesh
+resources. The textures and geometries you passed in are left alone: you own their lifecycle.
 
-Channels the editor marked "live" are driven from your code, not the timeline:
+## Where the module comes from
+
+Effects are built in the [Sparcoon Editor](https://jango-git.github.io/sparcoon-editor/): a
+browser-based node editor with a timeline and a three.js viewport. Each emitter there owns two
+graphs - behavior (per-particle simulation) and render (its material) - and exporting a project puts
+everything into one self-contained TypeScript module. You drop it into your source tree and import
+it, as in the example above.
+
+Transform channels and timeline values can be marked by the artist as excluded from the export: the
+timeline does not drive those, your code supplies the values.
+
+## Driving it from code
 
 ```ts
-effect.setEmitterParam("Hearts", "spawnRate", 64);
-effect.setMeshParam("Mesh", "glow", [1, 0.4, 0.1]);
+effect.setEmitterParam("Sparks", "intensity", 0.7);
+effect.setMeshParam("Shockwave", "glow", [1, 0.4, 0.1]);
 
-effect.getEmitter("Hearts"); // the underlying emitter (Object3D)
-effect.getMesh("Mesh"); // the underlying THREE.Mesh
+effect.getEmitter("Sparks")?.position.set(0, 1, 0);
+effect.getMesh("Shockwave")?.rotateY(Math.PI);
 ```
 
-### Many effects, and separate worlds
+In the module the editor emitted, both setters and both getters are typed against the names the
+project actually declares, so a typo is caught at compile time. An unknown parameter name is always a
+safe no-op: a name drift never corrupts the runtime's data.
 
-Every effect joins the default world on construction, so any number of them are
-driven by the same single `FXWorld.update(deltaTime)` -- there is nothing extra
-to wire up per effect.
+`getEmitter` returns a live `FXEmitter` (an `Object3D`), which gives you direct control over emission
+outside the timeline:
 
-A world is a tick and clock domain (not a scene graph). Create your own
-`FXWorld` when you want an independent clock -- an isolated time scale, or a
-group you pause on its own -- and pass it to the effect:
+```ts
+const sparks = effect.getEmitter("Sparks");
+if (sparks) {
+  sparks.burst(64); // one-off release, optionally delayed; returns a handle for stop()
+  sparks.play(120); // continuous emission in particles per second; also returns a handle
+  sparks.stop(); // with no argument, cancels everything scheduled on this emitter
+  sparks.prewarm(2); // simulate 2 seconds forward so playback does not start from an empty screen
+
+  sparks.sortCamera = camera; // depth sorting; undefined turns it off
+  sparks.sortFraction = 0.1; // fraction of frames that re-sort (the default)
+}
+```
+
+An immediate `burst()` spawns from the emitter's pose and parameter values at the moment of the
+call, on the GPU path too - so moving the emitter between two bursts of one frame spawns them in two
+places.
+
+For diagnostics there are `particleCount` and `particleCapacity`. A GPU-driven emitter has no exact
+live count, so `particleCount` reports an honest upper bound - the buffer's current capacity.
+
+## Multiple effects and worlds
+
+A world is a tick and clock domain, not a scene graph. Every effect subscribes to a world on
+construction, so a single `FXWorld.update(deltaSeconds)` per frame drives them all.
 
 ```ts
 import { FXWorld } from "sparcoon";
 
 const slowmo = new FXWorld();
-const boss = new VFXDemo0(assets, { world: slowmo });
-scene.add(boss); // still added to your scene yourself
+const boss = new MyEffect(assets, { renderer, world: slowmo });
+scene.add(boss); // you still add the object to your scene yourself
 
-function frame(deltaTime: number): void {
-  FXWorld.update(deltaTime); // the default world
-  slowmo.update(deltaTime * 0.3); // its own, slower clock
+function frame(deltaSeconds: number): void {
+  FXWorld.update(deltaSeconds); // the default world
+  slowmo.update(deltaSeconds * 0.3); // its own, slower clock
   renderer.render(scene, camera);
 }
 ```
 
-Within one world every effect shares the clock and one delta per frame, so
-`effect.stop()` clears rather than freezes -- to freeze one effect on its own,
-give it its own world. `world.dispose()` disposes every effect in it.
+Within one world every effect shares the clock and one delta per frame, so `effect.stop()` clears the
+effect rather than freezing it. To freeze one effect on its own, give it its own world.
+`world.dispose()` disposes every effect in that world.
 
 ## How it works
 
-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), 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]`).
+The editor compiles a graph into artifacts and bakes them into a module together with the project's
+timeline:
+
+- **Render artifact** - GLSL, uniforms, texture references.
+- **Behavior artifact** - the authored spawn/update functions, bindings and buffer layout.
+- **GPU kernel** - a fused transform-feedback program, present only when the graph opted into GPU
+  simulation and compiled.
+
+The runtime executes those artifacts and compiles nothing. The editor/runtime boundary is frozen:
+each particle carries two core buffers, `position` (vec3) and `lifecycle` (vec3 `[age, lifetime,
+id]`), a particle counts as dead once `age >= lifetime`, and everything else lives in ordinary
+`a_fx_<name>` attributes. The package exports the constants of that layout (`FX_AGE`, `FX_LIFETIME`,
+`FX_ID`, `FX_CORE_POSITION` and the rest).
+
+The math the generated code calls comes from here too (`fxMix`, `fxSmoothstep`, `fxNoise1` /
+`fxNoise2` / `fxNoise3`, `fxFbm`, `fxFbm3`, `fxFract`, `fxMod`, `fxSampleLut`), along with
+`fxDataTexture` for baked curves and gradients. There is no reason to import them by hand: the effect
+module does it itself.
+
+## Development-build checks
+
+Arguments to public methods are sanity-checked (finite numbers, positive durations, integer
+capacities) and throw with the parameter's name when violated. The checks live behind
+`process.env.NODE_ENV !== "production"`, so they drop out of a production build entirely. The access
+to `process` is guarded by a `typeof` check, which keeps the package safe without a bundler - under
+import maps or from a CDN.
 
 ## Requirements
 
-- **A bundler** (Vite, webpack, Rollup, esbuild). `sparcoon` ships as
-  unbundled, unminified ES2020 modules plus types; your bundler tree-shakes and
-  minifies them, the same way three.js is consumed. Not a drop-in `<script>`.
-- **`three` >= 0.157**, as a peer dependency.
-- **Old devices.** Output targets ES2020; to run on pre-2015 hardware (for
-  example a first-generation iPad Pro), downlevel it in your own build
-  (Babel / SWC / your bundler's `target`). `sparcoon` leaves that final step
-  to you.
-
-## API overview
-
-- `FXEffect` -- whole-project timeline player (a `Group`); emitted modules
-  subclass it. `play` / `stop`, `setEmitterParam` / `setMeshParam`,
-  `getEmitter` / `getMesh`, `dispose`.
-- `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`, `fxNoise3`, ...), and `fxDataTexture`.
+|          |                                                                                    |
+| -------- | ---------------------------------------------------------------------------------- |
+| three.js | `>=0.157 <0.180`, a peer dependency                                                |
+| Bundler  | Vite, webpack, Rollup, esbuild - the package ships unminified ESM plus types       |
+| JS level | ES2020; for devices older than 2015, transpile it on your side                     |
+| WebGL    | WebGL1 is enough for the Baseline tier; WebGL2 unlocks Standard and the GPU kernel |
+
+Dropping the package in through a `<script>` tag is not supported: these are unminified ES modules
+that expect your bundler. The ES2020 target is deliberate, so that you can downlevel it with your own
+Babel or SWC as far as you need, down to first-generation iPad Pro hardware.
+
+## What the runtime does not do
+
+- **It does not load assets.** You prepare the textures and geometries and pass them to the effect's
+  constructor. Freeing them is yours as well: the runtime never disposes resources it does not own.
+- **It contains no compiler, graph or validator.** All of that stays in the
+  [editor](https://github.com/jango-git/sparcoon-editor); only the result arrives here.
+- **It brings no lighting.** A lit graph reads the lights of your scene, so a lit effect needs a
+  light probe and a directional light nearby. The preview's own lighting rig is not exported.
+- **It does not decide your scene's draw order.** Depth sorting of particles is enabled per emitter
+  and costs frame time.
+
+## The `sparcoon/editor` entry point
+
+A separate, unstable entry for tools that build objects from artifacts directly:
+`FXEmitter.fromArtifacts` and `FXMesh.fromArtifact`, targeted value updates, swapping the render half
+without resetting the simulation, and the keyframe-sampling functions shared with the editor. The
+editor's live preview uses it. An application that simply plays a finished effect has no reason to go
+there: the whole path it needs runs through `FXEffect`.
+
+## Local development
+
+```sh
+npm ci
+npm run build   # tsc -> dist/, unminified ESM plus .d.ts
+npm test        # vitest run
+npm run lint
+```
+
+## Status
+
+Pre-release, under active development. If you hit a bug, the most useful thing is a minimal
+reproduction plus the editor project `.json` it shows up on.
 
 ## License
 
-MIT (c) jango
+MIT - use it in commercial work, client projects and ads that ship; keep the copyright notice. See
+[LICENSE](LICENSE).

package/dist/effect/FXEffect.d.ts

@@ -65,6 +65,8 @@ export declare abstract class FXEffect extends Group {
     dispose(): void;
     private resetTransport;
     private advance;
+    /** Poses every entity for the frame `time` falls in, unless it already is. */
+    private poseAt;
     /** Fires burst/play events whose time lies in `[from, to)` on their owning emitter. */
     private fire;
     /**

package/dist/effect/FXEffect.js

@@ -372,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));

package/dist/emitter/FXEmitter.d.ts

@@ -25,7 +25,7 @@ export declare class FXEmitter extends Object3D {
     sortFraction: number;
     private readonly world;
     private readonly driver;
-    private material;
+    private artifactMaterial;
     private nextHandler;
     private readonly pendingBursts;
     private readonly activePlays;
@@ -54,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;
@@ -81,6 +84,14 @@ export declare class FXEmitter extends Object3D {
      * 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.

package/dist/emitter/FXEmitter.js

@@ -58,7 +58,7 @@ export class FXEmitter extends Object3D {
         };
         this.world = world;
         this.driver = driver;
-        this.material = material;
+        this.artifactMaterial = material;
         if (options.receiveShadow ?? EMITTER_DEFAULT_RECEIVE_SHADOW) {
             this.mesh.receiveShadow = true;
         }
@@ -135,12 +135,12 @@ export class FXEmitter extends Object3D {
      */
     onWorldTick(deltaTime, elapsedTime) {
         this.onRendering(deltaTime);
-        this.material.setElapsedTime(elapsedTime);
-        this.material.setDeltaTime(deltaTime);
+        this.artifactMaterial.setElapsedTime(elapsedTime);
+        this.artifactMaterial.setDeltaTime(deltaTime);
         // emitterTransform.velocity/angularVelocity are always length 3 (see its declaration) -
         // computed once per tick in onRendering -> tick.
-        this.material.setObjectVelocity(this.emitterTransform.velocity);
-        this.material.setObjectAngularVelocity(this.emitterTransform.angularVelocity);
+        this.artifactMaterial.setObjectVelocity(this.emitterTransform.velocity);
+        this.artifactMaterial.setObjectAngularVelocity(this.emitterTransform.angularVelocity);
     }
     /** Unregisters, removes from the scene, disposes mesh and material. Idempotent. */
     destroy() {
@@ -154,12 +154,15 @@ export class FXEmitter extends Object3D {
         this.activePlays.length = 0;
         // The material owns no per-emitter GPU resources; the driver teardown disposes the instanced
         // geometry and the mounted material (plus, for a GPU-driven emitter, the compiled program+VAO).
-        this.material.destroy();
+        this.artifactMaterial.destroy();
         this.driver.destroy();
         this.removeFromParent();
     }
     /**
-     * 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, options = {}) {
@@ -268,6 +271,20 @@ export class FXEmitter extends Object3D {
         // posed - drop the velocity/angular-velocity baseline along with the particles.
         this.motionTracker.reset();
     }
+    /**
+     * 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() {
+        if (this.destroyed) {
+            return;
+        }
+        this.stop();
+        this.motionTracker.reset();
+    }
     /**
      * Scrubs live parameter values into uniform/binding slots by name, picked up next frame - the
      * runtime's value channel for a non-structural edit. Unknown name = safe no-op; never recompiles.
@@ -278,7 +295,7 @@ export class FXEmitter extends Object3D {
             return;
         }
         if (values.uniforms !== undefined) {
-            this.material.applyUniformValues(values.uniforms);
+            this.artifactMaterial.applyUniformValues(values.uniforms);
         }
         if (values.bindings !== undefined) {
             this.driver.applyBindingValues(values.bindings);
@@ -305,7 +322,7 @@ export class FXEmitter extends Object3D {
         // Throws (leaving this emitter untouched) before anything below mutates it - see this
         // method's own @throws doc.
         this.driver.applyRenderArtifact(material, baseGeometry);
-        this.material = material;
+        this.artifactMaterial = material;
         this.mesh.receiveShadow = options.receiveShadow ?? EMITTER_DEFAULT_RECEIVE_SHADOW;
         const previousDepthMaterial = this.mesh.customDepthMaterial;
         if (options.castShadow ?? EMITTER_DEFAULT_CAST_SHADOW) {

package/dist/emitter/FXGPUEmitterDriver.Internal.js

@@ -15,15 +15,17 @@ import { FXTransformFeedbackSimulationHolder } from "./FXTransformFeedbackSimula
  */
 export class FXGPUEmitterDriver {
     constructor(kernel, renderer, material, capacity, baseGeometry) {
-        // Cursor/overwrite bookkeeping: `gpuSpawnCursor` is the next write position (mod
-        // capacity); `gpuSpawnRangeStart`/`gpuPendingSpawnCount` accumulate every spawn() call since the
-        // last endTick() into one contiguous range, since the GPU can only run one transform-feedback pass
-        // per tick (unlike the JS backend, which can grow its array once per call with no such constraint) -
-        // "since the last endTick()", not "since the start of this tick": an immediate `burst()` between
-        // ticks must not lose its contribution (see endTick()'s own doc comment).
+        // Cursor/overwrite bookkeeping: `gpuSpawnCursor` is the next write position (mod capacity).
+        // Spawns inside a tick (a delayed burst expiring, a play's rate accumulator) all share that
+        // tick's pose and parameters, so `gpuSpawnRangeStart`/`gpuPendingSpawnCount` gather them into
+        // one contiguous range the tick's own pass seeds. A spawn outside a tick - an immediate
+        // `burst()` from host code or from an effect's timeline - is seeded right away by a pass of its
+        // own instead (see spawn()), so the range is always empty between ticks.
         this.gpuSpawnCursor = 0;
         this.gpuSpawnRangeStart = 0;
         this.gpuPendingSpawnCount = 0;
+        // Between beginTick() and endTick(): spawns join the tick's pass instead of running their own.
+        this.ticking = false;
         // Depth sorting has no GPU-driven form - warned once, not every tick, if a host sets
         // sortCamera on one anyway.
         this.warnedAboutSortCamera = false;
@@ -62,32 +64,33 @@ export class FXGPUEmitterDriver {
     get canSpawn() {
         return true;
     }
-    spawn(count) {
+    spawn(count, transform) {
         // Cursor advances by `count`, wrapping at capacity - the buffer slots this claims may already
         // be occupied by still-alive particles, which are simply overwritten (the scheme's cheapness is
-        // not checking occupancy at all). Accumulates into
-        // `gpuPendingSpawnCount` regardless of whether this call happens during a tick's own scheduling
-        // (a delayed burst/play firing) or entirely between ticks (an immediate `burst()` call from host
-        // code) - endTick() is the only place that range is ever consumed and reset (see its own doc
-        // comment for why beginTick() must NOT also reset it).
+        // not checking occupancy at all).
+        const start = this.gpuSpawnCursor;
         this.gpuSpawnCursor = (this.gpuSpawnCursor + count) % this.mesh.capacity;
-        this.gpuPendingSpawnCount += count;
+        if (this.ticking) {
+            this.gpuPendingSpawnCount += count;
+            return;
+        }
+        // Outside a tick, the emitter may be moved or re-parametrized before the next one (two
+        // bursts from two poses in one frame is an ordinary way to author an effect), so this spawn
+        // is seeded now, from the pose and bindings of this call. More than `capacity` at once
+        // overwrites the whole ring; the extra births would only overwrite each other.
+        this.simulation.spawn(this.mesh, { start, count: Math.min(count, this.mesh.capacity) }, transform);
+        this.gpuSpawnRangeStart = this.gpuSpawnCursor;
     }
     beginTick() {
-        // No begin-of-tick bookkeeping needed: unlike the range/count fields (reset only once consumed,
-        // in endTick()), there is nothing here that must happen before this tick's scheduled bursts run.
+        this.ticking = true;
     }
     endTick(deltaTime, transform) {
+        this.ticking = false;
         // Every particle slot is always processed - there is no CPU-visible live count to skip on;
         // the render shader hides dead slots (FXArtifactMaterial.Internal.ts's
         // projectFromModelPos degenerate-position injection).
         this.simulation.tick(this.mesh, deltaTime, { start: this.gpuSpawnRangeStart, count: this.gpuPendingSpawnCount }, transform);
-        // Consumed - reset for the NEXT accumulation window, starting from wherever the cursor now sits.
-        // Must NOT happen in beginTick() instead: an immediate `burst()` call between two ticks (the
-        // ordinary way to spawn a one-shot effect, never touching pendingBursts/activePlays at all)
-        // already advances the cursor and this count the moment it is called - resetting at the START of
-        // the NEXT tick would silently discard that count before it was ever reported as a birth range,
-        // leaving those slots' data one full transform-feedback pass behind their real cursor claim.
+        // Consumed - the next tick's range starts wherever the cursor now sits.
         this.gpuSpawnRangeStart = this.gpuSpawnCursor;
         this.gpuPendingSpawnCount = 0;
     }
@@ -108,10 +111,7 @@ export class FXGPUEmitterDriver {
     reset() {
         this.mesh.drop();
         this.gpuSpawnCursor = 0;
-        // Must also clear any not-yet-consumed spawn accumulation (endTick() only resets it AFTER
-        // consuming it - see that method's own doc comment), or a burst() that ran earlier this same
-        // accumulation window would still spawn on the next tick despite reset() having just cancelled
-        // it - a stale range left over from before the cursor was zeroed here.
+        // Also drops a range gathered but not yet seeded, so nothing cancelled here spawns later.
         this.gpuSpawnRangeStart = 0;
         this.gpuPendingSpawnCount = 0;
     }

package/dist/emitter/FXTransformFeedbackSimulationHolder.js

@@ -78,18 +78,7 @@ export class FXTransformFeedbackSimulationHolder {
     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.bindProgramAndInputs(mesh);
         this.bufferNames.forEach((name, index) => {
             gl.bindBufferBase(gl.TRANSFORM_FEEDBACK_BUFFER, index, mesh.writeBuffer(name));
         });
@@ -99,11 +88,7 @@ export class FXTransformFeedbackSimulationHolder {
         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);
-        }
+        this.releaseFeedbackBuffers();
         for (const name of this.bufferNames) {
             mesh.swapBuffers(name);
         }
@@ -116,6 +101,64 @@ export class FXTransformFeedbackSimulationHolder {
         // optimization, not required for correctness.
         this.renderer.resetState();
     }
+    /**
+     * Seeds the slots of `spawnRange` right now, from `emitter` and the current binding values, and
+     * touches no other slot: the spawn half of {@link tick}, run on its own. Lets every `burst()`
+     * outside the emitter's tick spawn from the pose and parameters of the moment it was called,
+     * instead of sharing one pass - and so one pose - with everything else spawned that frame.
+     *
+     * Transform feedback cannot write the buffer it reads, so the seeded range is drawn into the
+     * write half of each pair (`drawArrays(first, count)`: `gl_VertexID` is the slot index, which
+     * makes every drawn vertex a birth under the kernel's own range test) and then copied into the
+     * read half - the side the renderer draws and the next {@link tick} reads. No swap: every slot
+     * outside the range keeps its state untouched. A range that wraps past the end of the ring is
+     * drawn as two segments. `spawnRange.count` must not exceed the mesh's capacity.
+     */
+    spawn(mesh, spawnRange, emitter) {
+        if (spawnRange.count <= 0) {
+            return;
+        }
+        const gl = this.gl;
+        this.randSeedCounter += 1;
+        const capacity = mesh.capacity;
+        const head = Math.min(spawnRange.count, capacity - spawnRange.start);
+        const segments = head < spawnRange.count
+            ? [
+                [spawnRange.start, head],
+                [0, spawnRange.count - head],
+            ]
+            : [[spawnRange.start, spawnRange.count]];
+        this.bindProgramAndInputs(mesh);
+        // dt 0: the spawn branch has no use for it, and nothing else runs in this pass.
+        this.setUniforms(0, spawnRange, emitter, capacity);
+        gl.enable(gl.RASTERIZER_DISCARD);
+        for (const [first, count] of segments) {
+            this.bufferNames.forEach((name, index) => {
+                const bytesPerSlot = this.strides[index] * Float32Array.BYTES_PER_ELEMENT;
+                gl.bindBufferRange(gl.TRANSFORM_FEEDBACK_BUFFER, index, mesh.writeBuffer(name), first * bytesPerSlot, count * bytesPerSlot);
+            });
+            gl.beginTransformFeedback(gl.POINTS);
+            gl.drawArrays(gl.POINTS, first, count);
+            gl.endTransformFeedback();
+        }
+        gl.disable(gl.RASTERIZER_DISCARD);
+        // Released before the copy: a buffer still bound for transform feedback cannot be a copy
+        // source.
+        this.releaseFeedbackBuffers();
+        this.bufferNames.forEach((name, index) => {
+            const bytesPerSlot = this.strides[index] * Float32Array.BYTES_PER_ELEMENT;
+            gl.bindBuffer(gl.COPY_READ_BUFFER, mesh.writeBuffer(name));
+            gl.bindBuffer(gl.COPY_WRITE_BUFFER, mesh.readBuffer(name));
+            for (const [first, count] of segments) {
+                gl.copyBufferSubData(gl.COPY_READ_BUFFER, gl.COPY_WRITE_BUFFER, first * bytesPerSlot, first * bytesPerSlot, count * bytesPerSlot);
+            }
+        });
+        gl.bindBuffer(gl.COPY_READ_BUFFER, null);
+        gl.bindBuffer(gl.COPY_WRITE_BUFFER, null);
+        this.spawnIdBase += spawnRange.count;
+        // Same reason as in tick(): the raw VAO bind is invisible to three's caches.
+        this.renderer.resetState();
+    }
     destroy() {
         this.gl.deleteProgram(this.program);
         this.gl.deleteVertexArray(this.vao);
@@ -130,6 +173,31 @@ export class FXTransformFeedbackSimulationHolder {
             }
         }
     }
+    /** Binds the program and wires every state buffer's read half as its vertex input. */
+    bindProgramAndInputs(mesh) {
+        const gl = this.gl;
+        // Routed through the renderer's own cache-aware setter (not raw gl.useProgram()) so three's
+        // `WebGLState.currentProgram` cache stays truthful - its own next draw then correctly detects
+        // the mismatch and re-binds, with no reset needed for this half of the state-hygiene problem.
+        // The other half (the VAO-identity cache) has no such setter - see the raw
+        // gl.bindVertexArray() call below and the resetState() that ends every pass.
+        this.renderer.state.useProgram(this.program);
+        gl.bindVertexArray(this.vao);
+        this.bufferNames.forEach((name, index) => {
+            gl.bindBuffer(gl.ARRAY_BUFFER, mesh.readBuffer(name));
+            gl.vertexAttribPointer(index, this.strides[index], gl.FLOAT, false, 0, 0);
+            gl.enableVertexAttribArray(index);
+        });
+    }
+    /**
+     * Unbinds every transform-feedback binding point. A bound base stays "active" for its point
+     * otherwise; released rather than left as a stale reference between passes.
+     */
+    releaseFeedbackBuffers() {
+        for (let index = 0; index < this.bufferNames.length; index += 1) {
+            this.gl.bindBufferBase(this.gl.TRANSFORM_FEEDBACK_BUFFER, index, null);
+        }
+    }
     setUniforms(deltaTime, spawnRange, emitter, capacity) {
         const gl = this.gl;
         gl.uniform1i(this.uniformLocations[FX_TRANSFORM_FEEDBACK_RAND_SEED_UNIFORM], this.randSeedCounter);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sparcoon",
-  "version": "0.9.2",
-  "description": "Runtime for VFX artifacts authored in the Sparcoon Editor.",
+  "version": "0.9.3",
+  "description": "Three.js runtime for visual effects authored in the Sparcoon Editor - precompiled artifacts, one draw call per emitter, no eval.",
   "keywords": [
     "three",
     "threejs",
@@ -14,13 +14,18 @@
     "instanced",
     "instancing",
     "billboard",
+    "transform-feedback",
     "webgl",
+    "webgl2",
+    "glsl",
     "3d",
     "animation",
+    "playable-ads",
+    "esm",
     "typescript",
     "sparcoon"
   ],
-  "homepage": "https://github.com/jango-git/sparcoon#readme",
+  "homepage": "https://jango-git.github.io/sparcoon-editor/",
   "bugs": {
     "url": "https://github.com/jango-git/sparcoon/issues"
   },
@@ -50,6 +55,9 @@
     "LICENSE"
   ],
   "sideEffects": false,
+  "publishConfig": {
+    "tag": "experimental"
+  },
   "engines": {
     "node": ">=18.18.0"
   },