Falkzera/hitman-mac-modding
GitHub: Falkzera/hitman-mac-modding
一个用于将 Windows 版《杀手：暗杀世界》Mod 迁移到 macOS Apple Silicon 原生版的 Rust 工具，通过内容匹配桥接两套不同的资源 ID 方案。
Stars: 0 | Forks: 0
# HITMAN World of Assassination — macOS (Apple Silicon) 原生 mod
在 **macOS 原生版本**（Feral Interactive 移植，通过 Steam）上运行 **HITMAN: World of Assassination** mod 的工具和方法 —— **游玩时无需 CrossOver/Wine**。
促使这一切的用例：在 Mac 原生版游戏中安装**社区制作的 PT-BR（巴西葡萄牙语）翻译**。但这里的技术（让为 Windows 制作的 mod 能在 Mac 版 Glacier 引擎上运行）适用于**任何**内容 mod。
## ⚠️ 重要警告（请先阅读）
- 本仓库**仅包含工具和文档**。它**不**分发游戏或翻译。
- 你需要**拥有游戏**（Steam）并自行在 NexusMods 下载 mod（链接见下文）。
- 该技术需要访问游戏 **Windows 版本的文件**（原因和获取方式见下文）。
- 修改游戏文件的风险由你**自行承担**。请做好备份。本仓库与 IO Interactive、Feral Interactive 或 NexusMods 没有任何隶属关系。
## 兼容性（已测试）
| 项目 | 已测试版本 |
|---|---|
| 游戏 | HITMAN World of Assassination — app **3.270.1**，Steam **buildid 23678892** (appid 1659040) |
| 平台 | macOS，**Apple Silicon (arm64)** — Feral 移植版 (`Hitman WOA.app`，bundle `dk.ioi.ios.hitman`) |
| Mod | **HITMAN World of Assassination PT-BR v2.0.5** (发布版 "3.270.1 Hotfix SMF") |
| Mod 来源 | https://www.nexusmods.com/hitman3/mods/1225 |
| 参考 (Windows) | 相同 build **23678892**（需要与 Mac 版和 mod 版本完全匹配） |
## 为什么这并不简单（发现过程）
HITMAN 的 mod 是 `.rpkg` 文件，它们通过**资源 ID**（RuntimeResourceID — 资源路径的哈希值）覆盖游戏资源。直觉告诉我们：Mac 移植版是同一个游戏，因此 ID 应该与 Windows 版相同，只需直接复制 mod 即可。
**事实并非如此。** 通过对比 Mac 版约 88.8 万个资源与 Windows 版约 89 万个资源（同一 build），我们发现：
- **`mod ∩ Windows` = 18,228 / 18,228 (100%)** — mod 与 Windows 版完美匹配。
- **`mod ∩ Mac` = 0** — 无论字节顺序如何，均不匹配。
- **`Windows ∩ Mac` = 0** — 这两款游戏**没有共享任何一个资源 ID**，即使逐字节对比也是如此。
也就是说：**Feral 的移植版使用了与 Windows 版完全不同的资源 ID 方案**。直接复制的 Windows mod 所指向的 ID 在 Mac 版游戏中**根本不存在** → 因此会被静默忽略（游戏正常打开，但没有任何变化）。
## 解决方案：*content-bridge*（将 Windows 作为罗塞塔石碑）
尽管 **ID** 不同，但本地化资源的内容（解压后的英文文本）在 Windows 和 Mac 之间是**字节完全相同**的。这就允许我们建立一座桥梁：
```
recurso do mod (ID-Windows, texto PT)
└─> acha o ORIGINAL inglês no Windows (mesmo ID)
└─> casa esse conteúdo inglês com o do Mac ──> descobre o ID-Mac
└─> re-emite o texto PT sob o ID-Mac, no chunk certo
```
这样我们就永远不需要“破解” Feral 的哈希值 —— 我们将内容本身作为密钥。匹配率为：
| 类型 | 覆盖率 |
|---|---|
| **LOCR** (菜单/UI/文本) | 639 / 648 (98.6%) |
| **DLGE** (对话字幕) | 17,426 / 17,448 (99.87%) |
| **RTLV** (过场动画字幕) | 128 / 132 — *blob 在第 152–159 字节处内嵌了视频 ID；我们对此 ID 进行了重新映射* |
| **总计** | **~18,193 / 18,228 (99.8%)** |
对于 DLGE（引用音频/动画），补丁使用了 **mod 中的 PT 文本 blob** + **Mac 原版的引用表**（即正确的 Mac 引用 ID）。验证结果：18,065 个资源 + 69,964 个引用，**全部**存在于 Mac 游戏中。
完整技术详情请见 [`docs/DEEP_DIVE.md`](docs/DEEP_DIVE.md)。
## 前置条件
1. **Apple Silicon Mac** 且已安装原生 **HITMAN WoA**（Steam 版）。
2. **Rust**（工具链）：使用 [`rustup`](https://rustup.rs) 安装。
3. 来自 NexusMods 的 **PT-BR mod**：https://www.nexusmods.com/hitman3/mods/1225 — 下载**Simple Mod Framework 的独立发布版**（即包含预编译 `content/` 文件的版本）并解压。
4. **游戏 Windows 版本的文件**（包含 `.rpkg` 的 `Runtime/` 文件夹），且必须是**相同的 build**。这是用于发现 Mac ID 的“罗塞塔石碑”。获取选项：
- 仅通过 **CrossOver** 安装游戏以获取这些文件（你不需要在里面玩），或者
- 从 Windows PC 复制 `Runtime/` 文件夹，或者
- 通过 Steam 在另一台机器上下载。
## 操作指南
```
# 1) 安装 Rust Toolchain（如果尚未安装）
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# 2) 克隆并编译
git clone https://github.com/Falkzera/hitman-mac-modding.git
cd hitman-mac-modding
cargo build --release
# 3) 定位这三个路径（如有需要请调整）：
MAC="$HOME/Library/Application Support/Steam/steamapps/common/HITMAN 3/Hitman WOA.app/Contents/Resources"
WIN="$HOME/Library/Application Support/CrossOver/Bottles/Steam/drive_c/Program Files (x86)/Steam/steamapps/common/HITMAN 3/Runtime"
MOD="$HOME/Downloads/HITMAN-World-of-Assassination-PTBR" # pasta extraída do mod (contém content/)
# 4) 在 build/remap-full/ 中生成 remap patches（LOCR + DLGE）
./target/release/remap "$MAC" "$WIN" "$MOD" "$PWD/build/remap-full"
# 5) （可选）验证：每个资源 ID 和引用 ID 都必须存在于 Mac 中
./target/release/vfull "$MAC" "$PWD/build/remap-full"
# 6) 安装前备份 config 文件
mkdir -p ~/HitmanModBackup
cp "$MAC/packagedefinition.txt" ~/HitmanModBackup/
# 7) 安装（复制 patches + 提升分区的 patchlevel）
./install.sh
# 8) 随时回滚
./uninstall.sh
```
游玩前：
- Steam → HITMAN WoA → **属性 → 更新 → “仅在我启动时更新游戏”**（防止更新还原 mod）。
- 安装 mod 后**切勿**运行“验证游戏文件完整性”（会还原所有更改）。
- **将游戏语言设置为 English** — mod 会用 PT 文本覆盖英语槽位。
## 在线模式
在作者的测试中，安装 mod 后**游戏在线连接完全正常** — 因为补丁仅替换了资源的**文本**（保留了 Mac 原生的 ID），这并未被系统检测为篡改内容。结果是：在线进度和在线功能均得以保留。
## 局限性
- **过场动画字幕 (RTLV)：** 已翻译 128/132。RTLV 的 blob 以 *inline* 方式内嵌了视频 ID（第 152–159 字节），这在各平台间有所不同 — 我们已重新映射了该 ID。还剩下约 35 个资源（部分 LOCR/DLGE/RTLV）由于内容不匹配而保持英文（约占 mod 的 0.2%）。
- **特定于 build 23678892。** 其他版本的游戏/mod 需要重新生成补丁（步骤相同）。
- **Steam 更新会还原 mod** — 之后需再次运行 `./install.sh`。
- **生成时需要 Windows 文件**（见路线图）。
- 不触碰 app 的可执行文件（仅修改 `Contents/Resources/`），因此 app 的 ad-hoc 签名**不会**失效。
## 工具说明 (`src/bin/`)
`remap` 是核心工具；其余的是在调查期间编写的，主要用于诊断/复现。
| 可执行文件 | 功能 |
|---|---|
| **`remap`** | 通过 content-bridge 对 mod（LOCR + DLGE）进行重新映射，**生成 Mac 补丁**。 |
| `verify` | 重新打开补丁，并与源文件逐字节进行校验。 |
| `vfull` | 验证补丁中的所有资源 ID 和引用是否都存在于 Mac 版中。 |
| `bridge` | 通过内容测量 Windows↔Mac 的匹配率（以评估可行性）。 |
| `distribute` / `ownership` / `wherein` | 查询每个资源位于哪个 chunk/文件中。 |
| `fullcheck` / `probe` / `hashcheck` | ID 集合对比及 IOI 哈希验证。 |
| `types` / `chunkmap` / `diag` | 资源类型及分区组装诊断。 |
`install.sh` / `uninstall.sh`：安装/还原（复制补丁 + 调整 `packagedefinition.txt`）。
## 路线图
- [ ] 发布**预计算好的 `ID-Windows → ID-Mac` 映射表**（仅包含哈希对，无游戏内容），让其他用户**无需 Windows 文件**。
- [ ] 研究 **RTLV**（过场动画字幕）的桥接方案。
- [ ] 泛化以支持其他 build / 其他内容 mod。
## 致谢
- **PT-BR 翻译：** FrankieScheuer 和 ImPedrooooo — [NexusMods mod 1225](https://www.nexusmods.com/hitman3/mods/1225)。所有的翻译工作均归功于他们。
- **[`rpkg-rs`](https://github.com/dafitius/rpkg-rs)** (dafitius / glacier-modding) — 用于读取/写入 RPKG 格式。
- **[glacier-modding](https://github.com/glacier-modding)** 社区和 Simple Mod Framework。
- 感谢 IO Interactive 和 Feral Interactive 带来的游戏和移植版（无隶属关系）。
## 许可证
代码采用 [MIT](LICENSE) 许可证。该许可证**仅**涵盖本仓库的工具 — 不包含游戏或翻译本身。
标签：Apple Silicon, Cutter, HITMAN, 可视化界面, 本地化翻译, 游戏, 游戏模组, 跨平台兼容, 通知系统