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

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

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

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)

O Ghidra é localizado via --ghidra DIR, $GHIDRA_INSTALL_DIR, ou um diretório ghidra/ghidra_* próximo ao jogo ou ao kit. O 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 (o 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 a substitui) e os armazena em GAME_analysis/retrokit.json; os comandos posteriores 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 adicionais) 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 trabalhar: 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 portabilidade. 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 - nomeadas e tipadas a partir de retrokit/knowledge/*.h.
• LE/LX: importação 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 incorretas de "sem retorno" desfeitas, strings curtas definidas e literais de string exibidos como "text", contagens de parâmetros a partir das limpezas ADD ESP,n nos pontos de chamada, protótipos recuperados dos chamados para os chamadores, exportação.
• PE: importação com o loader PE do Ghidra e análise automática, 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ção.

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 bibliotecas, veja docs/WORKFLOW.md), entries (PE: endereços de código sem uma função), modules --rules FILE (PE: funções → arquivos-fonte originais via caminhos de assert), strings EXE OUT (inventário de strings 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