@wolffo/three-fire 1.0.7 → 1.1.0

package/README.md

@@ -27,13 +27,27 @@ Modern TypeScript volumetric fire effect for Three.js and React Three Fiber.
 npm install @wolffo/three-fire
 ```
 
+## Entry Points Summary
+
+This package provides separate entry points to optimize bundle size and avoid unnecessary dependencies:
+
+| Entry Point | Use Case | Bundle Size | Dependencies |
+|-------------|----------|-------------|--------------|
+| `@wolffo/three-fire/vanilla` | Vanilla Three.js projects | Smallest | Only Three.js |
+| `@wolffo/three-fire/react` | React Three Fiber projects | Medium | React + Three.js |
+| `@wolffo/three-fire` | Legacy/mixed usage | Largest | All dependencies |
+
+**⚠️ Migration Notice**: For better performance, migrate from the main entry point to specific entry points:
+- Vanilla Three.js users → use `/vanilla`
+- React Three Fiber users → use `/react`
+
 ## Usage
 
 ### React Three Fiber (Recommended)
 
 ```tsx
 import { Canvas } from '@react-three/fiber'
-import { Fire } from '@wolffo/three-fire'
+import { Fire } from '@wolffo/three-fire/react'
 
 function App() {
   return (
@@ -52,7 +66,7 @@ function App() {
 ### With custom parameters
 
 ```tsx
-import { Fire, useFire } from '@wolffo/three-fire'
+import { Fire, useFire } from '@wolffo/three-fire/react'
 
 function CustomFire() {
   const fireRef = useFire()
@@ -79,7 +93,7 @@ function CustomFire() {
 ### Vanilla Three.js
 
 ```ts
-import { FireMesh } from '@wolffo/three-fire'
+import { FireMesh } from '@wolffo/three-fire/vanilla'
 import { Scene, TextureLoader } from 'three'
 
 const scene = new Scene()
@@ -109,6 +123,15 @@ function animate() {
 animate()
 ```
 
+### Legacy Usage (Backward Compatibility)
+
+⚠️ **Not recommended for new projects** - use specific entry points above for better performance.
+
+```ts
+// Legacy import - includes all dependencies
+import { FireMesh, Fire } from '@wolffo/three-fire'
+```
+
 ## API Reference
 
 ### FireComponent Props
@@ -148,7 +171,7 @@ class FireMesh extends Mesh {
 
 You need to provide a fire texture similar to the one shown below:
 
-![firetex](./src/Fire.png "Fire texture")
+![firetex](./src/Fire-grayscale.png "Fire texture")
 
 The texture should be a grayscale gradient that defines the fire's density distribution.
 

package/dist/react.d.ts

@@ -0,0 +1,262 @@
+import React from 'react';
+import { ReactThreeFiber } from '@react-three/fiber';
+import { Texture, Color, Matrix4, Vector3, Vector4, Mesh, ShaderMaterial } from 'three';
+
+/**
+ * Uniforms interface for the fire shader
+ */
+interface FireShaderUniforms {
+    /** Fire texture (grayscale mask) */
+    fireTex: {
+        value: Texture | null;
+    };
+    /** Fire color tint */
+    color: {
+        value: Color;
+    };
+    /** Current time for animation */
+    time: {
+        value: number;
+    };
+    /** Random seed for fire variation */
+    seed: {
+        value: number;
+    };
+    /** Inverse model matrix for ray marching */
+    invModelMatrix: {
+        value: Matrix4;
+    };
+    /** Scale of the fire object */
+    scale: {
+        value: Vector3;
+    };
+    /** Noise scaling parameters [x, y, z, time] */
+    noiseScale: {
+        value: Vector4;
+    };
+    /** Fire shape intensity */
+    magnitude: {
+        value: number;
+    };
+    /** Noise lacunarity (frequency multiplier) */
+    lacunarity: {
+        value: number;
+    };
+    /** Noise gain (amplitude multiplier) */
+    gain: {
+        value: number;
+    };
+}
+
+/**
+ * Properties for creating a Fire instance
+ */
+interface FireProps$1 {
+    /** Fire texture (grayscale mask defining fire shape) */
+    fireTex: Texture;
+    /** Fire color tint (default: 0xeeeeee) */
+    color?: Color | string | number;
+    /** Ray marching iterations - higher = better quality, lower performance (default: 20) */
+    iterations?: number;
+    /** Noise octaves for turbulence (default: 3) */
+    octaves?: number;
+    /** Noise scaling parameters [x, y, z, time] (default: [1, 2, 1, 0.3]) */
+    noiseScale?: [number, number, number, number];
+    /** Fire shape intensity (default: 1.3) */
+    magnitude?: number;
+    /** Noise lacunarity - frequency multiplier (default: 2.0) */
+    lacunarity?: number;
+    /** Noise gain - amplitude multiplier (default: 0.5) */
+    gain?: number;
+}
+/**
+ * Volumetric fire effect using ray marching shaders
+ *
+ * Creates a procedural fire effect that renders as a translucent volume.
+ * The fire shape is defined by a grayscale texture, with white areas being
+ * the most dense part of the fire.
+ *
+ * @example
+ * ```ts
+ * const texture = textureLoader.load('fire.png')
+ * const fire = new Fire({
+ *   fireTex: texture,
+ *   color: 0xff4400,
+ *   magnitude: 1.5
+ * })
+ * scene.add(fire)
+ *
+ * // In animation loop
+ * fire.update(time)
+ * ```
+ */
+declare class Fire extends Mesh {
+    material: ShaderMaterial & {
+        uniforms: FireShaderUniforms;
+    };
+    private _time;
+    /**
+     * Creates a new Fire instance
+     *
+     * @param props - Configuration options for the fire effect
+     */
+    constructor({ fireTex, color, iterations, octaves, noiseScale, magnitude, lacunarity, gain, }: FireProps$1);
+    /**
+     * Updates the fire animation and matrix uniforms
+     *
+     * Call this method in your animation loop to animate the fire effect.
+     *
+     * @param time - Current time in seconds (optional)
+     *
+     * @example
+     * ```ts
+     * function animate() {
+     *   fire.update(performance.now() / 1000)
+     *   renderer.render(scene, camera)
+     *   requestAnimationFrame(animate)
+     * }
+     * ```
+     */
+    update(time?: number): void;
+    /**
+     * Current animation time in seconds
+     */
+    get time(): number;
+    set time(value: number);
+    /**
+     * Fire color tint
+     *
+     * @example
+     * ```ts
+     * fire.fireColor = 'orange'
+     * fire.fireColor = 0xff4400
+     * fire.fireColor = new Color(1, 0.5, 0)
+     * ```
+     */
+    get fireColor(): Color;
+    set fireColor(color: Color | string | number);
+    /**
+     * Fire shape intensity
+     *
+     * Higher values create more dramatic fire shapes.
+     * Range: 0.5 - 3.0, Default: 1.3
+     */
+    get magnitude(): number;
+    set magnitude(value: number);
+    /**
+     * Noise lacunarity (frequency multiplier)
+     *
+     * Controls how much the frequency increases for each noise octave.
+     * Range: 1.0 - 4.0, Default: 2.0
+     */
+    get lacunarity(): number;
+    set lacunarity(value: number);
+    /**
+     * Noise gain (amplitude multiplier)
+     *
+     * Controls how much the amplitude decreases for each noise octave.
+     * Range: 0.1 - 1.0, Default: 0.5
+     */
+    get gain(): number;
+    set gain(value: number);
+}
+
+declare module '@react-three/fiber' {
+    interface ThreeElements {
+        fire: ReactThreeFiber.Object3DNode<Fire, typeof Fire>;
+    }
+}
+/**
+ * Props for the Fire React component
+ */
+interface FireProps extends Omit<FireProps$1, 'fireTex'> {
+    /** Fire texture URL or Three.js Texture object */
+    texture: string | Texture;
+    /** Auto-update time from useFrame (default: true) */
+    autoUpdate?: boolean;
+    /** Custom update function called each frame */
+    onUpdate?: (fire: Fire, time: number) => void;
+    /** Child components */
+    children?: React.ReactNode;
+    /** Position in 3D space */
+    position?: [number, number, number];
+    /** Rotation in radians */
+    rotation?: [number, number, number];
+    /** Scale factor (uniform or per-axis) */
+    scale?: [number, number, number] | number;
+}
+/**
+ * Ref interface for imperative fire control
+ */
+interface FireRef {
+    /** Fire mesh instance */
+    fire: Fire | null;
+    /** Update fire animation manually */
+    update: (time?: number) => void;
+}
+/**
+ * React Three Fiber component for volumetric fire effect
+ *
+ * Creates a procedural fire effect that can be easily integrated into R3F scenes.
+ * The component automatically handles texture loading, animation updates, and
+ * provides props for all fire parameters.
+ *
+ * @example
+ * ```tsx
+ * <Canvas>
+ *   <Fire
+ *     texture="/fire.png"
+ *     color="orange"
+ *     magnitude={1.5}
+ *     scale={[2, 3, 2]}
+ *     position={[0, 0, 0]}
+ *   />
+ * </Canvas>
+ * ```
+ *
+ * @example With custom animation
+ * ```tsx
+ * <Fire
+ *   texture="/fire.png"
+ *   onUpdate={(fire, time) => {
+ *     fire.fireColor.setHSL((time * 0.1) % 1, 1, 0.5)
+ *   }}
+ * />
+ * ```
+ */
+declare const FireComponent: React.ForwardRefExoticComponent<FireProps & React.RefAttributes<FireRef>>;
+/**
+ * Hook for easier access to fire instance and controls
+ *
+ * Provides a ref and helper methods for controlling fire imperatively.
+ *
+ * @returns Object with ref, fire instance, and update method
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const fireRef = useFire()
+ *
+ *   const handleClick = () => {
+ *     if (fireRef.fire) {
+ *       fireRef.fire.magnitude = 2.0
+ *     }
+ *   }
+ *
+ *   return (
+ *     <Fire ref={fireRef.ref} texture="/fire.png" />
+ *   )
+ * }
+ * ```
+ */
+declare const useFire: () => {
+    /** Ref to pass to Fire component */
+    ref: React.RefObject<FireRef>;
+    /** Fire mesh instance (null until mounted) */
+    fire: Fire | null;
+    /** Update fire animation manually */
+    update: (time?: number) => void | undefined;
+};
+
+export { FireComponent as Fire, useFire };
+export type { FireProps, FireRef };