Goemon64Recomp项目构建指南：从ROM解压到可执行文件生成

项目概述

Goemon64Recomp是一个针对N64游戏《神秘的忍者：Goemon》的重编译项目，它通过现代编译技术将原版游戏代码转换为可在现代系统上运行的版本。本文将详细介绍如何从零开始构建这个项目，包括环境准备、ROM处理、代码生成和最终编译的全过程。

环境准备

系统要求

项目支持Windows和Linux两大平台，以下是各平台的具体要求：

Windows平台

1. Visual Studio 2022：需包含以下组件：
   • 桌面开发C++工作负载
   • C++ Clang编译器
   • C++ CMake工具
2. Make工具：可通过包管理器安装

Linux平台(Ubuntu示例)

需要安装以下基础开发工具：

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

其他Linux发行版需安装对应的等效软件包。

获取项目代码

项目使用了多个子模块，因此克隆时需要特殊处理：

git clone --recurse-submodules [仓库地址]

如果克隆时忘记添加参数，可在项目目录下执行：

git submodule update --init --recursive

ROM处理流程

获取原始ROM

需要准备NTSC-U版《神秘的忍者：Goemon》ROM文件，其SHA1校验值应为： df8083a54296b8c151917c5333e1c85f014a2a66

ROM解压

1. 使用专门的解压工具处理原始ROM
2. 将解压后的ROM重命名为mnsg.us.decompressed.z64
3. 放置于项目根目录下

代码生成阶段

构建N64Recomp工具

1. 先构建N64Recomp和RSPRecomp两个核心工具
2. 将生成的可执行文件复制到项目根目录

执行代码转换

在项目根目录下运行：

./N64Recomp mnsg.us.toml
./RSPRecomp aspMain.us.toml

此步骤会将N64原生代码转换为现代C代码。

补丁应用

项目依赖的两个核心库需要应用特定补丁：

1. N64ModernRuntime补丁：

cp N64ModernRuntime.patch lib/N64ModernRuntime
cd lib/N64ModernRuntime
git apply N64ModernRuntime.patch

2. rt64补丁：

cp rt64.patch lib/rt64
cd lib/rt64
git apply rt64.patch

项目编译

Windows平台编译

1. 使用Visual Studio打开项目文件夹
2. 直接使用IDE的构建功能进行编译

命令行编译(跨平台)

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

调试版本只需将Release替换为Debug。

运行注意事项

1. 生成的可执行文件位于：

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

2. 运行时需确保：

   • 从项目根目录执行
   • 或复制assets文件夹到构建目录

3. 重要提示：实际游戏运行时需要使用标准ROM，而非解压后的版本。

常见问题排查

1. 子模块问题：确保所有子模块正确初始化
2. ROM校验失败：检查文件SHA1值是否匹配
3. 编译错误：确认所有依赖项已安装
4. 运行时崩溃：检查assets文件夹是否就位

通过以上步骤，您应该能够成功构建Goemon64Recomp项目，在现代硬件上体验这款经典的N64游戏。