GAME RULES

Definitions:

• Arena - program responsible for running the game.
• arena - referring to the overall game state.
• map - a 2-dimensional grid sequence containing the contents of each square in the arena.
• metrics - a short sequence containing aggregate information about the arena.
• units - a list of every unit in the arena. Each element can be referenced by its handle.
• player - a Euphoria program that competes in the game Eubots.
• results - a 2-element sequence containing the match results once the match is ended.

Introduction:

1. Each player controls an army of little pixel-sized units, all alike.

2. Two or more players do battle upon a miniature landscape, consisting of blank spaces, walls, and enemy units.

3. Every turn, every player is called upon to provide a set of orders for all of their units.

4. When either all orders have been received or the time allowed has run out, the Arena program takes all received sets of orders and resolves the arena state.

5. Those players that do not return their orders in the allowed time will not have them processed.

6. Once the arena state has been resolved, the Arena calls each player again to get the next set of orders.

7. Whether a unit's orders succeeded or not will be available in the next turn.

8. If a player has no units left to command it will not be called upon to provide orders.

9. When there is only one player left, that player is deemed to have won the match. It will receive 1 point for each unit it has left alive.

10. In the extremely unlikely event of two players wiping one another out in a single turn, the match is a draw, and neither program will receive points. (Although in the event of a points tie, it is considered better to have drawn than lost)

11. If all unit metrics remain constant for 500 turns, or all players command only a single unit, a stalemate is said to occur. If a stalemate occurs, each player is given points according to the number of units it has left and the match is drawn.

Metrics:

1. A metrics sequence contains all the particular details about the current match:
   • WIDTH - Width of the arena.
   • HEIGHT - Height of the arena.
   • NUM_OF_PLAYERS - The number of players competing this match.
   • IDENTITY - The identity of all units you control.
   • TOTAL_UNITS - The total number of units existing in the arena this turn.
   • UNITS_REMAINING - A sequence containing the number of units each player has this turn. The index of the player's sequence element corresponds to their identity.

2. The only elements of the sequence that change during a match are TOTAL_UNITS and UNITS_REMAINING.

3. This sequence is available to the player.

Map:

1. The arena is rectangular, metrics[WIDTH] squares wide, and metrics[HEIGHT] squares high.

2. The map sequence contains the contents of each grid square. It is a 2 dimensional array with the dimensions metrics[WIDTH] x metrics[HEIGHT].

3. A unit at the cartesian coordinate {5,7} can be found at map[5][7].
   NOTE: {x,y} = map[x][y]. NOT map[y][x]!

4. Each grid square contains one of the following:
   • BLANK - Empty square. Either force may occupy this square. In the map, has a value of 0.
   • WALL - Blocked square. Neither force may occupy this square. In the map, has a value of -1.
   • UNIT - A unit occupies this square (friend or foe). The value of this square is a unit handle.

5. The area outside the rectangle defined by {1,1}, {metrics[WIDTH],metrics[HEIGHT]} is impassable, and should be treated as WALL.

6. This sequence is available to the player.

Units:

1. Each unit in the game, is identified by a unit handle. If alive, that unit handle can be found somewhere in the map, and the properties for that unit can be found at units[unit_handle].

2. The structure of the units sequence is units[unit_handle][unit_property]
   The different properties are:

   • POS - Position. {X,Y} coordinate of the unit. If you check map[X][Y], it will contain the unit handle for this unit.
   • ID - Identity. Owner of the unit. (metrics[IDENTITY] if it's yours)
   • S_FLAG - Whether the last order given to that unit was successful.
     • MOVE_FAIL - Tried to move and was blocked. (negative)
     • ATTACK_FAIL - Did not succeed in killing another unit. (negative)
     • INVALID - Incorrectly formatted order was received. (negative)
     • MOVE_SUCCESS - Successfully moved last turn. (positive)
     • ATTACK_SUCCESS - Successfully killed another unit. (positive)
     • WAIT_SUCCESS - Successfully contemplated philosophy last turn. (positive)
   • ...More properties may be added if requested.

   Success or Failure depends on the order given.
   If a MOVE order was given, success is dependent on that unit not being blocked.
   If an ATTACK order was given, success depends on the attacked unit dying.
   If a WAIT order was given, it always succeeds.
   The value of S_FLAG will be positive if the order succeeded, or a negative value otherwise.
   NOTE: On the first turn, every S_FLAG will contain WAIT_SUCCESS.

3. Units are homogenous. In a turn, each can inflict 1 point of damage, and withstand 2. A single unit is therefore useless - winning a battle requires teamwork!

4. If a unit is killed, The element its handle refers to becomes 0, rather than the structure described above.
   NOTE: If you want to check whether a unit successfully moved, you must first check it is still alive.

5. The entirety of the index is public. You may view details of other player's units using this index.

6. The length of the index is constant, and will be equal to the initial value of metrics[TOTAL_UNITS].

7. This sequence is available to the player.

Orders:

1. Each unit may by supplied with one order per turn:
   • WAIT - Sit there, do nothing...
   • MOVE - Attempt to move to an adjacent square.
   • ATTACK - Attempt to attack an enemy unit in an adjacent square.

2. If the unit fails to undertake the order given, it will WAIT. (S_FLAG depends on the order)

3. If the unit is not given an order, it will WAIT. (And S_FLAG will be INVALID)

4. If the unit is given more than one order, it will WAIT. (And S_FLAG will be INVALID)

5. 'Adjacent square' is defined as the nearest square from the unit in any of these 8 directions;
   DIR_E, DIR_NE, DIR_N, DIR_NW, DIR_W, DIR_SW, DIR_S, DIR_SE

6. An order is a 3-element sequence: {unit_handle, action_type, direction}:
   • unit_handle - the handle of the unit the order is meant for.
   • action_type - one of the order types specified in point 3.
   • direction - one of the directions specified in point 5. (direction has no meaning for WAIT)

7. NOTE: The translation that each direction corresponds to is available to the player, but the direction must be returned, not the translation.

Turns:

1. At the start of each turn, the Arena program triggers code inside eubots.ew to update the game variables, and call get_moves().

2. When the player's get_moves() function is called, that function should calculate the orders for each unit, and return them.

3. Code inside eubots.ew returns those orders to the Arena program.

4. The orders are collated and resolved to find the new state of the arena.

5. The map is displayed on the screen, and new data is sent to each player so they can calculate their next orders.

Resolving orders:

1. Each order is checked for correct structure, data variables and correct owner.

2. Each order is sorted into WAIT, MOVE, ATTACK, and INVALID buckets.

3. Those orders in the WAIT and INVALID buckets are not used anymore, but their S_FLAG is set appropriately.

4. Then, the ATTACK and MOVE buckets are resolved in phases.

5. NOTE: The attack phase is completely resolved before the move phase is resolved.

   -=Attack Phase=-

   (For each unit ordered to ATTACK)
   1. If the attacked square does not contain an enemy unit, the attack wil fail.
   2. The unit that has been attacked has 1 point subtracted from its defence points.
   3. If a unit has less than 1 point remaining, it dies at the end of the attack phase. This means that it still inflicts damage if it was attacking, but if it were trying to MOVE away, it would die before it could move.
   4. At the end of the attack phase, any units that are no longer living are removed from the arena, and their units index element is set to -1.

   -=Movement Phase=-

   (For each surviving unit ordered to MOVE)
   1. If the destination square is a WALL, the move will fail.
   2. If a surviving unit of any team is in the destination square already and does not move from it this turn, the move will fail.
   3. If two or more surviving units of any team are attempting to move to the same destination square, all those moves will fail.
   4. If the movement is successful, the unit moves to that new square.

6. The resolving routine returns the new arena state.

Results:

1. This sequence contains data about the outcome of a match, that a learning program might find useful.
   • SCORE - The number of points earned this match. Will be 0 unless the program won or drew.
   • OUTCOME is one of the following:
     • WON - program won.
     • LOST - program lost.
     • DRAW - program drew.
2. The contents of this sequence are not meaningful, until the framework calls the cleanup() procedure.
3. This sequence is available to the program.