BizHawk ZIP movies. LogKey names determine digital controls and numeric channels. Known N64 and
PlayStation stick encodings can be transformed; other numeric channels remain raw.
The BK2 files that Gym Retro writes are read as well. Their input log names the controls
without the LogKey: prefix and its Reset and Power group; the reader restores both and notes
it in movie$header$logKeyRestored. Buttons 1 and 2 of a Master System or Game Gear pad, which
Gym Retro writes as B and A, are named B1 and B2 as in a BizHawk recording.
An arcade cabinet's analogue joysticks are its left and right analogue stick. MAME records their
raw values without centre or range, which differ from cabinet to cabinet; when directions or
angles are requested, both are estimated from the values of the recording, with a warning that
states the estimate.
Digital columns are compact; button_layout() gives their stable IDs.
Numeric source channels are always retained in analog_channels().
The full import defaults to a 256 MiB limit on the expanded input log to
avoid large temporary allocations. read_bk2_chunks() processes larger
recordings in bounded memory. The final movie and parsing buffers can use
substantially more memory than the text itself.
Usage
read_bk2(
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 throughstick_channels(). Original X/Y values remain inanalog_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.
NULLuses 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_Clampin 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 anNAangle. 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 thatbutton_layout()describes. WithFALSE, 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 of2147483647bytes. The limit is checked before extracting the input log.- ...
Reader-specific arguments, such as
controller_orderfor M64 or DTM, ormemberfor a recording inside a ZIP archive (seemovie_members()).
Value
A replayr_movie with compact digital columns and selected stick fields.
Details
Like BizHawk, the reader takes input rows and the LogKey only from lines
that start with them. If the LogKey line is indented, its control layout is
still used and a warning is given; indented input rows stay excluded and
are counted in header$indentedInputLines. A log without a LogKey is read
only when its header and every row match the standard two-pad NES layout;
any other log without a LogKey raises an error.
A digital control is held unless its character is ., as BizHawk reads
it; the letter written there is a convention.
BizHawk writes the hash of the game under header$SHA1, but several cores
write an MD5 or a CRC32 there. header$SHA1Kind says which it is:
"SHA1", "MD5" or "CRC32", and "" for a value that is no hash,
such as "N/A". The MD5 and CRC32 of a disc are BizHawk's hashes of part
of the disc, not those of an image file.
Examples
movie <- read_bk2(system.file("extdata", "sample.bk2", package = "replayr"))
movie
#> <replayr_movie [bk2] observations=3600 players=1 buttons=8 source=sample.bk2>
#> Header keys: MovieVersion, Platform, Core, GameName, Author, comment, controllerPorts, bk2NonStickPlayers, ...
#> P1 active observations: dpad_right=900, dpad_left=900, dpad_down=900, dpad_up=900, start=6, select=4, b=900, a=450
head(system_channels(movie), 3)
#> reset power
#> 1 FALSE FALSE
#> 2 FALSE FALSE
#> 3 FALSE FALSE
# A mouse recorded by BizHawk: its buttons are controls, its movement
# is two numeric channels.
mouse <- read_bk2(system.file("extdata", "paper", "mouse-drag.bk2", package = "replayr"))
button_layout(mouse)[, c("key", "name")]
#> key name
#> 1 start Start
#> 2 b Right Button
#> 3 a Left Button
#> 4 x Middle Button
channel_layout(mouse)
#> column key name
#> 1 1 mouse_dx P1 Motion Left / Right
#> 2 2 mouse_dy P1 Motion Up / Down