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



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:

  • Wander: run around aimlessly in search for food
  • Follow: if a pheromone trail is encountered, follow it to the food
  • Harvest: if food is nearby, collect it
  • Hoard: when carrying food, head straight home leaving a trail of scent


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

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:

  • colony.foodsources: a list of food objects in the surrounding area.
  • colony.food: a number representing the units of food the ants have harvested.
  • colony.x: the horizontal center of the colony.
  • colony.y: the vertical center of the colony.
  • colony.r: the radius of the colony.


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:

  • ant.x: the horizontal position of the ant.
  • ant.y: the vertical position of the ant.
  • ant.has_food: will be True when the ant is carrying food back to the colony.
  • ant.trail: a list of pheromone objects the ant uses to mark a path from a food source to the colony.
  • ant.wandering: the number of rounds an ant has been wandering around. If it exceeds the radius of the colony, the ant will return to the colony.

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.