## Session 1, 2007

### Project 3 - Animal Checkers

Due: Friday 8 June, 8:00 pm
Marks: 16% of final assessment

#### Introduction

In this project you will be writing an agent to play the game of Animal Checkers. Animal Checkers is a simplified version of a traditional Chinese board game called "Animal Chess" or "Jungle" en.wikipedia.org/wiki/Jungle_(board_game).

#### Board and Pieces

The game is played on a 7-by-7 board. Each player has four pieces - called the Elephant, Dog, Tiger and Mouse - which are initially set up on the first two rows, as shown below. The object of the game is to move one of your pieces onto a special square called the Den, at the opponent's end of the board.

 Dog Tiger Elephant Den Mouse

#### Movement and Capture

Players take turns to move one of their pieces to a neighbouring square either horizontally or vertically (not diagonally). You are not allowed to move a piece into your own Den. You may move a piece to a square occupied by an opponent piece - in which case the opponent piece is captured and removed from the board - but only if the two pieces conform to the following table:

ElephantTigerDogMouse
ElephantYesYesYesNo
TigerNoYesYesYes
DogNoNoYesYes
MouseYesNoNoYes

The general rule is that a piece can capture another piece of equal or lesser rank, but there is an exception concerning the Elephant and the Mouse: the Elephant cannot capture the Mouse (because the Mouse is small and can dodge the attack), but the Mouse can capture the Elephant (by crawling in the Elephant's ear and gnawing at his brains).

#### Getting Started

Copy the archive `src.zip` into your own filespace and unzip it. Then type
```cd src
make play
./playac
```
You should then see something like this:
```init
start
. m . x . e .
. . t . d . .
. . . . . . .
. . . . . . .
. . . . . . .
. . D . T . .
. E . X . M .

. m . x . e .
. . . t d . .
. . . . . . .
. . . . . . .
. . . . . . .
. . D . T . .
. E . X . M .

Move?
```
The program `playac` allows you to play against your own agent. The provided file `agent.c` simply chooses each move randomly among the available legal moves. In this example above, the agent has chosen to move its `TIGER` to the `LEFT` (from the agent's perspective). Note that your own pieces are represented by the uppercase characters `'M'` (Mouse), `'D'` (Dog), `'T'` (Tiger), `'E'` (Elephant), `'X'` (den) while your opponent's pieces are representod by the lowercase characters '`m`', `'d'`, `'t'`, `'e'`, `'x'`.

To make your move, type one of the letters `'m'`, `'d'`, `'t'` or `'e'`, followed by one of the letters `'r'`, `'u'`, `'l'` or `'d'` for `RIGHT, UP, LEFT` or `DOWN`. The program will then print the board state after your move, followed by the board state after the agent's next move, etc. You can win the game by either moving a piece to the opponent's den, or capturing all the opponent's pieces. At the end of the game, the program will print "Human Wins!" or "Agent Wins!" and then invite you to play another game.

#### Interface

You must implement these functions (note: you may leave some of them empty):

`agent_init()` is called at the beginning of a series of games
`agent_start()` is called at the beginning of each game
`agent_step()` is called each time a move needs to be made
`agent_end()` is called at the end of each game
`agent_cleanup()` is called at the end of the series

The function `agent_step()` has this prototype:

```int agent_step( int loc_p[WIDTH+1][HEIGHT+1] );
```
The array `loc_p[][]` specifies the current state of the board, from the perspective of the agent. The piece at column `j` and row `k` is `loc_p[j][k]`, where the columns are numbered from 1 (left) to 7 (right) and the rows are numbered from 1 (near) to 7 (far).

The function should return a move encoded as a number between `0` and `15`, as follows:

RightUpLeftDown
Mouse0123
Dog4567
Tiger891011
Elephant12131415

When you compare the code in `game.c` and `agent.c`, you will notice an important distinction between `glob_p[][]` and `loc_p[][]`. The array `glob_p[][]` describes the board in global co-ordinates while `loc_p[][]` describes it in local co-ordinates. This is done so that, when two agents play each other, each agent will effectively be "deluded" into thinking that it is Player 0 and the opponent is Player 1. In other words, each agent is presented a view of the board from its own perspective, and each agent believes that its own pieces are `MOUSE_0, DOG_0, TIGER_0, ELEPHANT_0` while those of the opponent are `MOUSE_1, DOG_1, TIGER_1, ELEPHANT_1`.

#### Client

The files `play.c` and `game.c` have been provided just as a tool to help you develop your agent. For submission, your player must be compiled in a form which allows it to play against other agents through a socket protocol. To see how this works, type
```make
```
You will see that it compiles `agent.c` and `client.o` to produce an executable called `client.ac`

Note that the files `play.c`, `game.c` and `game.h` are not required to produce `client.ac`. The contents of the arrays `can_move[][][]` and `can_eat[][]`, which you can see listed in `play.c`, have been compiled into `client.o` as well, so you are free to use them in your agent.

#### Question

At the top of your code, in a block of comments, you must provide a brief answer (two or three paragraphs) to this Question:
Briefly describe how your program works, including any algorithms and data structures employed, and explain any design decisions you made along the way.

#### Submission

Once submissions are open, you should submit by typing

`give cs3411 hw3 Makefile agent.c ...`

Please ensure that you submit the source files and NOT any binary file (i.e., compiled `client.ac` or `.o` files). The `give` system will compile your program using your `Makefile` and check that it produces a binary file with the correct name.

You can submit as many times as you like - later submissions will overwrite earlier ones. You can check that your submission has been received by using the following command:

`3411 classrun -check`

The submission deadline is Friday 8 June, 8:00 pm.
15% penalty will be applied to the (maximum) mark for every 24 hours late after the deadline. Late submissions will not participate in the final tournament, but may be evaluated against selected and pre-defined players.

Additional information may be found in the FAQ and will be considered as part of the specification for the project.

Questions relating to the project can also be posted to the MessageBoard on the course Web page.

If you have a question that has not already been answered on the FAQ or the MessageBoard, you can email it to your tutor, or to `cs3411.hw3@cse.unsw.edu.au`

#### Tournament

We will provide a mechanism for you to submit your players to a common directory and then watch them play against other submitted players. A preliminary tournament will be run every few days, and a final tournament will be run after the submissions deadline. Details of this process will be provided on the FAQ.

#### Marking scheme

• 10 marks for performance in the tournament as well as against a number of pre-defined opponents.
• 6 marks for Algorithms, Style, Comments and answer to the Question
More details of the marking scheme will be provided on the FAQ.

You should always adhere to good coding practices and style. In general, a program that attempts a substantial part of the job but does that part correctly will receive more marks than one attempting to do the entire job but with many errors.

#### Plagiarism Policy

Group submissions will not be allowed. Your program must be entirely your own work. Plagiarism detection software will be used to compare all submissions pairwise and serious penalties will be applied, particularly in the case of repeat offences.

DO NOT COPY FROM OTHERS; DO NOT ALLOW ANYONE TO SEE YOUR CODE

Please refer to the Yellow Form, or to section on Originality of Assignment Submissions in the Unix Primer, as well as the CSE Addendum to the UNSW Plagiarism Policy if you require further clarification on this matter.

Good luck!