BoidsJS

A highly customizable, lightweight, and performance-oriented library for boids (flocking) simulations. Built with TypeScript and optimized for both Vanilla JavaScript and React environments.

Features

• Multiple Algorithms: Classic Reynolds flocking, optimized 7-nearest neighbor selection, and dynamic Flow Fields.
• Environment Interaction: Built-in support for predators and mouse interactions (attraction/repulsion).
• Visualization Aids: Integrated noise map rendering and flow line visualizations for debugging and aesthetics.
• React Support: First-class React wrapper component for seamless integration into modern web apps.
• Performant: Minimal overhead with zero dependencies for core logic.

Installation

npm install @individual11/boidsjs
# or
yarn add @individual11/boidsjs

Basic Usage (Vanilla JS)

import { Engine } from '@individual11/boidsjs';

const canvas = document.getElementById('myCanvas');
const engine = new Engine({
  canvas: canvas,
  boidCount: 150,
  algorithm: 'reynolds',
  color: '#22d3ee'
});

engine.run();

Advanced Config

The Engine constructor accepts a wide range of options:

Core Configuration

| Property | Type | Default | Description | | :--- | :--- | :--- | :--- | | canvas | HTMLCanvasElement | - | Required. The canvas element to render on. | | width | number | - | Width of the simulation area. | | height | number | - | Height of the simulation area. | | boidCount | number | 50 | Total number of boids in simulation. | | color | string | "#22d3ee" | Color of the boids. | | shape | 'triangle' \| 'circle' \| 'line' | 'triangle' | Visual shape of the boids. | | boidSize | number | 5 | Size of the boids in pixels. |

Physics & Behavior

| Property | Type | Default | Description | | :--- | :--- | :--- | :--- | | algorithm | 'reynolds' \| 'optimized' \| 'flow-field' | 'reynolds' | The flocking algorithm to use. | | maxSpeed | number | 4 | Maximum velocity of a boid. | | minSpeed | number | 2 | Minimum velocity of a boid. | | maxForce | number | 0.1 | Stability/steering strength. | | reynoldsOptions | object | - | See Reynolds Options | | flowFieldOptions | object | - | See Flow Field Options |

Interactions

| Property | Type | Default | Description | | :--- | :--- | :--- | :--- | | mouseInteraction | 'none' \| 'attract' \| 'repulse' | 'none' | Mouse interaction mode. | | mouseRadius | number | 150 | Influence radius for mouse interaction. | | predatorCount| number | 0 | Number of predators to avoid. |

Visual Aids (Flow Field)

| Property | Type | Default | Description | | :--- | :--- | :--- | :--- | | showFlowField | boolean | false | Visualize the underlying flow lines. | | showNoiseBackground| boolean | false | Visualize the underlying noise map. | | flowFieldColor | string | "rgba(255,255,255,0.1)" | Color of the flow lines. | | noiseSpeed | number | 0.003 | Evolution speed of the noise field. |

Hooks & Callbacks

| Property | Type | Description | | :--- | :--- | :--- | | onFrame | () => void | Callback executed on every animation frame. |

Reynolds Options

| Property | Type | Default | Description | | :--- | :--- | :--- | :--- | | perceptionRadius | number | 50 | Radius within which boids consider others as neighbors. | | alignmentWeight | number | 1.0 | How strongly boids try to match neighbor velocity. | | cohesionWeight | number | 1.0 | How strongly boids try to stay close to neighbors. | | separationWeight | number | 1.0 | How strongly boids try to avoid each other. |

Flow Field Options

| Property | Type | Default | Description | | :--- | :--- | :--- | :--- | | scale | number | 0.003 | Density of the flow field noise (lower = smoother). | | strength | number | 0.25 | How strongly the field affects boid velocity. |

Roadmap

Curious about what's coming next? Check out our Roadmap for planned features like Spatial Hashing optimizations and new steering behaviors.

React Support

We provide a dedicated React component for easy integration:

import { BoidsJS } from '@individual11/boidsjs/react';

const MyComponent = () => (
  <BoidsJS 
    boidCount={100} 
    algorithm="flow-field" 
    showFlowField={true} 
  />
);

For more details, see the React Guide.

Development

# Install dependencies
yarn install

# Run demo app
yarn dev

# Build library
yarn build

License

MIT