mcpField
B
blitz3d-decomp

blitz3d-decomp

github.com/rehan-remade其他9.2k26 次安装1 天前更新
代码仓库

关于 blitz3d-decomp

用于研究 Blitz3D 游戏并移植其行为的技能，以 B3DDecomp 还原的 Blitz 源码作为参考。它指导反汇编、系统追踪、移植和测量验证，并明确受保护构建及再分发的限制。

主要功能

  1. 01构建并运行 B3DDecomp
  2. 02反汇编模块并还原 Blitz 源码
  3. 03从字符串和数据追踪游戏系统
  4. 04依据运行时参考移植行为
  5. 05用测量值验证移植结果
  6. 06遵守反编译与许可限制

适用场景

  1. 01研究符合条件的 Blitz3D 游戏
  2. 02实现移植前追踪相关数值
  3. 03对照原游戏验证移植行为

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/rehan-remade/universal-modder --skill blitz3d-decomp

安装后在 Claude Code 中输入/blitz3d-decomp确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
b3d-to-roblox.md
b3ddecomp-skip-failures.patch
blitz-runtime.md
scripts/roblox/
b3d_skin.py
vm_anim_data.py
vm_build.py
vm_render.py

详细介绍

Blitz3D 反编译与移植

Blitz3D 游戏以单个 exe 发布：运行时位于 .text 中，编译后的游戏则位于一个资源模块中，运行时会在加载时链接该模块。用 Ghidra 检查 exe 时，只能看到运行时。可行的方法是： B3DDecomp 会反汇编该模块，并将其反编译为 Blitz 源码。 随后以源代码作为移植的规格，并以原版游戏作为验证依据。

所有反汇编和反编译产物都应放在仓库之外（约定使用 ~/<game>-decomp/），绝不发布；此处的脚本可以保留。对于禁止反编译的专有 DLL，不要动它们：exe 中的导出名称已经足够。请在 mod 的 MODLOG.md 中记录过程。

有源代码时请先阅读：SCP: Containment Breach（Regalis11/scpcb）及其 Ultimate Edition Reborn 分支（Jabka666/scpcb-ue-my）均以 CC BY-SA 3.0 开源。

移植可以使用的内容。 移植如果重新实现游戏逻辑，或转换游戏的模型、关键帧、纹理或声音，那么在发布或上传（包括上传到 Roblox）后，就会重新分发该游戏。只移植用户有权使用的内容：用户自己的游戏，或依照其许可条款开放授权的游戏（SCP: Containment Breach：注明来源，并让移植版本遵循 CC BY-SA 3.0；同时检查每项资产的致谢信息，因为粉丝游戏混用了不同许可）。其他内容只能用于私人研究：不得上传或发布其中任何内容。

1. 工具

  • B3DDecomp（juanjp600/B3DDecomp，C#，GPL-3）：在仓库外克隆，然后运行 dotnet build Blitz3DDecomp.sln -c Release。它需要 .NET 8 SDK；用户可在本地安装，无需管理员权限 （dotnet-install.ps1 -Channel 8.0 -InstallDir <dir>）。运行时设置 DOTNET_ROLL_FORWARD=Major，并将 bin/Release/net8.0 加入 PATH：反编译器会按名称启动 Blitz3DDisasm。
  • 如果某个函数导致整个运行中止，应用 references/b3ddecomp-skip-failures.patch（git apply；基于 commit 2b3148b 制作）：这样反编译器遇到无法完成的函数时会跳过该函数，并输出一行 step5 failed，而不是停止运行。

当 Blitz3DDecomp.exe 和 Blitz3DDisasm.exe 均构建完成时，即算完成。

2. 反汇编与反编译

Blitz3DDecomp.exe <copy of game.exe> 会生成 <game>_disasm/（包含 Code/ per function、Type/、Strings.txt、 BuiltIn/、Libs/、BuiltInSymbols.txt），然后将其反编译到 <game>_decomp/。由 SCP: Containment Breach 代码构建的游戏还需要将游戏的 fmod.decls 作为第二个参数（B3DDecomp 的 README 说明：随附的 decls 在 FSOUND_Stream_Open 中漏掉了一个参数）。

如果仍然中止，异常会指出出问题的结构。不要为了绕过问题而让类型 setter 静默忽略写入：这样类型传播会无限循环，且不会产生任何输出。

遇到受保护的构建时：停止。 有些构建受到保护，无法执行此步骤：经过修改的编译器和运行时会对每个函数、类型和内置名称进行哈希处理（B3DDecomp 会报错 Unrecognized function: @_builtIn_f<garbled>；SCP: Containment Breach 2 的客户端就是以这种方式构建的），或者模块经过加密。这些保护是开发者为防止反编译而添加的。不要绕过保护：告知用户并停止（skills/mod-any-game/references/safety.md）。当前版本的 B3DDecomp 会在不作说明的情况下自行绕过其中一种保护：对 .b3dmod 段执行 XOR。先列出 exe 的段（使用 objdump -h 或任意 PE 查看器），如果其中有 .b3dmod 段，就停止。

当 <game>_decomp/ 中包含 Main.bb、Functions/、Types/ 和 Decls/，且运行最多只输出少量 step5 failed 行时，即算完成。

3. 查找系统

  • 先查找字符串：游戏加载的资源路径或声音（grep -l StringConstant_<n> Code/*）。
  • 数据驱动的模板：初始化函数会将常量存入每个项目对应的模板中。如果游戏有 addon/JSON 加载器，它会列出每个字段。

当移植要用的每个数字都能追溯到设置它的代码行和读取它的代码行时，即算完成。

4. 移植

编写移植代码前，请先阅读 references/blitz-runtime.md：Blitz3D 的时钟、 Animate、CurveValue、欧拉角、Rnd 和实体调用的行为都有其特殊之处，直接照搬会出错。 要将动画 .b3d 模型（第一人称视角模型、骨架、关键帧）移植到 Roblox，请参阅 references/b3d-to-roblox.md；其中的脚本位于 scripts/roblox/。

逐步移植：顺序、常量和每个刻度都要相同。每处偏差都要在注释中注明原因。 上面的权利规则对代码和模型同样适用。

5. 对照基准进行验证

不要凭肉眼判断；要根据引擎中反编译出的数值衡量移植效果：速率（固定刻度下每秒射击次数）、时长（帧数 / 速度 / 每秒刻度数）、瞄准（瞄准镜中的点是否位于屏幕中心）、服务器上的弹药数量。在日志中记录每项检查及其结果。

只有当每项已移植行为都记录了实测数值，并与反编译出的数值并列对照时，才算完成。

评论

支持 Markdown