Gearcoleco Romhacking

ColecoVision / Super Game Module ROM Hacking with Gearcoleco

Overview

Hack, modify, and translate ColecoVision and Super Game Module ROMs using the Gearcoleco emulator as an MCP server. Search memory for game variables, create cheats, find text strings for translation, locate sprite and tile data, inspect VRAM, patch RAM or ROM bytes in the emulator's in-memory copy, and reverse engineer data structures - all through MCP tool calls. Use save states or rewind as checkpoints and fast forward to reach specific game states. Hardware documentation is available in the references/ directory.

MCP Server Prerequisite

IMPORTANT - Check before installing: Before attempting any installation or configuration, you MUST first verify if the Gearcoleco MCP server is already connected in your current session. In the default mode, call debug_get_status directly. If Gearcoleco was intentionally started with --mcp-router, call get_tool_info with {"name":"debug_get_status"}, then call execute_tool with {"name":"debug_get_status","arguments":{}}. A valid response from either workflow means the server is active and ready.

Only if neither workflow is available or the call fails, you need to help install and configure the Gearcoleco MCP server:

Installing Gearcoleco

Run the bundled install script (macOS/Linux):

bash scripts/install.sh

This installs Gearcoleco via Homebrew on macOS or downloads the latest release on Linux. It prints the binary path on completion. You can also set INSTALL_DIR to control where the binary goes (default: ~/.local/bin).

Alternatively, download from GitHub Releases or install with brew install --cask drhelius/geardome/gearcoleco on macOS.

Connecting as MCP Server

Configure your AI client to run Gearcoleco as an MCP server via STDIO transport. Example for Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "gearcoleco": {
      "command": "/path/to/gearcoleco",
      "args": ["--mcp-stdio"]
    }
  }
}

Replace /path/to/gearcoleco with the actual binary path from the install script. Add --headless before --mcp-stdio on headless machines.

Hardware Documentation (References)

ColecoVision and Super Game Module hardware documentation is available in the references/ directory. Load them into your context when investigating specific hardware, BIOS, memory-map, graphics, sound, or SGM behavior.

Core Technique: Memory Search

Memory search is the primary tool for ROM hacking. It uses a capture -> change -> compare cycle to isolate memory addresses holding game values.

The Search Loop

1. list_memory_areas          -> identify WRAM, SGM RAM, or another area ID
2. memory_search_capture      -> snapshot current memory state
3. (change the value in-game using controller_button, fast forward, etc.)
4. memory_search              -> compare against snapshot to find changed addresses
5. Repeat 2-4 until only a few candidates remain
6. read_memory / write_memory -> verify and modify the found addresses

Search Operators and Types

memory_search supports these operators: <, >, ==, !=, <=, >=

Compare types:

• previous - compare current value to last captured snapshot (most common)
• value - compare current value to a specific number
• address - compare current value to value at another address

Data types: hex, signed, unsigned

Example: Finding the Lives Counter

1. list_memory_areas                                  -> find WRAM area ID
2. memory_search_capture                              -> snapshot with 3 lives
3. Lose a life in-game (play or use controller_button)
4. memory_search (operator: <, compare: previous)     -> values that decreased
5. memory_search_capture                              -> snapshot with 2 lives
6. Lose another life
7. memory_search (operator: <, compare: previous)     -> narrow further
8. Or use: memory_search (operator: ==, compare: value, value: 1)
   -> find addresses holding exactly 1
9. write_memory on the candidate offset to set lives to 99
10. get_screenshot to verify the change took effect

Example: Finding a Score Counter

Score values are often stored as multi-byte (16-bit little-endian on Z80):

1. memory_search_capture                              -> snapshot at score 0
2. Score some points in-game
3. memory_search (operator: >, compare: previous)     -> values that increased
4. memory_search_capture
5. Score more points
6. memory_search (operator: >, compare: previous)     -> narrow down
7. read_memory on candidates - look for values matching current score
8. write_memory to set a custom score

For 16-bit values: the low byte is at address N, high byte at N+1 (Z80 is little-endian). Many ColecoVision games use BCD (Binary Coded Decimal) for score display - each nibble holds a single digit (e.g., score 1234 stored as $12 $34).

Fast Forward for Efficiency

Use fast forward to speed through gameplay when you need to trigger in-game changes:

set_fast_forward_speed (4 = unlimited)
toggle_fast_forward (enabled: true)
(play through the game section)
toggle_fast_forward (enabled: false)

This is essential when you need to reach specific game states without waiting in real time.

Save States as Checkpoints

Save states are critical for ROM hacking - they let you save your position and retry modifications:

select_save_state_slot (1-5) -> pick a slot
save_state                   -> save current state
(try modifications)
load_state                   -> revert if something breaks

Use different slots for different game states (e.g., slot 1 = start, slot 2 = boss fight, slot 3 = specific level).

list_save_state_slots shows all slots with ROM name, timestamp, and screenshot availability.

Rewind as an Alternative

The emulator also records continuous snapshots into a rewind ring buffer. Use get_rewind_status to check availability, then rewind_seek to jump to any recorded point without manual save/load. This is especially useful for quickly reverting after a failed memory write - pause, seek back a few snapshots, and retry.

Finding and Modifying Game Data

Text and String Discovery

To find text strings for translation or modification:

1. Determine the character encoding - ColecoVision games often use custom character maps stored as VDP tile patterns, not ASCII
2. read_memory across ROM areas scanning for known byte patterns
3. Use memory_find with text for literal strings or hex_bytes for encoded byte sequences
4. Set read breakpoints on suspected text addresses with set_breakpoint (read: true) to confirm they are read by the text rendering routine
5. get_screenshot to correlate displayed text with memory contents
6. read_memory (VRAM area from list_memory_areas) to examine the tile patterns used for font rendering
7. Load references/colecovision.md for the Coleco BIOS title-screen character set and cartridge title format when dealing with BIOS-managed text

Sprite and Graphics Data

1. list_sprites - view all 32 sprites with positions, sizes, and pattern indices
2. get_sprite_image - capture individual sprite images as PNG
3. read_memory (VRAM area from list_memory_areas) - examine pattern generator, color table, name table, and sprite attribute table data
4. get_vdp_registers - check table base addresses and sprite mode bits
5. Set read/write breakpoints (area: vram) on sprite or tile data to find the rendering code
6. get_screenshot before/after modifications to see visual changes

VRAM and Tile Data

The TMS9918A uses VRAM for all graphics:

• Pattern generator table: bitmap patterns for characters/tiles/sprites
• Pattern name table: background tile map referencing pattern indices
• Color table: foreground/background color information depending on display mode
• Sprite attribute table: Y position, X position, pattern index, and color for each sprite
• Sprite generator table: sprite pattern data

Use read_memory (VRAM area from list_memory_areas) with base addresses from get_vdp_registers to access these. Use references/tms9918a.md for mode-specific table rules.