Skip to contents

The Atari Grand Challenge and Atari-HEAD data sets hold human demonstrations of Atari 2600 games, collected for research on reinforcement learning. Both store the input as text tables with one row for each frame, in .txt files. The reader knows by the first line which of the two a file is:

Usage

read_txt(
  path,
  analog = "raw",
  deadzone = NULL,
  triggers = "raw",
  aliases = TRUE,
  ...
)

Arguments

path

Recording file path.

analog

Stick representation: "raw" (default), "cardinal4", "cardinal8", "angle", or "angle+magnitude". A scalar applies to both sticks; c(left = "cardinal8", right = "angle") selects them independently. Cardinal modes add separate left/right logical direction columns. Continuous modes return numeric fields through stick_channels(). Original X/Y values remain in analog_channels() in every mode. Absent sticks add no columns.

deadzone

Radial threshold in centred axis half-range units, from zero to one. One value applies to both sticks; named left/right values are allowed. NULL uses the default of the controller, whichever emulator recorded it: 0.125 for the sticks of Nintendo's consoles (Nintendo 64, GameCube, Wii extensions, 3DS) and 0.25 for all other sticks. The first is close to the 15 of 128 units that the GameCube's controller library discards on each axis (PAD_Clamp in libogc). The second covers the resting position of a released PlayStation stick, up to about 32 of 128 units from the centre (psx-spx), and is close to the 7849 and 8689 of 32767 that Microsoft gives for the thumbsticks of PC gamepads (XInput). A game applies a threshold of its own, which the recording does not store; give that value to study one game. Neutral observations have no direction and an NA angle. Magnitude is kept.

triggers

"raw" (default) or "digital". For DTM, digital additionally projects each analogue trigger at 128/255 into separate L2/R2 columns. Hardware L/R click bits remain distinct from thresholded analogue triggers.

aliases

TRUE (default) places the controls of a recording under the shared IDs that button_layout() describes. With FALSE, a control that would be placed under another control's ID keeps the key of its source, so every control of the recording has a column of its own and no two are combined.

...

Reader-specific arguments, such as controller_order for M64 or DTM, or member for a recording inside a ZIP archive (see movie_members()).

Value

A replayr_movie with one player.

Details

  • A trajectory of the Atari Grand Challenge data set, version 1 (Kurin et al. 2017, doi:10.48550/arXiv.1705.10998 ): one episode of play, recorded at 60 frames per second. The data set keeps the trajectories of each game in a folder of its own (spaceinvaders, qbert, mspacman, pinball, revenge); the file does not name its game.

  • A trial of Atari-HEAD (Zhang et al. 2020, doi:10.1609/aaai.v34i04.6161 ; files at doi:10.5281/zenodo.3451402 ). The game waited for the player in every frame, and the table stores how long each frame was shown. The archive of each game holds the text files of its trials beside the archives of their screen images, and a trial can be read out of it: read_movie("breakout.zip", member = ...), with the members that movie_members() lists. The file meta_data.csv of the data set names the game of each trial.

Each row holds the action of its frame as one of the 18 action numbers of the Arcade Learning Environment. These are the states of one joystick, so player() returns its five controls: the four directions and the fire button, under the IDs an Atari 2600 joystick has in every other recording.

analog_channels() returns the action number as the table writes it (action) and, for a trial, how long each frame was shown (duration_ms, the column duration(ms)). A field that the table gives as null is NA; the last row of a trial has no action, so that no control is held in it. observation_time() of a trial is the time at which each frame appeared, the sum of the durations of the frames before it. movie$timing holds the frame numbers of a trajectory (frame) or the frame identifiers of a trial (frame_id), and movie$header$trajectoryId the number in the first line of a trajectory.

Only the input is read. The tables also give states of the game (the score, the reward of each frame, the episode and whether it ended) and, for a trial, the gaze positions of each frame: the points on the screen at which the player was looking, measured by an eye tracker. These are not returned; read.csv() reads them from the same files.

recording_info(movie)$format says which table was read: "atari_gc" or "atari_head". A text file that is neither is refused.

See also

recording_format() to tell the tables from other text files.

Examples

trajectory <- system.file("extdata", "tables", "atari-grand-challenge.txt", package = "replayr")
movie <- read_txt(trajectory)
colSums(player(movie))
#> dpad_right  dpad_left  dpad_down    dpad_up          a 
#>          6          5          3          3          6 
head(analog_channels(movie))
#>      action
#> [1,]      0
#> [2,]      0
#> [3,]      3
#> [4,]      3
#> [5,]     11
#> [6,]     11
trial <- read_txt(system.file("extdata", "tables", "atari-head.txt", package = "replayr"))
recording_info(trial)$format
#> [1] "atari_head"
observation_time(trial)
#>  [1] 0.000 0.900 0.950 1.000 1.051 1.100 1.150 1.500 1.550 1.600