sparcoon 0.9.0 → 0.9.2

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,97 @@
+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.2",
   "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",