core-vfx 0.0.10 → 0.1.0

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import * as zustand_vanilla from 'zustand/vanilla';
 import * as THREE from 'three/webgpu';
 import { Node, StorageBufferNode } from 'three/webgpu';
+import { Quaternion } from 'three';
 
 type ParticleSystemRef = {
     spawn: (x: number, y: number, z: number, count: number, overrides?: Record<string, unknown> | null) => void;
@@ -133,6 +134,101 @@ type StretchConfig = {
     factor: number;
     maxStretch: number;
 } | null;
+type NormalizedParticleProps = {
+    maxParticles: number;
+    sizeRange: [number, number];
+    speedRange: [number, number];
+    fadeSizeRange: [number, number];
+    fadeOpacityRange: [number, number];
+    lifetimeRange: [number, number];
+    gravity: [number, number, number];
+    direction3D: [[number, number], [number, number], [number, number]];
+    startPosition3D: [[number, number], [number, number], [number, number]];
+    rotation3D: [[number, number], [number, number], [number, number]];
+    rotationSpeed3D: [[number, number], [number, number], [number, number]];
+    frictionIntensityRange: [number, number];
+    frictionEasingType: number;
+    startColors: [number, number, number][];
+    endColors: [number, number, number][];
+    colorStartCount: number;
+    colorEndCount: number;
+    emitterRadiusRange: [number, number];
+    emitterHeightRange: [number, number];
+    intensity: number;
+    position: [number, number, number];
+    autoStart: boolean;
+    delay: number;
+    emitCount: number;
+    emitterShape: number;
+    emitterAngle: number;
+    emitterSurfaceOnly: boolean;
+    emitterDirection: [number, number, number];
+    turbulence: TurbulenceConfig;
+    attractors: AttractorConfig[] | null;
+    attractToCenter: boolean;
+    startPositionAsDirection: boolean;
+    softParticles: boolean;
+    softDistance: number;
+    collision: CollisionConfig;
+    appearance: string;
+    alphaMap: THREE.Texture | null;
+    flipbook: FlipbookConfig;
+    rotation: Rotation3DInput;
+    rotationSpeed: Rotation3DInput;
+    geometry: THREE.BufferGeometry | null;
+    orientToDirection: boolean;
+    orientAxis: string;
+    stretchBySpeed: StretchConfig;
+    lighting: string;
+    shadow: boolean;
+    blending: THREE.Blending;
+    depthTest: boolean;
+    renderOrder: number;
+    colorStart: string[];
+    colorEnd: string[] | null;
+    size: number | [number, number];
+    speed: number | [number, number];
+    fadeSize: number | [number, number];
+    fadeOpacity: number | [number, number];
+    lifetime: number | [number, number];
+    direction: Rotation3DInput;
+    startPosition: Rotation3DInput;
+    friction: FrictionConfig;
+    emitterRadius: number | [number, number];
+    emitterHeight: number | [number, number];
+};
+type VFXParticleSystemOptions = BaseParticleProps & {
+    /** TSL node or function for backdrop sampling */
+    backdropNode?: any | ((data: ParticleData) => any) | null;
+    /** TSL node or function for custom opacity */
+    opacityNode?: any | ((data: ParticleData) => any) | null;
+    /** TSL node or function to override color */
+    colorNode?: any | ((data: ParticleData, defaultColor: any) => any) | null;
+    /** TSL node or function for alpha test/discard */
+    alphaTestNode?: any | ((data: ParticleData) => any) | null;
+    /** TSL node or function for shadow map output */
+    castShadowNode?: any | ((data: ParticleData) => any) | null;
+    /** Depth test */
+    depthTest?: boolean;
+    /** Render order (higher values render on top) */
+    renderOrder?: number;
+    /** Path to pre-baked curve texture (skips runtime baking for faster load) */
+    curveTexturePath?: string | null;
+};
+type EmitterControllerOptions = {
+    emitCount?: number;
+    delay?: number;
+    autoStart?: boolean;
+    loop?: boolean;
+    localDirection?: boolean;
+    direction?: [[number, number], [number, number], [number, number]];
+    overrides?: Record<string, any> | null;
+    onEmit?: (params: {
+        position: [number, number, number] | number[];
+        count: number;
+        direction: any;
+    }) => void;
+};
 type BaseParticleProps = {
     /** Maximum number of particles */
     maxParticles?: number;
@@ -189,7 +285,7 @@ type BaseParticleProps = {
     /** Enable shadows on geometry instances */
     shadow?: boolean;
     /** Blending mode */
-    blending?: (typeof Blending)[keyof typeof Blending];
+    blending?: THREE.Blending;
     /** Color intensity multiplier */
     intensity?: number;
     /** Emitter position [x, y, z] */
@@ -228,12 +324,16 @@ type BaseParticleProps = {
     collision?: CollisionConfig;
 };
 
+declare const isWebGPUBackend: (renderer: unknown) => boolean;
 declare const hexToRgb: (hex: string) => [number, number, number];
 declare const toRange: (value: number | [number, number] | null | undefined, defaultVal?: [number, number]) => [number, number];
 declare const easingToType: (easing: string | number | undefined) => number;
 declare const axisToNumber: (axis: string) => number;
 declare const toRotation3D: (value: number | [number, number] | [[number, number], [number, number], [number, number]] | null | undefined) => [[number, number], [number, number], [number, number]];
 declare const lifetimeToFadeRate: (seconds: number) => number;
+declare const isNonDefaultRotation: (r: number | [number, number] | [[number, number], [number, number], [number, number]] | null | undefined) => boolean;
+
+declare const normalizeProps: (props: BaseParticleProps) => NormalizedParticleProps;
 
 /**
  * Channel bitmask for curve texture .bin files.
@@ -273,12 +373,34 @@ declare const createDefaultCurveTexture: () => THREE.DataTexture;
  * Only active channels contain baked curve data; inactive channels get default 1→0.
  */
 declare const buildCurveTextureBin: (sizeCurve: CurveData | null, opacityCurve: CurveData | null, velocityCurve: CurveData | null, rotationSpeedCurve: CurveData | null) => ArrayBuffer;
+type CurveTextureResolved = {
+    texture: THREE.DataTexture;
+    sizeEnabled: boolean;
+    opacityEnabled: boolean;
+    velocityEnabled: boolean;
+    rotationSpeedEnabled: boolean;
+};
 /**
  * Load a pre-baked curve texture from a .bin file.
  * Supports both old format (raw 256*4 floats, all channels active)
  * and new format (4-float header + 256*4 floats with channel bitmask).
  */
 declare const loadCurveTextureFromPath: (path: string) => Promise<CurveTextureResult>;
+/**
+ * Resolve a curve texture from either a .bin path or inline curve data.
+ *
+ * Priority:
+ * 1. curveTexturePath → load from .bin file (with fallback to baking on error)
+ * 2. Inline curve data → bake synchronously
+ * 3. No curves → default 1→0 texture
+ */
+declare const resolveCurveTexture: (options: {
+    fadeSizeCurve?: CurveData | null;
+    fadeOpacityCurve?: CurveData | null;
+    velocityCurve?: CurveData | null;
+    rotationSpeedCurve?: CurveData | null;
+    curveTexturePath?: string | null;
+}) => Promise<CurveTextureResolved>;
 
 type ParticleStorageArrays = {
     positions: StorageBufferNode;
@@ -297,6 +419,8 @@ type ShaderFeatures = {
     collision: boolean;
     rotation: boolean;
     perParticleColor: boolean;
+    needsPerParticleColor: boolean;
+    needsRotation: boolean;
 };
 type MaterialOptions = {
     alphaMap: THREE.Texture | null;
@@ -345,4 +469,115 @@ declare const createUpdateCompute: (storage: ParticleStorageArrays, uniforms: Pa
  */
 declare const createParticleMaterial: (storage: ParticleStorageArrays, uniforms: ParticleUniforms, curveTexture: THREE.DataTexture, options: MaterialOptions) => THREE.SpriteNodeMaterial | THREE.MeshBasicNodeMaterial | THREE.MeshStandardNodeMaterial | THREE.MeshPhysicalNodeMaterial;
 
-export { Appearance, type AttractorConfig, AttractorType, type BaseParticleProps, Blending, CURVE_RESOLUTION, type CollisionConfig, type CoreState, CurveChannel, type CurveData, type CurvePoint, type CurveTextureResult, DEFAULT_LINEAR_CURVE, Easing, EmitterShape, type FlipbookConfig, type FrictionConfig, Lighting, MAX_ATTRACTORS, type MaterialOptions, type ParticleData, type ParticleStorageArrays, type ParticleUniforms, type Rotation3DInput, type ShaderFeatures, type StretchConfig, type TurbulenceConfig, axisToNumber, bakeCurveToArray, buildCurveTextureBin, coreStore, createCombinedCurveTexture, createDefaultCurveTexture, createInitCompute, createParticleMaterial, createSpawnCompute, createUpdateCompute, easingToType, evaluateBezierSegment, hexToRgb, lifetimeToFadeRate, loadCurveTextureFromPath, sampleCurveAtX, selectColor, toRange, toRotation3D };
+declare function createUniforms(props: NormalizedParticleProps): ParticleUniforms;
+declare function updateUniforms(uniforms: ParticleUniforms, props: NormalizedParticleProps): void;
+declare function updateUniformsPartial(uniforms: ParticleUniforms, rawProps: Record<string, any>): void;
+declare function updateUniformsCurveFlags(uniforms: ParticleUniforms, flags: {
+    fadeSizeCurveEnabled: boolean;
+    fadeOpacityCurveEnabled: boolean;
+    velocityCurveEnabled: boolean;
+    rotationSpeedCurveEnabled: boolean;
+}): void;
+declare function applySpawnOverrides(uniforms: ParticleUniforms, overrides: Record<string, any> | null): (() => void) | null;
+
+declare const STRUCTURAL_KEYS: readonly ["maxParticles", "lighting", "appearance", "shadow", "orientToDirection"];
+declare function resolveFeatures(props: {
+    colorStart?: string[];
+    colorEnd?: string[] | null;
+    rotation?: Rotation3DInput;
+    rotationSpeed?: Rotation3DInput;
+    turbulence?: {
+        intensity: number;
+        frequency?: number;
+        speed?: number;
+    } | null;
+    attractors?: Array<{
+        position?: [number, number, number];
+        strength?: number;
+        radius?: number;
+        type?: 'point' | 'vortex';
+        axis?: [number, number, number];
+    }> | null;
+    collision?: {
+        plane?: {
+            y: number;
+        };
+        bounce?: number;
+        friction?: number;
+        die?: boolean;
+        sizeBasedGravity?: number;
+    } | null;
+}): ShaderFeatures;
+declare function needsRecreation(currentFeatures: ShaderFeatures, changedProps: Record<string, any>, mergedConfig: Record<string, any>): boolean;
+declare function createStorageArrays(maxParticles: number, features: ShaderFeatures): ParticleStorageArrays;
+declare function createRenderObject(geometry: THREE.BufferGeometry | null, material: THREE.Material, maxParticles: number, shadow: boolean): THREE.Sprite | THREE.InstancedMesh;
+
+declare class VFXParticleSystem {
+    readonly uniforms: ParticleUniforms;
+    readonly storage: ParticleStorageArrays;
+    readonly features: ShaderFeatures;
+    renderObject: THREE.Sprite | THREE.InstancedMesh;
+    material: THREE.Material;
+    curveTexture: THREE.DataTexture;
+    computeInit: any;
+    computeSpawn: any;
+    computeUpdate: any;
+    readonly options: VFXParticleSystemOptions;
+    readonly normalizedProps: NormalizedParticleProps;
+    private renderer;
+    nextIndex: number;
+    initialized: boolean;
+    isEmitting: boolean;
+    private emitAccumulator;
+    private turbulenceSpeed;
+    position: [number, number, number];
+    constructor(renderer: THREE.WebGPURenderer, options: VFXParticleSystemOptions);
+    init(): Promise<void>;
+    dispose(): void;
+    spawn(x: number, y: number, z: number, count?: number, overrides?: Record<string, unknown> | null): void;
+    update(delta: number): Promise<void>;
+    autoEmit(delta: number): void;
+    start(): void;
+    stop(): void;
+    clear(): void;
+    updateProps(props: Partial<BaseParticleProps>): void;
+    setPosition(position: [number, number, number]): void;
+    setDelay(delay: number): void;
+    setEmitCount(emitCount: number): void;
+    setTurbulenceSpeed(speed: number): void;
+    setCurveTexture(texture: THREE.DataTexture): void;
+}
+
+declare class EmitterController {
+    private system;
+    isEmitting: boolean;
+    private emitAccumulator;
+    private hasEmittedOnce;
+    private options;
+    constructor(options: EmitterControllerOptions);
+    setSystem(system: ParticleSystemRef | null): void;
+    getSystem(): ParticleSystemRef | null;
+    updateOptions(options: Partial<EmitterControllerOptions>): void;
+    transformDirectionByQuat(dirRange: [[number, number], [number, number], [number, number]], quat: Quaternion): [[number, number], [number, number], [number, number]];
+    update(delta: number, worldPosition: {
+        x: number;
+        y: number;
+        z: number;
+    }, worldQuaternion?: Quaternion): void;
+    emit(emitOverrides?: Record<string, unknown> | null): boolean;
+    emitAtPosition(worldPosition: {
+        x: number;
+        y: number;
+        z: number;
+    }, worldQuaternion?: Quaternion, emitOverrides?: Record<string, unknown> | null): boolean;
+    burst(count: number, worldPosition: {
+        x: number;
+        y: number;
+        z: number;
+    }, worldQuaternion?: Quaternion): boolean;
+    start(): void;
+    stop(): void;
+    private doEmit;
+}
+
+export { Appearance, type AttractorConfig, AttractorType, type BaseParticleProps, Blending, CURVE_RESOLUTION, type CollisionConfig, type CoreState, CurveChannel, type CurveData, type CurvePoint, type CurveTextureResolved, type CurveTextureResult, DEFAULT_LINEAR_CURVE, Easing, EmitterController, type EmitterControllerOptions, EmitterShape, type FlipbookConfig, type FrictionConfig, Lighting, MAX_ATTRACTORS, type MaterialOptions, type NormalizedParticleProps, type ParticleData, type ParticleStorageArrays, type ParticleSystemRef, type ParticleUniforms, type Rotation3DInput, STRUCTURAL_KEYS, type ShaderFeatures, type StretchConfig, type TurbulenceConfig, VFXParticleSystem, type VFXParticleSystemOptions, applySpawnOverrides, axisToNumber, bakeCurveToArray, buildCurveTextureBin, coreStore, createCombinedCurveTexture, createDefaultCurveTexture, createInitCompute, createParticleMaterial, createRenderObject, createSpawnCompute, createStorageArrays, createUniforms, createUpdateCompute, easingToType, evaluateBezierSegment, hexToRgb, isNonDefaultRotation, isWebGPUBackend, lifetimeToFadeRate, loadCurveTextureFromPath, needsRecreation, normalizeProps, resolveCurveTexture, resolveFeatures, sampleCurveAtX, selectColor, toRange, toRotation3D, updateUniforms, updateUniformsCurveFlags, updateUniformsPartial };