Code Tutorial

##ALE Python Interface Code Tutorial The ALE Python Interface is simply a wrapper for the Arcade Learning Environment interface. It is suggested that you read the manual contained in the Arcade Learning Environment, and also refer to ale_interface.hpp contained within the arcade learning environment source code. This header file contains the C++ API, which is simply wrapped in python. It also contains very useful comments.

This wiki page provides a quick walk through, to get you started. The code shown here is similar to what is found under the test programs in the /examples directory.

###Basic Usage

from ale_python_interface import ALEInterface

This imports the ale python interface class, the first thing we must do is declare an object instance of this class

ale = ALEInterface()

Next, any parameters you wish to set can be set via the "set" function. These are all internal parameters, and they appear to be documented in the arcade learning environment manual in the "Command Line Arguments" section. For example, to set the frame_skip to 4 so that the arcade learning environment executes 4 frames per step, simply use

ale.set("frame_skip",4)

To set the random seed, use

ale.set("random_seed",123)

Once the options you need have been set, a ROM must be loaded, this can be done via (for example):

ale.loadROM("pong.bin")

Some games may not use all actions for all combinations of control inputs, for example, pong only uses 2 directions and the fire buttons. To get the action set the current game uses, returned as a numpy array, simply call:

minimal_actions = ale.getMinimalActionSet()

To begin executing the game, reset_game() can be used to reset the game, act(action) can be used to perform the next action and game_over() is a function that returns True when the game is in it's terminal state. These can all be used to create a loop that takes random actions until the game ends like so (This code shown is from ale_python_test1.py):

for episode in range(10):
    total_reward = 0.0
    while not ale.game_over():
        a = legal_actions[np.random.randint(legal_actions.size)]
        reward = ale.act(a);
        total_reward += reward
    print("Episode " + str(episode) + " ended with score: " + str(total_reward))
    ale.reset_game()

###Reading RAM and the Screen Data To retrieve RAM data from the game and/or screen data, it was decided for performance reasons that it should be placed in a numpy array that you create. This numpy array should have a particular format that will be explained.

For RAM, the numpy array MUST be a 1d uint8 array, with a size equal to the value returned by get_ram(). This can be performed via the following

ram_size = ale.getRAMSize()
ram = np.zeros((ram_size),dtype=np.uint8)
ale.getRAM(ram)

The above code creates the array and fills it with data from the game's ram. Please note that the getRAM() function will overwrite random memory if a proper numpy array is not provided, which could lead to unpredictable behavior. Also note that you do not have to recreate this array every time you retrieve the ram, getRAM() can be called multiple times with the same numpy array.

The technique to get screen data is similar, except this time the numpy array MUST be a uint32 1d array with size equal to screen_width*screen_height where screen_width and screen_height are determined via getScreenDims(). For example to create this array you could do:

(screen_width,screen_height) = ale.getScreenDims()
screen_data = np.zeros(screen_width*screen_height,dtype=np.uint32)

After creating the array, it can be filled with RGB values via:

ale.getScreenRGB(screen_data)

There is also a function to get the raw atari pallete values, it takes a numpy array of uint8's and can be invoked like so

(screen_width,screen_height) = ale.getScreenDims()
screen_data = np.zeros(screen_width*screen_height,dtype=np.uint8)
ale.getScreen(screen_data)

Note: Again I will reiterate, the getRAM(), getScreenRGB(), and getScreen() functions may overwrite random memory if a proper numpy array is not provided.

The example program ale_python_test_pygame_player.py contains a demonstration that uses pygame. This demo allows the player to play using keyboard input from the arrow keys and the 'z' key to fire. Refer to the code in this demonstration for an example of how to use the getScreenRGB() function in a way that places it directly into a pygame buffer for rendering, should you wish to do so.