mgba_dump_oam
Extract sprite data from Game Boy Advance games by dumping Object Attribute Memory (OAM) to analyze sprite positions, tiles, flags, and palettes for debugging or game analysis.
Instructions
Dump OAM (Object Attribute Memory) sprite data - shows all 40 sprites with position, tile, flags, and palette
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| rom_path | Yes | Path to the ROM file | |
| savestate_path | No | Optional savestate to load | |
| frames | No | Frames to run before dumping (default: 60) |
Implementation Reference
- src/mgba_mcp/emulator.py:188-225 (handler)Core handler implementation for mgba_dump_oam: generates Lua script to read OAM sprite attributes (Y, X, tile, flags, palette, visibility) from 0xFE00-0xFE9F, writes JSON output, captures screenshot.def dump_oam( self, rom_path: str, savestate_path: Optional[str] = None, frames_before_dump: int = 60, ) -> EmulatorResult: """Dump OAM (sprite) data.""" lua_script = f""" local frame = 0 callbacks:add("frame", function() frame = frame + 1 if frame >= {frames_before_dump} then local f = io.open("output.json", "w") if f then f:write('{{"oam": [') for slot = 0, 39 do local addr = 0xFE00 + slot * 4 local y = emu:read8(addr) local x = emu:read8(addr + 1) local tile = emu:read8(addr + 2) local flags = emu:read8(addr + 3) if slot > 0 then f:write(',') end f:write(string.format( '{{"slot":%d,"y":%d,"x":%d,"tile":%d,"flags":%d,"palette":%d,"visible":%s}}', slot, y, x, tile, flags, flags % 8, (y > 0 and y < 160) and "true" or "false" )) end f:write(']}}') f:close() end emu:screenshot("screenshot.png") emu:quit() end end) """ return self._run_with_lua(rom_path, lua_script, savestate_path)
- src/mgba_mcp/server.py:116-138 (schema)Input schema and tool registration for mgba_dump_oam in the list_tools() function.Tool( name="mgba_dump_oam", description="Dump OAM (Object Attribute Memory) sprite data - shows all 40 sprites with position, tile, flags, and palette", inputSchema={ "type": "object", "properties": { "rom_path": { "type": "string", "description": "Path to the ROM file", }, "savestate_path": { "type": "string", "description": "Optional savestate to load", }, "frames": { "type": "integer", "description": "Frames to run before dumping (default: 60)", "default": 60, }, }, "required": ["rom_path"], }, ),
- src/mgba_mcp/server.py:283-309 (handler)Dispatch handler in call_tool(): calls emulator.dump_oam(), formats OAM data for text output, adds screenshot if available.elif name == "mgba_dump_oam": result = emu.dump_oam( rom_path=arguments["rom_path"], savestate_path=arguments.get("savestate_path"), frames_before_dump=arguments.get("frames", 60), ) if result.success and result.data: oam = result.data["oam"] lines = ["OAM Sprite Data (40 slots):"] lines.append("Slot Y X Tile Flags Pal Visible") lines.append("-" * 45) for sprite in oam: if sprite["visible"]: lines.append( f"{sprite['slot']:3d} {sprite['y']:3d} {sprite['x']:3d} " f"0x{sprite['tile']:02X} 0x{sprite['flags']:02X} {sprite['palette']} *" ) result_content.append(TextContent(type="text", text="\n".join(lines))) if result.screenshot: result_content.append(ImageContent( type="image", data=base64.b64encode(result.screenshot).decode(), mimeType="image/png", )) else: result_content.append(TextContent(type="text", text=f"Error: {result.error}"))