nemo22/retrokitНабор инструментов Headless-Ghidra для реверс-инжиниринга 32-битных DOS и Win32 игр (1993-2010): собственный загрузчик LE/LX, соглашения о вызовах Watcom, сигнатуры библиотек, сервер MCP
Набор инструментов для декомпиляции 32-битных игр примерно 1993–2010 годов с помощью headless Ghidra:
Результат — рабочее пространство с одним большим файлом .c, содержащим все функции плюс индексы
(функции, граф вызовов, строки, fixups/таблицы указателей, импорты), которые можно искать через grep и разделять
между людьми или AI-агентами. Имена, найденные в ходе анализа, возвращаются в Ghidra, и экспорт
перегенерируется.
Требования: Ghidra 12.x
(распакованная), 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 находится через --ghidra DIR, $GHIDRA_INSTALL_DIR или каталог ghidra/ghidra_* рядом
с игрой или набором. install-loader компилирует загрузчик с помощью javac против этой Ghidra
(без Gradle), устанавливает его в Ghidra/Extensions и регистрирует спецификации компилятора Watcom; запустите его
снова после обновления Ghidra (doctor сообщит вам, когда).
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 определяет формат, загрузчик и — для Watcom — соглашение о вызовах
(--cspec watcom|watcomreg переопределяет его) и сохраняет их в GAME_analysis/retrokit.json;
последующим командам нужен только рабочий каталог. Рабочий каталог:
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/
AI-агенты: retrokit mcp GAME_analysis — это MCP-сервер (stdio, без дополнительных пакетов) поверх
рабочего пространства: функции, декомпилированный код, граф вызовов, перекрёстные ссылки, строки, таблицы
указателей, дизассемблирование и байты, библиотеки; он записывает предложения имён и заметки и может
повторно экспортировать с применёнными именами (по запросу, в фоновом режиме). Claude Code:
claude mcp add retrokit -- retrokit mcp /path/to/GAME_analysis
Настройка для других клиентов, каждый инструмент и то, как должен работать агент: docs/MCP.md; краткая версия для агентов в AGENTS.md.
Имена: записывайте предложения в notes/names_<topic>.csv (addr,name,confidence,comment, confidence
V verified или G guess); retrokit names WS переименовывает функции/метки (V побеждает G,
коллизии получают _<addr>) и выполняет повторный экспорт.
Что делает конвейер:
retrokit libs (также часть info и analyze ->
notes/libraries.md) распознаёт ~20 библиотек того периода - Miles/AIL, HMI SOS, DIGPAK,
Smacker, Bink, FMOD, BASS, DirectX, zlib, libjpeg, libpng, PKWARE DCL, Lua, ... - по
строкам, импортам и файлам данных, с версией, заметками об их форматах и подсказками по портированию.
Код библиотек находится по сигнатурам (поставляются: среда выполнения Watcom C/C++, математические и C++ библиотеки
из Open Watcom, zlib 1.0.4-1.2.3, libjpeg 6b; retrokit sigs build создаёт их из
библиотек, которыми вы владеете, sigs learn из функций, которые вы идентифицировали) - сначала точные совпадения, затем
похожий код из других версий компилятора - именуется и типизируется из retrokit/knowledge/*.h.switch сохраняются внутри своих функций,
ошибочные флаги "no return" отменяются, короткие строки определяются, а строковые литералы отображаются как "text", количество параметров берётся из очисток ADD ESP,n в местах вызовов,
прототипы восстанавливаются начиная с вызываемых функций, экспорт.Другие команды: classes (классы MSVC C++ из RTTI), libs (используемые библиотеки), convert (XMIDI/HMI/HMP -> MIDI, VOC -> WAV,
Smacker/Bink/FLIC -> MP4, по содержимому), sigs match|build|learn (сигнатуры библиотек, см.
docs/WORKFLOW.md),
entries (PE: адреса кода без функции), modules --rules FILE
(PE: функции → исходные файлы через пути assert), strings EXE OUT (инвентаризация строк PE
без Ghidra), match (перенос имён в связанный EXE: сиквел, дополнение, другая версия),
le EXE info|dump|rec|s16|s32 (чтение таблиц из LE по адресам Ghidra), rnc (RNC ProPack),
flic info|png|video (Autodesk FLI/FLC). retrokit COMMAND --help для опций.
Подробная процедура, чего ожидать и известные подводные камни описаны в docs/WORKFLOW.md; сервер
MCP в docs/MCP.md; шаблоны задач для AI-агентов в docs/AGENT_PROMPTS.md; запланированная
работа в docs/ROADMAP.md; поддержка и выпуск в docs/MAINTAINING.md.
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