sparcoon 0.9.0 → 0.9.1

package/dist/editor/index.d.ts

@@ -0,0 +1,8 @@
+export { FXEmitter } from "../emitter/FXEmitter.js";
+export type { FXFromArtifactsOptions } from "../emitter/FXFromArtifactsOptions.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. See the frozen-contract note in CLAUDE.md.
+export { frameOfTime, keyframeSegment, normalizeQuaternion, quaternionFromValue, sampleTrack, sampleTracks, sampleTransform, slerpQuaternion, timeOfFrame, vectorFromValue, } from "../effect/FXEffectSampling.Internal.js";

package/dist/emitter/FXEmitter.d.ts

@@ -1,5 +1,8 @@
 import type { Camera } from "three";
 import { Object3D } from "three";
+import type { FXBehaviorArtifact, FXRenderArtifact } from "../artifact/FXArtifact.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
@@ -33,6 +36,13 @@ export declare class FXEmitter extends Object3D {
     private kernelBuffersCacheVersion;
     get particleCount(): number;
     get particleCapacity(): number;
+    /**
+     * 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;
     /**

package/dist/emitter/FXEmitter.js

@@ -101,7 +101,7 @@ export class FXEmitter extends Object3D {
         }
         this.assertCanSpawn("FXEmitter.constructor");
         this.add(this.mesh);
-        this.world.registerEmitter(this);
+        this.world.registerObject(this);
     }
     get particleCount() {
         return this.mesh.instanceCount;
@@ -110,8 +110,10 @@ export class FXEmitter extends Object3D {
         return this.mesh.instanceCapacity;
     }
     /**
-     * @internal Builds an emitter into `world` from a precompiled effect. Called by {@link FXEffect};
-     * the editor emits the two artifacts as an ESM module and the effect hands them here.
+     * 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, behavior, options = {}, world = FXWorld.getDefault()) {
         const material = new FXArtifactMaterial(render, options.textures);
@@ -138,7 +140,7 @@ export class FXEmitter extends Object3D {
             return;
         }
         this.destroyed = true;
-        this.world.unregisterEmitter(this);
+        this.world.unregisterObject(this);
         // Drop scheduled work and the buffer cache so nothing references the mesh's buffers after teardown.
         this.pendingBursts.length = 0;
         this.activePlays.length = 0;

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export type { FXGraphLambertMaterialOptions, FXGraphUnlitMaterialOptions, FXRend
 export type { FXGeometryPrimitive } from "./artifact/FXArtifact.js";
 export { FXEffect } from "./effect/FXEffect.js";
 export type { FXEffectOptions, FXEffectSpec } from "./effect/FXEffectSpec.js";
+export type { FXEmitter } from "./emitter/FXEmitter.js";
 export { FXWorld } from "./world/FXWorld.js";
 export { fxFbm, fxFract, fxHash, fxMix, fxMod, fxSampleLut, fxSmoothstep, fxSnoise2, fxSnoise3, fxValueNoise, } from "./miscellaneous/fxMath.js";
 export { fxDataTexture } from "./miscellaneous/texture/fxDataTexture.js";

package/dist/instancedParticle/primitiveGeometry.d.ts

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

package/dist/instancedParticle/primitiveGeometry.js

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

package/dist/render/FXMesh.d.ts

@@ -0,0 +1,47 @@
+import { Mesh, type BufferGeometry, type Texture } from "three";
+import type { FXRenderArtifact } from "../artifact/FXArtifact.js";
+import { FXWorld } from "../world/FXWorld.js";
+/** Options for {@link FXMesh.fromArtifact}. */
+export interface FXFromMeshArtifactOptions {
+    /** External textures by slot name (a `{ type: "sampler2D", external }` uniform binds from here). */
+    readonly textures?: Readonly<Record<string, Texture>>;
+    /** Custom geometries by name, resolving a `{ type: "custom", external }` geometry source. */
+    readonly geometries?: Readonly<Record<string, BufferGeometry>>;
+    /** Cast a shape-aware shadow (builds a depth material from the render artifact). default false */
+    readonly castShadow?: boolean;
+    /** Receive shadows. default false */
+    readonly receiveShadow?: boolean;
+}
+/**
+ * A single, non-instanced VFX mesh built from one precompiled render artifact - the mesh twin of
+ * {@link FXEmitter}. Extends `THREE.Mesh`, so the host adds it to its own scene; it self-subscribes
+ * to an {@link FXWorld} on construction and unsubscribes on {@link destroy}, so one
+ * {@link FXWorld.update} per frame drives it alongside every emitter. Each tick pushes the shared
+ * clock and the mesh's world-space velocity/angular velocity, so a render graph reading the
+ * object-velocity/object-angular-velocity builtins works without the host tracking motion by hand.
+ *
+ * Not exported from the main package (the runtime path is running whole projects through
+ * {@link FXEffect}); reached through the `sparcoon/editor` entry, for editor live preview and
+ * similar tooling that renders one artifact-driven mesh at a time.
+ */
+export declare class FXMesh extends Mesh {
+    private readonly world;
+    private readonly driver;
+    private readonly motionTracker;
+    private readonly ownsGeometry;
+    private readonly depthMaterial?;
+    private readonly motionPositionScratch;
+    private readonly motionQuaternionScratch;
+    private readonly motionScaleScratch;
+    private destroyed;
+    private constructor();
+    /** Builds a mesh into `world` from a precompiled render artifact. */
+    static fromArtifact(render: FXRenderArtifact, options?: FXFromMeshArtifactOptions, world?: FXWorld): FXMesh;
+    /** Scrubs live uniform values by name (picked up next frame). Unknown name = safe no-op. */
+    applyValues(values: Readonly<Record<string, number | readonly number[] | Texture>>): void;
+    /**
+     * Unsubscribes from its world and disposes GPU resources (the mounted material, its depth
+     * material, and a built-in primitive geometry - never an app-supplied custom one). Idempotent.
+     */
+    destroy(): void;
+}

package/dist/render/FXMesh.js

@@ -0,0 +1,99 @@
+import { Mesh, Quaternion, Vector3, } from "three";
+import { FXObjectMotionTracker } from "../emitter/FXObjectMotion.Internal.js";
+import { resolveGeometrySource } from "../instancedParticle/primitiveGeometry.js";
+import { FXWorld } from "../world/FXWorld.js";
+import { FXMeshMaterial } from "./FXMeshMaterial.js";
+/**
+ * A single, non-instanced VFX mesh built from one precompiled render artifact - the mesh twin of
+ * {@link FXEmitter}. Extends `THREE.Mesh`, so the host adds it to its own scene; it self-subscribes
+ * to an {@link FXWorld} on construction and unsubscribes on {@link destroy}, so one
+ * {@link FXWorld.update} per frame drives it alongside every emitter. Each tick pushes the shared
+ * clock and the mesh's world-space velocity/angular velocity, so a render graph reading the
+ * object-velocity/object-angular-velocity builtins works without the host tracking motion by hand.
+ *
+ * Not exported from the main package (the runtime path is running whole projects through
+ * {@link FXEffect}); reached through the `sparcoon/editor` entry, for editor live preview and
+ * similar tooling that renders one artifact-driven mesh at a time.
+ */
+export class FXMesh extends Mesh {
+    constructor(geometry, driver, threeMaterial, depthMaterial, ownsGeometry, world) {
+        super(geometry, threeMaterial);
+        this.motionTracker = new FXObjectMotionTracker();
+        // Reused decompose scratch (avoids a per-tick allocation); scale is discarded.
+        this.motionPositionScratch = new Vector3();
+        this.motionQuaternionScratch = new Quaternion();
+        this.motionScaleScratch = new Vector3();
+        this.destroyed = false;
+        this.driver = driver;
+        this.ownsGeometry = ownsGeometry;
+        this.world = world;
+        if (depthMaterial !== undefined) {
+            this.depthMaterial = depthMaterial;
+            this.castShadow = true;
+            this.customDepthMaterial = depthMaterial;
+        }
+        this.world.registerObject(this);
+    }
+    /** Builds a mesh into `world` from a precompiled render artifact. */
+    static fromArtifact(render, options = {}, world = FXWorld.getDefault()) {
+        const driver = new FXMeshMaterial(render, options.textures);
+        const geometry = resolveGeometrySource(render.geometry, options.geometries ?? {});
+        const ownsGeometry = render.geometry === undefined || render.geometry.type === "primitive";
+        const depthMaterial = (options.castShadow ?? false)
+            ? driver.buildThreeDepthMaterial()
+            : undefined;
+        const mesh = new FXMesh(geometry, driver, driver.buildThreeMaterial(), depthMaterial, ownsGeometry, world);
+        if (options.receiveShadow ?? false) {
+            mesh.receiveShadow = true;
+        }
+        return mesh;
+    }
+    /** @internal Driven by {@link FXWorld.update}. */
+    onWorldTick(deltaTime, elapsedTime) {
+        this.updateWorldMatrix(true, false);
+        this.matrixWorld.decompose(this.motionPositionScratch, this.motionQuaternionScratch, this.motionScaleScratch);
+        const motion = this.motionTracker.sample({
+            position: [
+                this.motionPositionScratch.x,
+                this.motionPositionScratch.y,
+                this.motionPositionScratch.z,
+            ],
+            quaternion: [
+                this.motionQuaternionScratch.x,
+                this.motionQuaternionScratch.y,
+                this.motionQuaternionScratch.z,
+                this.motionQuaternionScratch.w,
+            ],
+        }, deltaTime);
+        this.driver.setElapsedTime(elapsedTime);
+        this.driver.setDeltaTime(deltaTime);
+        this.driver.setObjectVelocity(motion.velocity);
+        this.driver.setObjectAngularVelocity(motion.angularVelocity);
+    }
+    /** Scrubs live uniform values by name (picked up next frame). Unknown name = safe no-op. */
+    applyValues(values) {
+        if (this.destroyed) {
+            return;
+        }
+        this.driver.applyUniformValues(values);
+    }
+    /**
+     * Unsubscribes from its world and disposes GPU resources (the mounted material, its depth
+     * material, and a built-in primitive geometry - never an app-supplied custom one). Idempotent.
+     */
+    destroy() {
+        if (this.destroyed) {
+            return;
+        }
+        this.destroyed = true;
+        this.world.unregisterObject(this);
+        if (this.ownsGeometry) {
+            this.geometry.dispose();
+        }
+        this.material.dispose();
+        if (this.depthMaterial !== undefined) {
+            this.depthMaterial.dispose();
+        }
+        this.removeFromParent();
+    }
+}

package/dist/world/FXWorld.d.ts

@@ -1,22 +1,32 @@
 /**
- * The tick domain that drives effects. A world owns a pool of emitters, a registry of effects, and
- * a single monotonic clock; one {@link FXWorld.update} call per frame advances every playing
- * effect's timeline and then ticks the shared particle pool exactly once.
+ * A world-registered renderable driven once per frame: an emitter or a VFX mesh. `onWorldTick` reads
+ * the object's own `matrixWorld` and pushes the shared clock plus its world-space motion; `destroy`
+ * frees its GPU resources and unregisters it.
+ */
+export interface FXWorldObject {
+    onWorldTick(deltaTime: number, elapsedTime: number): void;
+    destroy(): void;
+}
+/**
+ * The tick domain that drives effects and their renderables. A world owns a registry of effects, a
+ * pool of world objects (emitters and meshes), and a single monotonic clock; one
+ * {@link FXWorld.update} call per frame advances every playing effect's timeline, then ticks every
+ * registered emitter and mesh exactly once with the shared clock.
  *
- * An {@link FXEffect} subscribes to a world on construction and unsubscribes on
- * {@link FXEffect.dispose} - the host never wires that up by hand. Pass a world through
- * `FXEffectOptions.world` to place an effect in a specific world; omit it and the effect joins the
- * lazily created default world, which the static {@link FXWorld.update} ticks.
+ * An {@link FXEffect} (and each standalone emitter/mesh it or the editor builds) subscribes to a
+ * world on construction and unsubscribes on disposal - the host never wires that up by hand. Pass a
+ * world through `FXEffectOptions.world` to place an effect in a specific world; omit it and it joins
+ * the lazily created default world, which the static {@link FXWorld.update} ticks.
  *
- * A world is only a tick/clock domain, NOT a scene graph: an effect is still a `THREE.Object3D` you
- * add to your own scene. Two worlds give two independent clocks (for an independent time scale or an
- * isolated group); within one world every effect shares the clock and one delta per frame, so
- * {@link FXEffect.stop} clears rather than freezes - freeze one effect independently by giving it
- * its own world.
+ * A world is only a tick/clock domain, NOT a scene graph: a renderable is still a `THREE.Object3D`
+ * you add to your own scene. Two worlds give two independent clocks (for an independent time scale or
+ * an isolated group); within one world every effect shares the clock and one delta per frame, so
+ * {@link FXEffect.stop} clears rather than freezes - freeze one effect independently by giving it its
+ * own world.
  */
 export declare class FXWorld {
     private static defaultInstance;
-    private readonly emitters;
+    private readonly objects;
     private readonly effects;
     private elapsedTime;
     private disposed;
@@ -29,14 +39,14 @@ export declare class FXWorld {
     static update(deltaTime: number): void;
     /**
      * Advances this world by `deltaTime` seconds: every playing effect drives its own timeline and
-     * meshes, then the shared particle pool ticks once. Call exactly once per frame, before rendering.
-     * A disposed world is a no-op.
+     * meshes, then every registered emitter and mesh ticks once. Call exactly once per frame, before
+     * rendering. A disposed world is a no-op.
      */
     update(deltaTime: number): void;
     /**
      * Disposes every effect registered in this world (each frees its emitters and mesh resources),
-     * then drops any remaining emitters. Idempotent. After this the world's {@link update} is a
-     * no-op; disposing the default world simply makes the next {@link getDefault} create a fresh one.
+     * then drops any remaining objects. Idempotent. After this the world's {@link update} is a no-op;
+     * disposing the default world simply makes the next {@link getDefault} create a fresh one.
      */
     dispose(): void;
 }

package/dist/world/FXWorld.js

@@ -1,23 +1,24 @@
 import { EMITTER_TIME_WRAP_PERIOD } from "../emitter/FXEmitter.Internal.js";
 /**
- * The tick domain that drives effects. A world owns a pool of emitters, a registry of effects, and
- * a single monotonic clock; one {@link FXWorld.update} call per frame advances every playing
- * effect's timeline and then ticks the shared particle pool exactly once.
+ * The tick domain that drives effects and their renderables. A world owns a registry of effects, a
+ * pool of world objects (emitters and meshes), and a single monotonic clock; one
+ * {@link FXWorld.update} call per frame advances every playing effect's timeline, then ticks every
+ * registered emitter and mesh exactly once with the shared clock.
  *
- * An {@link FXEffect} subscribes to a world on construction and unsubscribes on
- * {@link FXEffect.dispose} - the host never wires that up by hand. Pass a world through
- * `FXEffectOptions.world` to place an effect in a specific world; omit it and the effect joins the
- * lazily created default world, which the static {@link FXWorld.update} ticks.
+ * An {@link FXEffect} (and each standalone emitter/mesh it or the editor builds) subscribes to a
+ * world on construction and unsubscribes on disposal - the host never wires that up by hand. Pass a
+ * world through `FXEffectOptions.world` to place an effect in a specific world; omit it and it joins
+ * the lazily created default world, which the static {@link FXWorld.update} ticks.
  *
- * A world is only a tick/clock domain, NOT a scene graph: an effect is still a `THREE.Object3D` you
- * add to your own scene. Two worlds give two independent clocks (for an independent time scale or an
- * isolated group); within one world every effect shares the clock and one delta per frame, so
- * {@link FXEffect.stop} clears rather than freezes - freeze one effect independently by giving it
- * its own world.
+ * A world is only a tick/clock domain, NOT a scene graph: a renderable is still a `THREE.Object3D`
+ * you add to your own scene. Two worlds give two independent clocks (for an independent time scale or
+ * an isolated group); within one world every effect shares the clock and one delta per frame, so
+ * {@link FXEffect.stop} clears rather than freezes - freeze one effect independently by giving it its
+ * own world.
  */
 export class FXWorld {
     constructor() {
-        this.emitters = [];
+        this.objects = [];
         this.effects = [];
         this.elapsedTime = 0;
         this.disposed = false;
@@ -38,8 +39,8 @@ export class FXWorld {
     }
     /**
      * Advances this world by `deltaTime` seconds: every playing effect drives its own timeline and
-     * meshes, then the shared particle pool ticks once. Call exactly once per frame, before rendering.
-     * A disposed world is a no-op.
+     * meshes, then every registered emitter and mesh ticks once. Call exactly once per frame, before
+     * rendering. A disposed world is a no-op.
      */
     update(deltaTime) {
         if (this.disposed) {
@@ -49,31 +50,31 @@ export class FXWorld {
             effect.advanceFrame(deltaTime);
         }
         // Wrap the clock so a float32 `u_time` keeps sub-millisecond resolution in long sessions, then
-        // tick the whole pool once with the shared clock.
+        // tick every registered object once with the shared clock.
         this.elapsedTime = (this.elapsedTime + deltaTime) % EMITTER_TIME_WRAP_PERIOD;
-        for (const emitter of this.emitters) {
-            emitter.onWorldTick(deltaTime, this.elapsedTime);
+        for (const object of this.objects) {
+            object.onWorldTick(deltaTime, this.elapsedTime);
         }
     }
     /**
      * Disposes every effect registered in this world (each frees its emitters and mesh resources),
-     * then drops any remaining emitters. Idempotent. After this the world's {@link update} is a
-     * no-op; disposing the default world simply makes the next {@link getDefault} create a fresh one.
+     * then drops any remaining objects. Idempotent. After this the world's {@link update} is a no-op;
+     * disposing the default world simply makes the next {@link getDefault} create a fresh one.
      */
     dispose() {
         if (this.disposed) {
             return;
         }
         this.disposed = true;
-        // dispose() unregisters each effect from this world, so iterate a snapshot.
+        // Each disposal unregisters from this world, so iterate snapshots.
         for (const effect of [...this.effects]) {
             effect.dispose();
         }
-        for (const emitter of [...this.emitters]) {
-            emitter.destroy();
+        for (const object of [...this.objects]) {
+            object.destroy();
         }
         this.effects.length = 0;
-        this.emitters.length = 0;
+        this.objects.length = 0;
         if (FXWorld.defaultInstance === this) {
             FXWorld.defaultInstance = undefined;
         }
@@ -89,15 +90,15 @@ export class FXWorld {
             this.effects.splice(index, 1);
         }
     }
-    /** @internal Called by {@link FXEmitter}'s constructor. */
-    registerEmitter(emitter) {
-        this.emitters.push(emitter);
+    /** @internal Called by an emitter's or mesh's constructor. */
+    registerObject(object) {
+        this.objects.push(object);
     }
-    /** @internal Called by {@link FXEmitter.destroy}. */
-    unregisterEmitter(emitter) {
-        const index = this.emitters.indexOf(emitter);
+    /** @internal Called on an emitter's or mesh's destroy. */
+    unregisterObject(object) {
+        const index = this.objects.indexOf(object);
         if (index !== -1) {
-            this.emitters.splice(index, 1);
+            this.objects.splice(index, 1);
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparcoon",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Runtime for VFX artifacts authored in the Sparcoon Editor.",
   "keywords": [
     "three",
@@ -36,6 +36,10 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./editor": {
+      "types": "./dist/editor/index.d.ts",
+      "import": "./dist/editor/index.js"
+    },
     "./package.json": "./package.json"
   },
   "main": "./dist/index.js",