Skip to contents

Dispatches by extension to the format-specific reader. Every reader returns compact digital columns, a stable cross-controller ID map, and original numeric channels. A row may be a frame, poll, input event, or tic depending on the format.

Usage

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

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.

format

Format of the file, as one of the extensions of supported_formats() ("fm2" or ".fm2"), or "atari_gc" or "atari_head" for a table of these data sets. The default NULL takes it from the extension of path, or from the content as described above. With format, a file called .zip is read as a recording of that format and not searched for recordings.

...

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, or a replayr_poll_stream for unassigned controller ports or heterogeneous device polls, as in CTM. Use button_layout() for column identities, player() for logical states, and stick_channels() for selected stick fields.

Details

The extension decides the reader. A file under another extension, or under none, is recognised by its content where its format has a signature: the first bytes of most binary formats, the version 3 line of FCEUX, the members of a BizHawk or lsnes archive, the header of a BizHawk text movie or an openMSX replay, and the first line of a table of the Atari Grand Challenge data set or of Atari-HEAD (read_txt()). These two share the extension .txt, which says too little by itself: a .txt file is read as what its content shows. A file whose extension and signature disagree is refused, with the format its content shows. format names the format in every other case, for example for a Doom demo that is not called .lmp.

Examples

path <- system.file("extdata", "sample.m64", package = "replayr")
movie <- read_movie(path, analog = "angle+magnitude")
button_layout(movie)
#>    column id        key mnemonic    name   kind
#> 1       1  1 dpad_right        R   Right button
#> 2       2  2  dpad_left        L    Left button
#> 3       3  3  dpad_down        D    Down button
#> 4       4  4    dpad_up        U      Up button
#> 5       5  5      start        T   Start button
#> 6       6  7          b        B       B button
#> 7       7  8          a        A       A button
#> 8       8 11         l1        p      L1 button
#> 9       9 12         r1        q      R1 button
#> 10     10 18          z        Z       Z button
#> 11     11 20    c_right        > C-Right button
#> 12     12 21     c_left        <  C-Left button
#> 13     13 22     c_down        v  C-Down button
#> 14     14 23       c_up        ^    C-Up button
head(stick_channels(movie))
#>      left_angle left_magnitude
#> [1,]   0.000000      0.5468750
#> [2,]   1.636577      0.5470982
#> [3,]   3.270488      0.5477671
#> [4,]   4.085617      0.5482683
#> [5,]   5.710593      0.5496026
#> [6,]   7.431408      0.5436288
# A recording under another name: an SNES movie is known by its signature,
# a Doom demo has none and is named.
copy <- tempfile(fileext = ".dat")
file.copy(system.file("extdata", "sample.smv", package = "replayr"), copy)
#> [1] TRUE
read_movie(copy)
#> <replayr_movie [smv] observations=3600 players=1 buttons=12 source=file1a6b33666eb.dat>
#> Header keys: version, uid, rerecordCount, ctrlMask, opts, isPal, sync, inputSampleCount, ...
#> P1 active observations: dpad_right=900, dpad_left=900, dpad_down=900, dpad_up=900, start=6, select=4, b=900, a=450, x=288
file.copy(system.file("extdata", "sample.lmp", package = "replayr"), copy, overwrite = TRUE)
#> [1] TRUE
read_movie(copy, format = "lmp")
#> <replayr_movie [lmp] observations=2100 players=4 buttons=2 source=file1a6b33666eb.dat>
#> Header keys: version, emulator, game, observationUnit, fps, enabledPorts, controllerPorts, outerHeader, ...
#> P1 active observations: action_attack=420, action_use=71
unlink(copy)