Now you can have Your Own Digital Antfarm (YODA) too! The Ants library provides easy-to-understand tools to implement cooperative foraging behaviour for small animals like ants. Ants in real-life are pretty cool. They work together in a social context, communicating by means of pheromone scent. Ants are capable of finding food, building burial grounds, even herding caterpillars (led to feeding areas in the daytime, and brought inside the ants’ nest at night)!

Essentially, an ant in the Ants library has four simple behaviours:


download (4KB)
Last updated for NodeBox 1.9.1.
Author: Tom De Smedt



Play movie


How to get the library up and running

Put the ants 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/.

ants = ximport("ants")

Creating a colony

The colony() command returns a new community consisting of n ants with an operating radius of r, and located at coordinates x and y.

colony(n, x, y, r)

The returned colony object has a number of properties:


The ants in a colony

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

colony = ants.colony(30, WIDTH/2, HEIGHT/2, 200)
for ant in colony:
    print ant.x, ant.y

Each ant object has a number of useful properties:

Each ant object also has a number of methods. The primary method is ant.forage(), which you usually call each frame in an animation to have the ant search for food.


The other methods contain the ant AI for wandering, trailing and harvesting. Check the source code.


This method sets the object obj, which has x and y properties, as a goal for the ant. The ant starts moving towards it. This low-level ant command allows you to modify the ant’s behaviour by defining custom goals.

ant.near(obj, radius=10)

This command checks if something is nearby. If the object’s x and y properties are within the radius of the ant, returns True. This low-level ant command allows you to modify the ant’s behaviour by defining custom behaviour when reaching a goal.



The food() command creates a new heap of food for the ants to harvest. When you add it to the foodsources list in the colony, the ants can find it:

food(x, y, size)
for i in range(8):
    x = 50 + random(WIDTH-100)
    y = 50 + random(HEIGHT-100)
    s = random(20,40)


The ant.trail list contains pheromones the ants use to mark a path between a source of food and their home. A pheromone object has an x and y position, a strength and an evaporate() method that diminishes its strength. The stronger the smell of a pheromone the more an ant will be attracted to it.