Pac-Man Solutions - Backend

Documentation · License · Demo (Coming Soon)

An artificial intelligence environment enabling users to watch simulated solutions to the original 1980's Pac-Man arcade game.

Key Features

• Simulate intelligent agents attempting to solve Pac-Man levels in a custom-built environment
• Watch these solutions in an interactive React application
• Develop agents to compete against the pre-built models

Getting Started

Below are the instructions required to get the application running locally. Only the back-end is required for a minimum application which will run on the command line, while the front-end is optional to aesthetically render solutions.

# once Python is successfully installed
pip install venv
# create the virtual environment
python3 -m venv venv

# activate the virtual environment (windows)
venv\Scripts\activate
# activate the virtual environment (unix)
source venv/bin/activate

# install dependencies
pip install -r requirements.txt

Once the environment is setup and activated, the driver script can be run:

❯ python3 main.py -h
usage: main.py [-h] [-l LEVEL] [-v] [-d] [-o OUTPUT_FILE] [-r RUNS] {single,analytics}

Pac-Man Solutions - Back-End: AI solutions to abstractions of Pac-Man levels.

positional arguments:
  {single,analytics}    single = Run single game, analytics = Run analytics tool

options:
  -h, --help            show this help message and exit
  -l LEVEL, --level LEVEL
                        specify level number as an integer

Single Run Options:
  -v, --verbose         enable verbose output - full final state printing
  -d, --debug           enable debug output - full final state printing + all noteworthy events

Analytics Options:
  -o OUTPUT_FILE, --output_file OUTPUT_FILE
                        write the output data to a file
  -r RUNS, --runs RUNS  the number of runs completed to assess performance

Development

Pre-Commit

This project makes use of pre-commit as a tool for development. Usage requires Python to be installed, however, this should already be installed should you have followed the installation steps.

# only run this if not already installed
pip install pre-commit
# the following command should be successful
pre-commit --version
# inside the project directory, run this command to install the git hook scripts
pre-commit install --hook-type pre-commit --hook-type pre-push

With this now configured, a series of jobs will now run upon every commit and push. Commit jobs will consist of linting whilst push jobs involve testing. See pre-commit-config.yaml for more detailed information.

Server

There are two options to work with the functions during development. The correct use case depends on how you want to interact with the functions.

• If you are looking to test the endpoints ability to call code; this can be done with either option
• If you are looking to test the interaction with firebase services, use the emulator.
• If you are looking to test the intergration with a front-end application, use Flask

Firebase Emulator

This project uses Firebase Functions, during development, the Firebase Emulator can be used to develop in a test environment. To setup and use this, follow these steps:

# Initialise Firebase Emulators
firebase init emulators
# Start Emulator
firebase emulators:start
# OPTIONAL - run the emulator whilst saving state
firebase emulators:start --import .env --export-on-exit .env

The functions endpoints can now be accessed through the following url:

http://localhost:5001/{MY_PROJECT}/us-central1/{ENDPOINT}

Flask

To run the flask server, use the runner file:

python3 functions/runner.py flask

The flask endpoints can now be accessed through

http://localhost:5001/{ENDPOINT}

Deployment

The application uses Firebase Functions. To deploy, a Firebase project must be initialised using the steps below:

# Log into Firebase account
firebase login
# Initialise Firebase Project
firebase init
# Deploy functions
firebase deploy --only functions

Acknowledgements

• Pacman - For the inspiration to solve this game
• Public Pixel Font - For the font used in the web application