retro-kit – الهندسة العكسية للألعاب القديمة (Ghidra بدون واجهة)

مجموعة أدوات لفك تجميع الألعاب ذات 32 بت من الفترة 1993–2010 تقريبًا باستخدام Ghidra بدون واجهة:

• DOS LE/LX (DOS/4GW، DOS/32A، PMODE/W، CauseWay، ربط DOS/4G؛ وكذلك OS/2 LX وVxD) المبنية بـ Watcom C/C++ – مع محمّل LE/LX خاص بها لـ Ghidra ومواصفات مترجم Watcom لكلا اصطلاحي الاستدعاء.
• Win32 PE (عادةً MSVC): استدعاءات DirectX عبر جداول COM الافتراضية معروضة بأسماء دوالها، واستيرادات Miles/Smacker/Bink/FMOD/BASS مُنمّطة، وفئات C++ من MSVC RTTI، وإصدار المترجم من ترويسة Rich.

الناتج هو مساحة عمل تحتوي على ملف .c كبير واحد يضم كل الدوال بالإضافة إلى الفهارس (الدوال، مخطط الاستدعاء، السلاسل النصية، التصحيحات/جداول المؤشرات، الاستيرادات) التي يمكنك البحث فيها وتقسيمها بين الأشخاص أو وكلاء الذكاء الاصطناعي. الأسماء المكتشفة أثناء التحليل تُعاد إلى 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/

وكلاء الذكاء الاصطناعي: 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، الثقة V مُتحقَّق منها أو G تخمين)؛ 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.
• LE/LX: الاستيراد بمحمّل LE وcspec الخاص بـ Watcom، والدوال عند أهداف التثبيتات (fixups) في الكود (ألعاب Watcom تستدعي الكثير من منطقها عبر جداول المؤشرات)، وجداول القفز switch تُحفظ داخل دوالها، وأعلام "no return" الخاطئة تُلغى، والسلاسل النصية القصيرة تُعرَّف والقيم الحرفية النصية تُعرض كـ "text"، وأعداد المعاملات من تنظيفات ADD ESP,n عند مواضع الاستدعاء، والنماذج الأولية تُستعاد بدءًا من الدوال المُستدعاة، ثم التصدير.
• PE: الاستيراد بمحمّل PE الخاص بـ Ghidra والتحليل التلقائي، ثم الدوال عند أهداف جداول المؤشرات وبعد الحشو حتى لا تظهر دوال جديدة، ونفس مراحل السلاسل النصية / المعاملات / النماذج الأولية، ثم التصدير.

أوامر أخرى: 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؛ وقوالب المهام لوكلاء الذكاء الاصطناعي في docs/AGENT_PROMPTS.md؛ والعمل المخطط له في docs/ROADMAP.md؛ والصيانة والإصدار في 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