Hide and Seek Arena - Course Lab Book

1. Introduction¶

Hide and Seek Arena aims to help students understand, implement, and optimize search algorithms through an automated arena that simulates the game of hide-and-seek, where student teams can compete against one another for ranking.

Each student team will develop both of the following agents:

Hide agent: Hide for as long as possible.
Seek agent: Find and catch as quickly as possible.

The agents will be automatically matched in the Arena to compute win rates and rankings.

2. Arena¶

The Arena is an automated framework, implemented in Python, that serves as the competitive environment for the agents. Given the teams’ submissions, the Arena will automatically import each team’s agents, then run a series of matches between teams, and finally output the results.

The model of the Arena is illustrated as below:

Algorithm 1  Agent – Environment Interaction Loop
1: while episode not terminated do
2:     ap ← PacmanAgent.step()
3:     ag ← GhostAgent.step()
4:     Environment.step(ap, ag)
5:     Update agent positions
6:     Check collisions or termination
7:     s ← observe new environment state
8: end while

At each step in Algorithm 1, the provided information includes:

A 21 × 21 map, where 0 indicates a traversable cell and 1 a non-traversable cell.
The current positions of the two agents.
The current step count.

# # # # # # # # # # # # # # # # # # # # #
# . . . . . . . . . # . . . . . . . . . #
# . # # # . # # # . # . # # # . # # # . #
# . # # # . # # # . # . # # # . # # # . #
# . . . . . . . . . . . . . . . . . . . #
# . # # # . # . # # # # # . # . # # # . #
# . . . . . # . . . # . . . # . . . . . #
# # # # # . # # # . # . # # # . # # # # #
# # # # # . # . . . G . . . # . # # # # #
# # # # # . # . # # . # # . # . # # # # #
# . . . . . . . # . . . # . . . . . . . #
# # # # # . # . # # # # # . # . # # # # #
# # # # # . # . . . . . . . # . # # # # #
# # # # # . # . # # # # # . # . # # # # #
# . . . . . . . . . # . . . . . . . . . #
# . # # # . # # # . # . # # # . # # # . #
# . . . # . . . . . P . . . . . # . . . #
# # # . # . # . # # # # # . # . # . # # #
# . . . . . # . . . # . . . # . . . . . #
# . # # # # # # # . # . # # # # # # # . #
# . . . . . . . . . . . . . . . . . . . #
# # # # # # # # # # # # # # # # # # # # #

Figure 1: Arena map (P: Pacman, G: Ghost, #: Walls, .: Empty path)

At each step, both agents receive the same state information and make their decisions simultaneously. The win conditions are defined as follows:

The Seek agent wins: if the Seek agent touches the Hide agent, meaning a Manhattan distance strictly below 2.
The Hide agent wins: if the maximum number of allowed steps is reached.

Please note that the framework is provided to you for reference, and evaluating your own agent against the above conditions may require some tweakings. Also note that the framework has a fog setting which we will not use in this lab.

The source code of this framework is provided as pacman.zip in the Google Drive folder. The source code will be provided to students with the following directory structure:

Arena/
├── src/                       # Framework source code (do NOT modify)
├── submissions/               # Student workspace
│   ├── example_student/
│   │   └── agent.py           # Reference implementation
│   ├── <student id>/
│   │   └── agent.py           # Student team's agent
│   ├── STUDENT_GUIDE.md       # Student instructions
│   └── run_game.sh            # Quick-run script

Besides that, the given folder also includes a Clear folder featuring selected instances of previous courses where the top submissions are sampled. About the speed: if both agents move at the same speed, the Seek Agent can never win because it cannot make contact with the Hide Agent. To ensure fairness, the Seek Agent moves at a speed of 2 cells per step when moving in a straight line but cannot move with an L-shaped turn immediately during a turn.

At each step, a student team’s agent must return an action in the following format:

class AgentInterface(ABC):
    @abstractmethod
    def step(self, map_state, my_position, enemy_position, step_number):
        # For Pacman Agent: return a Move or (Move, steps), where:
        # - steps is an int from 1 to the configured max straight-line speed.
        # For Ghost Agent: return a Move (UP, DOWN, LEFT, RIGHT, or STAY).

The recommended algorithms are: Minimax, Monte Carlo, Alpha-beta Pruning, Expectiminimax, etc.

3. Tournament¶

Each team will participate in both roles, Hide and Seek, and will compete against the agents of all other teams. Based on the outcomes, the win rates are computed as:

\text{win rate}_{\text{hide}} = \frac{\text{Hide wins}}{\text{Hide games}} \qquad \text{win rate}_{\text{seek}} = \frac{\text{Seek wins}}{\text{Seek games}}

(1)

The results are recorded in the following example table.

Hide \ Seek	Team 1	Team 2	Team 3	Team 4
Team 1	–	0	1	1
Team 2	0	–	1	0
Team 3	1	0	–	1
Team 4	0	0	1	–

Here, a value of 0 denotes a Hide win, while a value of 1 denotes a Seek win.

Based on the table above, an example of the win rates for Team 1 is as follows:

As the Hide agent, Team 1 wins 1 out of 3 matches, resulting in $\text{win rate}_{\text{hide}} = 33.3\%$ .
As the Seek agent, Team 1 wins 2 out of 3 matches, resulting in $\text{win rate}_{\text{seek}} = 66.6\%$ .

Note that, besides the raw winning result, we also record your agent’s average steps required to end each match. For Pacman, you should also minimize this value, while for Ghost, you should also maximize this value. In order to tie-break teams with similar winning rates, we evaluate their difference between Pacman’s and Ghost’s average steps, where the one with the lower difference ranks higher.

The scoring criteria for each team is defined as follows:

Criterion	Score
Algorithm implementation completeness	3
Ranking in the initial submission, see the timeline in Section 4	Up to 3
Ranking in the optimized submission per the timeline in Section 4	Up to 4

4. Submission¶

Each team must submit a single <group id>.zip file to Moodle containing the following directory structure, where <group id> denotes a single integer for your group’s ID only. For example please use 1.zip INSTEAD of group 1.zip or group 01.zip. The general structure of your submitted zip folder should be:

<group id>/
├── agent.py
└── etc.

The submitted agent is allowed to import other files located within the same submission directory. The submission timeline is specified as follows:

Figure 1:Statement submission timeline (initial and optimized submission phases).

5. Notices¶

Please pay attention to the following notices:

This is a GROUP assignment.
Late submissions will not be accepted under any circumstances.
This project has two submission phases. Only teams that submitted in the first phase are allowed to submit in the second phase.
Student teams must ensure that their agent returns an action within a maximum of 1 second while consuming at most 128 MB under the setting of Google Colab’s CPU-only instance, where the grading hardware is kept fixed on this configuration for a stable environment and the most reproducible results. The allowed libraries are already installed on that instance, so do not submit a requirements.txt. The built-in time library may be used together with all built-in libraries bundled with Python 3. External libraries available for your team include: numpy, pandas, scipy, and gurobi.
AI tools are NOT restricted, but students should use them wisely. Lab instructors have the right to conduct additional oral interviews to assess their knowledge of the project.
Any form of plagiarism, dishonesty, or misconduct will result in a grade of zero for the course.

The end.