Antomata - The Language of Ant Wars

September 15, 2004
SW Rev 0.2.3 beta

Contents

Introduction

The Ant Wars compiler, which is part of the standard distribution, takes a program written with a Scheme syntax and converts it to a bytecode form used by the simulator. Ant Wars 'brains', as the programs are called, consist only of constants, states, commands and conditionals. There is no memory such as a stack or heap.

Each Ant Wars brain must consist of at least one state. Each state may consist of zero or more conditionals and commands, and flow must never reach the end of a state. The following is an example of a very minimal (and pretty much useless) ant brain:

(define-state start
   (turn left)
   (-> start))
    

This ant merely spins left, in place. Note the (-> start) at the end of the state. It is important that if control reaches the end of the state that control is redirected, either back to the same state, or to another state. This statement says to transfer control to the state labeled start.

The State Machine

Most ant brains will have more than a single state. There are two scopes for states in Antomata: global and local. The example above is a global state, which means that control may be transferred to that state from any other state in the program. Local states are defined within a global state, and may only be jumped to from within that global state or another local state therein. The following example shows how to implement the minimal ant brain above using local states:

(define-state start
   (states ((spin-left
              (turn left)
              (-> spin-left)))
      (-> spin-left)))
    

In this example, the global state start defines a local state spin-left. This local state can only be accessed from within the start global state or any local states defined within it. A slightly more complicated example illustrates this:

(define-state start
    (states
        ((spin-left
             (turn left)
             (turn left)
             (turn left)
             (-> spin-right))
         (spin-right
             (turn right)
             (turn right)
             (turn right)
             (-> spin-left)))
      (-> spin-left)))
    

In this example, control is transferred to spin-left which causes the ant to turn left three times. Then control is transferred to the local spin-right state, wherein the ant turns right three times. Control then goes back to spin-left and the process repeats.

When any state defines local states, it must specify which local state should receive control when the global state receives control. This is specified by the last expression in the states block, which in this case reads -> spin-left. More complicated expressions are allowed, as can be seen below.

(define-state start
    (states 
        ((spin-left
             (turn left)
             (turn left)
             (turn left)
             (-> spin-right))
         (spin-right
             (turn right)
             (turn right)
             (turn right)
             (-> spin-left)))
     (if (flip 2)
         (-> spin-left)
         (-> spin-right))))
    

For this definition of start, control will be transferred to either spin-left or spin-right with equal chance (the flip statement will be described in more detail later.)

More detailed examples are part of the standard distribution and, when used with this document, should provide a solid foundation for building new ants.

Statements and Syntax

The following section specifies all of the valid commands and syntax for the standard Ant Wars language, Antomata.

Constants

In Antomata, integer values may be assigned names for use anywhere an integer value is allowed.

(define-constant name integer)
Scope: global
Purpose: Binds an alphanumeric name to an integer value name: Any valid identifier, consisting of alphanumeric characters, including - and _
integer: Any positive integer value See Also: mark unmark flip

States

States may be declared both globally and locally. At least one global state must exist within any program.

(define-state name state-expression...)
Scope: global
Purpose: Defines a new global state
name: Any valid identifier state-expression: One or more state expressions.
See Also: states ->

(states ( (state-name state-expression...)... ) initial-state-expression...)
Scope: Anywhere state expressions are allowed
Purpose: Defines a set of states local to this scope
state-name: Any valid identifier. Names the state being defined.
state-expression: The statements to be executed when the named state gains control.
initial-state-expression: The statements to be executed when states expression is evaluated. Typically this is used to jump to one of the states defined by this expression.
See Also: define-state ->

(-> state-name)
Scope: Anywhere state expressions are allowed
Purpose: Transfers control to another state in this scope or an enclosing scope.
state-name: Any valid identifier. Names the state to which control will be transferred.
See Also: define-state states

Conditionals

Conditional statements are used to make decisions.

(if condition consequent-state-expression alternate-state-expression)
Scope: Anywhere state expressions are allowed
Purpose: Tests the specified condition, and then executes either the consequent or alternate expression
condition: One of the valid Tests below
consequent-state-expression: The state expression to be evaluated if the condition is true.
alternate-state-expression: The state expression to be evaluated if the condition is false.
See Also: cond begin Tests
Note: If multiple state expressions are to be executed as part of the consequent or alternate expression, they must be wrapped in a begin statement (see below).

(cond (condition consequent-state-expressions... )... (else alternate-state-expressions...) )
Scope: Anywhere state expressions are allowed
Purpose: Tests a set of conditions in order. The first condition to be met will have its associated consequent-state-expressions evaluated. If no specified conditions are met, the alternate-state-expression will be evaluated.
condition: One of the valid Tests below
consequent-state-expressions: One or more valid state expressions to be evaluated if the associated condition is true
alternate-state-expressions: One or more valid state expressions to be evaluated if no conditions are true
See Also: if Tests
Note: This is really just syntactic sugar for nested if statements.
Note: Sometimes each (condition consequent-state-expressions... ) and the else clause will appear additionally surrounded by square brackets. These are optional an have no effect on the program.

Tests

Tests are used inside conditionals to make decisions. Some Tests also cause the ant to perform an action, much like a Command.

(and first-test second-test)
Scope: Anywhere a condition is allowed
Purpose: Evaluates to true if both first-test and second-test evaluate to true
first-test: Any valid Test
second-test: Any valid Test. This test is not evaluated if first-test evaluates to false
See Also: if cond

(or first-test second-test)
Scope: Anywhere a condition is allowed
Purpose: Evaluates to true if either first-test or second-test evaluate to true
first-test: Any valid Test
second-test: Any valid Test. This test is evaluated regardless of the result of evaluating first-test
See Also: if cond

(not test)
Scope: Anywhere a condition is allowed
Purpose: Evaluates to true if test evaluates to false
test: Any valid Test
See Also: if cond
BUG: Boolean operations may currently not be nested under not (as of 0.2.3beta)

(flip max)
Scope: Anywhere a condition is allowed
Purpose: Selects a random number from 1 to max inclusive. If that number is 1, this expression evaluates to true. Otherwise it evaluates to false.
See Also: if define-constant
max: Any positive integer

(pick-up)
Scope: Anywhere a condition is allowed
Purpose: Evaluates to true if there is food at the current cell and the ant is not currently carrying food. If this evaluates the true, the ant takes one food from the current cell and begins carrying it.
See Also: drop sense if cond

(move)
Scope: Anywhere a condition is allowed
Purpose: Evaluates to true if the ant can legally move to the cell directly ahead. The ant may legally move if the cell ahead contains no other ant, and contains no rock. If this expression evaluates to true, then the ant will be repositioned to the cell directly ahead.
See Also: sense turn if cond
Note: Once an ant has moved, it will be unable to move again until 14 turns have passed. If the ant attempts to perform any operation before the 14 turns have elapsed, it will wait (immobile and not evaluating other expressions) until the turns have elapsed before trying again.

(sense direction attribute)
Scope: Anywhere a condition is allowed
Purpose: Evaluates to true if the attribute specified is present in the direction specified.
direction: One of left, right, ahead or here
attribute: One of the following: See Also: if cond
Note: Because cells are hexagonal, the sense test can only 'see' half the cells surrounding the ant.
Note: It is not possible to distinguish between the different pheromones used by enemy ants.

Commands

These are statements which cause the ant to take action unconditionally.

(drop)
Scope: Anywhere a state expression is allowed
Purpose: If the ant is carrying food, the food is placed in the current cell. If the ant is carrying no food, then nothing happens. See Also: pick-up

(turn direction)
Scope: Anywhere a state expression is allowed
Purpose: Causes the ant to change direction.
direction: May be one of left or right.
See Also: move

(mark pheromone amount)
Scope: Anywhere a state expression is allowed
Purpose: Causes the ant to mark the current cell with the specified amount of the specified pheromone.
pheromone: An integer from 0 to 7. Multiple pheromones may be marked in the same cell at the same time.
amount: Any positive integer. Each unit of pheromone will remain for 50 turns.
See Also: unmark sense define-constant

(unmark pheromone)
Scope: Anywhere a state expression is allowed
Purpose: Causes the ant to remove the specified pheromone mark from the current cell. pheromone: An integer from 0 to 7. See Also: unmark sense define-constant

Grouping

(begin state-expression...)
Scope: Anywhere a state expression is allowed
Purpose: Combines a set of state expressions into a single state expression which is evaluated in order. Usually used in association with conditionals to allow multiple statements to be specified for the consequent and alternate clauses.
state-expression: Any valid state expression
See Also: if

Comments

There are two types of comments: line and region. Line comments begin with a semicolon (;) and run until the end of the line. Region comments begin with #| and end with |# and may span multiple lines.