Controllers¶
Stable Retro supports one to four player input channels. The default is one
player, and omitting controller_devices preserves the emulator core’s default
controller setup. Increasing players changes the action space; it does not
automatically enable a console’s multitap or other adapter.
Selecting controller devices¶
Use controller_devices to map zero-based physical connector numbers to
core-advertised device IDs:
import stable_retro as retro
env = retro.make(
"NHL94-Genesis-v0",
players=4,
controller_devices={0: 1025},
)
try:
print(env.em.controller_devices)
observation, info = env.reset()
observation, reward, terminated, truncated, info = env.step(
env.action_space.sample(),
)
finally:
env.close()
For the Genesis core, device 1025 is the three-button EA 4-Way Play adapter.
The core advertises two physical connectors; selecting this adapter on connector
0 enables four input channels across both connectors. The game and selected
savestate must also support the adapter and the desired multiplayer mode.
Device IDs and available adapters are core-specific.
env.em.controller_devices returns a list of dictionaries, one per advertised
connector, mapping device IDs to descriptions. The low-level method
env.em.set_controller_port_device(port, device) rejects invalid connectors and
devices that the core does not advertise. For a core without controller
metadata, only the standard joypad (1) and disconnected (0) devices can be
selected.
The controller_devices constructor argument configures devices after loading
the ROM and before restoring the starting state. Changing a device resets its
protocol state, so do not repeat device setup after restoring a gameplay
snapshot. The Genesis core preserves its chosen adapter across reset and state
restore, while restoring the saved console I/O state separately. A savestate
made without an adapter may require game-specific initialization of its
controller-polling registers; enabling the adapter alone cannot repair it.
Player inputs and rewards¶
players must be an integer from 1 through RetroEmulator.max_players
(currently 4). Player input channels are zero-based and distinct from physical
connectors.
The default MultiBinary action space has env.num_buttons * players entries,
grouped by player: all player 1 buttons, then all player 2 buttons, and so on.
Actions.DISCRETE and Actions.MULTI_DISCRETE also scale with the player count.
The low-level env.em.set_button_mask(mask, player) sets one input channel,
not a physical connector. Unused channels should remain neutral.
The Gymnasium reset and step return formats are unchanged. Rewards remain
scalar by default, including in multiplayer environments. Setting
env.multi_rewards = True returns a reward per player, using the integration’s
configured rewards.
Native input callbacks support individual joypad buttons and packed joypad bitmasks. Unsupported device types, indices, channels, and buttons return neutral input. Python button masks must be contiguous one-dimensional vectors with at most 16 buttons; omitted buttons are released.
Movies and replay¶
BK2 movies support one to four players. Movie reads and writes reject player
indices outside the movie’s player count and button indices outside 0 through
15.
BK2 files do not encode controller-device configuration. Record that
configuration separately and pass the same controller_devices mapping when
creating the replay environment, before restoring the movie state. Match
players to movie.players; specifying four players alone does not select an
adapter. See Python API for recording and playback examples.
Regression tests¶
Controller tests use the bundled Genesis homebrew ROM; no commercial ROM is required:
python -m pytest tests/test_python/test_controllers.py
They cover device metadata and validation, input bounds, four-player movies,
and environment contracts. Native callback coverage is included in
EmulatorTest.ControllerInputBoundsAndBitmasks.