Check connectivity to the mGBA bridge. Returns 'pong' if the emulator is running and the Lua bridge is loaded.

Get the currently-loaded game title, game code (e.g. AGBE), platform identifier, current frame count, and a capabilities object listing which optional emu methods this build of mGBA supports (pause, frameAdvance, saveStateSlot, etc.). Use the capabilities map to feature-detect before calling tools that depend on optional methods.

Read a single unsigned byte (u8) from a GBA memory address.

GBA address space: 0x02000000 EWRAM (256 KiB, general-purpose) 0x03000000 IWRAM (32 KiB, fast stack/variables) 0x04000000 IO registers 0x05000000 Palette RAM (1 KiB) 0x06000000 VRAM (96 KiB) 0x07000000 OAM (1 KiB) 0x08000000 ROM (up to 32 MiB, read-only)

Game Boy / GBC address space (when running a GB/GBC ROM): 0x0000 ROM bank 0 (16 KiB, read-only on bus; writes here trigger MBC commands but mgba_write* bypasses the bus) 0x4000 ROM banked (switchable) 0x8000 VRAM (8 KiB) 0xA000 Cartridge SRAM (8 KiB) — disabled by default on MBC1/3/5 carts 0xC000 WRAM (8 KiB; CGB has banked extension to 0xD000) 0xFE00 OAM (160 B) 0xFF00 I/O registers 0xFF80 HRAM (127 B)

Read an unsigned 16-bit little-endian value from a GBA memory address. Address should be 2-byte aligned.

Read an unsigned 32-bit little-endian value from a GBA memory address. Address should be 4-byte aligned.

Write a single byte value to a memory address. Only works on RAM regions; writes to ROM are no-ops.

NOTE: writes use mGBA's debug-direct memory access, which bypasses the cartridge bus model. On Game Boy with an MBC cartridge, this means writes to ROM region (0x0000-0x7FFF) won't trigger MBC bank-switch / RAM-enable commands, and writes to SRAM (0xA000-0xBFFF) hit the underlying buffer regardless of MBC enable state. To seed cartridge SRAM cleanly, use mgba_save_state / mgba_load_state with a pre-prepared state file.

Write a 16-bit value (little-endian) to a memory address. Address must be 2-byte aligned.

NOTE: writes use mGBA's debug-direct memory access, which bypasses the cartridge bus model. On Game Boy with an MBC cartridge, this means writes to ROM region (0x0000-0x7FFF) won't trigger MBC bank-switch / RAM-enable commands, and writes to SRAM (0xA000-0xBFFF) hit the underlying buffer regardless of MBC enable state. To seed cartridge SRAM cleanly, use mgba_save_state / mgba_load_state with a pre-prepared state file.

Write a 32-bit value (little-endian) to a memory address. Address must be 4-byte aligned.

NOTE: writes use mGBA's debug-direct memory access, which bypasses the cartridge bus model. On Game Boy with an MBC cartridge, this means writes to ROM region (0x0000-0x7FFF) won't trigger MBC bank-switch / RAM-enable commands, and writes to SRAM (0xA000-0xBFFF) hit the underlying buffer regardless of MBC enable state. To seed cartridge SRAM cleanly, use mgba_save_state / mgba_load_state with a pre-prepared state file.

Read a contiguous range of bytes from emulated memory and return them as an array of integers. Maximum 4096 bytes per call.

Write a contiguous range of bytes to emulated RAM in one call. Useful for seeding SRAM, patching code blocks, or installing cheats. Maximum 4096 bytes per call.

NOTE: writes use mGBA's debug-direct memory access, which bypasses the cartridge bus model. On Game Boy with an MBC cartridge, this means writes to ROM region (0x0000-0x7FFF) won't trigger MBC bank-switch / RAM-enable commands, and writes to SRAM (0xA000-0xBFFF) hit the underlying buffer regardless of MBC enable state. To seed cartridge SRAM cleanly, use mgba_save_state / mgba_load_state with a pre-prepared state file.

Queue a button-press: hold the given buttons for frames frames, then release for release_frames frames before the next queued press starts. Each call appends to the queue rather than overwriting, so consecutive calls produce distinct edge events that ROMs see as separate presses (rather than one continuous hold). Returns immediately; the press fires asynchronously on the emulator's frame callback. Valid button names: A, B, Select, Start, Right, Left, Up, Down, R, L.

Advance emulation by N frames without returning to the event loop. Useful for precise timing in tests.

Pause emulation.

Resume emulation after a pause.

Reset the currently-loaded ROM (equivalent to pressing the GBA reset button).

Take a screenshot of the current display and save it to a file. Returns the saved file path.

Save the current emulator state. Pass either slot (0-9, mGBA-managed slot file) or path (absolute file path; only works on builds that expose the file API). Useful for capturing checkpoints to load later — and as a clean way to seed cartridge SRAM on Game Boy without fighting the MBC.

Load a previously-saved emulator state. Pass either slot (0-9) or path (absolute file path). The state must come from the same ROM and a compatible mGBA version.