HalmyLyseas/VandalHearts-PcPort

# Vandal Hearts — 原生 PC 移植 基于 **Vandal Hearts** 美版 PlayStation 1 发行版（`SLUS_004.47`）的原生 PC 移植，建立在游戏的逐字节匹配反编译基础之上。 该项目分为两个阶段，**均已完成**： 1. **匹配反编译。** 每个非 PsyQ 函数都被反编译为 C 语言代码，且能逐字节重新构建出原始的 `SLUS_004.47`（`md5 596bb082a2de5f1fe977dd3d7e160b03`，可通过 `make check` 验证）。这是移植的基础，且在每次更改中仍被严格执行。 2. **去主机化 → 原生 PC 移植。** 每个 PlayStation 硬件接口——包括 GPU 数据包提交、GTE 矩阵数学、CD-ROM / XA 音频、SPU、MDEC 视频以及手柄输入——均被替换为可移植的等效实现（SDL2 + OpenGL + OpenAL），使得游戏能够使用自身数据在现代桌面上启动并运行。 ## 状态 该移植版**能够使用原始数据完整运行整款游戏**——从开场 FMV、过场动画、战术战斗、世界地图、队伍管理、对话、商店到存档/读档——这一切均已通过在 Windows 和 Linux 上的完整通关测试验证，包括游戏终局和制作人员名单。 - **音视频保真度：完整**，已针对真实硬件（BizHawk）进行验证：GTE/透视以及地形/精灵图渲染；以采样精度运行的软件 SPU 驱动 SEQ 音乐和 VAG 音效；CD-XA 流式音频；MDEC/STR 视频；以及 PS1 Shift-JIS/汉字文本。 - **64 位**是默认构建版本。该移植版是内存安全的——它以非特权模式运行（无需 root，无需 `setcap`），并且通过了针对整款游戏的 AddressSanitizer 越界扫描和 UBSan 检查，这两者共同修复了零售版游戏中潜藏的七个真实越界漏洞。 - **平台：Windows 和 Linux**，基于单一源代码树。Windows 的 `.exe` 是在 Linux 上通过 MinGW-w64 交叉编译的；Linux 版则打包为 AppImage。CMake 构建系统与 Makefile 并存。macOS 已搭好框架但未深入开发——请参阅 [docs/cross-platform.md](docs/cross-platform.md)。 ## 路线图 两个基础阶段——逐字节匹配的反编译和忠实原版的原生移植——均**已完成**（见上文*状态*）。**阶段 3** 增加了一个可选的玩法和体验质量优化层：更好的控制（包括一目了然的敌方威胁覆盖层）、游戏内选项和存档管理覆盖层，以及可选的平衡模式。忠实于原版的体验始终得以保留；改变游戏玩法的添加项均为可选内容。 关于已发布与计划中功能的完整细分，请参阅 **[docs/roadmap.md](docs/roadmap.md)**。这些是计划，而非承诺：这是一个非商业性的业余游戏 preservation（保护）项目。 ## 游玩指南 游戏由你提供；移植版提供其他一切内容。**你需要拥有合法购买的 Vandal Hearts (USA) 版本，并将其导出为原始的 `.bin` 光盘镜像**——此处不分发任何源自游戏本身的内容。 发行版是自包含的，无需寻找任何依赖项： | 平台 | 安装包 | 要求 | |---|---|---| | **Windows** | `.zip` —— `vandalhearts_pc.exe`，6 个运行时 DLL 文件，`vandalhearts.ini` | Windows 10/11 | | **Linux** | `VandalHearts-x86_64.AppImage` + `vandalhearts.ini` | glibc ≥ 2.34 (Debian 12+, Ubuntu 22.04+, Fedora 35+, RHEL 9, Arch)；运行 AppImage 需要 FUSE2 | **安装极为简单：**将你的光盘镜像放在可执行文件旁的 `game/` 文件夹中（或直接放一个裸露的 `*.bin` 文件在其旁边），然后运行即可。无需配置，无需环境变量——光盘会被自动检测，并且其启动签名会经过验证，因此挂载错误的光盘会显示明确的错误提示，而不是启动后显示白屏。 **要修改配置**，请编辑可执行文件旁（在 Linux 上为 `.AppImage` 旁）的 `vandalhearts.ini`：包含窗口缩放、音频和兼容性选项，默认均被注释掉。相同的文件和键值适用于所有平台；环境变量仍可覆盖它们。完整的选项参考请见 [`platform/pc/OPTIONS.md`](platform/pc/OPTIONS.md) 和 [docs/configuration.md](docs/configuration.md)。 存档是位于可执行文件旁的 `saves/` 文件夹中的普通文件。它们采用固定的磁盘存储格式，因此与架构无关，并且可以在 32 位和 64 位版本之间互相读取。 ## 从源码构建 要求：一台安装了 SDL2、OpenAL 和 OpenGL 开发库的 Linux 主机；Python 3；以及用于匹配反编译验证的 PSY-Q 工具链。32 位工具链为可选项（仅用于 `-m32` 参考构建）。完整的环境配置说明位于 `.claude/skills/decomp-build/` 目录中。 原生移植版有两种可互换的构建系统（两者生成相同的二进制文件）： ``` cd platform/pc # Makefile make link # -> platform/pc/build/vandalhearts_pc (64-bit) make link M32=-m32 BUILD_DIR=build32 # 32-bit reference build # CMake cmake -S . -B build_cmake && cmake --build build_cmake # -> build_cmake/vandalhearts_pc ``` Windows 是**在 Linux 上交叉编译的**（无需 Windows 机器），通过 CMake 工具链文件完成： ``` cmake -S . -B build_win -DCMAKE_TOOLCHAIN_FILE=cmake/toolchain-mingw-w64.cmake cmake --build build_win # -> build_win/vandalhearts_pc.exe + bundled DLLs ``` Linux 发行版被打包为 AppImage，并在锁定的 Debian 12 容器内构建，以保持产物的 glibc 最低版本要求较低——完整流程请参阅 [docs/cross-platform.md](docs/cross-platform.md)： ``` packaging/appimage/build-appimage.sh build_deb/vandalhearts_pc # -> dist/VandalHearts-x86_64.AppImage ``` 构建好的二进制文件查找你的光盘和 `vandalhearts.ini` 的方式与发行版完全相同（见*游玩指南*）；`VH_DISC_IMAGE` 仍可覆盖路径。运行时选项和构建标志请见 [`platform/pc/OPTIONS.md`](platform/pc/OPTIONS.md)。 字节精确反编译检查：`make check` 会重新构建 `SLUS_004.47` 并将其与原始文件进行 md5 比较。**对 `src/` 或 `include/` 的任何更改都必须保持此检查通过**——请参阅 [docs/architecture.md](docs/architecture.md) 了解控制约定（`PERMUTER`、`PC_PORT`、`PC_DEBUG_*`），以确保移植工作不会影响匹配构建。 ## 文档 完整的开发者和用户文档位于 **[`docs/`](docs/)** 中： - [架构](docs/architecture.md) —— 双层设计以及移植版如何避免破坏匹配 - [构建说明](docs/building.md) · [配置与运行](docs/configuration.md) - [PC 移植内部机制](docs/pc-port/overview.md) 及各子系统深入解析 （[GPU](docs/pc-port/subsystems/gpu.md), [GTE](docs/pc-port/subsystems/gte.md), [SPU](docs/pc-port/subsystems/spu.md), [CD/XA](docs/pc-port/subsystems/cd-xa.md), [MDEC](docs/pc-port/subsystems/mdec.md), [Kernel](docs/pc-port/subsystems/kernel.md)） - [内存安全与 64 位移植](docs/memory-safety.md) · [跨平台与打包](docs/cross-platform.md) —— Windows 交叉编译，Linux AppImage 发行版 - [宽度漏洞](docs/width-bugs.md) —— **ASan 和 UBSan 均无法检测到**的 32→64 位漏洞类别（截断拷贝、union 别名、结构体布局漂移），并附带检测器表。在修改结构体布局或 `Object` union 之前请阅读本文档。 ## 仓库结构 - `src/`, `include/` —— 匹配的反编译代码（C 源码和项目头文件）。 - `platform/pc/` —— 原生 PC 移植：PSX 子系统后端（`src/lib*.c`, `pc_*.c`），构建系统（Makefile, CMake, `cmake/` 工具链文件），数据生成和 sanitizer 工具（`tools/`, `run_*san.sh`），发行版打包（`packaging/`），以及干净的逆向 PsyQ 头文件。 - `docs/` —— 开发者与用户文档。 - `SLUS_004.47.yaml`, `symbol_addrs.txt` —— splat 配置文件以及地址到符号的映射表。 部分数据文件是在构建时根据你自己的副本**动态生成的**，且未提交到仓库（例如从 `KROMDAT.BIN` 生成的 PS1 汉字字体，以及游戏内的描述字符串）——这与数据段的处理模式相同。详见 [NOTICE](NOTICE)。 ## 法律声明 这是一个非商业性的粉丝 preservation（保护）与互操作性项目，不附属于 Konami 或 Sony，也未获得其认可，非出售，且不产生任何利润。 - **Vandal Hearts 及所有相关 IP 均归 © Konami 所有。** PlayStation、其 BIOS 以及 PsyQ SDK 归 © Sony 所有。本声明不主张任何所有权。 - **本源码仓库中不包含：**游戏可执行文件、光盘镜像、Sony BIOS/SDK 数据（包括 PS1 汉字字体）、Konami 的游戏内文本或任何提取的资源。请自行提供游戏副本；构建过程会在本地重构所需的内容。 - **仓库中包含的内容：**游戏代码的逆向工程反编译（`src/`），以及少量从二进制文件中重构出的功能性游戏数据表（单位属性、动画/精灵图指针表）——此处包含是出于互操作性和保护目的，归 © Konami 所有，本项目不主张为其自身所有。 - **预编译的发行版二进制文件**确实*嵌入了*部分游戏衍生数据（可执行文件的静态数据段、少量的 BIOS 衍生汉字字体以及重构的文本/数据表），因为编译后的二进制文件会将源码树在本地重新生成的内容固化进去。这仅是游戏的一小部分——对话、地图、音频和视频均在运行时从你提供的光盘中加载，因此如果没有你合法拥有的副本，发行版二进制文件将毫无用处。详见 [NOTICE](NOTICE) 中的详细细分。 完整详情请见 [DISCLAIMER](DISCLAIMER)。 ## 许可证 为本项目编写的原始 PC 移植代码和工具（主要是 `platform/pc/`）按 **GPL-2.0** 协议授权（见 [LICENSE](LICENSE)）。这**不**适用于反编译的游戏代码或游戏衍生数据，它们归 Konami 所有，本项目无权进行授权——请参阅 [NOTICE](NOTICE) 了解 GPL-2.0 授权的具体涵盖范围及其不涵盖的内容。 ## 鸣谢 基于 **shao113** 的 Vandal Hearts 匹配反编译项目 （）。完整的致谢——包括反编译工具链（splat、maspsx、old-gcc）、psx-spx 硬件参考文档以及 BizHawk——请见 [CREDITS](CREDITS)。 ## 外部文件（请从你自己的副本中提供） 本仓库中不包含： | 文件 | md5 | |---|---| | `SLUS_004.47` (基础可执行文件) | `596bb082a2de5f1fe977dd3d7e160b03` | | `ASPSX.EXE` (ASPSX v2.21, PSYQ v3.3 / DTL-S2190) | `e3ae8aea2623b916f89384bf70f55487` | | `LIB34.ZIP` | `d25fd757e944a05369e8fb003a007dd2` |

标签：Bash脚本, C/C++, PS1模拟, SDL2, URL提取, 事务性I/O, 云资产清单, 反编译, 客户端加密, 游戏移植, 逆向工具, 逆向工程