Back to Details

blitz3d-decomp

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Blitz3D decompile and port

Blitz3D 反编译与移植

Blitz3D games ship as one exe: the runtime in 
.text
and the compiled game in a resource module that the runtime links at load. Ghidra on the exe shows only the runtime. The route that works: B3DDecomp disassembles the module and decompiles it to Blitz source. Then the source is the spec for the port, and the original game stays the oracle.
Keep every disassembly and decompile outside any repo (convention: 
~/<game>-decomp/
), and never publish them; the scripts here are fine to keep. Leave proprietary DLLs that forbid decompiling alone: their export names in the exe are enough. Journal in the mod's 
MODLOG.md
.
Read the source when there is one: SCP: Containment Breach (Regalis11/scpcb) and its Ultimate Edition Reborn fork (Jabka666/scpcb-ue-my) are open source under CC BY-SA 3.0.
What a port may use. A port that re-expresses a game's logic, or converts its models, keyframes, textures or sounds, redistributes that game once it is published or uploaded (to Roblox too). Port only what the user has the rights to: their own game, or an openly licensed one on its terms (SCP: Containment Breach: credit it and keep the port under CC BY-SA 3.0, and check each asset's credits, since fan games mix licences). Anything else stays a private study: nothing from it is uploaded or published.
Blitz3D 游戏以单个 exe 的形式发布：运行时位于 
.text
中，编译后的游戏位于资源模块中， 运行时会在加载时链接该模块。使用 Ghidra 分析 exe 时只能看到运行时。可行的路线是： **B3DDecomp 会反汇编该模块，并将其反编译为 Blitz 源代码。**之后，源代码便成为移植的规范， 而原游戏则作为 oracle。
将所有反汇编和反编译结果保存在任何 repo 之外（约定：
~/<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. Tools

1. 工具

  • B3DDecomp (juanjp600/B3DDecomp, C#, GPL-3): clone outside the repo, then 
    dotnet build Blitz3DDecomp.sln -c Release
    . It needs a .NET 8 SDK; a user-local one installs without admin (
    dotnet-install.ps1 -Channel 8.0 -InstallDir <dir>
    ). Run with 
    DOTNET_ROLL_FORWARD=Major
    and 
    bin/Release/net8.0
    on 
    PATH
    : the decompiler starts 
    Blitz3DDisasm
    by name.
  • If one function aborts the whole run, apply references/b3ddecomp-skip-failures.patch (
    git apply
    ; made on commit 2b3148b): the decompiler then skips a function it can't finish, with a 
    step5 failed
    line, instead of stopping.
Done when 
Blitz3DDecomp.exe
and 
Blitz3DDisasm.exe
build.
  • B3DDecomp（juanjp600/B3DDecomp，C#，GPL-3）：克隆到 repo 之外，然后执行 
    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. Disassemble and decompile

2. 反汇编与反编译

Blitz3DDecomp.exe <copy of game.exe>
writes 
<game>_disasm/
(Code/ per function, Type/, Strings.txt, BuiltIn/, Libs/, BuiltInSymbols.txt), then decompiles it to 
<game>_decomp/
. Games built from SCP: Containment Breach's code need the game's 
fmod.decls
as a second argument (B3DDecomp's README: the shipped decls drop a parameter from 
FSOUND_Stream_Open
).
When it still aborts, the exception names the construct. Never make a type setter silently ignore writes to get past one: the type propagation then loops forever with no output.
Protected builds: stop. Some builds are protected against this step: a modified compiler and runtime hash every function, type and builtin name (B3DDecomp stops with 
Unrecognized function: @_builtIn_f<garbled>
; SCP: Containment Breach 2's client is built this way), or the module is encrypted. Those are protections the developer added against decompiling. Don't reverse them: tell the user and stop (
skills/mod-any-game/references/safety.md
). Current B3DDecomp undoes one of them by itself, without saying so: an XOR on a 
.b3dmod
section. List the exe's sections first (
objdump -h
, or any PE viewer) and stop if it has one.
Done when 
<game>_decomp/
holds 
Main.bb
, 
Functions/
, 
Types/
and 
Decls/
and the run prints at most a handful of 
step5 failed
lines.
Blitz3DDecomp.exe <copy of game.exe>
会写入 
<game>_disasm/
（每个函数位于 Code/，以及 Type/、Strings.txt、 BuiltIn/、Libs/、BuiltInSymbols.txt），随后将其反编译到 
<game>_decomp/
。使用 SCP: Containment Breach 代码构建的游戏需要将游戏的 
fmod.decls
作为第二个参数（B3DDecomp 的 README：随附的 decls 会漏掉 
FSOUND_Stream_Open
的一个参数）。
如果运行仍然中止，异常会指明具体的语法结构。不要为了让程序越过某个问题而让类型 setter 静默忽略写入： 否则类型传播会陷入无限循环，并且不会产生任何输出。
**受保护的构建：停止。**某些构建针对此步骤采取了保护措施：经过修改的编译器和运行时会为每个函数、 类型和 builtin 名称计算哈希（B3DDecomp 遇到 
Unrecognized function: @_builtIn_f<garbled>
时会停止；SCP: Containment Breach 2 的客户端即以此方式构建），或者模块已经加密。 这些正是开发者为防止反编译而添加的保护。不要尝试逆向这些保护：告知用户并停止 （
skills/mod-any-game/references/safety.md
）。当前 B3DDecomp 会在不作提示的情况下自动解除其中一种保护： 对 
.b3dmod
节进行 XOR 运算。首先列出 exe 的节（
objdump -h
或任意 PE 查看器），如果存在此类节，则停止。
完成标准：
<game>_decomp/
中包含 
Main.bb
、
Functions/
、
Types/
和 
Decls/
，且运行输出中最多只有少数几行 
step5 failed
。

3. Find the system

3. 查找游戏系统

  • Strings first: an asset path or sound the system loads (
    grep -l StringConstant_<n> Code/*
    ).
  • Data-driven templates: the init function stores constants into a template per item. If the game has an addon/JSON loader, it names every field.
Done when every number the port will use is traced to the line that sets it and the line that reads it.
  • 先从字符串入手：查找系统加载的资产路径或声音（
    grep -l StringConstant_<n> Code/*
    ）。
  • 数据驱动的模板：init 函数会按物品将常量写入相应模板。如果游戏包含 addon/JSON 加载器， 它会列出每个字段的名称。
完成标准：移植将使用的每个数值都追踪到了写入它的行和读取它的行。

4. Port

4. 移植

Read references/blitz-runtime.md before writing port code: Blitz3D's clock, Animate, CurveValue, Euler angles, Rnd and entity calls behave in ways a straight transcription gets wrong. For animated 
.b3d
models (viewmodels, rigs, keyframes) into Roblox, follow references/b3d-to-roblox.md; its scripts are in 
scripts/roblox/
.
Port step for step: same order, same constants, same tick. Mark every deviation in a comment with the reason. The rights rule above covers the code as much as the models.
编写移植代码前，请阅读 references/blitz-runtime.md：Blitz3D 的时钟、 Animate、CurveValue、欧拉角、Rnd 和实体调用具有一些行为特征，直接照搬这些逻辑容易出错。 对于要移植到 Roblox 的动画 
.b3d
模型（viewmodel、rig、关键帧），请遵循 references/b3d-to-roblox.md；其中的脚本位于 
scripts/roblox/
。
逐步移植：采用相同的顺序、常量和 tick。用注释标出每项偏差及其原因。 上述权利规则同样适用于代码和模型。

5. Verify against the oracle

5. 与 oracle 对照验证

Measure the port against the decompiled numbers in the engine, not by eye: rates (shots per second at the fixed tick), durations (frames / speed / ticks per second), aim (the sight's dot on the screen centre), ammo on the server. Record each check and its result in the journal.
Done when every ported behaviour has a measured number next to the decompiled one.
在引擎中依据反编译得到的数值衡量移植效果，而不是仅凭肉眼判断：速率（固定 tick 下每秒射击次数）、 持续时间（帧数 / 速度 / 每秒 tick 数）、瞄准（准星与屏幕中心的点积）、服务器端弹药数量。 将每项检查及其结果记录在日志中。
完成标准：每项已移植行为旁边都附有一个实测数值，可与反编译得到的数值对照。