API1:Commands

From AntMe! Wiki
Jump to: navigation, search

Your ants understand you! But their vocabulary isn’t that large. The possibilities for communicating with them are listed below.

(Commands for versions older than 1.7.3 are available at Old Commands.)

Methods

Movement

The unit of length for the following commands is steps. For reference: an ant is four steps long and the map for a single-player game measures 1200 x 900 steps.

Method Description
GoForward The ant moves forward. The ant’s destination remains unaltered. If a value is specified, the ant will aim for its destination again as soon as it has travelled the specified distance.
GoToDestination The ant saves the specified destination and walks to it.
GoAwayFrom The ant turns in the direction opposite the specified destination and then walks straight ahead. The ant’s destination remains unaltered and the walking distance can be specified.
GoToAnthill The ant saves the nearest anthill as its destination and walks towards it.
Stop The ant stands still and forgets its current destination. In the next round the result of Waiting() is called.

Rotation

All values are specified as whole angles measured in degrees proceeding clockwise. 0 thus means right, 90 is down, 180 is left, 270 is up and 360 is right again. The values do not need to be between 0 and 359. Larger or smaller values will be recalculated automatically.

For an ant, turning always takes precedence over moving. Thus, if an ant receives a “turn” command before it has finished executing a “go” command, the “go” command will be interrupted, the “turn” command will be executed instead, and then the “go” command will be resumed. An ant cannot turn and walk at the same time.

Method Description
TurnToDirection The ant turns in the specified direction. The angle around which it turns is determined automatically.
TurnByDegrees The ant turns itself around the specified angle. Positive values turn the ant to the right, negative values turn it to the left.
TurnAround The ant turns 180 degrees in the opposite direction. Has the same effect as TurnByDegrees(180).
TurnToDestination The ant turns in the direction of the specified destination.

Food

AntMe! has two different food sources: sugar and apples (or fruit). Both can be picked up with the Take command, but they have different effects on the ant’s properties. Sugar is divided into individual cubes and each cube causes an increase in CurrentLoad. Apples, on the other hand, must be carried by several ants and can be recognized by the property CarryingFruit.

Method Description
Take The ant picks up the specified food. In the case of a mound of sugar, it takes as much as possible until it reaches its maximum load (see CurrentLoad and MaximumLoad). In the case of a piece of fruit, the ant begins carrying the fruit (see CarryingFruit).
Drop The ant drops the food that it is currently carrying. Sugar is lost while apples remain where they fall and can be picked up again later. The command is not necessary when delivering food to an anthill - that occurs automatically.

Communication

Markers are the primary means of communication for ants. Ants that want to communicate something to other ants use markers to pass on information.

Method Description
MakeMark The ant sprays a scent marker at the current location. The possible parameters are data contained in the marker (these can be read out of the result of Spots(Marker) via marker.Information) and how far the maker spreads out. The farther the marker spreads out, the faster it will disappear.

Combat

AntMe! is a peaceful approach to learning how to code, but even in this game, ants and programmers alike have to face their natural enemies—bugs. It is possible to actively attack bugs and enemy ants. You’ll find more information about combat on the Ant Development page.

Method Description
Attack The ant saves the specified bug or the specified enemy ant as its destination and walks toward it. When the ant arrives at its destination, it begins to fight.

Debug

If your ants aren’t doing what they’re supposed to, there are a couple of resources you can use to try to find out why. AntMe! provides some special tools in addition to those included in Visual Studio.

Method Description
Think This command causes the ant to display thought bubbles that can be used for troubleshooting and debugging.

Properties

Properties allow you to examine the conditions and values of ants and other game elements.

Caste-Related

The following values of an ant are determined by its caste.

Property Description
MaximumEnergy Returns the ant’s maximum energy. The unit is hit points.
MaximumSpeed Returns the ant’s maximum speed. The unit is steps per round.
MaximumLoad Returns the maximum load that the ant can bear. The unit is food points. This value determines how much sugar the ant can carry at once and how fast it can carry an apple without the help of other ants.
Range Specifies the distance in steps that the ant can travel before it dies of hunger. After the ant has travelled a third of the value, the event GettingTired() is called and the value of IsTired is set to “true”. (See WalkedRange).
Strength Specifies the ant's attack value. The attack value determines how many hit points the ant deducts from an enemy in each round. The unit is hit points.
Viewrange Specifies the ant’s visual range in steps. This range determines how far the ant must be from game elements like sugar in order for the ant to see them. The direction that the ant is facing does not play a role (ants have 360 vision in this game).
RotationSpeed Specifies the speed with which an ant can turn. The unit is degrees per round.

Misc

Property Description
CurrentEnergy Returns the ant’s current energy. The unit is hit points. If an ant has 0 hit points or fewer, it dies. This value is always less than or equal to MaximumEnergy.
CurrentSpeed Returns the ant’s current possible speed. The unit is steps per round. The value is influenced by the ant’s current load. Ants that are carrying a full load can only travel at half of their maximum speed. The property always returns a value greater than 0, even if the ant is standing still. This value is always less than or equal to MaximumSpeed.
CurrentLoad Returns the weight of the load that the ant is currently carrying. The unit is food points. This value is always smaller than or equal to MaximumLoad.
BugsInViewrange Returns the number of bugs in the ant’s 360° visual range. The result of this calculation depends on the ant’s visual range.
ForeignAntsInViewrange Returns the number of enemy ants in the ant’s 360° visual range. The result of this calculation depends on the ant’s visual range.
FriendlyAntsInViewrange Returns the number of friendly ants from the same colony in the ant’s 360° visual range. The result of the calculation depends on the ant’s visual range.
FriendlyAntsFromSameCasteInViewrange Returns the number of friendly ants from the same colony and the same caste in the ant’s 360° visual range. The result of this calculation depends on the ant’s visual range.
TeamAntsInViewrange Returns the number of friendly ants from the same team in the ant’s 360° visual range. The result of this calculation depends on the ant’s visual range.
DistanceToAnthill Returns the distance in steps to the nearest friendly anthill.
CarryingFruit Returns the piece of fruit the ant is currently carrying. If the ant is not carrying a piece of fruit, the value returned is null.
Caste Returns the name of the ant’s caste.
Destination Returns the ant’s current destination. If the ant currently has no destination, the value returned is null.
IsTired Returns whether the ant is tired. The ant becomes tired as soon as it has travelled a third of its maximum range. Once this value has been exceeded, this property changes from false to true and the event GettingTired() is called.
DistanceToDestination Returns how many steps forward the ant must go before it reaches its destination. This value is reduced each round by CurrentSpeed.
DegreesToDestination Returns how many degrees the ant still has to turn before it moves forward again. This value is reduced each round by RotationSpeed.
Direction Returns the direction that the ant is facing on the map.
ReachedDestination Returns whether the ant has reached its destination or not.
WalkedRange This property returns the total number of steps that the ant has travelled since its last visit to an anthill. See Range.


Helper

This section covers methods that are helpful but that are not commands issued to ants.

Food

The following methods help with the evaluation of food sources.

Method Description
NeedsCarrier Evaluates if the specified fruit needs more ants to carry it.

Navigation

Special keywords are required to refer to the current ant in the following commands. C# uses the keyword “this” and Visual Basic uses the keyword “Me”.

Method Description
Coordinate.GetDistanceBetween Returns the distance in steps between two specified game elements.
Coordinate.GetDegreesBetween Returns the direction from the first game element specified to the second game element specified.

Random Numbers

Method Description
RandomNumber.Number Generates a random number within the specified limits. If only one parameter is specified, a random number will be generated between 0 and the specified limit -1. If two parameters are specified, a number between will be generated between the lower limit and the upper limit -1.