react-particle-physics 1.0.0

package/BEST_PRACTICES.md

@@ -0,0 +1,45 @@
+# Particle Engine Architecture & Best Practices
+
+This library achieves 60fps rendering of 100k+ particles on mobile hardware by heavily offloading work to the GPU and entirely bypassing React's render lifecycle during active animation.
+
+Here are the core architectural best practices and shader logic we extracted from the project:
+
+## 1. Zero React Overhead (The Uniform Mutation Pattern)
+React Three Fiber's `useFrame` hook gives us direct access to the render loop. However, updating React state inside this loop causes constant re-rendering, completely destroying performance.
+
+**Practice**: We never store animation frames or pointer coordinates in React `useState`. Instead, we hold a `useMemo` reference to the `THREE.ShaderMaterial` and mutate `material.uniforms` directly inside `useFrame`. 
+
+```ts
+// INSIDE useFrame (Runs 60x per second)
+// Do NOT call setX() or setState()
+particleMaterial.uniforms.uTime.value = clock.elapsedTime;
+particleMaterial.uniforms.uPointer.value.copy(pointerCurrent.current);
+```
+
+## 2. Ping-Pong FBO Physics (GPU Trail Buffer)
+To calculate fluid-like displacement, particles need to know not just where the cursor *is*, but where it *was*. Running this physics simulation on the CPU for 100k particles is too slow.
+
+**Practice**: We use a **Ping-Pong Framebuffer Object (FBO)**.
+1. We set up an invisible offscreen scene containing a 2D quad and a custom shader (`trailFragmentShader.glsl`).
+2. We maintain two render targets (`write` and `read`).
+3. Every frame, we render the current pointer position onto the `write` target, blending it over the `read` target (which holds the previous frame).
+4. We multiply the color value by a `uDecay` value to slowly fade out old pointer coordinates over time.
+5. We swap the `read` and `write` buffers, and pass the `read` texture into the main particle shader.
+
+The particle vertex shader then looks up its own UV coordinate inside this trail texture to see if the fluid has been disturbed nearby, displacing its `gl_Position` on the GPU.
+
+## 3. BufferGeometry & Typed Arrays
+Instancing individual `THREE.Mesh` objects is too expensive. 
+
+**Practice**: We use a single `THREE.Points` or `THREE.LineSegments` draw call.
+During the one-time `sampleImageToParticles` pass, we parse the 2D image canvas and construct flat `Float32Array` objects for positions, colors, UVs, and seeds.
+
+```ts
+const positions = new Float32Array(particleCount * 3);
+```
+We inject these directly into a `THREE.BufferGeometry`. This maps the data directly into GPU memory, allowing the WebGL instance to render the entire scene in one extremely efficient draw call.
+
+## 4. Hardware Scaling
+**Practice**: We use dynamic pixel ratios. 
+`Math.min(window.devicePixelRatio || 1, 2)`
+This caps rendering to a maximum pixel ratio of 2, preventing high-density screens (like iPhone Pro Max 3x screens) from crashing due to over-rendering 100k particles at 3x resolution. We also keep `frustumCulled={false}` because the displacement shaders move vertices outside their original bounding box.

package/README.md

@@ -0,0 +1,42 @@
+# React Particle Physics
+
+A high-performance WebGL physics engine for React Three Fiber that converts images into interactive particle clouds and topographic lines. 
+
+Features 60fps performance on mobile, GPU-accelerated interaction, ping-pong fluid trails, and zero React overhead on the main render loop.
+
+## Installation
+
+```bash
+npm install react-particle-physics three @react-three/fiber
+```
+
+## Usage
+
+```tsx
+import { Canvas } from '@react-three/fiber';
+import { ParticleSystem } from 'react-particle-physics';
+
+export default function App() {
+  return (
+    <Canvas camera={{ position: [0, 0, 2.5] }}>
+      <ParticleSystem 
+        image="/path/to/logo.png"
+        particleCount={50000}
+        interactionRadius={0.25}
+        sampleMode="alpha" 
+      />
+    </Canvas>
+  );
+}
+```
+
+## Available Components
+
+### `<ParticleSystem />`
+Generates a `THREE.Points` particle cloud mapped to the brightness/alpha data of an input image.
+
+### `<LineSystem />`
+Generates a `THREE.LineSegments` topographic heightmap based on the luminance of the input image.
+
+### `sampleLogoToParticles`
+Headless utility to parse an image via 2D Canvas context and map it to `Float32Arrays` for injection into WebGL BufferGeometries.

package/dist/LineSystem.d.ts

@@ -0,0 +1,29 @@
+import type { ParticleSampleMode } from './sampleLogoToParticles';
+export type LineSystemProps = {
+    /** The URL or data URI of the image to sample */
+    image: string;
+    /** Approximate number of horizontal lines to generate */
+    lineCount?: number;
+    /** Rendering width of the lines */
+    lineWidth?: number;
+    /** Vertical displacement intensity from luminance */
+    lineAmplitude?: number;
+    /** How pixels are sampled */
+    sampleMode?: ParticleSampleMode;
+    /** Threshold for edge detection */
+    edgeThreshold?: number;
+    /** Line colors */
+    particleColor?: string;
+    colorMode?: 'base' | 'random' | 'original';
+    glowIntensity?: number;
+    opacityVariation?: number;
+    /** Physics and interaction */
+    interactionRadius?: number;
+    displacementStrength?: number;
+    /** Destruct sequence */
+    isDestructing?: boolean;
+    onDestructComplete?: () => void;
+    /** Callback when loading state changes */
+    onLoadStatus?: (isLoading: boolean, error: string | null) => void;
+};
+export declare function LineSystem({ image, lineCount, lineWidth, lineAmplitude, interactionRadius, displacementStrength, sampleMode, edgeThreshold, particleColor, colorMode, glowIntensity, opacityVariation, isDestructing, onDestructComplete, onLoadStatus, }: LineSystemProps): import("react").JSX.Element | null;

package/dist/ParticleSystem.d.ts

@@ -0,0 +1,32 @@
+import * as THREE from 'three';
+import { type ParticleSampleMode } from './sampleLogoToParticles';
+export type ParticleSystemProps = {
+    /** The URL or data URI of the image to sample */
+    image: string;
+    /** Number of particles to sample (default: 50000) */
+    particleCount?: number;
+    /** How pixels are sampled from the image */
+    sampleMode?: ParticleSampleMode;
+    /** Thresholds for sampling */
+    alphaThreshold?: number;
+    lumaThreshold?: number;
+    edgeThreshold?: number;
+    /** Particle appearance */
+    particleSize?: number;
+    particleColor?: string;
+    colorMode?: 'base' | 'random' | 'original';
+    glowIntensity?: number;
+    opacityVariation?: number;
+    /** Physics and interaction */
+    interactionRadius?: number;
+    displacementStrength?: number;
+    trailStrength?: number;
+    /** Destruct sequence */
+    isDestructing?: boolean;
+    onDestructComplete?: () => void;
+    /** Callback ref for the underlying THREE.Points mesh */
+    onPointsRef?: (ref: THREE.Points | null) => void;
+    /** Callback when loading state changes */
+    onLoadStatus?: (isLoading: boolean, error: string | null) => void;
+};
+export declare function ParticleSystem({ image, particleCount, interactionRadius, displacementStrength, particleSize, trailStrength, sampleMode, alphaThreshold, lumaThreshold, edgeThreshold, particleColor, colorMode, glowIntensity, opacityVariation, isDestructing, onDestructComplete, onPointsRef, onLoadStatus, }: ParticleSystemProps): import("react").JSX.Element | null;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { ParticleSystem, type ParticleSystemProps } from './ParticleSystem';
+export { LineSystem, type LineSystemProps } from './LineSystem';
+export { sampleLogoToParticles, type ParticleSample, type ParticleSampleMode } from './sampleLogoToParticles';
+export { detectPerformanceTier, getPresetSettings, type PerformanceTier } from './performance';