API1:Events

Events represent various triggers in the life of an individual ant. They enable you to write code that can react to these triggers. For example, an event could be something like “sees sugar”. The ant might react to it via the command “go to sugar”.

(Events from versions older than 1.7.3 are available at Old Events.)

Movement

In order to make the ant move, it needs events that occur independently of its surroundings.

Event	Description
Waiting	If the ant has no assigned tasks, it waits for new tasks. This method is called to inform you that it is waiting.
GettingTired	This method is called when an ant has travelled one third of its movement range.
HasDied	This method is called if an ant dies. It informs you that the ant has died. The ant cannot undertake any more actions from that point forward.
Tick	This method is called in every simulation round, regardless of additional conditions. It is ideal for actions that must be executed but that are not addressed by other methods.

Food

Events relating to seeing/detecting food items and reaching the location of food.

Event	Description
Spots(Fruit)	This method is called as soon as an ant sees an apple within its 360° visual range. The parameter is the piece of fruit that the ant has spotted.
Spots(Sugar)	This method is called as soon as an ant sees a mound of sugar in its 360° visual range. The parameter is the mound of sugar that the ant has spotted.
DestinationReached(Fruit)	If the ant’s destination is a piece of fruit, this method is called as soon as the ant reaches its destination. It means that the ant is now near enough to its destination/target to interact with it.
DestinationReached(Sugar)	If the ant’s destination is a mound of sugar, this method is called as soon as the ant has reached its destination. It means that the ant is now near enough to its destination/target to interact with it.

Communication

These events concern situations related to interactions with other ants.

Event	Description
DetectedScentFriend(Marker)	Friendly ants can detect markers left by other ants. This method is called when an ant smells a friendly marker for the first time.
SpotsFriend(Ant)	Just as ants can see various types of food, they can also visually detect other game elements. This method is called if the ant sees an ant from the same colony.
SpotsTeammate(Ant)	Just as ants can see various types of food, they can also visually detect other game elements. This method is called if the ant detects an ant from a friendly colony (an ant on the same team).

Combat

Unfortunately, sometimes the ants have to fight. These events occur when enemies are sighted or when the ant is involved in combat.

Event	Description
SpotsEnemy(Ant)	Just as ants can see various types of food, they can also visually detect other game elements. This method is called if the ant detects an ant from an enemy colony.
SpotsEnemy(Bug)	Just as ants can see various types of food, they can also visually detect other game elements. This method is called if the ant sees a bug.
UnderAttack(Ant)	Enemy creatures may actively attack the ant. This method is called if an enemy ant attacks; the ant can then decide how to react.
UnderAttack(Bug)	Enemy creatures may actively attack the ant. This method is called if a bug attacks; the ant can decide how to react.

Castes

The caste section contains methods related to selecting and controlling the casts your ants belong to.

Event	Description
ChooseCaste	Every time that a new ant is born, its job group must be set. You can do so with the help of the value returned by this method.