The Boids library provides features to implement coordinated animal motion such as bird flocks and fish schools. The code is based on Craig W. Reynolds flocking model and Conrad Parker’s pseudocode.

Essentially, a boid, a single element in the flock, has three simple steering behaviours:

The beauty of it is that the flock doesn’t have a predefined flight path, or any math describing its motion; a flock is totally and naturally self-organising.


download (5KB)
Last updated for NodeBox 1.9.2
Licensed under GPL
Author: Tom De Smedt



Play movie


How to get the library up and running

Put the boids library folder in the same folder as your script so PlotDevice can find the library. You can also put it in ~/Library/Application Support/PlotDevice/.

boids = ximport("boids")

Creating a flock

The flock() command returns a new flock consisting of n boids, that are caged in area starting at coordinates x and y and having a width w and height h.

flock(n, x, y, w, h)

The returned flock object has a number of properties:

The returned flock object also has a number of methods. The primary method is flock.update(), which you usually call at each frame in an animation:

             separation=10, alignment=5, cohension=100,
             goal=20, limit=30)

Each time flock.update() is called, the boids move another step in their flight pattern. There are six optional parameters. By default the flock is shuffled to ensure fluid movement of all individual boids. You can play around with the other parameters to get different flocking behavior.

flock.scatter(chance=0.005, frames=50)
flock.perch(ground=None, chance=1.0, frames=lambda:25+random(50))
flock.goal(x, y, z, flee=False)

The flock.scatter() method undoes the boids’s cohesion and alignment. The flock has a chance between 0.0 and 1.0 each of scattering during each update. Once scattered, the confusion lasts the given number of frames.

The flock.perch() method controls the boids’s resting behavior. Boids whose y-position becomes larger than ground have a chance between 0.0 and 1.0 of resting. Usually, chance is 1.0: when you hit the ground you can’t continue flying, a chance less than 1.0 would indicate water. A boid will rest for the given number of frames.

The flock.goal() method defines a point the flock finds interesting and has a tendency to move towards, and crowd around. The flock.nogoal() method removes the current goal.


The boids in a flock

A flock object returned from the flock() command is a list of individual boids. You can easily loop through it:

flock = boids.flock(10, 0, 0, WIDTH, HEIGHT)
for boid in flock:
    print boid.x, boid.y

Each boid object has a number of useful properties: