1. NodeBox 1
    1. Homepage
    2. NodeBox 3Node-based app for generative design and data visualization
    3. NodeBox OpenGLHardware-accelerated cross-platform graphics library
    4. NodeBox 1Generate 2D visuals using Python code (Mac OS X only)
  2. Gallery
  3. Documentation
  4. Forum
  5. Blog



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:

  • Separation: steer to avoid crowding local flockmates
  • Alignment: steer towards the average heading of local flockmates
  • Cohesion: steer to move towards the average position of local flockmates

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.


downloadboids.zip (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 NodeBox can find the library. You can also put it in ~/Library/Application Support/NodeBox/.

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:

  • flock.scattered:will be True when the flock is scattered in confusion.
  • flock.has_goal: will be True if the flock is thronging around a certain point of interest.
  • flock.flee: will be True if the flock has a goal, but is actually running away from it.

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:

  • boid.x: the horizontal position of the boid.
  • boid.y: the vertical position of the boid.
  • boid.z: the depth of the boid.
  • boid.angle: the boid's current heading.
  • boid.is_perching: will be True when the boid is resting on the ground.