Memory scanner

Technical overview. Game state is stored as changing byte values in the Game Boy address space. A value may occupy multiple bytes, use a particular byte order, or be encoded as binary-coded decimal (BCD), so finding it often requires comparing memory across multiple frames.

Using the API. MemoryScanner searches an address range with a standard comparison, then keeps the matching addresses for rescan_memory to filter using changes between scans. The comparison and value-type enums select whether a scan looks for exact, relational, integer, or BCD values.

class pyboy.api.memory_scanner.StandardComparisonType(*values)

Bases: Enum

Enumeration for defining types of comparisons that do not require a previous value.

class pyboy.api.memory_scanner.DynamicComparisonType(*values)

Bases: Enum

Comparisons between values found in the previous and current scans.

class pyboy.api.memory_scanner.ScanMode(*values)

Bases: Enum

Interpret scanned bytes as an unsigned integer or binary-coded decimal.

class pyboy.api.memory_scanner.MemoryScanner(pyboy)

Bases: object

A class for scanning memory within a given range.

scan_memory(target_value=None, start_addr=0x0000, end_addr=0xFFFF, standard_comparison_type=StandardComparisonType.EXACT, value_type=ScanMode.INT, byte_width=1, byteorder='little')

Scan the inclusive address range from start_addr to end_addr for a target value.

Example:

>>> pyboy.memory[0xC000] = 4
>>> pyboy.memory_scanner.scan_memory(4, start_addr=0xC000, end_addr=0xC000)
[49152]

Parameters:

• target_value (int or None) – Value to search for. If None, every value matches.

• start_addr (int) – First address to scan. Defaults to 0.

• end_addr (int) – Last address to scan, inclusive. Defaults to 65535.

• standard_comparison_type (StandardComparisonType) – Comparison to apply. Defaults to EXACT.

• value_type (ScanMode) – Interpret values as INT or BCD. Defaults to INT.

• byte_width (int) – Positive number of bytes per value. Defaults to 1.

• byteorder (str) – “little” or “big” byte order for multi-byte values. Defaults to “little”.

Returns:

Addresses where the target value is found.

Return type:

list[int]

Raises:

ValueError – If byte_width is not positive.

rescan_memory(new_value=None, dynamic_comparison_type=DynamicComparisonType.UNCHANGED, byteorder=None)

Filter cached addresses using values read in the current scan.

Example:

>>> pyboy.memory[0xC000] = 4
>>> pyboy.memory_scanner.scan_memory(4, start_addr=0xC000, end_addr=0xC000)
[49152]
>>> pyboy.memory[0xC000] = 8
>>> from pyboy.api.memory_scanner import DynamicComparisonType
>>> addresses = pyboy.memory_scanner.rescan_memory(8, DynamicComparisonType.MATCH)
>>> print(addresses)
[49152]

Parameters:

• new_value (int or None) – Target value used by MATCH; required for MATCH and ignored by other comparisons.

• dynamic_comparison_type (DynamicComparisonType) – Comparison to apply. Defaults to UNCHANGED.

• byteorder (str or None) – Byte order for reading values. If None, reuse the byte order from the previous scan_memory call.

Returns:

Addresses remaining in the cache after filtering.

Return type:

list[int]