r3f-vfx 0.1.8 → 0.2.0

package/dist/index.d.ts

@@ -1,226 +1,45 @@
 import * as react from 'react';
 import { RefObject, ReactNode } from 'react';
-import * as THREE from 'three/webgpu';
-import { CurveData, Rotation3DInput, Appearance, Lighting, ParticleData, EmitterShape, CoreState } from 'core-vfx';
-export { Appearance, AttractorConfig, AttractorType, BaseParticleProps, Blending, CollisionConfig, CurveChannel, CurveData, CurvePoint, CurveTextureResult, Easing, EmitterShape, FlipbookConfig, FrictionConfig, Lighting, ParticleData, Rotation3DInput, StretchConfig, TurbulenceConfig, bakeCurveToArray, buildCurveTextureBin, createCombinedCurveTexture } from 'core-vfx';
+import * as core_vfx from 'core-vfx';
+import { VFXParticleSystemOptions, EmitterControllerOptions, CoreState } from 'core-vfx';
+export { Appearance, AttractorConfig, AttractorType, BaseParticleProps, Blending, CollisionConfig, CurveChannel, CurveData, CurvePoint, CurveTextureResolved, CurveTextureResult, Easing, EmitterController, EmitterControllerOptions, EmitterShape, FlipbookConfig, FrictionConfig, Lighting, NormalizedParticleProps, ParticleData, Rotation3DInput, StretchConfig, TurbulenceConfig, VFXParticleSystem, VFXParticleSystemOptions, bakeCurveToArray, buildCurveTextureBin, createCombinedCurveTexture, isNonDefaultRotation, isWebGPUBackend, normalizeProps, resolveCurveTexture } from 'core-vfx';
 
-type VFXParticlesProps = {
+type VFXParticlesProps = VFXParticleSystemOptions & {
     /** Optional name for registering with useVFXStore (enables VFXEmitter linking) */
     name?: string;
-    /** Maximum number of particles */
-    maxParticles?: number;
-    /** Particle size [min, max] or single value */
-    size?: number | [number, number];
-    /** Array of hex color strings for start color */
-    colorStart?: string[];
-    /** Array of hex color strings for end color (null = use colorStart) */
-    colorEnd?: string[] | null;
-    /** Fade size [start, end] multiplier over lifetime */
-    fadeSize?: number | [number, number];
-    /** Curve data for size over lifetime */
-    fadeSizeCurve?: CurveData;
-    /** Fade opacity [start, end] multiplier over lifetime */
-    fadeOpacity?: number | [number, number];
-    /** Curve data for opacity over lifetime */
-    fadeOpacityCurve?: CurveData;
-    /** Curve data for velocity over lifetime */
-    velocityCurve?: CurveData;
-    /** Gravity vector [x, y, z] */
-    gravity?: [number, number, number];
-    /** Particle lifetime in seconds [min, max] or single value */
-    lifetime?: number | [number, number];
-    /** Direction ranges for velocity */
-    direction?: Rotation3DInput;
-    /** Start position offset ranges */
-    startPosition?: Rotation3DInput;
-    /** Speed [min, max] or single value */
-    speed?: number | [number, number];
-    /** Friction settings */
-    friction?: {
-        intensity?: number | [number, number];
-        easing?: string;
-    };
-    /** Particle appearance type */
-    appearance?: (typeof Appearance)[keyof typeof Appearance];
-    /** Alpha map texture */
-    alphaMap?: THREE.Texture | null;
-    /** Flipbook animation settings */
-    flipbook?: {
-        rows: number;
-        columns: number;
-    } | null;
-    /** Rotation [min, max] in radians or 3D rotation ranges */
-    rotation?: Rotation3DInput;
-    /** Rotation speed [min, max] in radians/second or 3D ranges */
-    rotationSpeed?: Rotation3DInput;
-    /** Curve data for rotation speed over lifetime */
-    rotationSpeedCurve?: CurveData;
-    /** Custom geometry for 3D particles */
-    geometry?: THREE.BufferGeometry | null;
-    /** Rotate geometry to face velocity direction */
-    orientToDirection?: boolean;
-    /** Which local axis aligns with velocity */
-    orientAxis?: string;
-    /** Stretch particles based on speed */
-    stretchBySpeed?: {
-        factor: number;
-        maxStretch: number;
-    } | null;
-    /** Material lighting type for geometry mode */
-    lighting?: (typeof Lighting)[keyof typeof Lighting];
-    /** Enable shadows on geometry instances */
-    shadow?: boolean;
-    /** Blending mode */
-    blending?: THREE.Blending;
-    /** Color intensity multiplier */
-    intensity?: number;
-    /** Emitter position [x, y, z] */
-    position?: [number, number, number];
-    /** Start emitting automatically */
-    autoStart?: boolean;
-    /** Delay between emissions in seconds */
-    delay?: number;
-    /** 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;
-    /** Number of particles to emit per frame */
-    emitCount?: number;
-    /** Emitter shape type */
-    emitterShape?: (typeof EmitterShape)[keyof typeof EmitterShape];
-    /** Emitter radius [inner, outer] */
-    emitterRadius?: number | [number, number];
-    /** Cone angle in radians */
-    emitterAngle?: number;
-    /** Cone height [min, max] */
-    emitterHeight?: number | [number, number];
-    /** Emit from surface only */
-    emitterSurfaceOnly?: boolean;
-    /** Direction for cone/disk normal */
-    emitterDirection?: [number, number, number];
-    /** Turbulence settings */
-    turbulence?: {
-        intensity: number;
-        frequency?: number;
-        speed?: number;
-    } | null;
-    /** Array of attractors (max 4) */
-    attractors?: Array<{
-        position?: [number, number, number];
-        strength?: number;
-        radius?: number;
-        type?: 'point' | 'vortex';
-        axis?: [number, number, number];
-    }> | null;
-    /** Particles move from spawn position to center over lifetime */
-    attractToCenter?: boolean;
-    /** Use start position offset as direction */
-    startPositionAsDirection?: boolean;
-    /** Fade particles when intersecting scene geometry */
-    softParticles?: boolean;
-    /** Distance over which to fade soft particles */
-    softDistance?: number;
-    /** Plane collision settings */
-    collision?: {
-        plane?: {
-            y: number;
-        };
-        bounce?: number;
-        friction?: number;
-        die?: boolean;
-        sizeBasedGravity?: number;
-    } | null;
     /** Show debug control panel */
     debug?: boolean;
-    /** Path to pre-baked curve texture (skips runtime baking for faster load) */
-    curveTexturePath?: string | null;
-    /** Depth test */
+    /** Optional fallback content to render when WebGPU is not available */
+    fallback?: React.ReactNode;
+};
+declare const VFXParticles: react.ForwardRefExoticComponent<core_vfx.BaseParticleProps & {
+    backdropNode?: any | ((data: core_vfx.ParticleData) => any) | null;
+    opacityNode?: any | ((data: core_vfx.ParticleData) => any) | null;
+    colorNode?: any | ((data: core_vfx.ParticleData, defaultColor: any) => any) | null;
+    alphaTestNode?: any | ((data: core_vfx.ParticleData) => any) | null;
+    castShadowNode?: any | ((data: core_vfx.ParticleData) => any) | null;
     depthTest?: boolean;
-    /** Render order (higher values render on top) */
     renderOrder?: number;
-};
-declare const VFXParticles: react.ForwardRefExoticComponent<VFXParticlesProps & react.RefAttributes<unknown>>;
+    curveTexturePath?: string | null;
+} & {
+    /** Optional name for registering with useVFXStore (enables VFXEmitter linking) */
+    name?: string;
+    /** Show debug control panel */
+    debug?: boolean;
+    /** Optional fallback content to render when WebGPU is not available */
+    fallback?: React.ReactNode;
+} & react.RefAttributes<unknown>>;
 
-interface VFXEmitterProps {
+interface VFXEmitterProps extends EmitterControllerOptions {
     /** Name of the registered VFXParticles system */
     name?: string;
     /** Direct ref to VFXParticles (alternative to name) */
     particlesRef?: RefObject<any> | any;
     /** Local position offset */
     position?: [number, number, number];
-    /** Particles to emit per burst */
-    emitCount?: number;
-    /** Seconds between emissions (0 = every frame) */
-    delay?: number;
-    /** Start emitting automatically */
-    autoStart?: boolean;
-    /** Keep emitting (false = emit once) */
-    loop?: boolean;
-    /** Transform direction by parent's world rotation */
-    localDirection?: boolean;
-    /** Direction override [[minX,maxX],[minY,maxY],[minZ,maxZ]] */
-    direction?: [[number, number], [number, number], [number, number]];
-    /** Per-spawn overrides (size, speed, colors, etc.) */
-    overrides?: Record<string, any> | null;
-    /** Callback fired after each emission */
-    onEmit?: (params: {
-        position: [number, number, number] | number[];
-        count: number;
-        direction: any;
-    }) => void;
     /** Children elements */
     children?: ReactNode;
 }
-/**
- * VFXEmitter - A reusable emitter component that links to a VFXParticles system
- *
- * Multiple VFXEmitters can share a single VFXParticles instance without adding
- * supplementary draw calls. Each emitter just calls spawn() on the shared system.
- *
- * The emitter renders a <group> that inherits parent transforms automatically,
- * so you can place it as a child of any object and it will follow.
- *
- * Usage:
- *
- * // First, set up a VFXParticles with a name
- * <VFXParticles name="sparks" maxParticles={1000} autoStart={false} ... />
- *
- * // Place emitter as child - it automatically follows parent transforms!
- * <group ref={playerRef}>
- *   <VFXEmitter
- *     name="sparks"
- *     position={[0, 1, 0]}  // Local offset from parent
- *     emitCount={5}
- *     delay={0.1}
- *   />
- * </group>
- *
- * // Use localDirection to emit relative to parent's rotation
- * <VFXEmitter
- *   name="sparks"
- *   direction={[[0, 0], [0, 0], [-1, -1]]}  // Emit backward in local space
- *   localDirection={true}  // Direction is transformed by parent's rotation
- * />
- *
- * @param {object} props
- * @param {string} props.name - Name of the registered VFXParticles system
- * @param {object} [props.particlesRef] - Direct ref to VFXParticles (alternative to name)
- * @param {[number, number, number]} [props.position=[0,0,0]] - Local position offset
- * @param {number} [props.emitCount=10] - Particles to emit per burst
- * @param {number} [props.delay=0] - Seconds between emissions (0 = every frame)
- * @param {boolean} [props.autoStart=true] - Start emitting automatically
- * @param {boolean} [props.loop=true] - Keep emitting (false = emit once)
- * @param {boolean} [props.localDirection=false] - Transform direction by parent's world rotation
- * @param {array} [props.direction] - Direction override [[minX,maxX],[minY,maxY],[minZ,maxZ]]
- * @param {object} [props.overrides] - Per-spawn overrides (size, speed, colors, etc.)
- * @param {function} [props.onEmit] - Callback fired after each emission
- */
 declare const VFXEmitter: react.ForwardRefExoticComponent<VFXEmitterProps & react.RefAttributes<unknown>>;
 /**
  * Higher-order hook for programmatic emitter control
@@ -242,14 +61,7 @@ declare function useVFXEmitter(name: string): {
     clear: () => boolean;
     isEmitting: () => boolean;
     getUniforms: () => Record<string, unknown> | null;
-    getParticles: () => {
-        spawn: (x: number, y: number, z: number, count: number, overrides?: Record<string, unknown> | null) => void;
-        start: () => void;
-        stop: () => void;
-        clear: () => void;
-        isEmitting: boolean;
-        uniforms: Record<string, unknown>;
-    } | null;
+    getParticles: () => core_vfx.ParticleSystemRef | null;
 };
 
 declare function useVFXStoreImpl(): CoreState;
@@ -264,24 +76,4 @@ declare const useVFXStore: typeof useVFXStoreImpl & {
     getInitialState: () => CoreState;
 };
 
-type CurveTextureHookResult = {
-    texture: THREE.DataTexture;
-    /** Per-channel enabled state, combining curve props and loaded .bin channels */
-    sizeEnabled: boolean;
-    opacityEnabled: boolean;
-    velocityEnabled: boolean;
-    rotationSpeedEnabled: boolean;
-};
-/**
- * Hook for curve texture loading/baking.
- *
- * If curveTexturePath is provided, loads pre-baked texture from file.
- * The .bin file contains a header with a bitmask of which channels are active.
- * Only those channels override the curve props; the rest use curve props or defaults.
- *
- * If curves are defined (no path), bakes them synchronously on the main thread.
- * If no curves AND no path, returns default texture (no baking needed).
- */
-declare const useCurveTextureAsync: (sizeCurve: CurveData | null, opacityCurve: CurveData | null, velocityCurve: CurveData | null, rotationSpeedCurve: CurveData | null, curveTexturePath?: string | null) => CurveTextureHookResult;
-
-export { type CurveTextureHookResult, VFXEmitter, VFXParticles, useCurveTextureAsync, useVFXEmitter, useVFXStore };
+export { VFXEmitter, VFXParticles, type VFXParticlesProps, useVFXEmitter, useVFXStore };