reverse-engineering

模组逆向工程

第一条规则：看实际内容，别靠猜测。 反编译代码、实际数据、实时内存视图或 GPU 捕获都是真正的规范。边研究边把发现记录到 MODLOG.md（名称、ID、偏移量、格式）。

将所有反编译输出和提取的资源都保存在模组仓库之外（例如 ~/<game>-decomp/），绝不要发布。仅限单人游戏、离线游戏或用户自己运行的服务器。不要对带有反作弊的游戏附加调试器或扫描器（参见 skills/mod-any-game/references/safety.md）。

根据代码类型选择工具（um scan 会告诉你）

托管 .NET（XNA/FNA、Unity Mono、大多数独立游戏 C#）

• 先运行 dotnet tool install -g ilspycmd，然后运行 ilspycmd -p -o ~/<game>-decomp <Game>.exe（或 Assembly-CSharp.dll）。这会生成一个完整的 C# 项目，可供 grep 搜索。
• dnSpyEx：使用调试器逐步执行、设置断点、编辑方法。
• MCP：ILSpy-MCP / dnspy-mcp 可让 Agent 直接查询类型和方法。

Unity IL2CPP

• 使用 Cpp2IL（或 Il2CppDumper）处理 GameAssembly.dll 和 global-metadata.dat，可获取类型、字段、方法签名和地址，以及供 ILSpy 使用的虚拟 DLL。
• 方法体是原生代码：在 Ghidra/IDA 中加载 GameAssembly.dll，并应用生成的脚本为函数命名。
• 实时查看：使用 UnityExplorer，或 il2cpp-frida-mcp。

Java（Minecraft、Slay the Spire……） 使用 Vineflower / CFR / Recaf。对于 Minecraft，使用 Loom 的 genSources 和 Mojang 映射。

原生 C/C++（自定义引擎、Unreal 游戏代码、主机游戏重编译）

• 使用 Ghidra（免费）或 IDA，并通过 MCP 驱动，让 Agent 能够反编译、重命名、重新设定类型并追踪交叉引用：
  • Ghidra：GhidraMCP（LaurieWired）、pyghidra-mcp（无头模式，带有运行脚本工具；能编写代码的工具胜过数百个小工具）、ReVa。
  • IDA：官方 Hex-Rays IDA MCP（IDA 9.4+ Pro/Home；“code mode”运行 IDAPython），或 ida-pro-mcp。
  • Binary Ninja 和 radare2 也有 MCP 服务。
• 工作流：
  1. 先看字符串，再看交叉引用，最后看函数。
  2. 为所有理解的内容命名并设定类型。重命名会逐步积累，最终形成可读的程序。
  3. 在基于猜测继续之前，先动态确认（见下文）。Agent 可能会自信地误判事物。
• Unreal：先转储反射数据（使用 UE4SS dumper 或 Dumper-7）；它们可以免费提供大多数游戏类和属性的名称。

动态 / 实时

• Cheat Engine：扫描数值 → “查找哪些内容会写入此地址” → 结构体 → 所有者。也有 CheatEngine MCP 服务。
• x64dbg：断点和跟踪（x64dbg-mcp；将其绑定到 127.0.0.1，因为有些工具默认绑定到 0.0.0.0）。
• Frida（frida-mcp、frida-game-hacking-mcp）：从 JavaScript 挂钩函数并记录参数。
• ReClass.NET 可根据实时内存重建结构体。

图形

• RenderDoc（renderdoc-mcp）可捕获一帧，并显示每次绘制、渲染目标、常量缓冲区（视图 / 投影矩阵）和深度缓冲区。
• 这就是如何找到注入几何体或效果的位置（mashup-mods），以及哪个纹理包含精灵图集。

数据文件和资源格式

优先使用社区工具：

• Unity：UABEA、AssetRipper
• Unreal：FModel、UAssetGUI
  • 完全压缩的 UE3 .upk（UELib 显示 Exports=0）：使用 Gildor 的 decompress（来自 UE Viewer）解压副本；对于 LZO 包，则使用 unpack_upk.py。
• Bethesda：xEdit、BSArch
• GameMaker：UndertaleModTool
• Genie：genieutils
• Source：VRF、Crowbar
• FromSoft：WitchyBND、Smithbox
• Godot：GDRE Tools

在自行逆向格式之前，先搜索社区档案。2000 年代和 2010 年代的大多数游戏格式都已在那里被研究出来：

• XeNTaX（于 2023 年关闭）：论坛、维基和附件均已存档在 archive.org，另有一份 GitHub 公开备份；
• ZenHAX：游戏文件研究和 QuickBMS 脚本（帖子更新至 2023 年初）；
• 探索文件格式权威指南 （Mr. Mouse，XeNTaX）：阅读未知格式的经典教程。

无论来源如何（测试版、泄露的 SDK），都可以利用这些资源了解格式并寻找工具。但不要从中下载游戏文件、泄露的代码、SDK 或许可证密钥。

对于未记录的格式：

1. 收集若干原始文件。比较大小，并对文件头进行十六进制转储（xxd | head）。查找魔数、计数、偏移量和固定大小记录表。
2. 先推测文件头，再推测帧／记录布局，最后推测压缩方式。解析所有原始文件，确保没有错误，以此验证推测。
3. 编写一个读取器，将数据解码成可查看的格式（PNG、JSON），然后亲自查看。
4. 编写写入器，并用往返测试证明其正确性：解码 → 编码 → 解码，再与原始文件比较。AoE2 SLD 精灵图写入器只有在原始骑士精灵图的往返测试平均误差达到 0.9/255 时才获通过（examples/aoe2-de-civ/sld.py）。
5. 然后再编写新文件。先用一个资源在游戏中测试，再批量转换。

将其用作验证基准

• 移植引擎逻辑（用于模拟器、训练器或重新实现）时：从游戏中记录真实运行轨迹（每个 tick 的位置、速度），并用它们对照移植版本进行回放。在 Terraria 眼球克苏鲁的研究中，移植版本改为使用 t+1 帧应用的动作后，眼球的速度匹配率达到 99.9%。Float32 常量也很重要（0.2f ≠ 0.2）。剩余的一处不匹配最终查明是由一个隐藏增益造成的（Happy!，移动速度 ×1.21）。回放能发现阅读代码时遗漏的问题。
• 长时间逆向工程时：
  • 使用日志文件；
  • 每次只进行小步且经过验证的操作；
  • 为每个问题设置尝试次数上限（约 3 次相同失败后，就换一种方法）；
  • 每确认一项事实，就提交一次。