Logo MsPacMan Vs Ghosts

MsPacMan Vs Ghosts

MsPacMan Vs Ghosts competition environment to develop and test AI techniques for building Intelligent Behaviours

About MsPacMan Vs Ghosts

This project allows to test several AI techniques for the implementation of Intelligent Behaviours.
The simulation environment is a fork of the sourcecode created by Philipp Rohlfshagen, David Robles and Simon Lucas of the University of Essex for a competition that took place in the IEEE Computational Intelligence and GamesConference 2016.

The goal is to provide a simulation environment for teaching and research purposes. This environment is currently used in the subject Engineering of Intelligent Behaviours at the School of Computing of the Universidad Complutense de Madrid.

The implementation available at this web page has been developed by Prof. Juan A. Recio-García from the original project, correcting bugs, including batch evaluation and components for the development of Finite State Machines, Logic Rules, Fuzzy Logic and Case-based Reasoning.


The goal of Ms Pac-Man is to obtain the highest possible score by eating all the pills and power pills in the maze (and thus advancing to the next stage). Each pill eaten scores 10 points, each power pill is worth 50 points. Ms Pac-Man's quest is opposed by the four ghosts: Blinky (red), Pinky (pink), Inky (green) and Sue (brown). At the start of each level, the ghosts start in the lair in the middle of the maze and, after some idle time, enter the maze in their pursuit of Ms Pac-Man. Their goal is to eat Ms Pac-Man and each time this happens, a life is lost and Ms Pac-Man and the ghosts return to their initial positions; the time spent by the ghosts in the lair decreases as the player progresses to higher levels.

There are four power pills in each of the four mazes, which, when eaten, reverse the direction of the ghosts and turn them blue; they may now be eaten for extra points. The score for eating each ghost in succession immediately after a power pill has been consumed starts at 200 points and doubles each time, for a total of 200+400+800+1600=3000 additional points. Any ghost that has been eaten re-appears in the lair and emerges soon after, once again chasing Ms Pac-Man. If a second power pill is consumed while some ghosts remain edible, the ghost score is reset to 200; if the level is cleared while the ghosts remain edible, play continuous immediately to the next level.

The goal of a Ms Pac-Man controller is to maximise the score of the game. In the competition, it is the average score against multiple ghost teams that counts and the winning controller is the one which obtains the highest total average score.

The goal of a ghost-team controller is to minimise the average score obtained agains t it by the different Ms Pac-Man controllers. The winning ghost team will be team with the lowest average score against it.

Getting Started

Create a project

  1. Download: Download the MsPacMan Engine and unzip it in a convenient location on your computer.
  2. Create a Project: Open Eclipse and create a new (empty) Java project.
  3. Copy downloaded files into the new project
  4. Select project >> Right click >> Configure >> Convert to Maven Project This should automatically install dependences.

Start coding

  1. To implement your behaviours, the classes you need to extend are:

    1. pacman.controllers.PacmanController
    2. pacman.controllers.GhostController

    These files extend Controller.java. You will need to provide code for the getMove(Game game, long timeDue) method.

  2. The getMove() Method

    In order to create a controller, you need to provide code for the method: getMove(Game game, long timeDue).

    In the case of Ms Pac-Man, this method returns an element of the MOVE enumeration found in Constants.java. The elements are:

    • MOVE.UP

    In the case of the ghosts, this method returns an EnumMap that maps every element from the enumeration GHOST to MOVE:


    To calculate a good move, you can query the game object to access information about the game state. The long timeDue indicates the system time the next move is due. You have 40ms per game tick to provide a response.

  3. The Game object Every game tick, your controller receives a copy of the current game state via the getMove() method. The game object contains all the information required to make an informed decision. The class Game.java is the only class you need to be concerned with (you may also need to know about Constants.java, which holds all the game's enumerations and constants). The game is represented as an adjacency graph: you move from one node to another throughout the game. Nodes are referred to by their indices, and Pills and powerpills are located on specific nodes throughout the maze.

    Whenever the getMove(-) method gets called, you receive a new copy of the game and the time the move is due. Query the game state using its many methods to obtain information about the pills, powerpills, positions of Pac-Man and the Ghosts etc. The game also provides numerous additional helper methods to obtains things like shortest paths or moves to take to approach a specific target.

  4. An example. You can try the following classes that implement random behaviours: PacManRandom.java and GhostsRandom.java.
  5. Run it!. To execute the simulation you must instantiate the pacman.Executor class. It can be configured with several options: Partial Observation (PO), tick limit, visual representation, etc. Here you can find an example: ExecutorTest.java. You can also configure the HumanController to control MsPacMan with the keyboard.


Batch evaluation is provided by classes es.ucm.fdi.ici.PacManEvaluator and es.ucm.fdi.ici.PacManParallelEvaluator. These classes allows to repeat simulations several times with different behaviours. The first one executes them linearly whereas the second one, runs simulation using parallel threads. Both are configured through a config.properties file, where you can define trials (repetitions), if partial visibility is enabled and the teams to evaluate. Here you can find an example of configuration file and a simple class to run the evaluation

An introductory step-by-step tutorial of the envirnoment can be downloaded here (in Spanish)


The FSM extension allows to implement Hierarchical Finite State Machines to define the behaviour of the MsPacMan and the Ghosts. It includes a plugable graphical interface to debug and inspect the FMSs.

A simple example of FSM is provided in the downloads section, together with the library, source code, and the graphical observer. The main elements of the FSM implementation are:

  • Input. Abstract class to encapsulate the input variables required to evaluate the transitions and apply the actions over the game. It follows a template pattern where the constructor calls the parseInput() abstract method. Here, subclasses must extract from the game the required information.
  • State. Interface for FSM states. Each state is responsible of executing an action over the Game object (inside Input) and according to other input variables. SimpleStates contain an action to be executed when the state is activated, and CompoundStates store internally another FSM.
  • Transition. Evaluates the game input to change to another state. Each state is associtated with several transitions to other states in the FSM implementation.
  • FSM. Is the implementation of a generic Finite State Machine. The add(State source, Transition transition, State target) method defines its structure. The MOVE run(Input in) executes a tick on the FSM, evaluating any out transition from the current state according to the input. If a transition is applicable, it changes to the target state and executes it. If no transitions are available or applicable, executes the action of the current state.
  • FSMObserver. Defines the interface for classes that want to receive the events of the FSM. The library provides console and graphical observers


Here you can find the downloads of MsPacMan Vs Ghosts:

MsPacMan Engine Basic engine including evaluation classes and adaptors to implement controllers MsPacManEngine_2.2.zip
FSM library Compiled jar library to implement FSMs PacManEngineFSM.jar
FSM source code Source code of the FSM library for debugging PacManEngineFSM-src.zip
FSM Documentation (JavaDoc) Javadoc documentation of the FSM implementation PacManEngineFSM-doc.zip
FSM Graph observer Graphical observer for the FSM library. Includes dependencies PacManEngineFSM-doc.zip
FSM Example Simple example that shows how to use the FSM library FSMExmaple.zip

People in MsPacMan Vs Ghosts

Juan A. Recio García
Juan A. Recio García
Guillermo Jiménez Díaz
Guillermo Jiménez Díaz
Marta Caro-Martínez
Marta Caro-Martínez
Belén Díaz Agudo
Belén Díaz Agudo

Contact with Contact

Thank you for your message.
Something went wrong. Please, check the form and try again.