sparcoon 0.7.3 → 0.9.1

package/dist/emitter/FXFromArtifactsOptions.d.ts

@@ -0,0 +1,13 @@
+import type { BufferGeometry, Texture } from "three";
+import type { FXEmitterOptions } from "./FXEmitter.Internal.js";
+/**
+ * Options for {@link FXEmitter.fromArtifacts}: the emitter options plus external textures by slot -
+ * a uniform declared `{ type: "sampler2D", external: "<slot>" }` binds from `textures[<slot>]` -
+ * and custom geometries by name, resolving a `{ type: "custom", external: "<name>" }` geometry
+ * source from `geometries[<name>]`. The app owns both maps' lifecycle; the runtime never disposes
+ * them.
+ */
+export interface FXFromArtifactsOptions extends Partial<FXEmitterOptions> {
+    readonly textures?: Record<string, Texture>;
+    readonly geometries?: Record<string, BufferGeometry>;
+}

package/dist/emitter/FXFromArtifactsOptions.js

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

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

@@ -0,0 +1,33 @@
+/**
+ * Pure world-space motion tracking shared by {@link FXEmitter} and `FXEffect`'s VFX-mesh
+ * driving: given an object's current world position/quaternion (from a decomposed
+ * `matrixWorld`) and the real per-frame `dt`, derives its linear and angular velocity - both
+ * already normalized to units/radians per second, never a raw "delta this frame". Three-free
+ * (like `FXEffectSampling.Internal`) so the math unit-tests as plain arithmetic.
+ */
+export type FXObjectVec3 = readonly [number, number, number];
+/** A rotation quaternion in `[x, y, z, w]` order (three's component order). */
+export type FXObjectQuat = readonly [number, number, number, number];
+/** An object's world-space pose at one instant: position + rotation: scale is not tracked. */
+export interface FXObjectPose {
+    readonly position: FXObjectVec3;
+    readonly quaternion: FXObjectQuat;
+}
+/** World-space linear + angular velocity, both already per-second. */
+export interface FXObjectMotion {
+    readonly velocity: FXObjectVec3;
+    readonly angularVelocity: FXObjectVec3;
+}
+/**
+ * Tracks one object's pose across ticks to derive its world velocity/angular velocity. The
+ * first `sample()` call (and the one right after `reset()`) has no prior pose to diff against,
+ * so it reports zero motion and just records the baseline - a restarted effect never reports a
+ * teleport spike from wherever the object was last posed.
+ */
+export declare class FXObjectMotionTracker {
+    private previous;
+    /** The motion arriving at `pose` over the last `deltaTime` seconds; `deltaTime <= 0` (paused) reports zero. */
+    sample(pose: FXObjectPose, deltaTime: number): FXObjectMotion;
+    /** Drops the stored baseline, so the next `sample()` reports zero motion instead of a restart spike. */
+    reset(): void;
+}

package/dist/emitter/FXObjectMotion.Internal.js

@@ -0,0 +1,87 @@
+/**
+ * Pure world-space motion tracking shared by {@link FXEmitter} and `FXEffect`'s VFX-mesh
+ * driving: given an object's current world position/quaternion (from a decomposed
+ * `matrixWorld`) and the real per-frame `dt`, derives its linear and angular velocity - both
+ * already normalized to units/radians per second, never a raw "delta this frame". Three-free
+ * (like `FXEffectSampling.Internal`) so the math unit-tests as plain arithmetic.
+ */
+const ZERO_VEC3 = [0, 0, 0];
+const ZERO_MOTION = { velocity: ZERO_VEC3, angularVelocity: ZERO_VEC3 };
+/** Below this rotation angle (radians) the axis is numerically undefined - report no spin. */
+const MIN_ANGLE = 1e-6;
+function clamp(value, min, max) {
+    return Math.min(Math.max(value, min), max);
+}
+/** Hamilton product `a * b` (applies `b`'s rotation first, then `a`'s - three's convention). */
+function multiplyQuat(a, b) {
+    const [ax, ay, az, aw] = a;
+    const [bx, by, bz, bw] = b;
+    return [
+        aw * bx + ax * bw + ay * bz - az * by,
+        aw * by - ax * bz + ay * bw + az * bx,
+        aw * bz + ax * by - ay * bx + az * bw,
+        aw * bw - ax * bx - ay * by - az * bz,
+    ];
+}
+/** Inverse of a *unit* quaternion (conjugate) - `Matrix4.decompose` always yields one. */
+function invertUnitQuat(q) {
+    return [-q[0], -q[1], -q[2], q[3]];
+}
+/**
+ * World-space angular velocity (axis * rad/s) for the rotation from `previous` to `current`.
+ * Composed in world order (`current * previous^-1`: undo `previous`, then apply `current`), so
+ * it reads directly in world axes - matching the linear `velocity` this module also derives.
+ */
+function angularVelocityBetween(current, previous, deltaTime) {
+    const delta = multiplyQuat(current, invertUnitQuat(previous));
+    // `q` and `-q` represent the same rotation; without this flip a small rotation can land on
+    // the "long way around" (w < 0), reporting an angle near 2*pi instead of near 0.
+    const w = delta[3] < 0 ? -delta[3] : delta[3];
+    const sign = delta[3] < 0 ? -1 : 1;
+    const angle = 2 * Math.acos(clamp(w, -1, 1));
+    if (angle < MIN_ANGLE) {
+        return ZERO_VEC3;
+    }
+    const x = delta[0] * sign;
+    const y = delta[1] * sign;
+    const z = delta[2] * sign;
+    const axisLength = Math.hypot(x, y, z);
+    if (axisLength < MIN_ANGLE) {
+        return ZERO_VEC3;
+    }
+    const rate = angle / deltaTime;
+    return [(x / axisLength) * rate, (y / axisLength) * rate, (z / axisLength) * rate];
+}
+/** `current`'s world velocity/angular velocity relative to `previous`, `deltaTime` seconds apart. */
+function diffPose(current, previous, deltaTime) {
+    const velocity = [
+        (current.position[0] - previous.position[0]) / deltaTime,
+        (current.position[1] - previous.position[1]) / deltaTime,
+        (current.position[2] - previous.position[2]) / deltaTime,
+    ];
+    const angularVelocity = angularVelocityBetween(current.quaternion, previous.quaternion, deltaTime);
+    return { velocity, angularVelocity };
+}
+/**
+ * Tracks one object's pose across ticks to derive its world velocity/angular velocity. The
+ * first `sample()` call (and the one right after `reset()`) has no prior pose to diff against,
+ * so it reports zero motion and just records the baseline - a restarted effect never reports a
+ * teleport spike from wherever the object was last posed.
+ */
+export class FXObjectMotionTracker {
+    /** The motion arriving at `pose` over the last `deltaTime` seconds; `deltaTime <= 0` (paused) reports zero. */
+    sample(pose, deltaTime) {
+        const previous = this.previous;
+        // Always record the latest pose, even on a zero/negative-deltaTime or first call, so a paused
+        // frame's teleport is not mistaken for a spike on the next real tick.
+        this.previous = pose;
+        if (previous === undefined || deltaTime <= 0) {
+            return ZERO_MOTION;
+        }
+        return diffPose(pose, previous, deltaTime);
+    }
+    /** Drops the stored baseline, so the next `sample()` reports zero motion instead of a restart spike. */
+    reset() {
+        this.previous = undefined;
+    }
+}

package/dist/emitter/FXSimulationHolder.d.ts

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

package/dist/emitter/FXSimulationHolder.js

@@ -0,0 +1,43 @@
+import { FX_CORE_LIFECYCLE, FX_CORE_POSITION } from "../coreLayout.js";
+const CORE_BUFFER_NAMES = new Set([FX_CORE_POSITION, FX_CORE_LIFECYCLE]);
+/**
+ * @internal The runtime's behavior driver: holds a precompiled {@link FXBehaviorArtifact} and just
+ * calls its `spawn`/`update` each tick (no graph, compiler, or `new Function`). The artifact's
+ * `bindings` record is passed through on every call, so a value scrub is read next tick.
+ */
+export class FXSimulationHolder {
+    constructor(artifact) {
+        this.artifact = artifact;
+    }
+    /** Declared buffers minus the fixed core `position`/`lifecycle` - one per user attribute. */
+    get attributeBuffers() {
+        return this.artifact.buffers.filter((buffer) => !CORE_BUFFER_NAMES.has(buffer.name));
+    }
+    get attributeWrites() {
+        return this.artifact.attributeWrites;
+    }
+    get canSpawn() {
+        return this.artifact.spawn !== undefined;
+    }
+    get spawnWrittenBuffers() {
+        return this.artifact.spawnWrittenBuffers ?? [];
+    }
+    get updateWrittenBuffers() {
+        return this.artifact.updateWrittenBuffers;
+    }
+    /** Seeds newborns `[begin, begin + count)`. No-op if the artifact is update-only. */
+    spawn(buffers, begin, count, emitter) {
+        this.artifact.spawn?.(buffers, begin, count, this.artifact.bindings, emitter);
+    }
+    update(buffers, count, deltaTime, emitter) {
+        this.artifact.update(buffers, count, deltaTime, this.artifact.bindings, emitter);
+    }
+    /** Behavior half of {@link FXEmitter.applyValues}: mutate each named slot in place; unknown name = no-op. */
+    applyBindingValues(values) {
+        for (const name in values) {
+            if (name in this.artifact.bindings) {
+                this.artifact.bindings[name].value = values[name];
+            }
+        }
+    }
+}

package/dist/index.d.ts

@@ -1,39 +1,11 @@
-export { FXBehaviorDirectionalForce } from "./emitter/behavior/FXBehaviorDirectionalForce";
-export { FXBehaviorPointForce } from "./emitter/behavior/FXBehaviorPointForce";
-export { FXBehaviorScaleOverLife } from "./emitter/behavior/FXBehaviorScaleOverLife";
-export { FXBehaviorTorqueDamping } from "./emitter/behavior/FXBehaviorTorqueDamping";
-export { FXBehaviorTorqueNoise } from "./emitter/behavior/FXBehaviorTorqueNoise";
-export { FXBehaviorTorqueOverLife } from "./emitter/behavior/FXBehaviorTorqueOverLife";
-export { FXBehaviorVelocityDamping } from "./emitter/behavior/FXBehaviorVelocityDamping";
-export { FXBehaviorVelocityNoise } from "./emitter/behavior/FXBehaviorVelocityNoise";
-export { FXBehaviorVelocityOverLife } from "./emitter/behavior/FXBehaviorVelocityOverLife";
-export { FXEmitter } from "./emitter/FXEmitter";
-export { FXSpawnBox } from "./emitter/spawn/FXSpawnBox";
-export { FXSpawnLifetime } from "./emitter/spawn/FXSpawnLifetime";
-export { FXSpawnOffset } from "./emitter/spawn/FXSpawnOffset";
-export { FXSpawnPoint } from "./emitter/spawn/FXSpawnPoint";
-export { FXSpawnRotation } from "./emitter/spawn/FXSpawnRotation";
-export { FXSpawnScale } from "./emitter/spawn/FXSpawnScale";
-export { FXSpawnSphere } from "./emitter/spawn/FXSpawnSphere";
-export { FXSpawnTorque } from "./emitter/spawn/FXSpawnTorque";
-export { FXSpawnVelocity } from "./emitter/spawn/FXSpawnVelocity";
-export { FXDiffuseMaterial } from "./materials/FXDiffuseMaterial/FXDiffuseMaterial";
-export { FXBlending, FXMaterial } from "./materials/FXMaterial/FXMaterial";
-export { FXUnlitMaterial } from "./materials/FXUnlitMaterial/FXUnlitMaterial";
-export { FXColor } from "./miscellaneous/color/FXColor";
-export { FXCurve1D } from "./miscellaneous/curve/FXCurve1D";
-export type { FXCurve1DAnchor, FXCurve1DConfig, FXCurve1DPoint, } from "./miscellaneous/curve/FXCurve1D";
-export { FXTextureView } from "./miscellaneous/texture/FXTextureView";
-export type { FXTextureAtlasConfig, FXTextureConfig, FXTextureRect, FXTextureSize, FXTextureTrim, } from "./miscellaneous/texture/FXTextureView.Internal";
-export { FXNodeBlending } from "./nodes/blending/FXNodeBlending";
-export { FXNodeLightnessBlendingMask } from "./nodes/blending/FXNodeLightnessBlendingMask";
-export { FXNodeColor } from "./nodes/color/FXNodeColor";
-export { FXNodeColorOverLife } from "./nodes/color/FXNodeColorOverLife";
-export { FXNodeSphericalClip } from "./nodes/color/FXNodeSphericalClip";
-export { FXNodeFlatNormal } from "./nodes/normal/FXNodeFlatNormal";
-export { FXNodeNormal } from "./nodes/normal/FXNodeNormal";
-export { FXNodeSphericalNormal } from "./nodes/normal/FXNodeSphericalNormal";
-export { FXNodeAnimatedTexture } from "./nodes/texture/FXNodeAnimatedTexture";
-export type { FXNodeAnimatedTextureOptions } from "./nodes/texture/FXNodeAnimatedTexture";
-export { FXNodeStaticTexture } from "./nodes/texture/FXNodeStaticTexture";
-export { FXNodeTexture } from "./nodes/texture/FXNodeTexture";
+export type { FXAttributeDecl, FXBehaviorArtifact, FXBufferLayout, FXGeometrySource, FXKernelBuffers, FXRenderArtifact, FXShaderStageSource, FXUniformInit, FXValueSlot, } from "./artifact/FXArtifact.js";
+export { FX_AGE, FX_CORE_LIFECYCLE, FX_CORE_LIFECYCLE_STRIDE, FX_CORE_LIFECYCLE_VARYING, FX_CORE_PARTICLE_DEFINES, FX_CORE_POSITION, FX_CORE_POSITION_STRIDE, FX_CORE_POSITION_VARYING, FX_LIFETIME, FX_POSITION_X, FX_POSITION_Y, FX_POSITION_Z, } from "./coreLayout.js";
+export type { FXGraphLambertMaterialOptions, FXGraphUnlitMaterialOptions, FXRenderMode, } from "./render/FXMaterialOptions.js";
+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";
+export type { FXDataTextureOptions } from "./miscellaneous/texture/fxDataTexture.js";

package/dist/index.js

@@ -1,36 +1,13 @@
-export { FXBehaviorDirectionalForce } from './emitter/behavior/FXBehaviorDirectionalForce.js';
-export { FXBehaviorPointForce } from './emitter/behavior/FXBehaviorPointForce.js';
-export { FXBehaviorScaleOverLife } from './emitter/behavior/FXBehaviorScaleOverLife.js';
-export { FXBehaviorTorqueDamping } from './emitter/behavior/FXBehaviorTorqueDamping.js';
-export { FXBehaviorTorqueNoise } from './emitter/behavior/FXBehaviorTorqueNoise.js';
-export { FXBehaviorTorqueOverLife } from './emitter/behavior/FXBehaviorTorqueOverLife.js';
-export { FXBehaviorVelocityDamping } from './emitter/behavior/FXBehaviorVelocityDamping.js';
-export { FXBehaviorVelocityNoise } from './emitter/behavior/FXBehaviorVelocityNoise.js';
-export { FXBehaviorVelocityOverLife } from './emitter/behavior/FXBehaviorVelocityOverLife.js';
-export { FXEmitter } from './emitter/FXEmitter.js';
-export { FXSpawnBox } from './emitter/spawn/FXSpawnBox.js';
-export { FXSpawnLifetime } from './emitter/spawn/FXSpawnLifetime.js';
-export { FXSpawnOffset } from './emitter/spawn/FXSpawnOffset.js';
-export { FXSpawnPoint } from './emitter/spawn/FXSpawnPoint.js';
-export { FXSpawnRotation } from './emitter/spawn/FXSpawnRotation.js';
-export { FXSpawnScale } from './emitter/spawn/FXSpawnScale.js';
-export { FXSpawnSphere } from './emitter/spawn/FXSpawnSphere.js';
-export { FXSpawnTorque } from './emitter/spawn/FXSpawnTorque.js';
-export { FXSpawnVelocity } from './emitter/spawn/FXSpawnVelocity.js';
-export { FXDiffuseMaterial } from './materials/FXDiffuseMaterial/FXDiffuseMaterial.js';
-export { FXBlending, FXMaterial } from './materials/FXMaterial/FXMaterial.js';
-export { FXUnlitMaterial } from './materials/FXUnlitMaterial/FXUnlitMaterial.js';
-export { FXColor } from './miscellaneous/color/FXColor.js';
-export { FXCurve1D } from './miscellaneous/curve/FXCurve1D.js';
-export { FXTextureView } from './miscellaneous/texture/FXTextureView.js';
-export { FXNodeBlending } from './nodes/blending/FXNodeBlending.js';
-export { FXNodeLightnessBlendingMask } from './nodes/blending/FXNodeLightnessBlendingMask.js';
-export { FXNodeColor } from './nodes/color/FXNodeColor.js';
-export { FXNodeColorOverLife } from './nodes/color/FXNodeColorOverLife.js';
-export { FXNodeSphericalClip } from './nodes/color/FXNodeSphericalClip.js';
-export { FXNodeFlatNormal } from './nodes/normal/FXNodeFlatNormal.js';
-export { FXNodeNormal } from './nodes/normal/FXNodeNormal.js';
-export { FXNodeSphericalNormal } from './nodes/normal/FXNodeSphericalNormal.js';
-export { FXNodeAnimatedTexture } from './nodes/texture/FXNodeAnimatedTexture.js';
-export { FXNodeStaticTexture } from './nodes/texture/FXNodeStaticTexture.js';
-export { FXNodeTexture } from './nodes/texture/FXNodeTexture.js';
+// Public surface of the thin runtime: an editor-emitted module subclasses FXEffect, joins an
+// FXWorld, and is driven by a single FXWorld.update per frame - plus the runtime-owned types the
+// editor imports (artifact contracts and the core layout). No graph, compiler, validator, or live
+// protocol lives here.
+export { FX_AGE, FX_CORE_LIFECYCLE, FX_CORE_LIFECYCLE_STRIDE, FX_CORE_LIFECYCLE_VARYING, FX_CORE_PARTICLE_DEFINES, FX_CORE_POSITION, FX_CORE_POSITION_STRIDE, FX_CORE_POSITION_VARYING, FX_LIFETIME, FX_POSITION_X, FX_POSITION_Y, FX_POSITION_Z, } from "./coreLayout.js";
+// Whole-project playback: the generic runtime behind every editor-emitted project module (base
+// class + scene specification). An emitted module supplies only its `FXEffectSpec` data and a thin subclass.
+export { FXEffect } from "./effect/FXEffect.js";
+// The tick domain: an effect joins one on construction; a single FXWorld.update per frame drives
+// every effect's timeline and the shared particle pool.
+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/FXInstancedParticle.d.ts

@@ -1,22 +1 @@
-import type { Material, Vector3 } from "three";
-import { InstancedBufferAttribute, Mesh } from "three";
-import type { GLTypeInfo } from "./shared";
-export declare class FXInstancedParticle extends Mesh {
-    private readonly capacityStep;
-    readonly propertyBuffers: Record<string, InstancedBufferAttribute>;
-    private readonly instancedGeometry;
-    private readonly particleMaterial;
-    private capacity;
-    private sortingIndices;
-    private sortingSquaredDistances;
-    private sortingTemporaryBuffer;
-    constructor(varyings: Record<string, GLTypeInfo>, expectedCapacity: number, capacityStep: number, material: Material);
-    get instanceCount(): number;
-    get instanceCapacity(): number;
-    createInstances(count: number): void;
-    removeDeadParticles(): void;
-    sortByDistance(cameraWorldPosition: Vector3): void;
-    drop(): void;
-    destroy(): void;
-    private ensureCapacity;
-}
+export {};