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 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.
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.
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.
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.
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/.
Thorben Pelzer ([email protected]). GPL version 2 or later. Format sources and attribution are listed in inst/COPYRIGHTS.