mgba_dump_entities
Extract entity and actor data from mGBA emulator memory to analyze game objects and their properties during gameplay.
Instructions
Dump entity/actor data from WRAM - useful for analyzing game objects
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| rom_path | Yes | Path to the ROM file | |
| entity_base | No | Base address of entity array (default: 0xC200) | |
| entity_size | No | Size of each entity in bytes (default: 24) | |
| entity_count | No | Number of entities to dump (default: 10) | |
| savestate_path | No | Optional savestate to load | |
| frames | No | Frames to run before dumping (default: 60) |
Implementation Reference
- src/mgba_mcp/emulator.py:227-264 (handler)Core handler function that generates Lua script to dump entity data from WRAM (boss_flag at 0xFFBF and entity array), runs the emulator, and returns the result.def dump_entities( self, rom_path: str, entity_base: int = 0xC200, entity_size: int = 24, entity_count: int = 10, savestate_path: Optional[str] = None, frames_before_dump: int = 60, ) -> EmulatorResult: """Dump entity data from WRAM.""" 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('{{"boss_flag":' .. emu:read8(0xFFBF) .. ',"entities":[') for ent = 0, {entity_count - 1} do local base = {entity_base} + ent * {entity_size} if ent > 0 then f:write(',') end f:write('{{"index":' .. ent .. ',"address":' .. base .. ',"bytes":[') for i = 0, {entity_size - 1} do if i > 0 then f:write(',') end f:write(tostring(emu:read8(base + i))) end f:write(']}}') 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:139-176 (registration)Registers the mgba_dump_entities tool in the MCP server's list_tools, including description and input schema.Tool( name="mgba_dump_entities", description="Dump entity/actor data from WRAM - useful for analyzing game objects", inputSchema={ "type": "object", "properties": { "rom_path": { "type": "string", "description": "Path to the ROM file", }, "entity_base": { "type": "integer", "description": "Base address of entity array (default: 0xC200)", "default": 49664, }, "entity_size": { "type": "integer", "description": "Size of each entity in bytes (default: 24)", "default": 24, }, "entity_count": { "type": "integer", "description": "Number of entities to dump (default: 10)", "default": 10, }, "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:142-174 (schema)Defines the input schema for validating arguments to mgba_dump_entities tool.inputSchema={ "type": "object", "properties": { "rom_path": { "type": "string", "description": "Path to the ROM file", }, "entity_base": { "type": "integer", "description": "Base address of entity array (default: 0xC200)", "default": 49664, }, "entity_size": { "type": "integer", "description": "Size of each entity in bytes (default: 24)", "default": 24, }, "entity_count": { "type": "integer", "description": "Number of entities to dump (default: 10)", "default": 10, }, "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:311-339 (handler)MCP server dispatcher handler for mgba_dump_entities: calls emulator.dump_entities and formats the result into text output with screenshot.elif name == "mgba_dump_entities": result = emu.dump_entities( rom_path=arguments["rom_path"], entity_base=arguments.get("entity_base", 0xC200), entity_size=arguments.get("entity_size", 24), entity_count=arguments.get("entity_count", 10), savestate_path=arguments.get("savestate_path"), frames_before_dump=arguments.get("frames", 60), ) if result.success and result.data: lines = [f"Boss flag: 0x{result.data['boss_flag']:02X}"] lines.append("\nEntity Data:") for ent in result.data["entities"]: bytes_data = ent["bytes"] # Check if entity has any non-zero data if any(b != 0 for b in bytes_data): hex_str = " ".join(f"{b:02X}" for b in bytes_data[:16]) lines.append(f" Entity {ent['index']} (0x{ent['address']:04X}): {hex_str}...") 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}"))