KakarottoCake/EclipseRecompiled

# Eclipse 重新编译 [](#current-status) [](https://github.com/KakarottoCake/EclipseRecompiled/actions/workflows/ci.yml) [](LICENSE) Eclipse Recompiled 是一项实验，旨在使用 [GameCubeRecompiled](https://github.com/KaiserGranatapfel/GameCubeRecompiled) 将 **Super Mario Eclipse 1.1.0** 转换为原生的 Windows 程序。 其长期目标是打造一个在 PC 上体验自然、支持识别真实的 GameCube 控制器适配器、支持常见现代控制器且易于修改的版本。 该项目目前已经能够读取合法获取的 Eclipse 光盘镜像，将其主程序翻译为 Rust，编译生成 Windows 可执行文件，加载其文件，并启动主机端 runtime。它**目前还无法进入菜单或进行游戏**，因为底层 GameCube runtime 的部分重要功能尚未完成。 ## 请先阅读此说明 - 本仓库**不包含任何游戏、ROM、ISO、DOL、任天堂资产或重新编译的游戏二进制文件**。 - 您必须自行提供合法获取的 `GMSE04` Super Mario Eclipse 1.1.0 镜像。 - 生成的游戏代码和提取的资产将保留在本地，并被 Git 忽略。 - 构建成功并不意味着游戏是可以玩的。 - 本项目为非官方项目，与任天堂、Super Mario Eclipse 团队或下文提及的上游项目均无任何附属关系。 ## “重新编译”是什么意思？ GameCube 游戏包含 PowerPC 机器指令。静态重新编译器会提前将这些指令翻译为现代 PC 可以运行的代码。 这项翻译工作只完成了一半。原版游戏还依赖于 GameCube 的图形芯片、音频处理器、控制器、光盘驱动器、操作系统服务、时序和内存行为。PC runtime 必须为所有这些都提供可用的替代实现。 一个通俗的比喻： - 重新编译器翻译了游戏的**语言**。 - runtime 重建了**游戏期望运行的宿主机环境**。 Eclipse 的语言目前已基本翻译完成。但重建的环境还不够完整，不足以让 Sunshine 运行起来。 ## 当前状态 | 领域 | 状态 | 说明 | | --- | --- | --- | | Eclipse 光盘验证 | 可用 | 能识别 `GMSE04` 1.1.0 镜像并记录哈希值 | | DOL 提取 | 可用 | 在本地提取游戏的主要 PowerPC 可执行文件 | | 静态翻译 | 可用，但不完整 | 从修补后的 Eclipse DOL 生成约 111 MB 的 Rust 代码 | | 原生 Windows 构建 | 可用 | 生成的 crate 通过检查，且 debug 主机链接成功 | | 启动 | 部分可用 | Eclipse 的重新编译入口点可以运行并返回 | | 光盘文件系统 | 可用 | 通过外部的压缩归档文件提供 473 个文件 | | 主机 Lua 模组 | 可用 | 本地 `.lua` 文件按文件名顺序加载 | | 散落资产覆盖 | 可用 | `mods/files/` 目录下的文件可以替换光盘文件 | | GameCube 适配器检测 | 已实现 | 通过 USB 直接处理 Nintendo 和 Mayflash 适配器 | | 现代控制器 | 在主机端已实现 | SDL 负责映射 Xbox、PlayStation、Switch 等类似控制器 | | 游戏内控制器输入 | 未完成 | 主机输入仍需要连接到 Sunshine 的 PAD/SI 调用 | | 图形 | 未达到游戏可用标准 | Vulkan 主机渲染器已启动，但 Sunshine 无法生成可用的 framebuffer | | 音频 | 未达到游戏可用标准 | 主机音频已启动，但 GameCube DSP 行为不完整 | | 菜单和游戏玩法 | 不可用 | 游戏目前的启动进度还不够远 | | Better Sunshine/Kuribo 模块 | 不可用 | 原生 `.kxe` 模块的加载和重定位尚未实现 | ### 最近验证的本地里程碑 使用 Super Mario Eclipse 1.1.0： - 发现了 13,496 个函数； - 解码了 901,056 条 PowerPC 指令； - 98.8% 的指令翻译覆盖率； - 58 项核心和 runtime 测试通过； - 完整生成的 crate 通过编译检查； - 一个 353 MB 的 debug 主机链接成功； - 在冒烟测试期间，Vulkan 渲染、主机音频、Lua、DVD、SDL 和 GameCube 适配器后端均成功初始化。 上述百分比衡量的是重新编译器是否为某条指令生成了代码。它**并不能**证明每条翻译后的指令都能正确运行。 ## 目前还缺少什么？ 大多数剩余的阻碍因素是 [GameCubeRecompiled](https://github.com/KaiserGranatapfel/GameCubeRecompiled) 尚未完全提供的功能。其中一些工作对所有 GameCube 重新编译项目都有用；另一些工作则是 Sunshine 和 Eclipse 特有的。 ### 1. 持续的游戏执行循环 主机目前仅在启动时调用 Eclipse 的入口点。一个真正的游戏必须在窗口处理帧、输入、音频、中断和计时器的同时持续执行。这些系统需要一个可靠的调度器，而不是一次性的调用和看门狗。 ### 2. GameCube 操作系统行为 Sunshine 依赖于 Nintendo 的 GameCube OS 行为。runtime 仍然需要更完整地实现以下内容： - 线程和上下文切换； - 警报和计时器； - 中断； - 消息队列和同步； - 缓存和内存行为； - 异常处理。 这里哪怕有微小的偏差，也可能导致游戏陷入死循环或走错代码分支。 ### 3. GX 图形支持 必须将 GameCube 的 GX 图形系统转换为现代 GPU 指令。主机可以创建 Vulkan 窗口并呈现 framebuffer，但 Sunshine 使用的 GX 状态、顶点格式、纹理、拷贝操作和同步机制要比 runtime 目前处理的复杂得多。 这是最大的可见阻碍：在 GX 足够完善之前，没有真正的游戏画面可以显示。 ### 4. DSP 和流式音频 启动 PC 音频设备并不等同于重现 GameCube 的音频处理器。Sunshine 和 Better Sunshine Engine 需要的 DSP 任务、混音、流式传输、时序和回调目前仍然缺失。 ### 5. 将控制器连接到游戏 主机端的控制器层已经实现： - Nintendo `057e:0337` 适配器； - 处于 Wii U 模式的 Mayflash `0079:1843` 适配器； - 四个 GameCube 控制器端口； - 模拟摇杆和扳机； - 震动； - 合理的 modern-controller 面键映射。 在 runtime 实现并分发被翻译后游戏调用的 GameCube `PAD` 和 `SI` API 之前，Sunshine 无法使用这些数据。 ### 6. 光盘、存档和异步 I/O 行为 基础的文件查找和读取功能可以正常工作。但游戏还期望支持异步 DVD 请求、回调、优先级、时序、取消、错误状态以及记忆卡服务。这些都需要在行为上与原版硬件足够接近。 ### 7. 重新编译器的正确性 完整生成的 Eclipse crate 可以编译通过，但更深层的启动测试几乎肯定会发现需要修正的翻译指令、间接分支、寄存器行为或函数边界。“能编译”和“与原版主机一致”是非常不同的标准。 ### 8. Better Sunshine Engine 和 Kuribo 支持 Eclipse 使用了 [Better Sunshine Engine](https://github.com/DotKuribo/BetterSunshineEngine)。它的 Kuribo `.kxe` 模块需要一个加载器，该加载器必须能理解模块元数据、重定位、导入、导出和生命周期回调。当前的主机 Lua 层可用于 PC 端的实验，但它无法替代 Kuribo。 ### 9. Eclipse 特有的测试和修复 一旦普通的 Super Mario Sunshine 能够通过 runtime 启动，就必须对 Eclipse 的自定义代码、关卡、资产和引擎修改进行单独测试。可能仍需要针对特定游戏提供适配层。 ## 什么时候才算准备就绪？ 在满足以下条件之前，该项目不应被视为已完成： - 可靠地启动并进入 Eclipse 标题画面； - 进入关卡并维持游戏运行； - 在常见的 GPU 上正确渲染； - 播放音乐和声音且没有重大的时序问题； - 使用真实的 GameCube 适配器和常见的现代控制器； - 安全地进行存档和读档； - 加载 Eclipse 依赖的 Better Sunshine/Kuribo 模块； - 运行时不需要在仓库或发布版本中包含受版权保护的文件； - 提供一套可从用户自有镜像重复执行的构建流程。 ## 控制器目标 预期的默认行为是： - 真实的 GameCube 适配器只需最少的设置即可工作； - 适配器的所有四个端口均可见； - 模拟 L/R 扳机和数字扳机点击都能正常工作； - 震动功能正常； - 现代控制器遵循物理 GameCube 布局： 南面 = A，西面 = B，东面 = X，北面 = Y，扳机 = L/R，右肩键 = Z； - 稍后可以添加高级重映射功能，且不会使默认设置变得复杂。 在 Windows 上，官方适配器通常需要通过 WinUSB 暴露其接口。当适配器可见但无法被占用时，输入日志会对此进行说明。 ## 模组目标 Eclipse 已经建立在 [Better Sunshine Engine](https://github.com/DotKuribo/BetterSunshineEngine) 和 [Super Mario Sunshine decompilation](https://github.com/doldecomp/sms) 之上。本项目旨在保留这种对模组友好的精神。 目前存在两种早期的工作流程： 1. **散落文件覆盖** 将替换文件放在 `mods/files/`。无需重建 ISO，它将优先于归档的光盘文件生效。 2. **主机 Lua 脚本** 将 `.lua` 文件直接放在 `mods/` 目录下。它们会在主机启动时按文件名顺序加载。 Kuribo `.kxe` 支持仍然是一个独立且未完成的需求。 ## 本地构建 经过测试的环境是 Windows。首次构建的数据量很大，可能需要几分钟的时间。 ### 环境要求 - Windows 10 或 11； - [rustup](https://rustup.rs/)； - 带有 `pip` 的 Python； - 合法获取的 Super Mario Eclipse 1.1.0 `GMSE04` 镜像； - 几 GB 的可用磁盘空间。 ### 1. 克隆并初始化 ``` git clone https://github.com/KakarottoCake/EclipseRecompiled.git cd EclipseRecompiled .\scripts\bootstrap-windows-toolchain.ps1 git clone https://github.com/DotKuribo/BetterSunshineEngine.git ..\third_party\BetterSunshineEngine ``` 初始化脚本会在父级工作区下安装便携版的 LLVM-MinGW 和 CMake。它不需要 Visual Studio 或管理员权限。 ### 2. 准备您的私有镜像 ``` .\scripts\prepare-eclipse.ps1 -IsoPath "D:\path\to\your-eclipse.iso" ``` 这将创建被忽略的本地文件： - `eclipse/main.dol`； - `eclipse/manifest.json`； - `game/assets.bin`； - 生成的内存镜像数据。 请勿提交或分发它们。 ### 3. 生成并构建 ``` .\scripts\build-eclipse.ps1 ``` 如果在与此仓库同级的位置检出了 Better Sunshine Engine 仓库，则构建过程会使用它的 NTSC-U 符号映射，位置在： ``` ../third_party/BetterSunshineEngine/maps/us.map ``` 您也可以显式指定映射文件： ``` .\scripts\build-eclipse.ps1 -SymbolMap "D:\path\to\us.map" ``` ### 4. 运行实验性主机 ``` .\scripts\play-eclipse.ps1 ``` 预期会弹出一个调试图口，而不是一个可玩的游戏。 ### 5. 检查控制器 ``` .\scripts\input-doctor.ps1 ``` 诊断程序会监听十秒钟，并打印出已连接的控制器和实时的输入状态。 ## 仓库结构 ``` gcrecomp-core/ PowerPC decoding, translation, memory, and SDK services gcrecomp-runtime/ Graphics, audio, controller, and host runtime gcrecomp-cli/ Analyze, prepare, and recompile commands gcrecomp-lua/ Host-side Lua and disc archive helpers gcrecomp-ui/ Host configuration UI game/ Native host application recompiled/ Placeholder for generated private game code mods/ Host Lua examples and ignored loose asset overrides scripts/ Windows bootstrap, build, launch, and diagnostics docs/ECLIPSE_PORT.md Technical bring-up notes and validated measurements ``` ## 常见问题解答 ### 可以玩了吗？ 不行。它可以编译并启动，但无法进入菜单或进行游戏。 ### 该仓库包含 Super Mario Eclipse 吗？ 不包含。它仅包含源代码和工具。 ### 为什么不直接用 Dolphin？ Dolphin 是目前玩 Eclipse 最实用的方式。本项目探索的是一条原生的静态重编译和模组化道路。它属于研发性质，在现阶段并不能替代 Dolphin。 ### 可执行文件能编译成功，是否意味着重新编译器完成了？ 不是。编译成功仅证明 Rust 接受了生成的源代码。它并不能证明生成的结果重现了 GameCube 的硬件行为。 ### 上游 GameCubeRecompiled 的改进会有帮助吗？ 是的。通用性的 GX、DSP、OS、DVD 和输入改进都将惠及本项目。但 Sunshine/Eclipse 的集成以及 Kuribo 支持仍需要针对具体游戏进行专项工作。 ## 上游项目与致谢 本仓库是 [KaiserGranatapfel/GameCubeRecompiled](https://github.com/KaiserGranatapfel/GameCubeRecompiled) 的开发分支，并保留了其 Git 历史记录和 CC0-1.0 许可证。 它使用或参考了以下项目的公开信息： - [DotKuribo/BetterSunshineEngine](https://github.com/DotKuribo/BetterSunshineEngine)； - [doldecomp/sms](https://github.com/doldecomp/sms)； - [mstorsjo/llvm-mingw](https://github.com/mstorsjo/llvm-mingw)。 这些项目并未在此处打包，它们各自保留其原作者身份和许可证。 ## 法律声明 本仓库旨在用于互操作性、研究、保存以及使用合法获取的游戏数据进行开发。它不授予对任天堂、Super Mario、Super Mario Sunshine、Super Mario 或任何其他第三方材料的任何权利。请勿分发光盘镜像、提取的资产、生成的游戏代码或编译后的游戏二进制文件。 有关本仓库现有的条款，请参阅 [LICENSE](LICENSE) 和 [EULA.md](EULA.md)。

标签：Bash脚本, GameCube, rizin, Rust, 云资产清单, 可视化界面, 游戏模拟器, 游戏移植, 网络流量审计, 逆向工具, 逆向工程, 通知系统, 静态重编译