Skip to contents

Reads ZIP input logs with controlsversion 0: Game Boy/Game Boy Color pads, SNES 12- and 16-button pads, multitaps, Y-cabled pads, and a declared Super Scope on port 2. Super Game Boy movies retain their SNES controller layout. The four spare bits of a 16-bit pad report are not buttons of the pad; system_channels() returns them as pad<n>_ext0 to pad<n>_ext3.

Usage

read_lsmv(
  path,
  analog = "raw",
  deadzone = NULL,
  triggers = "raw",
  aliases = TRUE,
  max_input_bytes = 256 * 1024^2,
  ...
)

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.

max_input_bytes

Maximum expanded input-log size for a full import, in bytes. The default is 256 * 1024^2. Increase this explicitly when sufficient memory is available, up to R's single-string limit of 2147483647 bytes. The limit is checked before extracting the input log.

...

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 observation per input subframe.

Details

Every non-empty input row is retained, including subframes between frame starts. n_observations() counts these observations; header$frameCount counts frame starts. subframes contains source_line, frame_start, source_frame, and subframe (the row's one-based position within its source frame). Player indices follow controller fields in the source log.

subframes also retains reset, hard_reset, reset_delay_high, and reset_delay_low. The encoded delay is 10000 * reset_delay_high + reset_delay_low. commands uses bit 0 for the reset flag and bit 1 for the hard-reset flag. source_input preserves the complete input text, including blank lines and original line endings.

Super Scope controls use a (trigger), b (cursor), mode (turbo), and start (pause). Their separate source keys remain in source_layout. analog_channels() returns its signed source coordinates as aim_x and aim_y. button_layout() gives stable control IDs. Mouse and Justifier port types raise an error.

The input member's ZIP checksum is verified before parsing. Full imports default to a 256 MiB expanded-input limit. Damaged controller metadata raises an error; other complete metadata with an integrity defect is retained with a warning.

Examples

movie <- read_lsmv(system.file("extdata", "sample.lsmv", package = "replayr"))
observation_unit(movie)
#> [1] "input subframe"
head(movie$subframes[, c("source_frame", "subframe", "reset")], 3)
#>   source_frame subframe reset
#> 1            1        1 FALSE
#> 2            2        1 FALSE
#> 3            3        1 FALSE