Register file¶

Technical overview. The Game Boy CPU has 8-bit registers A, F, B, C, D, and E, along with the 16-bit register pairs HL, SP, and PC. The F register contains the CPU flags, while PC and SP track execution and the stack.

Using the API. PyBoyRegisterFile is exposed as pyboy.register_file. Its properties read and write the CPU registers, making it useful from a callback registered with pyboy.PyBoy.hook_register(), where execution is paused at a precise instruction.

class pyboy.PyBoyRegisterFile(cpu)[source]¶

Bases: object

This class cannot be used directly, but is accessed through PyBoy.register_file.

This class serves the purpose of reading and writing to the CPU registers. It’s best used inside the callback registered with PyBoy.hook_register, as PyBoy.tick doesn’t return at a specific point.

See the Pan Docs: CPU registers and flags for a great overview.

Registers are accessed with the following names: A, F, B, C, D, E, HL, SP, PC where the last three are 16-bit and the others are 8-bit. Reads return integers. Assignments accept integers and mask them to the register width; F keeps only its upper four flag bits.

Example:

>>> def my_callback(pyboy):
...     print("Register A:", pyboy.register_file.A)
...     pyboy.memory[0xFF50] = 1 # Example: Disable boot ROM
...     pyboy.register_file.A = 0x11 # Modify to the needed value
...     pyboy.register_file.PC = 0x100 # Jump past existing code
>>> pyboy.hook_register(-1, 0xFC, my_callback, pyboy)
>>> pyboy.tick(120)
Register A: 1
True