retro-kit – ingeniería inversa de juegos antiguos (Ghidra headless)

Un conjunto de herramientas para descompilar juegos de 32 bits de aproximadamente 1993–2010 con Ghidra headless:

• DOS LE/LX (DOS/4GW, DOS/32A, PMODE/W, CauseWay, enlace DOS/4G; también OS/2 LX y VxD) compilados con Watcom C/C++ – con su propio cargador LE/LX para Ghidra y especificaciones del compilador Watcom para ambas convenciones de llamada.
• Win32 PE (típicamente MSVC): llamadas a DirectX a través de vtables COM mostradas con sus nombres de método, importaciones de Miles/Smacker/Bink/FMOD/BASS tipadas, clases de C++ a partir de RTTI de MSVC, la versión del compilador a partir de la cabecera Rich.

La salida es un espacio de trabajo con un único archivo .c grande que contiene todas las funciones más índices (functions, call graph, strings, fixups/pointer tables, imports) que puedes buscar con grep y dividir entre personas o agentes de IA. Los nombres encontrados durante el análisis vuelven a Ghidra y la exportación se regenera.

Instalación

Requisitos previos: Ghidra 12.x (descomprimido), un JDK 21+ (JAVA_HOME), Python 3.10+.

pipx install git+https://github.com/nemo22/retrokit   # or from a checkout: pip install .  (or python -m retrokit)
retrokit doctor                                    # checks Python, Ghidra, Java, loader, cspecs
retrokit install-loader                            # once per Ghidra install (DOS LE/LX only)

Ghidra se encuentra mediante --ghidra DIR, $GHIDRA_INSTALL_DIR, o un directorio ghidra/ghidra_* junto al juego o al kit. install-loader compila el loader con javac contra ese Ghidra (sin Gradle), lo instala en Ghidra/Extensions y registra las especificaciones del compilador Watcom; ejecútalo de nuevo después de actualizar Ghidra (doctor te avisa cuándo).

Uso

retrokit info GAME.EXE              # format, DOS extender, compiler, calling convention
retrokit analyze GAME.EXE           # full pipeline -> GAME_analysis/  (-o DIR to choose)
retrokit show GAME_analysis FUN_00012345 main
retrokit tables GAME_analysis       # function-pointer and string tables (from fixups)
retrokit names GAME_analysis        # apply notes/names_*.csv, re-export
retrokit reexport GAME_analysis     # re-run the fix-up passes + export without re-importing

analyze detecta el formato, el cargador y —para Watcom— la convención de llamada (--cspec watcom|watcomreg la sobrescribe) y los almacena en GAME_analysis/retrokit.json; los comandos posteriores solo necesitan el espacio de trabajo. Un espacio de trabajo:

GAME_analysis/
  retrokit.json        how the binary was analysed
  decomp/              <exe>_decompiled.c, functions.csv (addr,name,size,callers,callees,cc,signature),
                       calls.txt, strings.txt, data_symbols.txt, memory_blocks.txt,
                       fixups.txt (source -> target of every pointer: the key to pointer tables
                       and to which function uses which string), imports.txt (PE)
  notes/               findings, names_<topic>.csv proposals
  ghidra_project/      the Ghidra project (open it in the Ghidra GUI too)
  logs/

Agentes de IA: retrokit mcp GAME_analysis es un servidor MCP (stdio, sin paquetes adicionales) sobre el espacio de trabajo: funciones, código descompilado, grafo de llamadas, referencias cruzadas, cadenas, tablas de punteros, desensamblado y bytes, bibliotecas; registra propuestas de nombres y notas y puede reexportar con los nombres aplicados (a petición, en segundo plano). Claude Code:

claude mcp add retrokit -- retrokit mcp /path/to/GAME_analysis

Configuración para otros clientes, cada herramienta y cómo debe trabajar un agente: docs/MCP.md; una versión corta para agentes en AGENTS.md.

Nombres: escribe propuestas en notes/names_<topic>.csv (addr,name,confidence,comment, confianza V verificada o G conjetura); retrokit names WS renombra funciones/etiquetas (V gana sobre G, las colisiones reciben _<addr>) y reexporta.

Qué hace el pipeline:

• Bibliotecas (ambos formatos): retrokit libs (también parte de info y analyze -> notes/libraries.md) reconoce ~20 bibliotecas de la época - Miles/AIL, HMI SOS, DIGPAK, Smacker, Bink, FMOD, BASS, DirectX, zlib, libjpeg, libpng, PKWARE DCL, Lua, ... - a partir de cadenas, importaciones y archivos de datos, con versión, notas sobre sus formatos y pistas de portado. El código de biblioteca se encuentra por firma (incluidas: run-time de Watcom C/C++, bibliotecas matemáticas y de C++ de Open Watcom, zlib 1.0.4-1.2.3, libjpeg 6b; retrokit sigs build las crea a partir de bibliotecas que poseas, sigs learn a partir de funciones que hayas identificado) - primero las coincidencias exactas, luego código similar de otras versiones del compilador - nombradas y tipadas desde retrokit/knowledge/*.h.
• LE/LX: importar con el cargador LE y el cspec de Watcom, funciones en los destinos de los fixups hacia código (los juegos de Watcom llaman gran parte de su lógica a través de tablas de punteros), las tablas de salto de switch se mantienen dentro de sus funciones, se deshacen las banderas incorrectas de "no return", se definen cadenas cortas y los literales de cadena se muestran como "text", los recuentos de parámetros a partir de las limpiezas ADD ESP,n en los puntos de llamada, prototipos recuperados empezando por los llamados, exportar.
• PE: importar con el cargador PE de Ghidra y el análisis automático, luego funciones en los destinos de las tablas de punteros y tras el padding hasta que no aparezcan nuevas, las mismas pasadas de cadenas / parámetros / prototipos, exportar.

Otros comandos: classes (clases de C++ de MSVC a partir de RTTI), libs (bibliotecas en uso), convert (XMIDI/HMI/HMP -> MIDI, VOC -> WAV, Smacker/Bink/FLIC -> MP4, por contenido), sigs match|build|learn (firmas de bibliotecas, ver docs/WORKFLOW.md), entries (PE: direcciones de código sin una función), modules --rules FILE (PE: funciones → archivos fuente originales mediante rutas de assert), strings EXE OUT (inventario de cadenas de PE sin Ghidra), match (transferir nombres a un EXE relacionado: secuela, add-on, otra versión), le EXE info|dump|rec|s16|s32 (leer tablas de un LE en direcciones de Ghidra), rnc (RNC ProPack), flic info|png|video (Autodesk FLI/FLC). retrokit COMMAND --help para las opciones.

El procedimiento detallado, qué esperar y los escollos conocidos están en docs/WORKFLOW.md; el servidor MCP en docs/MCP.md; las plantillas de tareas para agentes de IA en docs/AGENT_PROMPTS.md; el trabajo previsto en docs/ROADMAP.md; el mantenimiento y las publicaciones en docs/MAINTAINING.md.

Layout

retrokit/               Python package (CLI: retrokit/cli.py)
  ghidra_scripts/       headless Ghidra scripts used by the pipelines
  tools/                standalone Python tools behind the CLI commands
  le-loader/            LE/LX loader for Ghidra (Java) + Watcom compiler specs (data/languages/)
  sigs/                 library signatures (Open Watcom C run-time)
  knowledge/            libraries.json (library catalog), library prototypes as C headers
scripts/                build_sigs.py: rebuilds the shipped signatures
tests/                  synthetic test programs, scoring against the linker map, baseline
docs/                   WORKFLOW, AGENT_PROMPTS, ROADMAP