Yokimitsuro/khdays-port
GitHub: Yokimitsuro/khdays-port
《王国之心 358/2 Days》的实验性原生 PC 移植运行时，将 DS 游戏代码适配为可在现代系统运行的可移植引擎，并支持 Mod 开发。
Stars: 1 | Forks: 0
# khdays-port
**《王国之心 358/2 Days》** 的实验性原生 PC runtime 和源码移植，与 [`khdays-decomp`](https://github.com/Yokimitsuro/khdays-decomp) 同步开发。
## 与 `khdays-decomp` 的关系
这两个代码库有着不同的目的：
- **`khdays-decomp`** 重构了 Nintendo DS 代码，编译后能在字节级别上与原版游戏完全一致。
- **`khdays-port`** 将已理解的游戏代码和行为适配到适用于现代系统的可移植 runtime。
匹配和逆向工程的工作属于 `khdays-decomp`。平台抽象、原生渲染、输入、音频、文件系统工作、易用性功能以及其他 PC 特定的更改则属于本项目。
该移植项目应使用固定版本的逆向工程代码，而不是将匹配代码库变成一堆特定平台的 `#ifdef` 块。
## 当前状态
阶段 0–3 已完成 —— 包括引导程序、用户数据 pipeline、平台 runtime 以及完整的资产/渲染 pipeline。目前的工作是 **阶段 4 —— 游戏流程**。当前可运行的内容：
**资产 pipeline** —— 每种资产类型都会被解码为中立、独立于引擎的格式：
- [x] TEX0 纹理 → RGBA
- [x] 2D/UI 图形：NCLR 调色板 + NCGR 图块 + NSCR 图块映射组合为 RGBA (`--render-tiles`, `--render-bg`)
- [x] NFTR 位图字体，支持文本渲染 (`--render-text`)
- [x] 带有骨骼和蒙皮的 MDL0 模型 → 中立、支持动画的网格
- [x] NSBCA 骨骼动画，逐帧 GPU 蒙皮；环境贴图 (NSBMD)
- [x] 来自 `db_.p2` 容器的消息文本和 UI `.s`/`.s.z` 字符串表 (`--message-info`, `--dump-messages`, `--dump-strings`)
- [x] 音频：SDAT 波形库 → PCM (PCM8/PCM16/IMA-ADPCM)，以及用于序列音乐的 SSEQ 软件合成器
**渲染与音频 (SDL3)**
- [x] GPU 渲染器：深度测试、纹理化、GPU 蒙皮、环绕摄像机，可播放任何 NSBCA
- [x] 音频输出：音效 (`--play-sound`) 和合成的音乐 (`--play-sequence`)
**Mod 开发** —— 在 DS 资产之前解析直接覆盖文件（参见 [Mod 开发](#modding)）：
- [x] 纹理 (PNG/BMP, HD)、绑定了骨骼的模型 (glTF，由 DS 骨骼驱动动画)、文本、音效、音乐采样、2D 图形、字体和原始文件
**阶段 4 —— 游戏流程（进行中）**
- [x] 游戏文件系统：`khdays::vfs` 解析 NitroFS 游戏路径 (mods → 解包 → 解压 → 原始) (`--vfs-resolve`)
- [ ] 启动循环和场景/任务状态机
- [ ] 初始场景（启动 → 标题 → 菜单）和实际游戏内容
阶段 4 *受限于逆向工程进度*：随着 [`khdays-decomp`](https://github.com/Yokimitsuro/khdays-decomp) 逐一还原各子系统的名称，本项目也会按子系统逐步重新实现这些已理解的游戏行为。完整计划请参见 [`docs/ROADMAP.md`](docs/ROADMAP.md)。
## 文档
- [`docs/ROADMAP.md`](docs/ROADMAP.md) — 里程碑与阶段计划。
- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — 中立格式的分层结构（导入器 → 资源层 → 引擎）。
- [`docs/MODDING.md`](docs/MODDING.md) — 通过 `mods/` 文件夹替换纹理、模型、文本、声音、2D 图形、字体和原始文件。
- [`docs/NATIVE_MESH_DECODER.md`](docs/NATIVE_MESH_DECODER.md) — 将 MDL0 几何体/蒙皮解码为中立网格。
- [`docs/NATIVE_TEX0_RUNTIME.md`](docs/NATIVE_TEX0_RUNTIME.md) — TEX0 纹理解码。
- [`docs/NATIVE_MDL0_INSPECTOR.md`](docs/NATIVE_MDL0_INSPECTOR.md) — `--model-info` 检查器。
- [`docs/PLATFORM_RUNTIME.md`](docs/PLATFORM_RUNTIME.md) — SDL3 平台 runtime。
- [`docs/MESSAGE_DATA_P2.md`](docs/MESSAGE_DATA_P2.md) — `db_.p2` 消息容器格式。
## 目标
- 为游戏构建原生、可移植的 runtime。
- 在可行的范围内保留原版游戏的行为。
- 将 PC 特定代码与字节匹配的 Nintendo DS 逆向工程代码分开。
- 要求用户提供游戏数据，而不是分发受版权保护的内容。
- 随着时间推移，支持现代输入、渲染、音频、显示分辨率和调试工具。
- 记录在逆向工程过程中发现的格式和行为。
## 非目标
- 分发游戏、预修补的 ROM、提取的资产或专有的开发工具。
- 取代或削弱 `khdays-decomp` 的字节匹配目标。
- 声称与原始版权所有者有关联或获得其认可。
- 将猜测或未经证实的代码视为已完成的逆向工程。
## 提议的架构
```
khdays-port/
├── CMakeLists.txt
├── include/
│ └── khdays/
│ └── port.h
├── src/
│ └── main.cpp
├── external/
│ └── khdays-decomp/ # pinned Git submodule
├── platform/
│ ├── common/
│ └── pc/
├── game/
│ └── ported/ # adapted, understood game code
├── tools/
│ ├── verify_rom/
│ └── extract_data/
├── docs/
│ └── ROADMAP.md
└── data/ # local generated data; never committed
```
当包含实际代码时，才应添加当前引导程序文件之外的其他目录。避免为尚未设计的系统提交空架子。
## 构建引导程序可执行文件
要求：
- CMake 4.2 或更高版本
- C++20 编译器：
- Windows 上使用 Visual Studio 2026
- Linux 上使用 Clang 或 GCC
- macOS 上使用 Apple Clang
配置并构建：
```
cmake -S . -B build
cmake --build build --config Release
```
在 Windows 上使用多配置生成器运行：
```
.\build\Release\khdays-port.exe
```
在 Linux 或 macOS 上使用单配置生成器运行：
```
./build/khdays-port
```
## 将逆向工程代码添加为 submodule
在代码库根目录下运行此命令：
```
git submodule add https://github.com/Yokimitsuro/khdays-decomp external/khdays-decomp
git submodule update --init --recursive
git add .gitmodules external/khdays-decomp
git commit -m "build: pin khdays-decomp as a submodule"
```
在正常构建期间，不要自动跟踪最新的逆向工程 commit。应有意识地更新固定的版本号，测试移植项目，并在移植项目的 commit 消息或 pull request 中记录该逆向工程的 commit。
## 首个技术里程碑
第一个有用的里程碑不是“启动整个游戏”。而是：
1. 接受本地 `.nds` 路径。
2. 计算并显示其加密哈希值。
3. 干净利落地拒绝不支持的版本。
4. 将所需文件提取到被忽略的本地存储中。
5. 打开原生窗口。
6. 加载并可视化一个纹理、模型或贴图资源。
7. 移植一个独立的函数或子系统，并将其行为与原版游戏进行比较。
这在尝试启动流程、叠加层、图形模拟、音频或游戏玩法之前，创建了一个合法且可测试的 pipeline。
## Mod 开发
由于 runtime 会先将 DS 资产解码为中立的开放格式，然后再提供给引擎，因此替换内容是一项受支持的功能，而不是修改底层字节。将开放格式的文件放入 `mods/` 文件夹中，资源层会在加载原始 DS 资产之前优先解析它们：
- **纹理** —— 位于 `mods//textures/**/.png` 的 PNG/BMP 文件会覆盖
DS 纹理。UV 坐标会根据原始 DS 尺寸进行归一化，因此更高分辨率的
(HD) 替换件能正确映射，且不会被缩小。
- **模型** —— 位于 `mods//models/.gltf` 且绑定了骨骼的 glTF 模型会替换 DS
模型的几何体，并**由 DS 骨骼驱动动画**：关节会根据名称与 DS 骨骼进行匹配，因此现有的 DS 动画可以在更高多边形数量的几何体上播放，无需重新制作动画。
- **文本** —— `mods//text/.txt` 文件会对游戏解码出的 UTF-8 字符串（`db_.p2` 剧情/菜单文本和 `UI/**/*.s.z` 表）进行重新翻译或修改，每行对应一个 `key = value`。
- **声音** —— 位于 `mods//sounds/_.wav` 的 WAV 文件会替换解码后的游戏波形（音效 / 语音片段）。
- **2D 图形和字体** —— 位于 `mods//graphics/.png` 的 PNG/BMP 文件会重绘 UI 背景，位于 `mods//fonts/.nftr` 的 NFTR 文件会替换字体。
Mod 永远只包含你自己的修改内容 —— 绝不包含受版权保护的游戏数据 —— 并且
`mods/` 已被 git 忽略。有关文件夹布局和导出/编辑工作流，请参见 [`docs/MODDING.md`](docs/MODDING.md)。
## 许可证
本代码库中的原始移植代码采用 [MIT 许可证](LICENSE) 授权。
从 `khdays-decomp` 导入或改编的代码仍受该项目的 CC0 1.0 公众领域贡献声明约束。第三方组件保留其各自的许可证。请参见 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)。
MIT 许可证仅适用于贡献者的原创作品。它不授予与原版游戏、其资产、名称、角色、商标或其他受版权保护材料相关的任何权利。
## 免责声明
这是一个非官方的、粉丝制作的逆向工程和保存项目。它不隶属于、不受其赞助，也未被 Square Enix、Disney、Nintendo、h.a.n.d. 或任何其他版权所有者认可。所有商标和原始游戏内容均归其各自所有者所有。
标签：C/C++, Nintendo DS, SDL3, 事务性I/O, 云资产清单, 游戏引擎, 源码移植, 逆向工程