PURPOSE: Verify that the mGBA Lua bridge is connected and responding to RPC over the TCP socket. USAGE: Call this once at start-of-session before issuing other tool calls; if it succeeds, every other tool will at least be reachable (individual tools may still fail if the loaded mGBA build doesn't expose a particular emu method — see mgba_get_info → capabilities for that). BEHAVIOR: No side effects — pure liveness probe. Times out after a few seconds with a clear error if mGBA isn't running, isn't pointed at the right host:port, or hasn't loaded the bridge Lua script (Tools → Scripting in mGBA). RETURNS: The literal string 'pong' on success.

PURPOSE: Get the loaded ROM's title, internal game code (e.g. 'AGBE' for GBA Pokemon Emerald US, 'BPRE' for FireRed), platform identifier (GBA vs GB/GBC), current frame count, and a capabilities map listing which optional emu methods this mGBA build exposes (pause, unpause, frameAdvance, saveStateSlot, saveStateFile, screenshot, etc.). USAGE: Call after mgba_ping at the start of a session to identify the loaded ROM and feature-detect optional capabilities BEFORE invoking tools that depend on them — pause/unpause/reset/save_state/load_state/advance_frames are all build-dependent on mGBA. The platform field tells you whether to address memory using the GBA layout (32-bit, EWRAM 0x02000000) or the GB/GBC layout (16-bit, WRAM 0xC000). BEHAVIOR: No side effects — pure read of emulator metadata. Returns '(unavailable)' for fields the loaded core can't expose (title when no ROM is loaded, code on systems without a header, etc.). Never throws on a partial read. RETURNS: Multi-line text with Title, Code, Platform, Frame, then the lists of present and missing capabilities for this build.

PURPOSE: Read an unsigned 8-bit byte from emulated memory at the given system bus address. USAGE: Use for single-byte status flags, counters, and 8-bit fields. For 16- or 32-bit values use mgba_read16/read32 (one call instead of multi-byte assembly); for spans of more than ~4 bytes use mgba_read_range (one round-trip instead of N frame-latency hops). Reads work the same way whether emulation is paused or running, so pause is optional but recommended when you need a coherent snapshot across multiple reads. BEHAVIOR: No side effects — pure read. Returns an error if the address is outside the platform's mapped regions or the bridge method is missing on this mGBA build. RETURNS: Single line 'ADDR_HEX: VAL_DEC (0xVAL_HEX)', e.g. '0x2000000: 99 (0x63)'.

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)

PURPOSE: Read an unsigned 16-bit little-endian value from emulated memory at the given system bus address. USAGE: Use for 16-bit fields (most game-state values: HP, score, coordinates on 16-bit-flavoured layouts). For single bytes use mgba_read8; for 32-bit values use mgba_read32; for non-aligned spans, big-endian fields, or arbitrary structures use mgba_read_range and decode the bytes yourself (this tool always interprets bytes as little-endian, which matches both GBA and GB/GBC native endianness). BEHAVIOR: No side effects — pure read. Reads two consecutive bytes (low byte at address, high byte at address+1) and combines them as little-endian. Returns an error if the address is unmapped, the read straddles a region boundary, or the bridge method is missing on this build. RETURNS: Single line 'ADDR_HEX: VAL_DEC (0xVAL_HEX)'.

PURPOSE: Read an unsigned 32-bit little-endian value from emulated memory at the given system bus address. USAGE: Use for 32-bit fields (timestamps, large counters, pointers on GBA, RGBA colours). For 8/16-bit reads use mgba_read8/read16; for big-endian or unaligned multi-word reads use mgba_read_range and decode yourself. BEHAVIOR: No side effects — pure read. mGBA's native emu.read32 is intermittently flaky when called via pcall on certain builds, so the bridge transparently routes 32-bit reads through readRange(addr, 4) and reassembles them little-endian — you get a stable answer either way. Returns an error only if the address is unmapped or the underlying readRange itself fails. RETURNS: Single line 'ADDR_HEX: VAL_DEC (0xVAL_HEX)'.

PURPOSE: Read a contiguous range of bytes from emulated memory and return them as a hex-formatted dump. USAGE: Use whenever you need more than ~4 bytes — one round-trip vs N frame-latency hops compared to looping mgba_read8. Maximum 4096 bytes per call (bridge serialization limit); for larger reads, batch in 4 KiB chunks. The classic two-snapshot RAM-hunt workflow uses this: snapshot before a known change, snapshot after, diff for matching deltas. Also useful for inspecting unknown structures and for 'capture, modify, restore' write_range workflows. This is the same primitive that mgba_read32 routes through internally. BEHAVIOR: No side effects — pure read. Reads length consecutive bytes starting at address. Returns an error if length > 4096, length < 1, the start address is unmapped, or the read crosses an unmapped region. RETURNS: Header line 'ADDR_HEX [N bytes]:' followed by space-separated 2-digit uppercase hex bytes.

PURPOSE: Write a single unsigned byte (0-255) to emulated memory at the given system bus address. USAGE: Use for single-byte cheats, debug pokes, and game-state mutations (give a player N lives, unlock a flag, set a counter). For 16/32-bit values prefer mgba_write16/write32 (single call instead of byte-at-a-time); for spans use mgba_write_range. To seed cart save RAM realistically (with proper MBC bank/enable behavior on Game Boy, or to install a known-good progression state on GBA), prefer mgba_save_state / mgba_load_state with a pre-prepared state file rather than poking SRAM bytes here. BEHAVIOR: DESTRUCTIVE: overwrites whatever was at address with no undo (snapshot via mgba_save_state first if you need rollback). The write is debug-direct memory access — bypasses MBC bank switches, cartridge mapper side-effects, RAM-enable gates, and bus protections — so it cannot be used to emulate cartridge hardware. Writes to ROM region addresses succeed at the memory level but produce no MBC effect on GB/GBC. Returns an error if the address is unmapped, value < 0 or > 255, or the bridge method is missing. Works whether emulation is paused or running. RETURNS: Single line 'Wrote VAL_DEC (0xVAL_HEX) → ADDR_HEX'.

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.

PURPOSE: Write an unsigned 16-bit little-endian value to emulated memory at the given system bus address. USAGE: Use for 16-bit cheats and pokes (HP, score, coordinates). For single bytes use mgba_write8; for 32-bit use mgba_write32; for big-endian fields, byteswap and use mgba_write_range; for cart save RAM seeding with proper MBC semantics, use mgba_save_state / mgba_load_state. BEHAVIOR: DESTRUCTIVE: overwrites two bytes (low byte at address, high byte at address+1) with no undo. Debug-direct memory write — no MBC/mapper/DMA mediation, see mgba_write8 notes for the cartridge-bus bypass details. Returns an error if the address is unmapped, address+2 crosses an unmapped boundary, value < 0 or > 65535, or the bridge method is missing. RETURNS: Single line 'Wrote VAL_DEC (0xVAL_HEX) → ADDR_HEX'.

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.

PURPOSE: Write an unsigned 32-bit little-endian value to emulated memory at the given system bus address. USAGE: Use for 32-bit cheats and pokes (timestamps, large counters, pointers on GBA). For 8/16-bit values use mgba_write8/write16; for big-endian layouts byteswap and use mgba_write_range. BEHAVIOR: DESTRUCTIVE: overwrites four bytes starting at address with no undo (snapshot via mgba_save_state first if you need rollback). Debug-direct memory write — bypasses MBC/mapper/DMA, see mgba_write8 notes. Returns an error if the address is unmapped, address+4 crosses an unmapped boundary, value < 0, or the bridge method is missing. RETURNS: Single line 'Wrote VAL_DEC (0xVAL_HEX) → ADDR_HEX'.

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.

PURPOSE: Write a contiguous byte sequence to emulated memory starting at the given system bus address. USAGE: Use whenever you're seeding more than ~4 bytes — one round-trip vs N frame-latency hops compared to looping mgba_write8. Maximum 4096 bytes per call (bridge serialization limit); for larger writes, batch in 4 KiB chunks. Useful for installing cheat tables, patching code blocks, restoring a captured byte window after experiments, and writing big-endian multi-byte values (byteswap them yourself first). For cart save RAM seeding with proper MBC semantics on Game Boy, use mgba_save_state / mgba_load_state instead — those go through the cartridge bus model. BEHAVIOR: DESTRUCTIVE: overwrites N bytes starting at address with no undo. Debug-direct memory write — bypasses MBC/mapper/DMA, see mgba_write8 notes for the cartridge-bus bypass details. Bytes are written sequentially address, address+1, ..., address+N-1. Returns an error if the address is unmapped, address+N crosses an unmapped boundary, the array contains a value outside 0-255, the array length is < 1 or > 4096, or the bridge method is missing. RETURNS: Single line 'Wrote N bytes → ADDR_HEX'.

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.

PURPOSE: Append a button-press to mGBA's input FIFO — hold the given buttons for frames frames, then release for release_frames frames before the next queued press starts. USAGE: Use to drive games with input. 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). To press the same button twice in a row reliably, send two presses — release_frames between them gives the ROM time to detect a key-up, which most input handlers require to register the second press. To advance emulation manually (without queueing inputs), use mgba_advance_frames. To inspect input-state side effects, pause first with mgba_pause and read RAM between presses. BEHAVIOR: Modifies the bridge's input queue; the press fires asynchronously on mGBA's frame callback. The call returns immediately with the new queue size — it does NOT block until the press completes. Returns an error if buttons contains a name not in the valid-key set, or if the bridge's input handling isn't installed on this build. RETURNS: Single line 'Queued press: KEYS (hold Nf, release Mf). Queue size: K'.

Valid button names: A, B, Select, Start, Right, Left, Up, Down, R, L.

PURPOSE: Step emulation by exactly N frames synchronously and return the new frame count. USAGE: Use for frame-precise input automation (combine with mgba_press_buttons to time inputs against in-game animation), letting the system initialize after a hard reset (RAM is mostly zero in the first ~30 frames after mgba_reset), or settling state between memory reads. For long jumps (thousands of frames) prefer mgba_save_state / mgba_load_state of a pre-prepared state — advance_frames scales linearly. To resume real-time playback indefinitely instead of stepping, use mgba_unpause. Works whether emulation is currently paused or running and does NOT change the pause state. BEHAVIOR: Advances mGBA's frame clock by N frames inside the bridge's frame callback. Each step costs roughly one real frame (~16ms at 60Hz GBA / ~16.7ms at 60Hz GB) plus one bridge round-trip — so advancing 600 frames takes ~10 seconds wall-clock. This method is build-dependent on mGBA; check capabilities.frameAdvance in mgba_get_info first. Returns an error if the capability is missing on this build. RETURNS: Single line 'Advanced N frame(s). Current frame: NEW_COUNT'.

PURPOSE: Pause emulation — freeze the game-logic clock and hold the current frame on screen. USAGE: Use before a sequence of memory-inspect / write / screenshot calls when you need a stable game state across calls (so the game doesn't advance between your reads). Use mgba_unpause to resume; use mgba_advance_frames to step single frames without leaving pause. Memory reads and writes work the same way whether paused or not, so pause is only required when you specifically need a coherent snapshot — for one-shot reads it's optional. BEHAVIOR: Modifies emulator run state. The Lua bridge keeps polling the socket while paused, so all other tool calls (memory r/w, screenshot, save_state, etc.) still work. This method is build-dependent on mGBA; check capabilities.pause in mgba_get_info first to handle missing capability gracefully. Returns an error if the capability is missing on this build. Calling pause when already paused is a no-op. RETURNS: Single line 'Emulation paused'.

PURPOSE: Resume emulation after a pause, returning to normal real-time playback. USAGE: Counterpart to mgba_pause. Use after a paused inspection sequence is complete. To advance only a few frames without resuming full speed, use mgba_advance_frames instead. BEHAVIOR: Modifies emulator run state. This method is build-dependent on mGBA; check capabilities.unpause in mgba_get_info first. Returns an error if the capability is missing on this build. Calling unpause when not paused is a no-op. RETURNS: Single line 'Emulation resumed'.

PURPOSE: Reset the loaded ROM — equivalent to pressing the reset button on the GBA / Game Boy. USAGE: Use to start fresh from boot. To return to a specific known-good point instead of boot, use mgba_load_state with a previously saved slot or .ss0/.ss1/etc state file. BEHAVIOR: DESTRUCTIVE: RAM contents become indeterminate (typically the BIOS-zeroed state), CPU returns to the reset vector, frame count resets to 0, input queue clears, and any in-progress audio/video state is discarded. The loaded ROM stays loaded — only volatile state is cleared. UNSAVED IN-GAME PROGRESS IS LOST (anything not committed to cartridge SRAM via the game's save menu, and anything not snapshotted via mgba_save_state). This method is build-dependent on mGBA; check capabilities.reset in mgba_get_info first. Returns an error if the capability is missing on this build. RETURNS: Single line 'ROM reset'.

PURPOSE: Save a PNG screenshot of the current emulator display to a file. USAGE: Use to capture visible game state for inspection, comparison across savestates, or sequence documentation. The image captures whatever the emulator is currently rendering — to capture a specific game state, pause / advance frames / load state first to get the frame you want, then call this. Path is optional; omit it to let mGBA write to its default screenshot directory and report back the chosen filename. BEHAVIOR: DESTRUCTIVE TO TARGET FILE if path is supplied: overwrites the file at path if it exists, with no prompt or backup. Returns an error if path is supplied but the parent directory doesn't exist or isn't writable, or if the bridge's screenshot method is missing on this build. RETURNS: Single line 'Screenshot saved: PATH', where PATH is the file actually written (the value you passed, or mGBA's default-directory file name if path was omitted).

PURPOSE: Save the entire emulator state (RAM, CPU/PPU/APU registers, mapper state, sound chip state, timing, in-flight DMA) to either an mGBA-managed numbered slot OR an arbitrary file path. USAGE: Use as a rollback point before risky writes, to bookmark interesting game states, to share repro states, or — on Game Boy — to seed cartridge SRAM cleanly without fighting MBC bus semantics that mgba_write* would bypass. EXACTLY ONE of slot or path must be supplied (passing both, or neither, returns an error). Slots 0-9 are managed by mGBA in its data directory and are ideal for ad-hoc rollback during a session; explicit paths are better for long-term storage and sharing across sessions/machines. The companion mgba_load_state restores from either form. BEHAVIOR: When path is supplied, DESTRUCTIVE TO TARGET FILE: overwrites the file at path if it exists, with no prompt or backup. When slot is supplied, DESTRUCTIVE TO THE NAMED SLOT: overwrites whatever was previously stored in that slot. The state is bound to the EXACT ROM and a compatible mGBA version that produced it — loading it on a different ROM or an incompatible mGBA version typically produces a corrupt run or a hard error. Returns an error if neither slot nor path is supplied, the path's parent directory doesn't exist, the path isn't writable, the slot is out of range, or the relevant bridge save-state method (saveStateSlot vs saveStateFile) is missing on this build (check capabilities in mgba_get_info). RETURNS: Single line 'Saved state to PATH' or 'Saved state to slot N' depending on which form you used.

PURPOSE: Restore the emulator from a previously saved slot or .ss state file. USAGE: Counterpart to mgba_save_state. Use to undo a sequence of writes/inputs (the snapshot/experiment/restore workflow), to jump to a bookmarked game state, or to start each tool-call sequence from a known baseline. EXACTLY ONE of slot or path must be supplied (passing both, or neither, returns an error). To start fresh from console boot instead of a snapshot, use mgba_reset. BEHAVIOR: DESTRUCTIVE TO LIVE STATE: replaces ALL current emulator state (RAM, registers, mapper, audio, frame count, in-flight DMA) with the snapshot's contents. Anything not previously snapshotted is lost (unsaved in-game progress, queued button presses, paused state). The state file/slot MUST come from the same ROM and a compatible mGBA version that produced it — loading mismatched data typically produces a corrupt run or a hard error. Returns an error if neither slot nor path is supplied, the file doesn't exist or isn't a valid mGBA state, the slot is empty or out of range, or the relevant bridge load-state method (loadStateSlot vs loadStateFile) is missing on this build (check capabilities in mgba_get_info). RETURNS: Single line 'Loaded state from PATH' or 'Loaded state from slot N' depending on which form you used.