Utilities

Technical overview. Game Boy integrations need values that cross the boundary between the emulated hardware and the host application, such as button events, BCD-encoded numbers, and errors describing invalid hardware access.

Using the API. pyboy.utils provides WindowEvent values for PyBoy.send_input, BCD conversion helpers, and the exception classes raised by the public API. The complete set of event names is listed below; use the high-level button methods when they are sufficient.

class pyboy.utils.WindowEvent(event)

Bases: object

Namespace of integer constants representing supported input and emulator events.

Pass one of these constants to PyBoy.send_input:

>>> from pyboy.utils import WindowEvent
>>> pyboy.send_input(WindowEvent.PAUSE)

Just for button presses, it might be easier to use: pyboy.PyBoy.button, pyboy.PyBoy.button_press and pyboy.PyBoy.button_release.

See WindowEvent options for the complete list of supported events.

pyboy.utils.dec_to_bcd(value, byte_width=1, byteorder='little')

Converts a decimal value to Binary Coded Decimal (BCD).

Parameters:

• value (int) – The integer value to convert.

• byte_width (int) – The number of bytes to consider for each value.

• byteorder (str) – The endian type to use. This is only used for 16-bit values and higher. See int.from_bytes for more details.

Example:

>>> from pyboy.utils import dec_to_bcd
>>> f"{dec_to_bcd(30):08b}"
'00110000'
>>> f"{dec_to_bcd(32):08b}"
'00110010'

Returns:

The BCD equivalent of the decimal value.

Return type:

int

pyboy.utils.bcd_to_dec(value, byte_width=1, byteorder='little')

Converts a Binary Coded Decimal (BCD) value to decimal.

Parameters:

• value (int) – The BCD value to convert.

• byte_width (int) – The number of bytes to consider for each value.

• byteorder (str) – The endian type to use. This is only used for 16-bit values and higher. See int.to_bytes for more details.

Example:

>>> from pyboy.utils import bcd_to_dec
>>> bcd_to_dec(0b00110000)
30
>>> bcd_to_dec(0b00110010)
32

Returns:

The decimal equivalent of the BCD value.

Return type:

int

exception pyboy.utils.PyBoyException

Bases: Exception

Custom exception class for PyBoy-related errors.

This exception is raised for errors specific to the PyBoy emulator.

exception pyboy.utils.PyBoyInternalError

Bases: PyBoyException

Exception raised for internal errors in the PyBoy emulator.

This exception is used to indicate errors that occur within the PyBoy emulator that are not expected to be encountered by the end user.

exception pyboy.utils.PyBoyAssertException

Bases: PyBoyException

Exception is used to indicate assertion errors that occur within the PyBoy emulator.

exception pyboy.utils.PyBoyOutOfBoundsException

Bases: PyBoyException

Exception raised for errors when an operation exceeds array or integer bounds in PyBoy.

exception pyboy.utils.PyBoyNotImplementedException

Bases: PyBoyException

Exception raised for methods that are not yet implemented in a base class.

exception pyboy.utils.PyBoyInvalidInputException

Bases: PyBoyException

Exception is used to indicate that an invalid input has been provided to a PyBoy function or method.

exception pyboy.utils.PyBoyInvalidOperationException

Bases: PyBoyException

Exception raised when the user requests an invalid operation, which cannot be performed.

exception pyboy.utils.PyBoyDependencyError

Bases: PyBoyException

Exception raised for errors related to missing dependencies in PyBoy.

exception pyboy.utils.PyBoyFeatureDisabledError

Bases: PyBoyException

Exception raised when the user requests a feature that has been disabled.

exception pyboy.utils.AccessError

Bases: PyBoyException

Base class that replaces an optional feature. Whenever this object is accessed, it raises a predefined exception. I.e. on missing dependencies etc.

exception pyboy.utils.PillowImportError

Bases: AccessError, PyBoyDependencyError

Exception raised when the Pillow library is not found.

exception pyboy.utils.SoundEnabledError

Bases: AccessError, PyBoyFeatureDisabledError

Compatibility exception for disabled sound access. Current sound accessors raise PyBoyFeatureDisabledError.

WindowEvent options

The internal events are included for completeness, but applications should use the public events when sending input.

QUIT PRESS_ARROW_UP PRESS_ARROW_DOWN PRESS_ARROW_RIGHT PRESS_ARROW_LEFT PRESS_BUTTON_A PRESS_BUTTON_B PRESS_BUTTON_SELECT PRESS_BUTTON_START RELEASE_ARROW_UP RELEASE_ARROW_DOWN RELEASE_ARROW_RIGHT RELEASE_ARROW_LEFT RELEASE_BUTTON_A RELEASE_BUTTON_B

RELEASE_BUTTON_SELECT RELEASE_BUTTON_START _INTERNAL_TOGGLE_DEBUG PRESS_SPEED_UP RELEASE_SPEED_UP STATE_SAVE STATE_LOAD PASS SCREEN_RECORDING_TOGGLE PAUSE UNPAUSE PAUSE_TOGGLE PRESS_REWIND_BACK PRESS_REWIND_FORWARD RELEASE_REWIND_BACK

RELEASE_REWIND_FORWARD WINDOW_FOCUS WINDOW_UNFOCUS _INTERNAL_RENDERER_FLUSH _INTERNAL_MOUSE _INTERNAL_MARK_TILE SCREENSHOT_RECORD DEBUG_MEMORY_SCROLL_DOWN DEBUG_MEMORY_SCROLL_UP MOD_SHIFT_ON MOD_SHIFT_OFF FULL_SCREEN_TOGGLE CYCLE_PALETTE SCREEN_RECORDING_TOGGLE_MP4 DEBUG_GAME_AREA_TOGGLE