angelof-exe/ygo-tf-5-decomp

# Tag Force 5 反编译 针对 PSP 平台*《游戏王 5D's Tag Force 5》*的一项**匹配反编译**项目 （光盘 **ULES-01474**，Konami，2010，MIPS Allegrex CPU）。 目标是手工重建游戏的 C 语言源代码，使得在使用原始工具链重新编译后，能够生成**逐字节完全相同**的二进制文件——并以此为基础去理解、修复和扩展游戏（首先从决斗逻辑开始，该逻辑是硬编码在代码中而非数据中的）。 ## ⚠️ 法律声明 - **本仓库中不存储任何受版权保护的内容。** ISO、`.prx` 文件、EBOOT 以及提取的资源文件均被 `.gitignore` 排除在外。您必须提供自己合法获取的游戏副本以提取文件。 - 这里仅包含手工编写的重建源代码、工具和文档。 - Mod 以补丁的形式分发，绝不提供完整的 ISO。 ## 状态 初始设置已完成，**反编译工作已经开始**。`rel_movie_viewer`（最小的模块，26 KB）已完全拆分，并配有准确的 splat 配置，其 16 个 `.text` 函数中有 **9 个已达到 100% 匹配**（参见 [`src/rel_movie_viewer.c`](src/rel_movie_viewer.c)，带有 `MATCH 100%` 标记的函数）。 现在可以**完全在本地**验证匹配结果（无需 decomp.me 账号）：`wibo` 加上真实的 `mwccpsp_3.0.1_219` 二进制程序编译候选的 C 代码，并且 `scripts/mwcc_diff.py` 会像 decomp.me 那样将结果与 splat 的目标汇编代码进行 diff 对比——当重定位字（全局变量/调用）引用相同符号时，无论实际生成的地址是什么，都会被视为相等。参见 [`docs/06-splitting-and-matching.md`](docs/06-splitting-and-matching.md) 中的“Local matching”。 **已确认的编译器配置** | 设置 | 值 | |---|---| | 原始编译器 | Metrowerks CodeWarrior for PSP — `MW MIPS C Compiler (2.4.1.01)` | | decomp.me / 构建 | **MWCC 1.3 SP7** (`mwccpsp_3.0.1_219`) — 具体构建版本仍在缩小范围中（180–219 均可匹配简单函数） | | Flags | **`-O4,p -sdatathreshold 0`** | | 关键技术 | 游戏状态全局变量是 **`volatile`**，通过本地指针访问（参见 [`docs/09-first-match.md`](docs/09-first-match.md)） | 已经确立的内容： - **28 个 `rel_*.prx` 游戏模块是普通的 Allegrex ELF** → 可以立即进行分析。 - **EBOOT.BIN 已解密** → `build/EBOOT.elf`（共享的 `modehsys` 引擎）。 `BOOT.BIN` 是一个全零的占位文件。 - 完整的 pipeline 已完成端到端验证，**包括本地的、无需 decomp.me 的匹配循环**： ISO 提取 → EBOOT 解密 → Allegrex 反汇编 (rabbitizer) → **splat** 生成带标签的汇编代码 + 完整且准确的 linker script → **mwccpsp (通过 wibo) + 感知重定位的 objdump diff** → 100% 匹配，已验证 9 个函数。 ## 工作原理 ``` ISO ──extract_iso.sh──► iso_extracted/ EBOOT.BIN (~PSP) ──decrypt_eboot.sh──► build/EBOOT.elf PRX / EBOOT.elf ──Ghidra + ghidra-allegrex / prxtool──► understand code, resolve NID imports ──splat (config/*.yaml)──► asm/ + linker script ──m2c──► draft C in src/*.c ──mwccpsp + asm-differ / decomp.me──► byte-exact match ──build + sha1sum vs checksums.sha1──► verify ``` 每个阶段的详细信息都在 [`docs/`](docs/) 中——请参阅下方索引。 ## 仓库结构 ``` README.md this file CONTRIBUTING.md how to help docs/ full documentation (English) scripts/ setup_tools.sh, extract_iso.sh, decrypt_eboot.sh, run_ghidra.sh config/ splat configs (rel_movie_viewer.yaml = full, section-accurate config) src/ reconstructed C source (matched functions) requirements.txt Python toolchain (splat / spimdisasm / rabbitizer) checksums.sha1 sha1 of the original modules (match targets) .claude/skills/ Claude Code skills for this project .gitignore excludes ISO / assets / binaries / build output # 生成 / git-ignored (从未提交)： iso_extracted/ tools/ .venv/ build/ asm/ ``` ## 快速开始 ``` # 1. system 依赖 (一次) sudo apt install -y p7zip-full build-essential libssl-dev python3-venv cmake ninja-build # 2. project toolchain (venv + git 工具) scripts/setup_tools.sh # 3. 解包 disc (使用你自己的 ISO) scripts/extract_iso.sh "path/to/your.iso" # 4. 解密 EBOOT (共享 modehsys engine) make -C tools/pspdecrypt # after libssl-dev scripts/decrypt_eboot.sh # 5. 拆分 module . .venv/bin/activate splat split config/rel_movie_viewer.yaml # 6. (可选) 本地匹配，无需 decomp.me 账户 — # setup_tools.sh 已经将 wibo + mwccpsp_3.0.1_219 拉取到 tools/ 中； # MIPS objdump 是你仍然需要全系统安装的唯一东西： sudo apt install -y binutils-mips-linux-gnu scripts/mwcc_build.sh src/rel_movie_viewer.c scripts/mwcc_diff.py asm/rel_movie_viewer/text.s build/mwcc/rel_movie_viewer.o ``` Ghidra + ghidra-allegrex 扩展和 PPSSPP 需要手动安装——参见 [`docs/03-tools.md`](docs/03-tools.md)。使用 `scripts/run_ghidra.sh` 启动 Ghidra。 ## 文档 1. [`docs/01-overview.md`](docs/01-overview.md) — 什么是匹配反编译、工作流、法律声明与预期 2. [`docs/02-iso-analysis.md`](docs/02-iso-analysis.md) — 光盘结构、模块、识别出的编译器 3. [`docs/03-tools.md`](docs/03-tools.md) — 在 Linux 上安装工具链 4. [`docs/04-extraction-and-decryption.md`](docs/04-extraction-and-decryption.md) — 提取 ISO，解密 EBOOT 5. [`docs/05-ghidra.md`](docs/05-ghidra.md) — 使用 Ghidra + ghidra-allegrex 进行分析，NIDs 6. [`docs/06-splitting-and-matching.md`](docs/06-splitting-and-matching.md) — 拆分、m2c、asm-differ、decomp.me、mwccpsp 7. [`docs/07-file-formats.md`](docs/07-file-formats.md) — 资源格式（EHP / CIP / 卡牌数据库 / 音频 / 模型） 8. [`docs/08-resources.md`](docs/08-resources.md) — 链接、社区、参考项目 (sotn-decomp) 9. [`docs/09-first-match.md`](docs/09-first-match.md) — **实践教程**：在 decomp.me 上的首次匹配 ## 鸣谢 建立在 PSP 逆向工程与反编译社区的工作基础之上： [splat](https://github.com/ethteck/splat), [m2c](https://github.com/matt-kempster/m2c), [asm-differ](https://github.com/simonlindholm/asm-differ), [decomp.me](https://decomp.me), [ghidra-allegrex](https://github.com/kotcrab/ghidra-allegrex), [pspdecrypt](https://github.com/John-K/pspdecrypt), 以及 [Tag Force modding 社区](https://github.com/xan1242)。 ## 许可证 本仓库中的重建源代码和工具基于 [LICENSE](LICENSE) 中的条款发布。本项目与 Konami 无关，也未获得其认可。所有游戏内容和商标均归其各自所有者所有。

标签：MIPS架构, PSP, 云资产清单, 代码反编译, 客户端加密, 游戏开发, 逆向工具, 逆向工程