mgba_dump_oam
Extract and display all 40 sprite data from Game Boy, GBC, or GBA games, including positions, tiles, flags, and palettes, for game analysis and testing.
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:350-389 (handler)Core implementation of mgba_dump_oam: generates Lua script to dump 40 OAM sprites (position, tile, flags, palette, visibility) from GBA memory (0xFE00-0xFE9F) after specified frames, outputs JSON, takes 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") -- Write DONE marker local done = io.open("DONE", "w") if done then done:write("OK"); done:close() end end end) """ return self._run_with_lua(rom_path, lua_script, savestate_path)
- src/mgba_mcp/server.py:119-137 (schema)Input schema defining parameters for mgba_dump_oam tool: required rom_path, optional savestate_path and frames.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:116-138 (registration)Registers the mgba_dump_oam tool in the MCP server's 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)MCP server handler for mgba_dump_oam: calls emulator.dump_oam, parses OAM JSON into formatted text table of visible sprites, 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}"))