mgba_write32
Write a 32-bit little-endian value to a 4-byte-aligned memory address in GBA RAM. Note that writes bypass cartridge bus effects on Game Boy MBC games.
Instructions
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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| address | Yes | RAM address (4-byte aligned) | |
| value | Yes | 32-bit value |
Implementation Reference
- src/tools.ts:114-125 (schema)Tool definition and input schema for mgba_write32 — declares name, description, and inputSchema with required 'address' and 'value' (32-bit integer) parameters.
{ name: "mgba_write32", description: `Write a 32-bit value (little-endian) to a memory address. Address must be 4-byte aligned.\n\n${MBC_CAVEAT}`, inputSchema: { type: "object", required: ["address", "value"], properties: { address: { type: "integer", description: "RAM address (4-byte aligned)" }, value: { type: "integer", minimum: 0, description: "32-bit value" }, }, }, }, - src/tools.ts:320-323 (handler)Handler case for mgba_write32 — calls mgba.call('write32', ...) via the MgbaClient RPC and returns a formatted success string.
case "mgba_write32": { await mgba.call("write32", { address: p.address, value: p.value }); return ok(`Wrote ${formatHex(p.value)} → 0x${(p.address as number).toString(16).toUpperCase()}`); } - src/tools.ts:258-259 (registration)Registration function registerTools that wires up both ListToolsRequestSchema (exposing the TOOLS array) and CallToolRequestSchema (dispatching to handlers via switch).
export function registerTools(server: Server, mgba: MgbaClient): void { server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS })); - src/mgba.ts:89-132 (helper)MgbaClient.call() method — the generic RPC helper that serializes the method name ('write32') and params to JSON and sends them over a TCP socket to the mGBA Lua bridge.
async call<T = unknown>( method: string, params?: Record<string, unknown>, ): Promise<T> { // Lazy (re)connect — bridge.lua reloads kill the socket, and the user // shouldn't have to restart the MCP host every time they edit the script. if (!this.socket || this.socket.destroyed) { try { await this.connect(); } catch (err) { throw new Error( `Cannot reach mGBA bridge at ${this.host}:${this.port}. ` + `Make sure mGBA is running with bridge.lua loaded (Tools > Scripting). ` + `Underlying error: ${(err as Error).message}`, ); } } return new Promise<T>((resolve, reject) => { const sock = this.socket; if (!sock) { reject(new Error("socket vanished after connect")); return; } const id = this.nextId++; this.pending.set(id, (resp) => { if (resp.error) { reject(new Error(`mGBA RPC error [${resp.error.code}]: ${resp.error.message}`)); } else { resolve(resp.result as T); } }); const msg = JSON.stringify({ id, method, params: params ?? {} }) + "\n"; sock.write(msg, (err) => { if (err) { this.pending.delete(id); reject(err); } }); }); } }