In this game each player controls a colony of ants. At each round of a match, players accumulate as many points to their score as the number of ants in their colony at the end of the round. The winner of the game is the player who, at the end of the match, has the highest score.
The game is played on a rectangular board of dimensions BOARD_ROWS × BOARD_COLS. Cells of the board can be of water or soil. Each ant occupies a single cell, and there cannot be two ants on the same cell at the same time. Ants are afraid of water and hence can only occupy cells of soil.
In colonies there are several categories of ants: queens, soldiers and workers. Ants have a finite life, which is decremented by one after each round. When the life of an ant is exhausted, the ant dies. Initially, the life of a queen is QUEEN_LIFE rounds, the life of a soldier is SOLDIER_LIFE rounds, and the life of a worker is WORKER_LIFE rounds.
Every colony has one queen. If the queen of a colony dies, then another ant of the colony (soldier or worker), if there is any, is chosen randomly and becomes the new queen. The life of this new queen is QUEEN_LIFE rounds.
A match consists of NUM_ROUNDS rounds. In a round, ants can move to one of the adjacent cells of soil within the board, following a horitzontal or a vertical direction (but not in diagonal). Queens can only move in rounds which are multiples of QUEEN_PERIOD. For example, if QUEEN_PERIOD is 2, queens can only move at rounds 0, 2, 4, 6, etc. Soldiers and workers can move at any round.
When an ant tries to move to a cell which is already occupied by another ant (be it of the same colony or not), the former attacks the latter. The result of the fight is determined as follows:
If the attacking ant survives, the movement is performed.
Independently of the presence of an ant, some soil cells may also contain a bonus of food of different kinds: bread, seeds or leafs. When a queen moves to a cell with food, it eats the bonus. On the other hand, when a worker moves to a cell with food, it can take up the food, carry it for some time and leave it some cells away. Food can only be left at the current position of the worker. A worker can only carry one bonus at a time, and can only leave it on cells that do not contain any bonus already. When a worker that carries food dies (because its life is exhausted, or as a result of a fight), the bonus gets destroyed. Soldiers cannot eat or carry food.
A queen may lay an egg (of a soldier or of a worker) in an adjacent (horitzontally or vertically) soil cell. At the end of the round the egg hatches and a new ant of the colony is born. If the newborn is a soldier, its life is SOLDIER_LIFE rounds, and if it is a worker, it is WORKER_LIFE rounds. However, if at the moment the egg hatches the cell is already occupied by another ant (be it of the same colony or not), the new ant dies automatically.
A queen needs three kinds of nutrients in its reserve to produce eggs: carbohydrates, proteins and lipids. Depending on whether the queen decides to lay an egg of a soldier or of a worker, the required quantity of these nutrients is different. The constants that define these quantities are summarized in the following table:
When a queen eats, the nutrients of the food accumulate to its reserve. The nutrients of each kind of food are determined by the constants in the following table:
When the match begins, a colony consists of its queen, NUM_INI_SOLDIERS soldiers and NUM_INI_WORKERS workers placed on soil cells at one of the four corners of the board (player 0 at the top-left one, player 1 at the top-right one, player 2 at the bottom-right one, and player 3 at the bottom-left one). Initially the queen has no nutrients to lay eggs, that is, its reserve is empty. Similarly, when a soldier or a worker becomes a queen it has no nutrients either. There is an exception, though: if the ant was a worker carrying food, the bonus is consumed and its nutrients accumulate to the reserve of the new queen; the same happens if the cell it occupies contains food. If the two situations take place, both bonuses are eaten.
For each of the four quadrants of the board there is a rectangle of BONUS_ROWS × BONUS_COLS cells included in the quadrant on which bonuses of bread may appear. There are also analogous rectangles for seeds and leafs. For each of these rectangles, every BONUS_PERIOD rounds (starting from round 0) a soil cell of that rectangle without bonuses and without an ant is chosen randomly and a new bonus appears. If there is no such cell, then no new food bonus is created. The exact location of these rectangles is determined randomly and is unknown to the players.
Each ant has a natural number that uniquely identifies it. In a round, players use these identifiers to command their ants to perform actions, at most one for each ant:
Only the first action commanded to an ant is selected for execution. The rest of the commands for that ant are ignored. Moreover, any player program that tries to give more than 1000 commands in the same round is aborted.
At the end of every round, all selected commands are ordered randomly and executed following this order. If a command cannot be executed (e.g., the commanded ant has died as a consequence of previously executed commands), the command is skipped. After executing all commands, life counters are decremented, and ants whose life has been exhausted die. Then eggs laid by queens hatch, also in random order (even if the queen that laid the egg has died, e.g., due to a fight). Then, for each colony that no longer has a queen, a new queen is chosen randomly among the remaining soldiers and workers, if there are any, as explained above. Then food bonuses (bread, seeds and leafs) are generated if the current number of rounds is a multiple of BONUS_PERIOD. Finally for each player the number of ants of the colony is added to the score.
Parameter Value Description NUM_PLAYERS 4 Number of players in the game. NUM_ROUNDS 250 Number of rounds a match lasts. BOARD_ROWS 25 Number of rows of the board. BOARD_COLS 25 Number of columns of the board. QUEEN_PERIOD 2 Queens are allowed to move every QUEEN_PERIOD rounds, starting from round 0. SOLDIER_CARBO 3 Units of carbohydrates needed for an egg of a soldier. SOLDIER_PROTE 3 Units of proteins needed for an egg of a soldier. SOLDIER_LIPID 3 Units of lipids needed for an egg of a soldier. WORKER_CARBO 1 Units of carbohydrates needed for an egg of a worker. WORKER_PROTE 1 Units of proteins needed for an egg of a worker. WORKER_LIPID 1 Units of lipids needed for an egg of a worker. BREAD_CARBO 2 Units of carbohydrates contained in a bonus of bread. BREAD_PROTE 0 Units of proteins contained in a bonus of bread. BREAD_LIPID 1 Units of lipids contained in a bonus of bread. SEED_CARBO 0 Units of carbohydrates contained in a bonus of seed. SEED_PROTE 1 Units of proteins contained in a bonus of seed. SEED_LIPID 2 Units of lipids contained in a bonus of seed. LEAF_CARBO 1 Units of carbohydrates contained in a bonus of leaf. LEAF_PROTE 2 Units of proteins contained in a bonus of leaf. LEAF_LIPID 0 Units of lipids contained in a bonus of leaf. NUM_INI_SOLDIERS 3 Number of initial soldiers. NUM_INI_WORKERS 11 Number of initial workers. BONUS_ROWS 3 Number of rows of a rectangle where food appears. BONUS_COLS 3 Number of columns of a rectangle where food appears. BONUS_PERIOD 25 Food bonuses appear every BONUS_PERIOD rounds, starting from round 0. WORKER_LIFE 75 Rounds after which a worker dies. SOLDIER_LIFE 150 Rounds after which a soldier dies. QUEEN_LIFE 300 Rounds after which a queen dies.
A game is defined by a board and the set of parameters of Figure ??.
Unless there is a force majeure event, the indicated values of the parameters are the ones that will be used in all matches of the game.
In Figure ?? a screenshot with all the elements of the game is shown.
The first thing you should do is to download the source code. This source code includes a C++ program that runs the matches and also an HTML viewer to watch them in a nice animated format. Also, a “Null” player and a “Demo” player are provided to make it easier to start coding your own player.
Here we will explain how to run the game under Linux, but a similar procedure should work as well under Windows, Mac, FreeBSD, OpenSolaris, …The only requirements on your system are g++, make and a modern browser like Mozilla Firefox or Google Chrome.
To run your first match, follow the next steps:
to build the game and all the players. Note that Makefile identifies any file matching AI*.cc as a player.
./Game Demo Demo Demo Demo -s 30 -i default.cnf -o default.out
In this case, this runs a match with random seed 30 where four instances of the player “Demo” play with the parameters defined in default.cnf (the default parameters). The output of this match is redirected to the file default.out.
Note: To get a larger view of the match, put your browser into full screen mode (press key F11).
to see the list of parameters that you can use. Particularly useful is
to show all the registered player names.
If needed, remember that you can run
to delete the executable and object files and start over the build.
To create a new player with, say, name MyPlayer, copy AINull.cc (an empty player that is provided as a template) to a new file AIMyPlayer.cc. Then, edit the new file and change the
The name you choose for your player must be unique, non-offensive and less than 12 letters long. It will be used to define a new class PLAYER_NAME, which will be referred to below as your player class. The name will be shown as well when viewing the matches and on the website.
Now you can start implementing the method play(). This method will be called every round and is where your player should decide what to do, and do it. Of course, you can define auxiliary methods and variables inside your player class, but the entry point of your code will always be this play() method.
From your player class you can also call functions to access the board state, as defined in the State class in State.hh, and to command your units, as defined in the Action class in Action.hh. These functions are made available to your code using multiple inheritance. The documentation on the available functions can be found in the aforementioned header files. You can also examine the code of the “Demo” player in AIDemo.cc as an example of how to use these functions. Finally, it may be worth as well to have a look at the files Structs.hh for useful data structures, Random.hh for random generation utilities, Settings.hh for looking up the game settings and Player.hh for the me() method.
Note that you should not modify the factory() method from your player class, nor the last line that adds your player to the list of registered players.
To test your strategy against the “Dummy” player, we provide the AIDummy.o object file. This way you still will not have the source code of our “Dummy”, but you will be able to add it as a player and compete against it locally.
To add the “Dummy” player to the list of registered players, you will have to edit the Makefile file and set the variable DUMMY_OBJ to the appropriate value. Remember that object files contain binary instructions targeting a specific machine, so we cannot provide a single, generic file. If you miss an object file for your architecture, contact us and we will try to supply it.
You can also ask your friends for the object files of their players and add them to the Makefile by setting the variable EXTRA_OBJ.
Once you think your player is strong enough to enter the competition, you should submit it to the Jutge.org website (https://www.jutge.org). Since it will run in a secure environment to prevent cheating, some restrictions apply to your code: