sparcoon 0.7.3 → 0.9.1

package/dist/effect/FXEffectSpec.d.ts

@@ -0,0 +1,115 @@
+import type { Camera } from "three";
+import type { FXBehaviorArtifact, FXGeometrySource, FXRenderArtifact } from "../artifact/FXArtifact.js";
+import type { FXWorld } from "../world/FXWorld.js";
+/**
+ * Data shapes for {@link FXEffect}: a whole exported project (every emitter + VFX mesh, its
+ * timeline and transforms) as plain, JSON-serializable data. The editor emits an `FXEffectSpec`
+ * literal into every project module; this file plus {@link FXEffect} is the runtime that plays it
+ * back, so the editor no longer needs to emit this scaffolding itself.
+ *
+ * Everything here is `readonly` so it structurally matches the editor's own `Transform` /
+ * `TransformTrack` / `AnimationTrack` model types - the editor's richer `Keyframe` (which also
+ * carries a UI-only `id`) is a valid `FXKeyframe` too, so the sampling functions in
+ * {@link FXEffectSampling.Internal.ts} serve both.
+ */
+export type FXVec3 = readonly [number, number, number];
+export type FXQuat = readonly [number, number, number, number];
+export interface FXTransform {
+    readonly position: FXVec3;
+    readonly rotation: FXQuat;
+    readonly scale: FXVec3;
+}
+export interface FXKeyframe {
+    readonly time: number;
+    readonly value: number | readonly number[];
+}
+/** A named value track (drives a render uniform / behavior binding by parameter name). */
+export interface FXTrack {
+    readonly name: string;
+    readonly keys: readonly FXKeyframe[];
+}
+export type FXTransformChannel = "position" | "rotation" | "scale";
+export interface FXTransformTrack {
+    readonly channel: FXTransformChannel;
+    readonly keys: readonly FXKeyframe[];
+}
+/** A timeline event: an instantaneous burst or a sustained emission rate over a window. */
+export type FXEffectEvent = {
+    readonly kind: "burst";
+    readonly time: number;
+    readonly count: number;
+} | {
+    readonly kind: "play";
+    readonly time: number;
+    readonly rate: number;
+    readonly duration: number;
+};
+/** One emitter's precompiled artifacts, transform, and timeline. */
+export interface FXEffectEmitterSpec {
+    /** The editor-authored name, addressing this emitter through {@link FXEffect.getEmitter} etc. */
+    readonly name: string;
+    readonly render: FXRenderArtifact;
+    readonly behavior: FXBehaviorArtifact;
+    readonly expectedCapacity: number;
+    readonly sortInterval: number;
+    /** Casts a shape-aware shadow; omitted (treated as false) by pre-shadow exports. */
+    readonly castShadow?: boolean;
+    /** Receives shadows; omitted (treated as false) by pre-shadow exports. */
+    readonly receiveShadow?: boolean;
+    readonly externalSlots: readonly string[];
+    readonly transform: FXTransform;
+    readonly transformTracks: readonly FXTransformTrack[];
+    readonly tracks: readonly FXTrack[];
+    readonly events: readonly FXEffectEvent[];
+    /** Transform channels the editor marked "fake": never sampled from `transformTracks`, left for
+     * {@link FXEffect.getEmitter} to drive directly. */
+    readonly liveChannels: readonly FXTransformChannel[];
+    /** Timeline Value names the editor marked "fake": excluded from `tracks`, driven only through
+     * {@link FXEffect.setEmitterParam}. */
+    readonly liveParams: readonly string[];
+}
+/** One VFX mesh's precompiled render artifact, transform, and value tracks (no behavior/events). */
+export interface FXEffectMeshSpec {
+    /** The editor-authored name, addressing this mesh through {@link FXEffect.getMesh} etc. */
+    readonly name: string;
+    readonly render: FXRenderArtifact;
+    readonly geometry: FXGeometrySource;
+    /** See {@link FXEffectEmitterSpec.castShadow}. */
+    readonly castShadow?: boolean;
+    /** See {@link FXEffectEmitterSpec.receiveShadow}. */
+    readonly receiveShadow?: boolean;
+    readonly externalSlots: readonly string[];
+    readonly transform: FXTransform;
+    readonly transformTracks: readonly FXTransformTrack[];
+    readonly tracks: readonly FXTrack[];
+    /** See {@link FXEffectEmitterSpec.liveChannels}. */
+    readonly liveChannels: readonly FXTransformChannel[];
+    /** See {@link FXEffectEmitterSpec.liveParams}. */
+    readonly liveParams: readonly string[];
+}
+/** A whole exported project: duration/fps, root transform, and every emitter + mesh. */
+export interface FXEffectSpec {
+    readonly duration: number;
+    readonly fps: number;
+    readonly transform: FXTransform;
+    /**
+     * Always empty: the editor forces every root transform channel "fake", so the root pose is
+     * never sampled after construction (see {@link FXEffect}) - the consumer poses the effect
+     * instance itself through the inherited `Object3D` position/quaternion/scale, like any other
+     * `Group` added to a scene.
+     */
+    readonly transformTracks: readonly FXTransformTrack[];
+    readonly emitters: readonly FXEffectEmitterSpec[];
+    readonly meshes: readonly FXEffectMeshSpec[];
+}
+/** Options shared by every {@link FXEffect}. */
+export interface FXEffectOptions {
+    /** Camera enabling per-emitter depth sorting (only emitters authored with a sort interval sort). */
+    readonly camera?: Camera;
+    /**
+     * The tick domain this effect joins. Omit to join the lazily created default world, which the
+     * static {@link FXWorld.update} advances. Pass an {@link FXWorld} to isolate the effect in its
+     * own clock and particle pool (an independent time scale, or a group you tick separately).
+     */
+    readonly world?: FXWorld;
+}

package/dist/effect/FXEffectSpec.js

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

package/dist/emitter/FXEmitter.Internal.d.ts

@@ -1,79 +1,44 @@
-import type { Camera } from "three";
-import type { FXPropertyName, GLTypeInfo } from "../instancedParticle/shared";
-import type { FXEmitter } from "./FXEmitter";
+import type { Camera, Texture } from "three";
 /**
- * Configuration options for {@link FXEmitter}
+ * Argument to {@link FXEmitter.applyValues}: values to scrub into uniform/binding slots by name.
+ * Both maps optional; an unknown name is a safe no-op. Only reaches parameters the compiled
+ * GLSL/kernel already declared - a structural edit is a fresh {@link FXEmitter.fromArtifacts}.
  */
+export interface FXApplyValues {
+    /** Scalar/vector, or a `Texture` for a `sampler2D`. Mutates the shared artifact slot, or this emitter's own slot for an `external` texture. */
+    readonly uniforms?: Readonly<Record<string, number | readonly number[] | Texture>>;
+    /** A `number`, or a `Float32Array` curve LUT. */
+    readonly bindings?: Readonly<Record<string, number | Float32Array>>;
+}
 export interface FXEmitterOptions {
-    /**
-     * Initial buffer size in particles; grows automatically when exceeded
-     *
-     * @defaultValue `32`
-     */
+    /** Initial buffer size in particles; grows automatically. default 32 */
     expectedCapacity: number;
-    /**
-     * Growth increment added to the buffer when capacity is reached
-     *
-     * @defaultValue `32`
-     */
+    /** Growth increment when capacity is reached. default 32 */
     capacityStep: number;
-    /**
-     * Enables shadow casting
-     *
-     * @defaultValue `false`
-     */
-    castShadow: boolean;
-    /**
-     * Enables shadow receiving
-     *
-     * @defaultValue `false`
-     */
+    /** default false */
     receiveShadow: boolean;
-    /** Camera used for back-to-front depth sorting; omit to disable sorting */
+    /** Casts a shape-aware shadow (a customDepthMaterial built from the render artifact). default false */
+    castShadow: boolean;
+    /** Camera for back-to-front depth sorting; omit to disable sorting. */
     sortCamera: Camera;
-    /**
-     * Fraction of frames on which sorting runs (`1` = every frame, `0.1` = ~every 10th frame)
-     *
-     * @defaultValue `0.1`
-     */
+    /** Fraction of frames sorting runs on (`1` = every frame, `0.1` = ~every 10th). default 0.1 */
     sortFraction: number;
 }
-/**
- * Options for {@link FXEmitter.burst}
- */
 export interface FXEmitterBurstOptions {
-    /**
-     * Delay in seconds before particles are spawned
-     *
-     * @defaultValue `0`
-     */
+    /** Delay in seconds before spawning. default 0 */
     delay: number;
 }
-/**
- * Options for {@link FXEmitter.play}
- */
 export interface FXEmitterPlayOptions {
-    /**
-     * Delay in seconds before emission starts
-     *
-     * @defaultValue `0`
-     */
+    /** Delay in seconds before emission starts. default 0 */
     delay: number;
-    /**
-     * Total emission duration in seconds
-     *
-     * @defaultValue `Infinity`
-     */
+    /** Total emission duration in seconds. default Infinity */
     duration: number;
 }
-export declare const EMITTERS: FXEmitter[];
 export declare const EMITTER_DEFAULT_EXPECTED_CAPACITY = 32;
 export declare const EMITTER_DEFAULT_CAPACITY_STEP = 32;
-export declare const EMITTER_DEFAULT_CAST_SHADOW = false;
 export declare const EMITTER_DEFAULT_RECEIVE_SHADOW = false;
+export declare const EMITTER_DEFAULT_CAST_SHADOW = false;
 export declare const EMITTER_DEFAULT_SORT_FRACTION: number;
 export declare const EMITTER_DEFAULT_PREWARM_MIN_STEP_DURATION: number;
-export declare const EMITTER_DEFAULT_PREWARM_MAX_STEP_COUNT = 10;
-export declare function collectProperties(keeper: Record<string, GLTypeInfo>, modules: readonly {
-    requiredProperties?: Record<string, FXPropertyName>;
-}[], debugContext: string): void;
+export declare const EMITTER_TIME_WRAP_PERIOD: number;
+export declare const EMITTER_DEFAULT_PREWARM_MAX_STEP_COUNT = 1000;

package/dist/emitter/FXEmitter.Internal.js

@@ -1,29 +1,13 @@
-import { resolveGLSLTypeInfo } from '../instancedParticle/shared.js';
-
-const EMITTERS = new Array();
-const EMITTER_DEFAULT_EXPECTED_CAPACITY = 32;
-const EMITTER_DEFAULT_CAPACITY_STEP = 32;
-const EMITTER_DEFAULT_CAST_SHADOW = false;
-const EMITTER_DEFAULT_RECEIVE_SHADOW = false;
-const EMITTER_DEFAULT_SORT_FRACTION = 1 / 10;
-const EMITTER_DEFAULT_PREWARM_MIN_STEP_DURATION = 1 / 60;
-const EMITTER_DEFAULT_PREWARM_MAX_STEP_COUNT = 10;
-function collectProperties(keeper, modules, debugContext) {
-    for (const module of modules) {
-        if (module.requiredProperties === undefined) {
-            continue;
-        }
-        for (const key in module.requiredProperties) {
-            const existingTypeInfo = keeper[key];
-            const newTypeInfo = resolveGLSLTypeInfo(module.requiredProperties[key]);
-            if (existingTypeInfo === undefined) {
-                keeper[key] = newTypeInfo;
-            }
-            else if (existingTypeInfo.glslTypeName !== newTypeInfo.glslTypeName) {
-                throw new Error(`${debugContext}: property conflict for "${key}"`);
-            }
-        }
-    }
-}
-
-export { EMITTERS, EMITTER_DEFAULT_CAPACITY_STEP, EMITTER_DEFAULT_CAST_SHADOW, EMITTER_DEFAULT_EXPECTED_CAPACITY, EMITTER_DEFAULT_PREWARM_MAX_STEP_COUNT, EMITTER_DEFAULT_PREWARM_MIN_STEP_DURATION, EMITTER_DEFAULT_RECEIVE_SHADOW, EMITTER_DEFAULT_SORT_FRACTION, collectProperties };
+export const EMITTER_DEFAULT_EXPECTED_CAPACITY = 32;
+export const EMITTER_DEFAULT_CAPACITY_STEP = 32;
+export const EMITTER_DEFAULT_RECEIVE_SHADOW = false;
+export const EMITTER_DEFAULT_CAST_SHADOW = false;
+export const EMITTER_DEFAULT_SORT_FRACTION = 1 / 10;
+export const EMITTER_DEFAULT_PREWARM_MIN_STEP_DURATION = 1 / 60;
+// A float32 `u_time` accumulated forever quantizes to multi-millisecond steps after hours; wrapping
+// keeps it small. A large multiple of 2pi (~1 hour) keeps unit-frequency sin/cos continuous across
+// the wrap - other frequencies see at most one negligible seam per hour.
+export const EMITTER_TIME_WRAP_PERIOD = 573 * 2 * Math.PI;
+// Runaway guard, not a quality knob. High enough that a normal `prewarm(duration)` at the default
+// `1/60` step honors its step size instead of being silently coarsened.
+export const EMITTER_DEFAULT_PREWARM_MAX_STEP_COUNT = 1000;

package/dist/emitter/FXEmitter.d.ts

@@ -1,81 +1,89 @@
 import type { Camera } from "three";
 import { Object3D } from "three";
-import type { FXMaterial } from "../materials/FXMaterial/FXMaterial";
-import type { FXBehavior } from "./behavior/FXBehavior";
-import type { FXEmitterBurstOptions, FXEmitterOptions, FXEmitterPlayOptions } from "./FXEmitter.Internal";
-import type { FXSpawn } from "./spawn/FXSpawn";
+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 - add to a scene to make particles visible
- *
- * @remarks
- * Drives a pipeline of spawn modules (run once at particle birth) and behavior modules
- * (run every frame). Call {@link FXEmitter.onWillRender} each frame to tick the system.
+ * Particle emitter - one instanced billboard/mesh draw call, per-particle state driven by a
+ * precompiled behavior artifact and appearance by a precompiled render artifact spliced into a
+ * Three material. Built and ticked by {@link FXEffect} through an {@link FXWorld}. Not exported from
+ * the package (the runtime path is running artifacts, not hand-building emitters); reached only as
+ * the live handle returned by {@link FXEffect.getEmitter}.
  */
 export declare class FXEmitter extends Object3D {
-    private readonly spawnSequence;
-    private readonly behaviorSequence;
-    /** Camera used for back-to-front depth sorting; `undefined` disables sorting */
+    /** Camera for back-to-front depth sorting; `undefined` disables it. Distances are world-space, so any emitter/ancestor transform is handled correctly. */
     sortCamera?: Camera;
-    /** Fraction of frames on which sorting runs (`1` = every frame, `0.1` = ~every 10th frame); defaults to `0.1` */
+    /** Fraction of frames sorting runs on (`1` = every frame, `0.1` = ~every 10th); defaults to `0.1`. */
     sortFraction: number;
+    private readonly world;
     private readonly mesh;
     private readonly material;
+    private readonly simulation?;
+    private readonly collectedProperties;
     private nextHandler;
     private readonly pendingBursts;
     private readonly activePlays;
     private sortingAccumulator;
     private readonly sortingCameraWorldPosition;
-    /**
-     * @param spawnSequence - Modules executed in order when particles are born
-     * @param behaviorSequence - Modules executed in order every frame for all live particles
-     * @param material - Particle material
-     * @param options - Emitter configuration
-     */
-    constructor(spawnSequence: FXSpawn[], behaviorSequence: readonly FXBehavior[], material: FXMaterial, options?: Partial<FXEmitterOptions>);
-    /** Number of currently alive particles */
+    private readonly emitterTransform;
+    private readonly motionPositionScratch;
+    private readonly motionQuaternionScratch;
+    private readonly motionScaleScratch;
+    private readonly motionTracker;
+    private destroyed;
+    private kernelBuffersCache?;
+    private kernelBuffersCacheVersion;
     get particleCount(): number;
-    /** Maximum number of particles that fit in the currently allocated buffers */
     get particleCapacity(): number;
     /**
-     * Ticks all active emitters; call once per frame before rendering
-     *
-     * @param deltaTime - Elapsed time in seconds since the last frame
+     * 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 onWillRender: (deltaTime: number) => void;
-    /** Unregisters the emitter, removes it from the scene, and disposes modules and material */
+    static fromArtifacts(render: FXRenderArtifact, behavior: FXBehaviorArtifact, options?: FXFromArtifactsOptions, world?: FXWorld): FXEmitter;
+    /** Unregisters, removes from the scene, disposes mesh and material. Idempotent. */
     destroy(): void;
     /**
-     * Spawns `count` particles immediately, or after a delay when `options.delay` is set
-     *
-     * @param count - Number of particles to spawn
-     * @param options - Burst options
-     * @returns Handler that can be passed to {@link stop} to cancel a pending delayed burst
+     * Spawns `count` particles immediately, or after `options.delay`.
+     * @returns Handler for {@link stop} to cancel a pending delayed burst.
      */
     burst(count: number, options?: Partial<FXEmitterBurstOptions>): number;
     /**
-     * Starts continuous emission at the given rate
-     *
-     * @param rate - Particles per second
-     * @param options - Play options
-     * @returns Handler that can be passed to {@link stop} to cancel
+     * Starts continuous emission at `rate` particles/second.
+     * @returns Handler for {@link stop} to cancel.
      */
     play(rate: number, options?: Partial<FXEmitterPlayOptions>): number;
     /**
-     * Stops an active play or pending burst by handler; stops all when called with no arguments
-     *
-     * @param handler - Handler returned by {@link play} or {@link burst}; omit to stop everything
-     * @returns `true` if anything was stopped
+     * Stops an active play or pending burst by handler; stops all when called with no arguments.
+     * @returns `true` if anything was stopped.
      */
     stop(handler?: number): boolean;
     /**
-     * Simulates the emitter forward in time to avoid a cold-start on frame 0
-     *
-     * @param duration - Total time to simulate in seconds
-     * @param stepDuration - Maximum simulation step size in seconds. Defaults to `1/60`
+     * Simulates forward in time to avoid a cold-start on frame 0.
+     * @param stepDuration - Maximum step size in seconds. Defaults to `1/60`.
      */
     prewarm(duration: number, stepDuration?: number): void;
-    /** Kills all live particles and cancels all active plays and pending bursts */
+    /** Kills all live particles and cancels all active plays and pending bursts. */
     reset(): 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.
+     * A structural edit is instead a fresh {@link fromArtifacts} (the editor decides which).
+     */
+    applyValues(values: FXApplyValues): void;
+    /**
+     * Merged attribute set (name -> component count): union of the behavior's writes and the render's
+     * reads. Throws on a cross-artifact width disagreement rather than sizing a buffer wrong.
+     */
+    private attributeComponents;
+    private buildCollectedProperties;
+    private setSortFraction;
+    private assertCanSpawn;
+    private kernelBuffers;
+    private worldTransform;
+    private markBuffersNeedUpdate;
     private tick;
     private readonly onRendering;
     private spawnBurst;