retro-kit – ingeniería inversa de juegos antiguos (Ghidra sin interfaz gráfica)

Un conjunto de herramientas para descompilar juegos de 32 bits de aproximadamente 1993–2010 con Ghidra sin interfaz gráfica:

• 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 (funciones, grafo de llamadas, cadenas, correcciones/tablas de punteros, importaciones) 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 localiza 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 tras 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 re-exportar con los nombres aplicados (bajo 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 breve para agentes en AGENTS.md.

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

Qué hace el pipeline:

• Bibliotecas (ambos formatos): retrokit libs (también forma 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 portabilidad. 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 genera 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 a partir de retrokit/knowledge/*.h.
• LE/LX: importación 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), tablas de salto switch mantenidas dentro de sus funciones, flags incorrectos de "sin retorno" revertidos, cadenas cortas definidas y literales de cadena mostrados como "text", recuentos de parámetros a partir de las limpiezas ADD ESP,n en los puntos de llamada, prototipos recuperados empezando por los destinatarios, exportación.
• PE: importación con el cargador PE de Ghidra y autoanálisis, luego funciones en los destinos de tablas de punteros y tras el relleno hasta que no aparezcan nuevas, las mismas pasadas de cadenas / parámetros / prototipos, exportación.

Otros comandos: classes (clases 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 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 (transfiere nombres a un EXE relacionado: secuela, add-on, otra versión), le EXE info|dump|rec|s16|s32 (lee 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