Zelda64Recomp项目构建指南：从ROM到可执行程序的全流程解析

Zelda64Recomp项目构建指南：从ROM到可执行程序的全流程解析

Zelda64Recomp Static recompilation of Majora's Mask (and soon Ocarina of Time) for PC (Windows/Linux) 项目地址: https://gitcode.com/gh_mirrors/ze/Zelda64Recomp

前言

Zelda64Recomp是一个基于N64游戏《塞尔达传说：姆吉拉的假面》的重新编译项目。该项目通过将N64平台的机器码逆向转换为现代C代码，实现在现代PC平台上运行经典游戏。本文将详细介绍从获取原始ROM到最终生成可执行程序的完整构建流程。

准备工作

获取项目代码

首先需要获取完整的项目代码库。由于该项目使用了多个子模块，克隆时需要特别注意包含所有子模块内容。正确的克隆命令如下：

git clone --recurse-submodules

如果克隆时忘记添加递归参数，可以在项目目录中执行以下命令来初始化子模块：

git submodule update --init --recursive

系统依赖安装

Linux系统（以Ubuntu为例）

在Ubuntu系统上，需要安装以下开发工具和库：

sudo apt-get install cmake ninja-build libsdl2-dev libgtk-3-dev lld llvm clang

这些软件包包括：

• CMake：跨平台的构建系统
• Ninja：高效的构建工具
• SDL2开发库：多媒体支持
• GTK3开发库：图形界面支持
• LLVM/Clang工具链：现代C/C++编译器

Windows系统

Windows环境下需要：

1. 安装Visual Studio 2022，选择以下组件：

   • 使用C++的桌面开发
   • C++ Clang编译器
   • C++ CMake工具

2. 通过包管理器安装make工具：

choco install make

ROM处理阶段

获取并解压缩原始ROM

项目需要特定版本的《塞尔达传说：姆吉拉的假面》ROM文件（NTSC-U美版，SHA1校验码：d6133ace5afaa0882cf214cf88daba39e266c078）。由于原始ROM是压缩格式，需要先进行解压缩处理。

解压缩后的ROM文件必须重命名为： mm.us.rev1.rom_uncompressed.z64 并放置在项目根目录下。

代码生成阶段

构建N64Recomp工具

N64Recomp是本项目的核心工具，负责将N64机器码转换为C代码。构建完成后会生成两个关键可执行文件：

• N64Recomp：主处理器代码转换器
• RSPRecomp：RSP协处理器代码转换器

执行代码转换

在项目根目录下运行以下命令进行代码转换：

./N64Recomp us.rev1.toml
./RSPRecomp aspMain.us.rev1.toml
./RSPRecomp njpgdspMain.us.rev1.toml

这些命令会：

1. 解析ROM文件
2. 分析N64机器码
3. 生成等效的现代C代码
4. 创建项目构建所需的源文件

项目构建阶段

Windows环境构建

使用Visual Studio 2022打开项目文件夹后，可以直接使用IDE的构建功能。VS会自动识别CMake配置，提供构建、运行和调试选项。

命令行构建（跨平台）

推荐使用CMake结合Ninja进行高效构建：

cmake -S . -B build-cmake -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_C_COMPILER=clang -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build-cmake --target Zelda64Recompiled -j$(nproc) --config Release

参数说明：

• -DCMAKE_BUILD_TYPE=Release：生成优化版本（调试可用Debug）
• -j$(nproc)：使用所有CPU核心并行编译
• -G Ninja：使用Ninja构建系统

运行注意事项

构建完成后会生成Zelda64Recompiled可执行文件，位置取决于构建方式：

• Visual Studio：out/build/x64-[Configuration]
• CMake命令行：build-cmake

重要提示：

1. 必须从项目根目录运行程序，或复制assets文件夹到构建目录
2. 实际游戏运行时需要使用标准ROM，而非解压缩版本

结语

通过以上步骤，开发者可以成功构建Zelda64Recomp项目，将经典的N64游戏代码转换为现代PC平台可执行程序。这个过程展示了逆向工程和代码重编译技术的强大能力，为经典游戏的现代化提供了可行路径。

Zelda64Recomp Static recompilation of Majora's Mask (and soon Ocarina of Time) for PC (Windows/Linux) 项目地址: https://gitcode.com/gh_mirrors/ze/Zelda64Recomp