adonis-singh/re4 来源：https://github.com/adonis-singh/re4

《生化危机 4》（GameCube）—— 反编译项目

这是一个针对任天堂 GameCube 平台《生化危机 4》的完整、逐字节对应的反编译工程：对应的是 G4BE08 调试版本（即 “Nov 25 2004” 原型，包含两张光盘），其 Bio4.sym 文件为每个函数提供了名称。

构建此仓库可精确重现 main.dol 文件以及全部 114 个 REL 覆盖层模块（config/G4BE08/build.sha1，每次构建均会校验）。

本仓库不包含任何游戏资源，也未复制光盘中的任何代码或数据。你需要自行拥有调试光盘的镜像文件才能进行构建（Disc 1 用于构建 main.dol 和大部分 REL 模块；Disc 2 用于构建四个岛屿关卡的 REL 模块）；原始文件在配置阶段（configure）从你的镜像中读取。

构建指南

需要 Linux 系统、Python 3 和 ninja (https://ninja-build.org/)。编译器和工具（decomp-toolkit、objdiff、wibo、CodeWarrior 编译器）将在首次配置运行时下载，但原生 SN GCC 除外：

# 1. 构建原生 cc1/cc1plus（一次性操作）：需要 SN 的 GPL 源码包，详见 tools/sn-gcc/build.sh
SN_GCC_SRC=/path/to/NGC_GNU_SRC/NGC
tools/sn-gcc/build.sh

# 2. 准备光盘镜像（Disc 1：main.dol + 110 个 REL；Disc 2：四个岛屿关卡 REL：st3_0..st3_3）
cp re4_debug_disc1.iso re4_debug_disc2.gcm orig/G4BE08/

# 3. 构建与验证
python3 configure.py && ninja

ninja 命令将以进度报告结束（DOL 和所有 REL 模块均达到 100% 匹配并链接成功）；执行 build/tools/dtk shasum -c config/G4BE08/build.sha1 将打印 115 行 OK。

若需处理某个单元，可使用 python3 tools/bytecmp.py game/foo 将其对象与原始文件逐字对比，或使用 python3 tools/fdiff.py game/foo <函数名> 查看单个函数的差异。

目录结构

• src/game/ —— 游戏主体代码（C++；包含少量 newlib C 单元）。其中 src/em*/ 为敌人，src/wep*/ 为武器，src/pl*/ 为玩家角色，src/st*/ 为房间（每个房间对应一个 REL），src/t_*/、src/Tools/、src/tools/ 为游戏内调试编辑器，src/Sscrn/ 为子画面，src/lib/ 为 SDK、CRI 和运行时库。
• include/ —— 头文件，包括重建的结构体布局。
• config/G4BE08/ —— 单元列表（objects.py、modules.py）、symbols.txt、splits.txt、链接器脚本、各模块 REL 数据（modules//）、build.sha1。
• tools/ —— 构建生成器（project.py）、ProDG 驱动程序（ngccc.py）、REL 重建工具（make_rel.py、link_rel.py）、比较工具、sn-gcc/（原生编译器构建）、research/（编译器分析套件）、motion_export.py + motion/（动画导出为 glTF/BVH，使用游戏自身代码评估并在 Dolphin 模拟器中验证）。
• docs/overview.md —— 引擎架构概述：按子系统划分的 src/ 目录阅读指南。
• docs/matching.md —— 匹配实现细节：编译器来源、用于重现其机制的编译器机制和源代码结构目录、两种编译器的经验法则。docs/unit-notes.md 为各单元注释。docs/research/ 为逐阶段研究日志。

“匹配”的含义

在此项目中，“匹配”意味着每个单元都使用原始编译器编译为原始字节。当编译器需要特定的源代码结构来重现寄存器选择或调度，且未找到自然表达方式时，该结构会通过 // COMPILER-DIFF: 注释标记（共 644 处：如死测试、空 asm("") 清洗与锚定、register T x asm("rN") 绑定、填充语句等）。这些注释本身不产生任何指令：python3 tools/asmcheck.py --all 会为每个 GCC 单元编译并标记其汇编模板，列出源自模板的指令——唯一命中的是下文列出的硬件内核代码（总计 231 条；八个包含内联汇编的单元单独报告，不计入此数字）。

本仓库早期版本曾包含约 100 条手工放置的汇编指令（如 asm("li %0,0")、asm("lis/addi")、asm("mr")）在游戏代码中，以及约 100 个寄存器绑定 asm { } 块在 CRI 库中；它们已于 2026-09-17 替换为 C 代码（docs/research/compiler.md 的 “Asm-removal pass” 章节记录了方法与每个位置的编译器机制）。每个标记的机制均在 docs/matching.md 和 docs/research/ 中有文档说明。

保留的汇编代码，均为原作者同样使用汇编编写的部分，因为他们的编译器无法以其他方式表达：

• GCC 2.95 游戏代码：配对单精度运算内核（math_sub 中的 SINF/COSF/RSQRT/LIMIT_ANGLE，trans、shape、dbmodule 中的矩阵内核，Espgen42/espgen45 中的量化 psq_l），main/scheduler 中的 GQR 设置，以及 libsn sndvd 异常处理器。
• MWCC CRI 库：配对单精度 / 缓存 / SPR 内核（mpv_umc、mpv_mc、dct_fsri、cftyp422_ppc、mpv_lib），SDK 的 mtx/vec/quat/GX 内置函数，以及 dct_ac 中一个寄存器引导块（dctac_Init：供应商编译器构建时将 .bss 段合并，但不合并函数的 8 字节字面量；我们的构建则合并两者）。

另外还残留 27 处无功能的 asm { mr r11, x; mr x, r11 } 绑定（两条移动指令均被分配器删除；它们通过减少一个寄存器来缩小色集）和 asm { mr v, v } 自复制（一个不透明的二次定义）。

• 八个包含内联汇编的单元：crt0（__start）、eabi、SN 的 tealeaf/fileserver/ppcdown/proview（src/lib/*.c），以及 Capcom 的 memset_2 和 yz2asm（src/game/*.cpp）。其原始文件即为汇编（SN 的 libsn/crt0 对象和 Capcom 自身的汇编；字节中不包含编译器习语），因此每个都是一个 C 文件，其中的函数作为顶层 asm() 主体，使用 GAS 语法编写（.globl/.type/标签/.size，本地 .L_ 标签，.4byte/.float/.skip 数据），由与其余部分相同的 ProDG 驱动程序编译（include/asm_regs.h 通过 .set 常量提供 r3/f1/GQR0 名称；NgcAs 接受裸数字）。tools/asmcheck.py 将它们列为 asm-bodied。

命名规范

函数名来自 Capcom 调试版本的 Bio4.sym 文件；它们是 C++ 修饰名，这就是为什么游戏代码是 C++，而 SDK、CRI 和 newlib 单元是 C。

文件名和单元边界来自二进制文件中 assert 留下的 D:/Bio4/Prog/.cpp 字符串。

结构体和字段名有三类：供应商名称（来自 PS2 调试版本的类型信息，通过 tools/ps2sym.py 与 GameCube 布局匹配）；我们根据用法命名的名称（已明确标记）；以及占位符 xNN（十六进制偏移，表示未知）。供应商名称保留其原始拼写，因此仓库有意混合了命名约定。

#line 指令重现了 assert 字符串中的供应商行号。docs/naming.md 中有完整说明和统计。

贡献指南

详见 CONTRIBUTING.md：构建步骤、三项验证检查、规则（字节永不改变、不得产生指令的汇编、命名规范），以及如何基于证据提议重命名。

法律声明

重建的游戏及 SDK 源码是其各自所有者（Capcom、任天堂、CRI Middleware）的知识产权，发布仅用于研究与保存目的。为此项目编写的构建脚本、工具和文档采用 CC0 许可协议发布（LICENSE）。