Dolphin GameCube and Wii recordings. Multiple enabled ports return an ordered
replayr_poll_stream with unassigned ports. An optional controller_order
constructs player streams using a caller-verified repeating port order.
Usage
read_dtm(
path,
analog = "raw",
deadzone = NULL,
triggers = "raw",
aliases = TRUE,
controller_order = NULL,
dtm_variant = "auto",
wii_variant = "auto",
wii_extension = "raw",
wii_key = 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 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.- controller_order
Optional integer sequence listing every enabled controller port once, in its verified repeating polling order. Digital columns are compact;
button_layout()gives their stable IDs. Numeric source channels are always retained inanalog_channels().- dtm_variant
"auto"(default),"standard"(8-byte records), or"zelda"(17-byte Dolphin Zelda Edition records). Automatic recognition uses the verified Zelda Edition revisiona6e66c227c592d09ff09ef9b238d15ff52dd9632; other revisions default to the standard layout. Select"zelda"explicitly for another build whose extended layout has been verified from its source.- wii_variant
"auto","hid","hid-prefix8","hid-nomarker","serialized","mixed-hid","mixed-hid-nomarker", or"mixed-hid-connected". Automatic selection uses packet structure and, for mixed recordings, verified Dolphin revision profiles."hid-nomarker"handles reports starting with the Wii report ID."mixed-hid-nomarker"implements the native encoder rule: connected GameCube reports set the connection flag, disconnected reports have zero controls (with optional disc/reset commands), and Wii reports carry a prescribed length and report ID. Noncanonical records are rejected. Profiles for Dolphin 5.0-20571 and 2407 are selected automatically from the stored revision.header$framingRulerecords the encoding rule."mixed-hid-connected"remains available for externally verified files requiring the additional assumption that every GameCube poll is connected; that assumption is recorded inheader$framingAssumption.polls()retains device family, connection flags, and source order. Individual ports remain unassigned when several same-family ports are enabled.- wii_extension
Legacy extension interpretation:
"raw"(default),"nunchuk", or"classic". A selected type assumes unencrypted reports unless an encryption key is supplied.- wii_key
Optional 16-byte numeric vector: the eight
ftbytes followed by the eightsbbytes of the verified Dolphin extension key.- ...
Reader-specific arguments, such as
controller_orderfor M64 or DTM, ormemberfor a recording inside a ZIP archive (seemovie_members()).
Value
A replayr_movie for assigned ports, or a replayr_poll_stream for a multi-controller recording with unassigned ports.
Details
Every complete stored poll is imported. Dolphin's header input statistic is
retained as header$inputCount, alongside header$availablePollCount and
their signed difference in header$pollCountDifference. Dolphin uses the
input count as a statistic, so differences remain metadata.
header$frameCount retains the separate video-frame count.
header$romId is the game ID of the disc, such as "GALE01", and
header$romMD5 the MD5 of the disc image, where Dolphin computed one.
Zelda Edition extends each poll with a loading flag, a Tingle Tuner event
code, and Link's X/Z coordinates used by the emulator to detect desyncs.
These are available in poll_fields, with one row per original poll,
including when controller_order groups polls into player cycles.
Columns are loading, tuner_event, link_x, and link_z; coordinates
retain the game's source units. poll_bytes retains all original bytes.
Wii Remote recordings retain buttons, source motion values, and IR coordinates.
Wii Remote 1/2 use X/Y (IDs 9/10), +/- use Start/Select (5/6), and
Home uses Mode (19). Its D-pad and A/B buttons share the gamepad IDs.
Nunchuk C/Z use 17/18, Classic Controller buttons use the corresponding
gamepad IDs, and libTAS Guide uses Mode. Light-gun triggers use A (8);
GunCon side A/B and offscreen shot use B/X/Y (7/9/10). Mouse left, right,
and middle buttons use A/B/X. See button_layout() for shared identities.
When multiple source buttons share an ID, the column is active if either
is pressed. source_inputs and source_layout preserve the separate
states and their mapping whenever aliases are combined. Wii device states
also appear in poll_fields as wii_remote_* and wii_classic_* columns,
which polls() includes for unassigned streams.
Legacy HID reports retain extension bytes; wii_extension = "nunchuk" or
"classic" decodes a caller-identified extension. Supply wii_key when its
reports are encrypted. The default retains the bytes because older DTM files
do not store an extension identity or encryption key. New serialised Dolphin
states include their extension type; Nunchuk and Classic Controller states
are decoded automatically. Other extension payloads remain source bytes.
Each row is a poll. poll_lengths gives valid bytes in the padded
poll_bytes matrix; historical eight-byte prefixes remain in poll_prefix_bytes.
Wii Remote acceleration is given on Dolphin's ten-bit scale. A report
stores nine bits for Y and Z, which are widened as Dolphin widens them,
by repeating the lowest stored bit.
Mixed GameCube/Wii streams from the verified legacy Dolphin layout retain
device family and physical port (when unique) on each poll. They stay in
source order and do not accept controller_order. Automatic mixed recognition
uses revision 7804f388aeb075266ae8c363e0932c355ba6ed5e; select mixed-hid
explicitly only for a build with the same verified record layout.
An incomplete final Wii packet is retained in source_tail, with a warning.
Invalid reports retain their raw bytes and have valid_report = FALSE.
poll_fields$report_issue describes the problem, and source_offset gives
the zero-based byte position in the file. Filter digital fields using the
validity flag before analysis.
Examples
movie <- read_dtm(system.file("extdata", "sample.dtm", package = "replayr"))
head(analog_channels(movie), 3)
#> left_trigger right_trigger left_x left_y right_x right_y
#> [1,] 0 0 198 128 128 128
#> [2,] 0 0 198 130 128 128
#> [3,] 0 0 198 132 128 128
# Polls of several controllers without a known order stay one stream.
stream <- read_dtm(system.file("extdata", "paper", "unassigned.dtm", package = "replayr"))
class(stream)
#> [1] "replayr_poll_stream"
polls(stream)[, c("poll", "port", "a", "left_x", "left_y")]
#> poll port a left_x left_y
#> 1 1 NA TRUE 128 128
#> 2 2 NA FALSE 200 160
#> 3 3 NA FALSE 128 128