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