Introduction

SuperSonicAI has lots of software dependencies. It requires a modern operating system like Windows, Mac or Linux. It needs python, pip, gym-retro, pytorch, numpy, opencv, and a few other packages that can be installed using pip. The last requirement is the game's read only memory provided in the git repo. Also, these instructions expect users to have some knowledge on using the command line.

Installing git

The first step in setting up SuperSonicAI is to have a working and compatible OS and installing Git. Git can be installed on any modern operating system. Download and installation instructions can be found on their website: https://www.git-scm.com/

git --version

Verify that git is installed by opening a terminal and running the above command. If git is installed, it will print the installed version of git.

Cloning the repo

Clone the repo to get all the source code and data of the SuperSonicAI. In your terminal, run the command below to move into a directory where you want to put the project.

cd

From that directory, run the git clone command below to download the repository.

git clone git@git.cs.vt.edu:dmath010/supersonicai.git

Once you have downloaded all of the files, change directory into the project directory of SuperSonicAI by calling the command:

cd supersonicai/

Installing Python

SuperSonicAI, needs an installation of python versions 3.7, 3.8 or 3.9. Newer and older versions of python are not compatible with all the software dependencies of SuperSonicAI. Installation instructions can be found on the python website https://www.python.org/.

Verify installation by calling the below. If installed correctily, a version number will be printed.

python --version

To use specific versions of python, append the version number like the following:

python3.8 --version

or

python3.8.exe --version

This will run python version 3.8 assuming it is installed. Once installed, the software packages can be installed using pip. The packages needed are listed in requirements.txt found in the directory of the git repo. You can install all of the required packages by running the command below.

pip install -r requirements.txt

You can install individual packages by using the command below.

pip install <package>

Verify the package installations by running the below command and checking that all packages listed under requirements.txt are printed by pip list.

pip list

Games ROM

SuperSonicAI is run from a small set of driver scripts. These scripts perform common tasks like training agents and demonstrating their performance and recording playbacks into mp4 videos. But before running these scripts, the games read-only memory needs to be added to the project. Without this, the emulator will not have the executables or data to run the game engine itself. Users will first need to download Sonic the Hedgehog via STEAM. Then, games can be imported by calling the below command for local ROM files

python scripts/import_path.py

or this command for STEAM ROM files.

python scripts/import_sega_classics.py

Random Agent

Random Agent was the initial model utilized to test our software environment. It requires no training and simply seeks to ensure that our teams' system capabilities align with the OpenAI GymRetro Interface. Random Agent renders an environment and creates an agent that randomly chooses 1 action per timestep from the predefined 7 moves in our action space.

python source/models/front_end_random.py

Random Agent Code

source/models/front_end_random.py

1import retro
2
3def main():
4    env = retro.make(game='SonicTheHedgehog-Genesis', state='GreenHillZone.Act1', record='.')
5    obs = env.reset() # Reset button on emulator
6    done = False
7    for i in range(2000): 
8            # Action space is array of the 12 buttons on genesis controller. 
9            # 1 if pressed, 0 if not
10        action = env.action_space.sample()
11        obs, rew, done, info = env.step(action)
12        env.render() #Show emulator
13
14    env.close()
15
16if __name__ == "__main__":
17    main()