A platform for applying machine learning algorithm to play pixel games

MLGame separates the machine learning part from the game core, which makes users easily apply codes to play the game.

MLGame Beta 5.0+ is not compatible with the previous version.

• Python 3.6+
• pygame==1.9.6
• Other machine learning libraries you needed

$ python MLGame.py [options] <game> [game_params]

• game: The name of the game to be started. Available games are "arkanoid" and "pingpong"
• game_params: The additional parameters for the game. See the README of the game for more information.
• options:
  • -f FPS: Specify the updating frequency of the game
  • -m: Play the game in the manual mode (as a normal game)
  • -1: Quit the game when the game is over or is passed. Otherwise, the game will restart automatically.
  • -r: Pickle the game progress (a list of SceneInfo) to log files.
  • -i SCRIPT [SCRIPT ...]: Specify the script(s) used in the machine learning mode. The script must have function ml_loop() and be put in the games/<game>/ml/ directory.

Use python MLGame.py -h for more information. Note that -i flag and its following "SCRIPTs" should be placed at the end of the command.

For example:

• Play the game arkanoid level 3 in manual mode on easy difficulty with 45 fps

  $ python MLGame.py -m -f 45 arkanoid EASY 3
  

• Play the game arkanoid level 2 on normal difficulty, record the game progress, and specify the script ml_play_template.py

  $ python MLGame.py arkanoid NORMAL 2 -r -i ml_play_template.py
  

If -m flag is not specified, the game will execute in the machine learning mode. In the machine learning mode, the main process will generate two new processes, one is for executing the machine learning code (called ml process), the other is for executing the game core (called game process). They use pipes to communicate with each other.

SceneInfo is the data structure that stores the game status and the position of gameobjects in the scene. GameCommand is the data structure that stores the command for controlling the gameobject (such as a platform). SceneInfo is defined in the file games/<game>/game/gamecore.py and GameCommand is defined in the file games/<game>/communication.py.

Note that the game process won't wait for the ml process (except for the initialization). Therefore, if the ml process cannot send a GameCommand in time, the instruction will be consumed in the next frame in the game process, which is "delayed".

The example script for the ml process is in the file games/<game>/ml/ml_play_template.py, which is a script that simply sent the same command to the game process. There are detailed comments in the script to describe how to write your own script.

if -r flag is specified, the game progress will be logged into a file. When a game round is ended, a list of SceneInfo is dumped to a file <prefix>_<timestamp>.pickle by using pickle.dump(). The prefix of the filename contains the game mode and game parameters, such as ml_EASY_2_<timestamp>.pickle. The file is saved in games/<game>/log/ directory. These log files can be used to train the model.

You can use pickle.load() to read the game progress from the file, but make sure that the top-level script is at the root directory of MLGame. Because the pickle module will try to import the related modules by absolute importing.

Here is the example for read the game progress:

1. Create a script named read_log.py in the game's log directory:

import pickle
import os.path

def print_log():
    dir_path = os.path.dirname(__file__)
    file_path = os.path.join(dir_path, "some.pickle")

    with open(file_path, "rb") as f:
        p = pickle.load(f)

    print(p[0])

2. Create an empty __init__.py in the same directory to make it become a package.
3. Create a script main_read_log.py in the root directory of the MLGame as the top-level script:

from games.<game>.log.read_log import print_log

if __name__ == "__main__":
    print_log()

You can manage reading scripts for different games, and execute the script by modifying the top-level script.

View CHANGELOG.md

• arkanoid
• pingpong
• snake