r3f-vfx 0.0.7 → 0.0.8

package/dist/index.d.ts

@@ -0,0 +1,252 @@
+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, CurveData, CurvePoint, Easing, EmitterShape, FlipbookConfig, FrictionConfig, Lighting, ParticleData, Rotation3DInput, StretchConfig, TurbulenceConfig, bakeCurveToArray, createCombinedCurveTexture } from 'core-vfx';
+
+type VFXParticlesProps = {
+    /** 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;
+};
+declare const VFXParticles: react.ForwardRefExoticComponent<VFXParticlesProps & react.RefAttributes<unknown>>;
+
+interface VFXEmitterProps {
+    /** 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
+ *
+ * Usage:
+ * const { emit, burst, start, stop } = useVFXEmitter("sparks");
+ *
+ * // Emit at a position
+ * emit([1, 2, 3], 50);
+ *
+ * // Burst with overrides
+ * burst([0, 0, 0], 100, { colorStart: ["#ff0000"] });
+ */
+declare function useVFXEmitter(name: string): {
+    emit: (position?: number[], count?: number, overrides?: null) => boolean;
+    burst: (position?: number[], count?: number, overrides?: null) => boolean;
+    start: () => boolean;
+    stop: () => boolean;
+    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;
+};
+
+declare function useVFXStore(): CoreState;
+declare function useVFXStore<T>(selector: (state: CoreState) => T): T;
+
+export { VFXEmitter, VFXParticles, useVFXEmitter, useVFXStore };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "r3f-vfx",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "license": "MIT",
   "type": "module",
   "repository": {