mgba_dump_entities
Extract entity and actor data from mGBA emulator's WRAM to analyze game objects during gameplay. Specify ROM path and adjust parameters like entity count and memory addresses.
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:391-430 (handler)Core handler: MGBAEmulator.dump_entities generates and executes a Lua script to dump entity bytes from WRAM starting at entity_base, for entity_count entities each of entity_size bytes, after running specified frames, and captures screenshot.
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") -- 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:142-175 (schema)Input schema defining parameters for the mgba_dump_entities tool, including rom_path (required), entity_base, entity_size, entity_count, savestate_path, and frames.
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:139-176 (registration)Registration of the mgba_dump_entities tool in the list_tools() function, including name, description, and inputSchema.
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:311-339 (handler)Server-side handler in call_tool that invokes emu.dump_entities with parsed arguments, formats the entity dump output as text (boss flag and hex dumps of non-zero entities), adds screenshot if available, or error message.
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}"))