Read Input Recordings of Video Games

Imports input recordings and demo files of video games, as made in tool-assisted speedrunning, reinforcement learning, and research on human-game interaction. Reads the formats of 'FCEUX', 'BizHawk', 'Dolphin', 'Citra', 'libTAS', 'openMSX', 'JPC-RR', 'Gym Retro', the 'Doom' and 'GoldSrc' engines, and other recording tools. Platforms include the Atari 2600, Nintendo, Sega, and Sony consoles, arcade machines, and personal computers. Imported recordings keep compact digital control arrays, stable control identities, original numeric channels, metadata, and emulator commands. Supports gamepads, keyboards, mice, touchscreens, and recorded motion or light-gun channels. Source timing distinguishes frames, controller polls, and timestamped events. Left and right stick directions, angles, and magnitudes can be selected independently. Allows analysis of input recordings without running an emulator.


replayr replayr hex logo

replayr imports input recordings and demo files of video games into R for analysis, as they are made in tool-assisted speedrunning, reinforcement learning, and research on human-game interaction. It reads buttons, keyboard keys, analogue sticks, mouse movement, touch, and motion sensors, together with recording metadata and timing information.

Formats and platforms

The package reads 33 recording formats, under 37 file extensions, from BizHawk, Dolphin, FCEUX, libTAS, Mupen64, Snes9x, openMSX, Gym Retro, and other recording tools, from the Doom and Half-Life engines, and from the Atari Grand Challenge and Atari-HEAD data sets. Supported platforms include:

Family Platforms
Arcade and application platforms Adobe Flash; Android; Arcade; IBM PC compatible; IBM PC DOS; Java 2 Platform, Micro Edition (J2ME); Mac OS / macOS; PICO-8; TIC-80; Web.
Atari Atari 2600; Atari 7800; Atari Jaguar; Atari Jaguar CD; Atari Lynx.
Home computers and calculators Amiga; Apple II; Commodore 64; MSX Home Computer System; Spectravideo SVI-318/328; Texas Instruments TI-83 Series; ZX Spectrum.
NEC NEC PC-98; PC Engine / TurboGrafx-16; PC Engine CD / TurboGrafx-CD; PC-FX; SuperGrafx.
Nintendo Famicom Disk System; Game Boy; Game Boy Advance; Game Boy Color; Nintendo 3DS; Nintendo 64; Nintendo 64DD; Nintendo DS; Nintendo DSi; Nintendo Entertainment System / Famicom; Nintendo GameCube; Satellaview; Super Game Boy; Super Nintendo / Super Famicom; Virtual Boy; Wii.
Other consoles 3DO; CD-i; ColecoVision; Fairchild Channel F; Intellivision; Neo Geo Pocket; Odyssey 2 / Videopac; Sony PlayStation; Uzebox; Vectrex; WonderSwan.
Sega Game Gear; Sega 32X; Sega CD / Mega-CD; Sega Genesis / Mega Drive; Sega Master System; Sega Saturn; Sega SG-1000.

The compatibility catalogue lists each format, version, controller variant, and platform combination. Some desktop and browser games use input recorded through a host application such as libTAS or Hourglass; the catalogue identifies these cases. It is also included in the installed package: vignette("compatibility", package = "replayr"). The readers were checked against published files; the repository's validation folder lists the source of every file and provides the scripts to repeat the checks.

Getting started

Install from GitHub:

# install.packages("remotes")
remotes::install_github("tp451/replayr")

Read a recording and summarise the use of one controller:

library(replayr)

path <- system.file("extdata", "paper", "hold.fm2", package = "replayr")
movie <- read_movie(path)
input <- player(movie, 1L)
sort(colMeans(input), decreasing = TRUE)  # Proportion held

read_movie() chooses the reader from the file extension. player() returns a logical matrix with observations in rows and controls in columns. A TRUE value means that the control is active. The example file contains sustained Right and B input with brief A presses. Package examples are original artificial recordings.

Controllers and analogue input

Each recording has compact columns for its controls. Shared identifiers make comparable controls match across devices; button_layout(movie) gives the mapping, and align_buttons() aligns matrices from several recordings.

See the universal controller layout for the shared identifiers.

Recorded numeric values are available through analog_channels(), in columns named by key (left_x, mouse_dx); channel_layout(movie) lists the labels of the recording. Stick input can additionally be represented as four or eight directions, an angle, or an angle with magnitude. Choose a representation for each stick:

path <- system.file("extdata", "sample.dtm", package = "replayr")
movie <- read_movie(path,
  analog = c(left = "angle+magnitude", right = "cardinal8"))

The original coordinates remain available. Mouse, touch, light-gun, and motion values retain the units supplied by their recording format.

Rows follow the source recording: they may be frames, controller polls, or timestamped events. n_observations() counts imported observations. Readers retain available timing information and identify polls whose controller port is unknown, so these distinctions can be handled in an analysis. recording_info() reports platform, video standard, frame rate and rerecord count under one name each, whatever the format calls them, and observation_time() gives the time of each observation in seconds.

Documentation

vignette("replayr", package = "replayr") reads a recording, looks at the input of one player, identifies its controls and the time of every observation, and shows sticks, mice, several players and the formats replayr reads. vignette("compatibility", package = "replayr") is the reference: the platforms, formats, versions and devices, and the rules for the IDs of controls. Reader help pages describe format-specific options; ?read_bk2_chunks explains how to process large BK2 recordings in chunks. The vignettes and help pages are also on the package website, https://tp451.github.io/replayr/.

Author and license

Thorben Pelzer ([email protected]). GPL version 2 or later. Format sources and attribution are listed in inst/COPYRIGHTS.

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.

install.packages("replayr")

0.4.0 by Thorben Pelzer, 8 hours ago


https://github.com/tp451/replayr, https://tp451.github.io/replayr/


Report a bug at https://github.com/tp451/replayr/issues


Browse source code at https://github.com/cran/replayr


Authors: Thorben Pelzer [aut, cre] (ORCID:


Documentation:   PDF Manual  


GPL (>= 2) license


Imports jsonlite, xml2, zip, utils

Suggests knitr, rmarkdown, testthat


See at CRAN