sparcoon 0.7.2 → 0.9.0

package/README.md

@@ -1,85 +1,133 @@
-# sparcoon
-
-[![npm](https://img.shields.io/npm/v/sparcoon.svg)](https://www.npmjs.com/package/sparcoon)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
-Instanced-mesh particle system for Three.js.
-
-## Editor
-
-Interactive visual **[EDITOR](https://jango-git.github.io/sparcoon/)**
-
-![Editor](assets/editor.jpg)
-
-## API
-
-- **FXEmitter** extends `Object3D`. Manages emission, lifetime, pooling, rendering. One draw call per emitter. Optional back-to-front sorting.
-- **Spawn modules** set initial particle state: position (box/sphere/point), velocity (cone), rotation, scale, lifetime. Numeric params accept ranges.
-- **Behavior modules** update particles per frame: directional/point force, velocity/torque damping, simplex noise, scale-over-life, velocity/torque over lifetime.
-- **Materials**: `FXUnlitMaterial` (MeshBasicMaterial), `FXDiffuseMaterial` (MeshLambertMaterial + optional subsurface scatter). Shadow support.
-- **Nodes** are composable material inputs: color-over-life, static/animated textures, normals (flat/spherical/map).
-
-## Example
-
-Smoke volume with animated sprite sheet, subsurface scattering, and shadow receiving:
-
-```typescript
-const RATE = 10;
-const LIFETIME = 6;
-
-const smoke = new FXEmitter(
-  [
-    new FXSpawnBox(areaMin, areaMax),
-    new FXSpawnLifetime({ min: LIFETIME * 0.5, max: LIFETIME }),
-    new FXSpawnScale({ min: 8, max: 16 }),
-    new FXSpawnRotation(),
-  ],
-  [],
-  new FXDiffuseMaterial({
-    enableScatter: true,
-    scatterPower: 10,
-    forwardScatterStrength: 1,
-    backScatterStrength: 0.25,
-    shadowSensitivity: 0.25,
-    premultipliedAlpha: true,
-    albedoNodes: [
-      new FXNodeAnimatedTexture({
-        texture: smokeAtlas,
-        rows: 8,
-        columns: 8,
-        interpolate: true,
-      }),
-      new FXNodeColorOverLife([
-        new FXColor(0xffffff, 0),
-        new FXColor(0xffffff, 0.4),
-        new FXColor(0xffffff, 0.4),
-        new FXColor(0xffffff, 0),
-      ]),
-    ],
-  }),
-  {
-    expectedCapacity: Math.ceil(LIFETIME * RATE) + 1,
-    receiveShadow: true,
-    sortCamera: camera,
-    sortFraction: 0.25,
-  },
-);
-
-scene.add(smoke);
-smoke.play(RATE);
-
-// render loop
-FXEmitter.onWillRender(delta);
-```
+# Sparcoon
+
+Three.js runtime for VFX authored in the Sparcoon Editor.
+
+`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.
+
+> Editor: link coming soon.
+
+## Features
+
+- Instanced billboard and 3D-mesh particles in a single draw call.
+- Per-particle simulation from a precompiled kernel -- no `eval`, no codegen.
+- 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.
 
 ## Install
 
+```sh
+npm install sparcoon three
+```
+
+`three` (>= 0.157) is a peer dependency.
+
+## 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.
+
+```ts
+import { TextureLoader } from "three";
+import { FXWorld } from "sparcoon";
+import { VFXDemo0 } from "./effects/VFXDemo_0"; // emitted by the editor
+
+const loader = new TextureLoader();
+const assets = {
+  heart: loader.load("heart.png"),
+  fire: loader.load("fire.png"),
+};
+const effect = new VFXDemo0(assets);
+
+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
+  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.
+
+### Live parameters
+
+Channels the editor marked "live" are driven from your code, not the timeline:
+
+```ts
+effect.setEmitterParam("Hearts", "spawnRate", 64);
+effect.setMeshParam("Mesh", "glow", [1, 0.4, 0.1]);
+
+effect.getEmitter("Hearts"); // the underlying emitter (Object3D)
+effect.getMesh("Mesh"); // the underlying THREE.Mesh
 ```
-npm install sparcoon
+
+### Many effects, and separate worlds
+
+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.
+
+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
+import { FXWorld } from "sparcoon";
+
+const slowmo = new FXWorld();
+const boss = new VFXDemo0(assets, { world: slowmo });
+scene.add(boss); // still added to your scene yourself
+
+function frame(deltaTime: number): void {
+  FXWorld.update(deltaTime); // the default world
+  slowmo.update(deltaTime * 0.3); // its own, slower clock
+  renderer.render(scene, camera);
+}
 ```
 
-Peer dep: `three` >=0.157.0 <0.180.0
+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.
+
+## 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). This runtime executes them -- your bundler compiles
+the authored functions like any other source, so nothing is evaluated at
+runtime. The editor/runtime boundary is a frozen ABI: two core per-particle
+buffers, `position` and `lifecycle` (`[age, lifetime]`).
+
+## 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`, `fxSnoise3`, ...), and `fxDataTexture`.
 
 ## License
 
-MIT
+MIT (c) jango

package/dist/artifact/FXArtifact.d.ts

@@ -0,0 +1,120 @@
+import type { Texture } from "three";
+import type { FXGraphLambertMaterialOptions, FXGraphUnlitMaterialOptions } from "../render/FXMaterialOptions.js";
+/**
+ * Frozen editor<->runtime boundary. The editor compiles a graph into a plain ESM module that
+ * exports an {@link FXRenderArtifact} (GLSL + uniforms + textures) and an {@link FXBehaviorArtifact}
+ * (authored spawn/update functions + bindings + buffer layout); the runtime only executes them.
+ * Runtime-owned and exported; no code generation, no eval (the app's bundler compiles the authored
+ * functions). Every value scrub must no-op on an unknown name so a name drift never corrupts values.
+ */
+/** One state buffer: name + per-particle stride in floats. */
+export interface FXBufferLayout {
+    readonly name: string;
+    readonly stride: number;
+}
+/** A user attribute declaration (width in components). */
+export interface FXAttributeDecl {
+    readonly name: string;
+    readonly components: 1 | 2 | 3 | 4;
+}
+/** Named set of state buffers handed to a kernel (core + attribute buffers). */
+export type FXKernelBuffers = Readonly<Record<string, Float32Array>>;
+/**
+ * Emitter world transform passed to spawn/update: `matrixWorld` as a column-major mat4 (16 floats),
+ * read through the shared `world-matrix` node; `velocity`/`angularVelocity` are the emitter's
+ * world-space linear/angular velocity (units and radians per second), read through the
+ * `object-velocity`/`object-angular-velocity` nodes. The whole argument is optional - a graph
+ * reading none of these never touches it - but each field, once passed, is always fully populated.
+ */
+export interface FXEmitterTransform {
+    readonly worldMatrix: readonly number[];
+    readonly velocity: readonly number[];
+    readonly angularVelocity: readonly number[];
+}
+/** A live value slot (uniform/binding): the runtime mutates `value` in place. */
+export interface FXValueSlot<T> {
+    value: T;
+}
+/**
+ * Built-in primitive instanced per particle. The vertex program is geometry-agnostic, so `"plane"`
+ * + a camera-facing `particleTransform` is the classic billboard while `"box"`/`"sphere"` are true
+ * 3D mesh particles. Absent => `"plane"`.
+ */
+export type FXGeometryPrimitive = "plane" | "box" | "sphere";
+/**
+ * The geometry an emitter/mesh instances: a built-in primitive, or an app-supplied `BufferGeometry`
+ * bound by name (a custom mesh baked in the editor's content library) - the same external-slot
+ * duality as {@link FXUniformInit}'s `sampler2D` case. Absent `FXRenderArtifact.geometry` => `"plane"`.
+ */
+export type FXGeometrySource = {
+    readonly type: "primitive";
+    readonly primitive: FXGeometryPrimitive;
+} | {
+    readonly type: "custom";
+    readonly external: string;
+};
+/** A uniform's serialized initial value. */
+export type FXUniformInit = {
+    readonly type: string;
+    value: number | readonly number[];
+} | {
+    readonly type: "sampler2D";
+    value: Texture;
+} | {
+    readonly type: "sampler2D";
+    readonly external: string;
+    value?: Texture;
+};
+/** One shader stage's spliceable source (matches the compiler's per-stage IR shape). */
+export interface FXShaderStageSource {
+    readonly varyingDeclarations: readonly string[];
+    readonly helperFunctions: readonly string[];
+    readonly body: readonly string[];
+}
+/** Render half of an emitted effect: compiled GLSL spliced into a Three material, plus live uniforms. */
+export interface FXRenderArtifact {
+    /**
+     * Lighting capability: the sorted, deduplicated set of `fx_`-ABI shade intrinsics the graph's
+     * lighting nodes call (e.g. `["fxLambertShade"]`), derived from the graph (not authored). Empty =>
+     * unlit: the runtime builds the flat material. Non-empty => the runtime lights up Three's light
+     * infrastructure and defines exactly these functions. The shaded color is produced inside the graph
+     * (the `albedo` output already carries it), so there is no per-model material dispatch.
+     */
+    readonly lightingIntrinsics: readonly string[];
+    /** Absent => `"plane"`. */
+    readonly geometry?: FXGeometrySource;
+    readonly options?: FXGraphUnlitMaterialOptions | FXGraphLambertMaterialOptions;
+    readonly uniformDeclarations: readonly string[];
+    readonly vertex: FXShaderStageSource;
+    readonly fragment: FXShaderStageSource;
+    /**
+     * slot -> GLSL expression: `albedo` (required; already carries the shaded color when lit), the
+     * optional fragment-stage compositing slots (`additivity` / `alphaThreshold`), and the optional
+     * vertex-stage `particleTransform` / `vertexTransform` (mat4). Shading normal and emission are node
+     * inputs now, not surface slots.
+     */
+    readonly outputs: Readonly<Record<string, string>>;
+    readonly uniforms: Record<string, FXUniformInit>;
+    /** Attributes the shader reads (`p_fx_<name>`); the emitter merges these with the sim's write set. */
+    readonly attributeReads: readonly FXAttributeDecl[];
+}
+/**
+ * Behavior half of an emitted effect: authored spawn/update functions mutating the packed state
+ * buffers, plus buffer layout and live bindings. Math helpers are inlined, so the artifact carries
+ * no runtime dependency. Attribute offsets are literals derived from {@link buffers}; only the core
+ * position/lifecycle offsets are the fixed ABI (`coreLayout.ts`).
+ */
+export interface FXBehaviorArtifact {
+    readonly buffers: readonly FXBufferLayout[];
+    readonly attributeWrites: readonly FXAttributeDecl[];
+    /** number, or Float32Array (a curve LUT). */
+    readonly bindings: Record<string, FXValueSlot<number | Float32Array>>;
+    /** Buffers `spawn` writes; the host marks only these `needsUpdate`. */
+    readonly spawnWrittenBuffers?: readonly string[];
+    /** Buffers `update` writes; the host marks only these `needsUpdate`. */
+    readonly updateWrittenBuffers: readonly string[];
+    /** Seeds newborns `[start, start+count)`. Optional (an update-only, non-particle host). */
+    spawn?(buffers: FXKernelBuffers, start: number, count: number, bindings: Record<string, FXValueSlot<number | Float32Array>>, emitter?: FXEmitterTransform): void;
+    /** Advances all live particles `[0, count)`. */
+    update(buffers: FXKernelBuffers, count: number, deltaTime: number, bindings: Record<string, FXValueSlot<number | Float32Array>>, emitter?: FXEmitterTransform): void;
+}

package/dist/artifact/FXArtifact.js

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

package/dist/coreLayout.d.ts

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

package/dist/coreLayout.js

@@ -0,0 +1,32 @@
+/**
+ * Frozen per-particle ABI shared by the runtime loop and every editor-emitted module.
+ * Two GPU-mirrored core buffers only: `position` (vec3) and `lifecycle` (vec2 [age, lifetime]);
+ * a particle is dead once `age >= lifetime`. Everything else (velocity, scale, ...) is an ordinary
+ * node-declared `a_fx_<name>` attribute, not core.
+ *
+ * Split into two buffers because a Three instanced attribute is at most a vec4 - a 5-float core
+ * cannot be one attribute, whereas vec3 + vec2 are two clean varyings. Dependency-free (the editor's
+ * module emitter imports this too), so keep it three-free and portable.
+ */
+export const FX_CORE_POSITION = "position";
+export const FX_CORE_LIFECYCLE = "lifecycle";
+export const FX_CORE_POSITION_STRIDE = 3;
+export const FX_CORE_LIFECYCLE_STRIDE = 2;
+export const FX_POSITION_X = 0;
+export const FX_POSITION_Y = 1;
+export const FX_POSITION_Z = 2;
+export const FX_AGE = 0;
+export const FX_LIFETIME = 1;
+export const FX_CORE_POSITION_VARYING = "p_position";
+export const FX_CORE_LIFECYCLE_VARYING = "p_lifecycle";
+// Stable macro names so emitted render GLSL reads PARTICLE_POSITION_X / PARTICLE_AGE etc. instead
+// of hardcoding the varying names this module owns.
+export const FX_CORE_PARTICLE_DEFINES = `
+  #define PARTICLE_POSITION_X ${FX_CORE_POSITION_VARYING}.x
+  #define PARTICLE_POSITION_Y ${FX_CORE_POSITION_VARYING}.y
+  #define PARTICLE_POSITION_Z ${FX_CORE_POSITION_VARYING}.z
+  #define PARTICLE_POSITION ${FX_CORE_POSITION_VARYING}
+
+  #define PARTICLE_AGE ${FX_CORE_LIFECYCLE_VARYING}.x
+  #define PARTICLE_LIFETIME ${FX_CORE_LIFECYCLE_VARYING}.y
+`;

package/dist/effect/FXEffect.d.ts

@@ -0,0 +1,77 @@
+import { Group, Mesh, type BufferGeometry, type Texture } from "three";
+import { FXEmitter } from "../emitter/FXEmitter.js";
+import type { FXEffectOptions, FXEffectSpec } from "./FXEffectSpec.js";
+/** One asset slot: an external texture OR (per {@link FXGeometrySource}) an external geometry, keyed by the same flat `assets` namespace. */
+type FXEffectAsset = Texture | BufferGeometry;
+/**
+ * Runtime for a whole exported Sparcoon project: a `Group` that builds every emitter + VFX mesh
+ * from precompiled artifacts and drives the shared timeline. Add it to your scene, call `play()`,
+ * and `update(deltaSeconds)` each frame. Lit graphs read the scene's lights, so a lit effect needs
+ * a light probe + directional light in the host scene (studio lighting is not part of the export).
+ * An editor-emitted module supplies only the data (`FXEffectSpec` + a scene name) and a thin named
+ * subclass; this base class is identical for every export.
+ *
+ * The timeline drive mirrors the editor's own transport: burst/play events fire across the
+ * continuous swept interval, while value + transform tracks are frame-stepped onto the `fps` grid.
+ */
+export declare abstract class FXEffect extends Group {
+    private readonly specification;
+    private readonly world;
+    private readonly emitters;
+    private readonly meshMaterials;
+    private readonly meshes;
+    private readonly meshMotionTrackers;
+    private readonly emitterDriven;
+    private readonly meshDriven;
+    private readonly emitterIndexByName;
+    private readonly meshIndexByName;
+    private time;
+    private lastTime;
+    private lastFrame;
+    private meshClock;
+    private playing;
+    private disposed;
+    private readonly meshPositionScratch;
+    private readonly meshQuaternionScratch;
+    private readonly meshScaleScratch;
+    protected constructor(specification: FXEffectSpec, assets: Record<string, FXEffectAsset>, options?: FXEffectOptions);
+    /** Restarts the timeline from the top: clears live particles and begins playback. */
+    play(): void;
+    /** Halts playback and clears live particles, returning to the authored frame-0 state. */
+    stop(): void;
+    /**
+     * The runtime emitter named `name` (its `FXEmitter`, an `Object3D`) - for a live channel the
+     * editor marked "fake" (see {@link FXEffectSpec}), pose it directly through its own
+     * `position`/`quaternion`/`scale`; `driveFrame` never touches that channel again. `undefined`
+     * for an unknown name or once disposed (matching {@link dispose}'s emptied index).
+     */
+    getEmitter(name: string): FXEmitter | undefined;
+    /** The runtime mesh named `name` (a `three.Mesh`), for the same live-channel posing as {@link getEmitter}. */
+    getMesh(name: string): Mesh | undefined;
+    /**
+     * Pushes `value` into emitter `name`'s Timeline Value `parameter` (a uniform/binding slot the
+     * editor marked "fake", so it is never sampled from baked keyframes). No-op for an unknown
+     * emitter, or once disposed - the underlying slot writer already no-ops for an unknown parameter.
+     */
+    setEmitterParam(name: string, parameter: string, value: number | readonly number[]): void;
+    /** Pushes `value` into mesh `name`'s Timeline Value `parameter`. See {@link setEmitterParam}. */
+    setMeshParam(name: string, parameter: string, value: number | readonly number[]): void;
+    /**
+     * Unsubscribes from its world, destroys every emitter, and disposes mesh resources; the group
+     * empties itself from its parent. Idempotent.
+     */
+    dispose(): void;
+    private resetTransport;
+    private advance;
+    /** Fires burst/play events whose time lies in `[from, to)` on their owning emitter. */
+    private fire;
+    /**
+     * Poses every entity and scrubs its sampled parameter values into the runtime at time `time`. The
+     * root itself is never re-posed here (see {@link FXEffectSpec.transformTracks}) - only
+     * emitters/meshes, and only their non-live channels/parameters.
+     */
+    private driveFrame;
+    private driveEmitterValues;
+    private driveMeshValues;
+}
+export {};