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

التخطيط

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