7akeem0/forzatech-localization-toolkit
GitHub: 7akeem0/forzatech-localization-toolkit
逆向工程并公开记录 ForzaTech 引擎的文本、字体与 UI 归档二进制格式，提供经过逐字节验证的 Python 工具以支持社区进行多语言本地化。
Stars: 3 | Forks: 0
# ForzaTech 本地化工具包
## 这个项目是什么
ForzaTech 是 Playground Games 和 Turn 10 Studios 在《Forza》系列中使用的引擎。直到现在，还没有公开文档说明游戏如何存储其文本（`.str`）、字体（`.vfont` / `.vfont0`），或者其 UI 归档（`UI.zip`）如何在修改后保持 memory-mapped alignment。
本仓库记录了这些二进制格式，并提供了 Python 工具来读取和写入它们，同时在原版游戏文件上进行了逐字节的 roundtrip 验证。
这项工作的参考应用是：[《Forza Horizon 6》的首个完整阿拉伯文本地化 mod](https://www.nexusmods.com/forzahorizon6/mods/65)，已发布在 Nexus Mods 上。该 mod 本身不在此仓库的范围内——这里记录的是使该 mod 成为可能的底层工程工作。
## 已破解的内容
| 子系统 | 状态 | 验证 |
|---|---|---|
| `.str` 二进制格式（字符串表） | 完全记录 | 对 287 个文件 × 24 种语言进行逐字节 roundtrip |
| `.vfont`（metrics + slot table） | 完全记录 | 对 20/20 种字体进行逐字节 roundtrip |
| `.vfont0`（mesh blobs: vertex + index） | 完全记录 | 对 19/20 种字体进行逐字节 roundtrip |
| `UI.zip` custom `0x1123` extra field | 已记录 | 在 454 个 entry 上确认了字段的语义 |
| Slot-preserving PKZIP repack | 已记录 + 工具 | 修改 UI 而不破坏 memory-mapped offsets 所必需 |
| Silent integrity checks（索引） | 已记录 | 即使 CRC 正确也无法修改的文件列表 |
| Latin-LSB glyph convention | 已记录 | 影响所有非拉丁语系 scripts 的引擎假设 |
## 快速开始
```
git clone https://github.com/7akeem0/forzatech-localization-toolkit
cd forzatech-localization-toolkit
pip install -r requirements.txt
```
如需查看完整本地化的分步指南（8 个步骤，适用于任何语言）：
**📖 [阅读 QUICKSTART.md](QUICKSTART.md)**
`examples/` 中提供了三个现成的示例：
```
# 提取所有文本为可翻译的 JSON 格式
python examples/01_extract_all_strings.py /path/to/EN.zip ./strings_json
# 修改后重建文本表格
python examples/02_modify_one_string.py ./strings_json /path/to/EN.zip output.zip
# 从 TTF 构建自定义 font
python examples/03_build_custom_font.py NotoSans.ttf out.vfont out.vfont0 \
--base Horizon_A.vfont --base0 Horizon_A.vfont0 --range 0x0400 0x04FF
```
## 文档
| 文件 | 主题 |
|---|---|
| [`QUICKSTART.md`](QUICKSTART.md) | 从头到尾的分步指南（从这里开始） |
| [`docs/install.md`](docs/install.md) | 游戏文件布局、备份、安装模式 |
| [`docs/str_format.md`](docs/str_format.md) | `.str` 二进制格式（header、sections、hash-linked key↔value） |
| [`docs/vfont_format.md`](docs/vfont_format.md) | `.vfont`：slot table、glyph records、kerning trailer、font fingerprint tags |
| [`docs/vfont0_format.md`](docs/vfont0_format.md) | `.vfont0`：atlas prelude、per-glyph blob、vertex/index encoding |
| [`docs/ui_zip_repack.md`](docs/ui_zip_repack.md) | `0x1123` extra field、4 KB alignment、slot-preserving repack algorithm |
| [`docs/silent_integrity_checks.md`](docs/silent_integrity_checks.md) | 引擎以非 CRC 方式检查的文件；哪些可行，哪些不可行 |
| [`docs/latin_lsb_convention.md`](docs/latin_lsb_convention.md) | 引擎关于 glyph origin 的假设；非拉丁语系 scripts 所需的 vertex shift |
| [`docs/rtl_in_ltr_engines.md`](docs/rtl_in_ltr_engines.md) | 在从左向右的引擎中渲染从右向左 scripts 的通用方法 |
| [`STORY.md`](STORY.md) | 逆向工程之旅的叙述 |
## 工具
| 工具 | 功能 |
|---|---|
| `tools/str_codec.py` | 读取和写入 `.str` 文件。已验证 roundtrip。 |
| `tools/vfont_codec.py` | 读取和写入 `.vfont` 和 `.vfont0` 文件。已验证 roundtrip。 |
| `tools/build_font_from_ttf.py` | 从 TrueType 字体构建 `.vfont` + `.vfont0`。可处理任何 codepoints 范围。 |
| `tools/patch_fontsettings.py` | 修复 `fontsettings.xml` 中的 fallback 链，以便所有权重（Bold/Condensed）都能返回到你注入新脚本的字体。 |
| `tools/ui_zip_patcher.py` | 用于 `UI.zip` 的 slot-preserving patcher。保留所有 4 KB-aligned data offsets。 |
## 为什么会有这个项目
《Forza》系列内置了 24 种官方语言。许多语言社区（泰语、乌克兰语、越南语、印地语、波斯语等）没有官方支持。在这个仓库之前，粉丝本地化受限于三个未解决的问题：
1. `.str` 格式是封闭的。文本无法提取或重新注入。
2. `.vfont` / `.vfont0` 格式是封闭的。无法添加新的 glyphs。
3. `UI.zip` 使用了 custom `0x1123` extra field，如果保存不当，游戏在启动时会崩溃。
这三个问题在这里都得到了记录和解决。任何业余翻译者现在都可以为任何《Forza》游戏制作其语言的完整本地化。
## 兼容性
已在 **Forza Horizon 6**（2026 年 5 月版本，Steam build）上验证。这些格式在 ForzaTech 的各个版本中保持稳定，预计在对 **Forza Horizon 4**、**Forza Horizon 5** 和 **Forza Motorsport (2023)** 进行微调后也能运行。具体的 offsets 和 font sets 因游戏而异；格式本身不会改变。
## 兼容 Anti-Cheat
ForzaTech 游戏支持联网，发行商的服务条款禁止修改游戏文件。本仓库中的工具仅触及客户端的本地化资源，对游戏性没有任何影响，**但在连接到在线服务时使用任何修改的风险由用户自行承担**。单机离线模式是这些工具产出的唯一支持模式。
## 许可证
- **代码**（`tools/`, `examples/`）：MIT License。参见 [`LICENSE`](LICENSE)。
- **文档**（`docs/`, `README.md`, `STORY.md`, `QUICKSTART.md`）：Creative Commons Attribution 4.0 (CC-BY-4.0)。
## English（英文原版说明）
首次公开逆向工程 **ForzaTech**（驱动《Forza Horizon 4/5/6》和《Forza Motorsport》的专有游戏引擎）的文本和字体子系统。该工具包允许你提取、修改并重新打包基于该引擎构建的任何游戏的本地化数据。
### 这是什么
ForzaTech 是 Playground Games 和 Turn 10 Studios 用于《Forza》系列的引擎。到目前为止，还没有关于该引擎如何存储其文本字符串（`.str`）、其字体（`.vfont` / `.vfont0`），或者其 UI 归档（`UI.zip`）在修改后如何保持 memory-mapped alignment 的公开文档。
本仓库记录了这些二进制格式，并提供了 Python 工具来读取和写入它们，同时针对已发布的游戏文件验证了逐字节的 roundtrip。
这项工作的伴随项目是：[《Forza Horizon 6》的首个完整阿拉伯文本地化 mod](https://www.nexusmods.com/forzahorizon6/mods/65)，作为参考实现发布在 Nexus Mods 上。该 mod 本身不在此仓库的范围内；这里记录的是使其成为可能的底层引擎工作。
### 快速开始
```
git clone https://github.com/7akeem0/forzatech-localization-toolkit
cd forzatech-localization-toolkit
pip install -r requirements.txt
```
如需完整的端到端操作指南（8 个步骤，适用于所有 scripts 通用）：请参阅 **[QUICKSTART.md](QUICKSTART.md)**。
### 已逆向工程的内容
| 子系统 | 状态 | 验证 |
|---|---|---|
| `.str` 字符串表二进制格式 | 完全记录 | 对 287 个文件 × 24 种语言进行逐字节 roundtrip |
| `.vfont` font metrics + slot table | 完全记录 | 对 20/20 种受测字体进行逐字节 roundtrip |
| `.vfont0` mesh blob 格式 | 完全记录 | 对 19/20 种受测字体进行逐字节 roundtrip |
| `UI.zip` custom `0x1123` extra field | 已记录 | 在 454 个 entries 上确认了语义 |
| Slot-preserving PKZIP repack 技术 | 已记录 + 工具 | 修改 UI 而不破坏 memory-mapped offsets 所必需 |
| Silent integrity checks（目录） | 已记录 | 即使具有正确的 CRC 也无法修改的文件列表 |
| Latin-LSB glyph convention | 已记录 | 影响所有非拉丁语系 scripts 的引擎假设 |
### 文档
从 [`QUICKSTART.md`](QUICKSTART.md) 和 [`docs/install.md`](docs/install.md) 开始。`docs/` 中的其余文档是每个子系统的正式规范。[`STORY.md`](STORY.md) 是逆向工程之旅的叙述。
### 工具
- `tools/str_codec.py` — `.str` 读取器/写入器（已验证 roundtrip）。
- `tools/vfont_codec.py` — `.vfont` 和 `.vfont0` 读取器/写入器（已验证 roundtrip）。
- `tools/build_font_from_ttf.py` — 从任何 TrueType 字体生成 `.vfont` + `.vfont0`。
- `tools/patch_fontsettings.py` — 重写字体 fallback 链，以便所有权重都能通过你修改后的字体解析。
- `tools/ui_zip_patcher.py` — 用于 `UI.zip` 的 slot-preserving patcher（保留 4 KB-aligned data offsets）。
### 为什么会有这个项目
《Forza》系列提供 24 种官方文本语言。许多语言社区（泰语、乌克兰语、越南语、印地语、波斯语等）没有官方支持。在这个工具包之前，粉丝本地化被三个未解决的问题所阻挡：`.str` 格式是不透明的，`.vfont` / `.vfont0` 格式是不透明的，而 `UI.zip` 使用了 custom `0x1123` extra field，如果保存不当会导致崩溃。这三个问题都在这里得到了记录和解决。
### 兼容 Anti-cheat
ForzaTech 游戏支持联网，发行商的服务条款禁止修改游戏文件。本仓库中的工具仅触及客户端的本地化资源，对游戏性没有任何影响，**但在连接到在线服务时使用任何修改的风险由用户自行承担**。单机离线模式是唯一支持的模式。
### 鸣谢
逆向工程、文档和工具：**Hesham**。Nexus 上的阿拉伯文本地化 mod（参考实现）由同一作者发布。
### 许可证
- **代码**（`tools/`, `examples/`）：MIT License。
- **文档**（`docs/`, `README.md`, `STORY.md`, `QUICKSTART.md`）：Creative Commons Attribution 4.0 (CC-BY-4.0)。
标签：Python, 云资产清单, 文件格式, 无后门, 本地化, 游戏Modding, 游戏引擎, 逆向工具, 逆向工程