@kairos/particles

GPU particle engine for React Three Fiber — adaptive breathing, emergent geometry, and multi-shape WebGL shaders.

Features

• Adaptive breathing — particle field breathes at 0.3–2.0 Hz based on real system load and RAM usage
• Emergent geometry — nodes cluster into geometric shapes driven by live data metrics
• Multiple shapes — sphere, cube, torus, DNA helix
• 4D Clifford rotation — organs turn inside-out organically in the organism view
• Zero dependencies beyond peer deps — ships as ESM + CJS with full TypeScript types

Install

npm install @kairos/particles

Peer dependencies:

npm install react react-dom three @react-three/fiber @react-three/drei

Usage

import { ParticleField, ParticleGraph } from '@kairos/particles';

// Basic adaptive breathing field
function Scene() {
  return (
    <Canvas>
      <ParticleField
        count={4000}
        size={0.015}
        systemLoad={65}   // 0-100: drives breath frequency
        ramPercent={42}   // 0-100: drives breath amplitude
      />
    </Canvas>
  );
}

// Graph with emergent clusters
import { ParticleGraph } from '@kairos/particles';

function GraphScene({ nodes, edges }) {
  return (
    <Canvas>
      <ParticleGraph
        nodes={nodes}
        edges={edges}
        particleCount={2000}
        seed={42}
      />
    </Canvas>
  );
}

API

ParticleField

| Prop | Type | Default | Description | |------|------|---------|-------------| | count | number | 4000 | Number of particles | | size | number | 0.015 | Point size | | systemLoad | number | 0 | CPU load 0–100 → breath frequency | | ramPercent | number | 0 | RAM % 0–100 → breath amplitude |

ParticleGraph

Renders a force-directed graph as a particle system with emergent geometric clustering.

Geometry utilities

import { sphere, cube, torus, dna, generatePositions } from '@kairos/particles';
import { generateEmergentPositions, calculateParticleCount } from '@kairos/particles';

License

Apache-2.0 — see LICENSE