nemo22/retrokitHeadless-Ghidra-Toolkit für das Reverse Engineering von 32-Bit-DOS- und Win32-Spielen (1993–2010): eigener LE/LX-Loader, Watcom-Aufrufkonventionen, Bibliothekssignaturen, MCP-Server
Ein Toolkit zum Dekompilieren von 32-Bit-Spielen aus der Zeit von etwa 1993–2010 mit headless Ghidra:
Die Ausgabe ist ein Workspace mit einer großen .c-Datei, die jede Funktion enthält, plus Indizes
(Funktionen, Aufrufgraph, Strings, Fixups/Zeigertabellen, Importe), die du greppen und zwischen
Personen oder KI-Agenten aufteilen kannst. Während der Analyse gefundene Namen gehen zurück in Ghidra und der Export
wird neu generiert.
Voraussetzungen: Ghidra 12.x
(entpackt), ein 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 wird über --ghidra DIR, $GHIDRA_INSTALL_DIR oder ein ghidra/ghidra_*-Verzeichnis neben
dem Spiel oder dem Kit gefunden. install-loader kompiliert den Loader mit javac gegen diese Ghidra-
Installation (kein Gradle), installiert ihn in Ghidra/Extensions und registriert die Watcom-Compiler-Spezifikationen; führe es
erneut aus, nachdem Ghidra aktualisiert wurde (doctor sagt dir, wann).
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 erkennt das Format, den Loader und – bei Watcom – die Aufrufkonvention
(--cspec watcom|watcomreg überschreibt sie) und speichert sie in GAME_analysis/retrokit.json;
spätere Befehle benötigen nur den Workspace. Ein 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/
KI-Agenten: retrokit mcp GAME_analysis ist ein MCP-Server (stdio, keine zusätzlichen Pakete) über
dem Workspace: Funktionen, dekompilierter Code, Aufrufgraph, Querverweise, Strings, Zeiger-
tabellen, Disassembly und Bytes, Bibliotheken; er zeichnet Namensvorschläge und Notizen auf und kann
mit den angewendeten Namen erneut exportieren (auf Anfrage, im Hintergrund). Claude Code:
claude mcp add retrokit -- retrokit mcp /path/to/GAME_analysis
Einrichtung für andere Clients, jedes Tool und wie ein Agent arbeiten sollte: docs/MCP.md; eine Kurzfassung für Agenten in AGENTS.md.
Namen: Vorschläge nach notes/names_<topic>.csv schreiben (addr,name,confidence,comment, Konfidenz
V verifiziert oder G Vermutung); retrokit names WS benennt Funktionen/Labels um (V gewinnt über G,
Kollisionen erhalten _<addr>) und exportiert neu.
Was die Pipeline macht:
retrokit libs (auch Teil von info und analyze ->
notes/libraries.md) erkennt ~20 Bibliotheken der Zeit - Miles/AIL, HMI SOS, DIGPAK,
Smacker, Bink, FMOD, BASS, DirectX, zlib, libjpeg, libpng, PKWARE DCL, Lua, ... - anhand
von Strings, Imports und Datendateien, mit Version, Hinweisen zu ihren Formaten und Portierungshinweisen.
Bibliothekscode wird per Signatur gefunden (mitgeliefert: Watcom C/C++-Laufzeit, Mathe- und C++-Bibliotheken
von Open Watcom, zlib 1.0.4-1.2.3, libjpeg 6b; retrokit sigs build erzeugt sie aus
Bibliotheken, die Sie besitzen, sigs learn aus Funktionen, die Sie identifiziert haben) - exakte Treffer zuerst, dann
ähnlicher Code aus anderen Compilerversionen - benannt und typisiert aus retrokit/knowledge/*.h.switch-Sprungtabellen
innerhalb ihrer Funktionen belassen, falsche "no return"-Flags rückgängig gemacht, kurze Strings definiert und String-
Literale als "text" angezeigt, Parameteranzahlen aus den ADD ESP,n-Bereinigungen an Aufrufstellen,
Prototypen callee-first wiederhergestellt, Export.Weitere Befehle: classes (MSVC-C++-Klassen aus RTTI), libs (verwendete Bibliotheken), convert (XMIDI/HMI/HMP -> MIDI, VOC -> WAV,
Smacker/Bink/FLIC -> MP4, nach Inhalt), sigs match|build|learn (Bibliothekssignaturen, siehe
docs/WORKFLOW.md),
entries (PE: Codeadressen ohne Funktion), modules --rules FILE
(PE: Funktionen → ursprüngliche Quelldateien über Assert-Pfade), strings EXE OUT (PE-String-Inventar
ohne Ghidra), match (Namen auf eine verwandte EXE übertragen: Sequel, Add-on, andere Version),
le EXE info|dump|rec|s16|s32 (Tabellen aus einer LE an Ghidra-Adressen lesen), rnc (RNC ProPack),
flic info|png|video (Autodesk FLI/FLC). retrokit COMMAND --help für Optionen.
Das detaillierte Vorgehen, was zu erwarten ist und die bekannten Fallstricke stehen in docs/WORKFLOW.md; der
MCP-Server in docs/MCP.md; Aufgaben-Templates für KI-Agenten in docs/AGENT_PROMPTS.md; geplante
Arbeiten in docs/ROADMAP.md; Pflege und Release in 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