r3f-vfx 0.0.5 → 0.0.6

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import * as react from 'react';
+import { RefObject, ReactNode } from 'react';
 import * as THREE from 'three/webgpu';
 import { CoreState } from 'core-vfx';
 
@@ -36,39 +37,185 @@ declare const Lighting: Readonly<{
     STANDARD: "standard";
     PHYSICAL: "physical";
 }>;
-declare function bakeCurveToArray(curveData: any, resolution?: number): Float32Array<ArrayBuffer>;
-declare function createCombinedCurveTexture(sizeCurve: any, opacityCurve: any, velocityCurve: any, rotationSpeedCurve: any): THREE.DataTexture;
-declare const VFXParticles: react.ForwardRefExoticComponent<react.RefAttributes<any>>;
-
-/**
- * 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: any): {
-    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>;
+type CurvePoint = {
+    pos: [number, number];
+    handleIn?: [number, number];
+    handleOut?: [number, number];
+};
+type CurveData = {
+    points: CurvePoint[];
+} | null;
+declare const bakeCurveToArray: (curveData: CurveData, resolution?: number) => Float32Array;
+declare const createCombinedCurveTexture: (sizeCurve: CurveData, opacityCurve: CurveData, velocityCurve: CurveData, rotationSpeedCurve: CurveData) => THREE.DataTexture;
+type Rotation3DInput = number | [number, number] | [[number, number], [number, number], [number, number]] | null | undefined;
+type ParticleData = Record<string, any>;
+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
  *
@@ -113,7 +260,36 @@ declare function useVFXEmitter(name: any): {
  * @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<react.RefAttributes<any>>;
+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;

package/dist/index.js

@@ -5117,7 +5117,7 @@ ${" ".repeat(indent - 2)}}`;
   }
 });
 
-// src/VFXParticles.jsx
+// src/VFXParticles.tsx
 import {
   forwardRef,
   useImperativeHandle,
@@ -5149,7 +5149,6 @@ import {
   positionLocal,
   cos,
   sin,
-  atan,
   sqrt,
   acos,
   PI,
@@ -5164,7 +5163,7 @@ import {
 import { jsx as jsx2 } from "react/jsx-runtime";
 var Appearance, Blending, EmitterShape, AttractorType, Easing, Lighting, MAX_ATTRACTORS, hexToRgb, toRange, easingToType, axisToNumber, CURVE_RESOLUTION, evaluateBezierSegment, sampleCurveAtX, bakeCurveToArray, createCombinedCurveTexture, toRotation3D, VFXParticles;
 var init_VFXParticles = __esm({
-  "src/VFXParticles.jsx"() {
+  "src/VFXParticles.tsx"() {
     "use strict";
     init_react_store();
     Appearance = Object.freeze({
@@ -5388,10 +5387,11 @@ var init_VFXParticles = __esm({
         ];
       if (Array.isArray(value)) {
         if (Array.isArray(value[0])) {
+          const nested = value;
           return [
-            toRange(value[0], [0, 0]),
-            toRange(value[1], [0, 0]),
-            toRange(value[2], [0, 0])
+            toRange(nested[0], [0, 0]),
+            toRange(nested[1], [0, 0]),
+            toRange(nested[2], [0, 0])
           ];
         }
         const range = toRange(value, [0, 0]);
@@ -5510,7 +5510,7 @@ var init_VFXParticles = __esm({
       debug = false
     }, ref) {
       const { gl: renderer } = useThree();
-      const spriteRef = useRef2();
+      const spriteRef = useRef2(null);
       const initialized = useRef2(false);
       const nextIndex = useRef2(0);
       const [emitting, setEmitting] = useState2(autoStart);
@@ -5618,8 +5618,9 @@ var init_VFXParticles = __esm({
         return [0, 0];
       }, [friction]);
       const frictionEasingType = useMemo(() => {
+        var _a;
         if (typeof friction === "object" && friction !== null && "easing" in friction) {
-          return easingToType(friction.easing);
+          return easingToType((_a = friction.easing) != null ? _a : "linear");
         }
         return 0;
       }, [friction]);
@@ -5850,14 +5851,15 @@ var init_VFXParticles = __esm({
         );
         for (let i = 0; i < MAX_ATTRACTORS; i++) {
           const a = attractorList[i];
+          const u = uniforms;
           if (a) {
-            uniforms[`attractor${i}Pos`].value.set(...(_d = a.position) != null ? _d : [0, 0, 0]);
-            uniforms[`attractor${i}Strength`].value = (_e = a.strength) != null ? _e : 1;
-            uniforms[`attractor${i}Radius`].value = (_f = a.radius) != null ? _f : 0;
-            uniforms[`attractor${i}Type`].value = a.type === "vortex" ? 1 : 0;
-            uniforms[`attractor${i}Axis`].value.set(...(_g = a.axis) != null ? _g : [0, 1, 0]).normalize();
+            u[`attractor${i}Pos`].value.set(...(_d = a.position) != null ? _d : [0, 0, 0]);
+            u[`attractor${i}Strength`].value = (_e = a.strength) != null ? _e : 1;
+            u[`attractor${i}Radius`].value = (_f = a.radius) != null ? _f : 0;
+            u[`attractor${i}Type`].value = a.type === "vortex" ? 1 : 0;
+            u[`attractor${i}Axis`].value.set(...(_g = a.axis) != null ? _g : [0, 1, 0]).normalize();
           } else {
-            uniforms[`attractor${i}Strength`].value = 0;
+            u[`attractor${i}Strength`].value = 0;
           }
         }
         uniforms.attractToCenter.value = attractToCenter ? 1 : 0;
@@ -6729,6 +6731,7 @@ var init_VFXParticles = __esm({
         });
       }, [renderer, computeInit]);
       const applySpawnOverrides = useCallback2(
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         (overrides) => {
           if (!overrides) return null;
           const saved = {};
@@ -6775,15 +6778,16 @@ var init_VFXParticles = __esm({
             saved.gravity = uniforms.gravity.value.clone();
             uniforms.gravity.value.set(...overrides.gravity);
           }
+          const u = uniforms;
           if (overrides.colorStart !== void 0) {
             const colors = overrides.colorStart.slice(0, 8).map(hexToRgb);
             while (colors.length < 8)
               colors.push(colors[colors.length - 1] || [1, 1, 1]);
             setUniform("colorStartCount", overrides.colorStart.length);
             colors.forEach((c, i) => {
-              if (uniforms[`colorStart${i}`]) {
-                saved[`colorStart${i}`] = uniforms[`colorStart${i}`].value.clone();
-                uniforms[`colorStart${i}`].value.setRGB(...c);
+              if (u[`colorStart${i}`]) {
+                saved[`colorStart${i}`] = u[`colorStart${i}`].value.clone();
+                u[`colorStart${i}`].value.setRGB(...c);
               }
             });
           }
@@ -6793,9 +6797,9 @@ var init_VFXParticles = __esm({
               colors.push(colors[colors.length - 1] || [1, 1, 1]);
             setUniform("colorEndCount", overrides.colorEnd.length);
             colors.forEach((c, i) => {
-              if (uniforms[`colorEnd${i}`]) {
-                saved[`colorEnd${i}`] = uniforms[`colorEnd${i}`].value.clone();
-                uniforms[`colorEnd${i}`].value.setRGB(...c);
+              if (u[`colorEnd${i}`]) {
+                saved[`colorEnd${i}`] = u[`colorEnd${i}`].value.clone();
+                u[`colorEnd${i}`].value.setRGB(...c);
               }
             });
           }
@@ -6836,7 +6840,8 @@ var init_VFXParticles = __esm({
       );
       const spawn = useCallback2(
         (x = 0, y = 0, z = 0, count = 20, overrides = null) => {
-          const [px, py, pz] = positionRef.current;
+          var _a;
+          const [px, py, pz] = (_a = positionRef.current) != null ? _a : [0, 0, 0];
           spawnInternal(px + x, py + y, pz + z, count, overrides);
         },
         [spawnInternal]
@@ -6935,6 +6940,7 @@ var init_VFXParticles = __esm({
       const prevGeometryTypeRef = useRef2(null);
       const prevGeometryArgsRef = useRef2(null);
       const handleDebugUpdate = useCallback2(
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         (newValues) => {
           var _a, _b, _c, _d, _e, _f, _g, _h, _i, _j, _k, _l, _m, _n, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _A, _B, _C;
           debugValuesRef.current = __spreadValues(__spreadValues({}, debugValuesRef.current), newValues);
@@ -7407,7 +7413,7 @@ var init_VFXParticles = __esm({
 // src/index.ts
 init_VFXParticles();
 
-// src/VFXEmitter.jsx
+// src/VFXEmitter.tsx
 init_react_store();
 import {
   useRef as useRef3,
@@ -7436,7 +7442,7 @@ var VFXEmitter = forwardRef2(function VFXEmitter2({
   onEmit,
   children
 }, ref) {
-  const groupRef = useRef3();
+  const groupRef = useRef3(null);
   const emitAccumulator = useRef3(0);
   const emitting = useRef3(autoStart);
   const hasEmittedOnce = useRef3(false);
@@ -7446,18 +7452,28 @@ var VFXEmitter = forwardRef2(function VFXEmitter2({
     }
     return useVFXStore.getState().getParticles(name);
   }, [name, particlesRef]);
-  const transformDirectionByQuat = useCallback3((dirRange, quat) => {
-    if (!dirRange) return null;
-    const minDir = _tempVec.set(dirRange[0][0], dirRange[1][0], dirRange[2][0]);
-    minDir.applyQuaternion(quat);
-    const maxDir = new Vector32(dirRange[0][1], dirRange[1][1], dirRange[2][1]);
-    maxDir.applyQuaternion(quat);
-    return [
-      [Math.min(minDir.x, maxDir.x), Math.max(minDir.x, maxDir.x)],
-      [Math.min(minDir.y, maxDir.y), Math.max(minDir.y, maxDir.y)],
-      [Math.min(minDir.z, maxDir.z), Math.max(minDir.z, maxDir.z)]
-    ];
-  }, []);
+  const transformDirectionByQuat = useCallback3(
+    (dirRange, quat) => {
+      const minDir = _tempVec.set(
+        dirRange[0][0],
+        dirRange[1][0],
+        dirRange[2][0]
+      );
+      minDir.applyQuaternion(quat);
+      const maxDir = new Vector32(
+        dirRange[0][1],
+        dirRange[1][1],
+        dirRange[2][1]
+      );
+      maxDir.applyQuaternion(quat);
+      return [
+        [Math.min(minDir.x, maxDir.x), Math.max(minDir.x, maxDir.x)],
+        [Math.min(minDir.y, maxDir.y), Math.max(minDir.y, maxDir.y)],
+        [Math.min(minDir.z, maxDir.z), Math.max(minDir.z, maxDir.z)]
+      ];
+    },
+    []
+  );
   const getEmitParams = useCallback3(() => {
     if (!groupRef.current) {
       return { position, direction };
@@ -7563,7 +7579,10 @@ var VFXEmitter = forwardRef2(function VFXEmitter2({
     }),
     [emit, burst, start, stop, getParticleSystem]
   );
-  return /* @__PURE__ */ jsx3("group", { ref: groupRef, position, children });
+  return (
+    // @ts-expect-error
+    /* @__PURE__ */ jsx3("group", { ref: groupRef, position, children })
+  );
 });
 function useVFXEmitter(name) {
   const getParticles = useVFXStore((s) => s.getParticles);

package/package.json

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