retro-kit – engenharia reversa de jogos antigos (Ghidra headless)

Um toolkit para descompilar jogos de 32 bits de aproximadamente 1993–2010 com Ghidra headless:

• DOS LE/LX (DOS/4GW, DOS/32A, PMODE/W, CauseWay, DOS/4G bind; também OS/2 LX e VxD) compilados com Watcom C/C++ – com seu próprio carregador LE/LX para Ghidra e especificações do compilador Watcom para ambas as convenções de chamada.
• Win32 PE (tipicamente MSVC): chamadas DirectX através de vtables COM mostradas com seus nomes de métodos, imports Miles/Smacker/Bink/FMOD/BASS tipados, classes C++ a partir de RTTI do MSVC, a versão do compilador a partir do Rich header.

A saída é um workspace com um único arquivo .c grande contendo todas as funções mais índices (funções, grafo de chamadas, strings, fixups/tabelas de ponteiros, imports) que você pode pesquisar com grep e dividir entre pessoas ou agentes de IA. Nomes encontrados durante a análise voltam para o Ghidra e a exportação é regenerada.

Instalação

Pré-requisitos: Ghidra 12.x (descompactado), um 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 é encontrado via --ghidra DIR, $GHIDRA_INSTALL_DIR, ou um diretório ghidra/ghidra_* ao lado do jogo ou do kit. install-loader compila o loader com javac contra esse Ghidra (sem Gradle), instala-o em Ghidra/Extensions e registra as especificações do compilador Watcom; execute-o novamente após atualizar o Ghidra (doctor avisa quando).

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 o formato, o loader e – para Watcom – a convenção de chamada (--cspec watcom|watcomreg substitui-a) e armazena-os em GAME_analysis/retrokit.json; os comandos seguintes precisam apenas do workspace. Um workspace:

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 é um servidor MCP (stdio, sem pacotes extras) sobre o workspace: funções, código descompilado, grafo de chamadas, referências cruzadas, strings, tabelas de ponteiros, desmontagem e bytes, bibliotecas; ele registra propostas de nomes e notas e pode reexportar com os nomes aplicados (sob demanda, em segundo plano). Claude Code:

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

Configuração para outros clientes, cada ferramenta e como um agente deve funcionar: docs/MCP.md; uma versão curta para agentes em AGENTS.md.

Nomes: escreva propostas em notes/names_<topic>.csv (addr,name,confidence,comment, confiança V verificada ou G suposição); retrokit names WS renomeia funções/rótulos (V prevalece sobre G, colisões recebem _<addr>) e reexporta.

O que o pipeline faz:

• Bibliotecas (ambos os formatos): retrokit libs (também parte de info e analyze -> notes/libraries.md) reconhece ~20 bibliotecas da época - Miles/AIL, HMI SOS, DIGPAK, Smacker, Bink, FMOD, BASS, DirectX, zlib, libjpeg, libpng, PKWARE DCL, Lua, ... - a partir de strings, imports e arquivos de dados, com versão, notas sobre seus formatos e dicas de porte. O código de biblioteca é encontrado por assinatura (incluídas: run-time do Watcom C/C++, bibliotecas matemáticas e C++ do Open Watcom, zlib 1.0.4-1.2.3, libjpeg 6b; retrokit sigs build as cria a partir de bibliotecas que você possui, sigs learn a partir de funções que você identificou) - correspondências exatas primeiro, depois código semelhante de outras versões de compilador - nomeado e tipado a partir de retrokit/knowledge/*.h.
• LE/LX: importa com o loader LE e o cspec do Watcom, funções nos destinos dos fixups para código (jogos Watcom chamam grande parte de sua lógica através de tabelas de ponteiros), tabelas de salto switch mantidas dentro de suas funções, flags "no return" incorretas desfeitas, strings curtas definidas e literais de string mostrados como "text", contagens de parâmetros a partir das limpezas ADD ESP,n nos locais de chamada, protótipos recuperados dos chamados primeiro, exporta.
• PE: importa com o loader PE do Ghidra e auto-análise, depois funções nos destinos de tabelas de ponteiros e após padding até que nenhuma nova apareça, as mesmas passagens de string / parâmetro / protótipo, exporta.

Outros comandos: classes (classes C++ MSVC a partir de RTTI), libs (bibliotecas em uso), convert (XMIDI/HMI/HMP -> MIDI, VOC -> WAV, Smacker/Bink/FLIC -> MP4, por conteúdo), sigs match|build|learn (assinaturas de biblioteca, veja docs/WORKFLOW.md), entries (PE: endereços de código sem uma função), modules --rules FILE (PE: funções → arquivos de código-fonte originais via caminhos de assert), strings EXE OUT (inventário de strings de PE sem Ghidra), match (transfere nomes para um EXE relacionado: sequência, add-on, outra versão), le EXE info|dump|rec|s16|s32 (lê tabelas de um LE em endereços do Ghidra), rnc (RNC ProPack), flic info|png|video (Autodesk FLI/FLC). retrokit COMMAND --help para opções.

O procedimento detalhado, o que esperar e as armadilhas conhecidas estão em docs/WORKFLOW.md; o servidor MCP em docs/MCP.md; modelos de tarefas para agentes de IA em docs/AGENT_PROMPTS.md; trabalho planejado em docs/ROADMAP.md; manutenção e lançamento em 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