DragonHD
175 lines
12 KiB
Markdown
175 lines
12 KiB
Markdown
# DragonHD 高收益、低复杂度优先 Implementation Plan
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** 先补齐可直接影响游玩体验的教程中文，再用少量贴图证明 2× 高清化收益，最后按验证结果扩大范围。
|
||
|
||
**Architecture:** 沿用已验收的字体补丁、GB2312 文本和资源解包成果。显示文本采用原文校验后的定点替换；高清素材采用独立清单、小批量构建及恢复。中文排版和贴图升级各自交付，避免同时更换多个变量。
|
||
|
||
**Tech Stack:** Python、Pillow、现有 res 工具；字体回归使用 Keystone/Unicorn；DDS 写回先确认编码工具及 mipmap 支持。
|
||
|
||
**Spec:** `docs/superpowers/specs/2026-09-20-next-steps.md`
|
||
|
||
## Global Constraints
|
||
|
||
- 游戏目录：`F:\steam\steamapps\common\The I of the Dragon`；工作目录：`E:\DragonHD`。
|
||
- 保留目前 12px CJK 字库和通过验收的排版补丁。
|
||
- 脚本仅改显示调用中的文本字面量；逻辑标识、事件名、路径、单位类型保持字节不变。
|
||
- 每批单独记录原文件 SHA256、变更文件清单和可验证的恢复方式。
|
||
- 新文本须能 GB2312 编码，保留原有格式占位符和引擎控制符。
|
||
- 贴图第一轮只做 2×，保留比例；透明通道、压缩类型及 mipmap 策略逐项核验。
|
||
- Git 只提交自制工具、文本映射和文档，原始/生成游戏资源留在本地。
|
||
- 先看原比例游戏截图，再判断是否扩大处理范围；局部放大截图只辅助检查。
|
||
|
||
## 排序与完成条件
|
||
|
||
| 顺序 | 工作 | 可见收益 | 复杂度 | 首批完成条件 |
|
||
|---|---|---|---|---|
|
||
| 1 | 教程显示文本汉化 | 入门流程基本不再出现英文讲解 | 低—中 | 教程提示/任务说明中文；关键教程事件正常推进 |
|
||
| 2 | 8 张贴图 2× 试做 | 判断实际清晰度提升，避免白做整库 | 中，TGA 较低 | 至少 2 张通过实机原比例对比；逐文件可恢复 |
|
||
| 3 | 合格类型批量 20–50 张 | 扩大已确认有效的高清范围 | 低—中，依赖第 2 项 | 常见素材观感提升，未出现黑边、接缝或明显卡顿 |
|
||
| 4 | 主线按章翻译 | 扩大中文覆盖到正式任务 | 中，依赖第 1 项 | 首章显示文本完成，任务触发和读档正常 |
|
||
|
||
第 1、2 项是下一轮可执行任务；第 3、4 项是通过前置验收后再展开的队列。
|
||
不以“479/496”补到 100% 为目标：格式串、路径和空值保留其原有用途。
|
||
|
||
## 开始前复核
|
||
|
||
在工作目录运行：
|
||
|
||
```powershell
|
||
python tools/test_cjk_layout.py -q
|
||
python tools/test_cjk_titles.py -q
|
||
python tools/check_translations.py
|
||
git status --short
|
||
```
|
||
|
||
预期：14 项排版测试及 2 项标题测试通过，格式占位符不匹配为 0。
|
||
记录当前游戏文件哈希，不覆盖 `backup_game/font-layout-20260920` 中的既有快照。
|
||
|
||
## Task 1: 教程文本完整提取、翻译与回灌
|
||
|
||
**Files:**
|
||
- Create: `tools/script_text.py`（扫描允许的显示调用并精确定位字符串跨度）。
|
||
- Create: `tools/test_script_text.py`（编码、转义、续行、只修改显示文本的行为测试）。
|
||
- Create: `tools/tutorial_cn.json`（原文校验值及中文映射）。
|
||
- Modify: `docs/DEVLOG.md`（验收结果及未覆盖项）。
|
||
- Local input: `F:\steam\steamapps\common\The I of the Dragon\Data\Scripts\English\Tutorial.dsc`。
|
||
- Local output: `build/tutorial/Tutorial.dsc`、`build/tutorial/manifest.json`。
|
||
|
||
**Interfaces:**
|
||
- `patch_display_calls(source: bytes, translations: dict[str, str]) -> bytes`。
|
||
- 映射键为解码后的原文字面量；同文同步替换，未命中的映射报错。
|
||
- 仅允许 `DisplayMessage` 的两个字符串实参与 `SetMissionDescription` 的字符串实参。
|
||
- CLI：`python tools/script_text.py --source <path> --mapping tools/tutorial_cn.json --out build/tutorial/Tutorial.dsc`。
|
||
- 工具只生成文件，不在构建时写游戏目录。
|
||
|
||
- [ ] **Step 1：固定输入。** 复制教程到本批次备份并计算 SHA256。当前文件为 21,166 字节；扫描可见 22 处 `DisplayMessage(`（含函数定义）、15 处 `SetMissionDescription(`，最终以解析出的字面量为准。
|
||
- [ ] **Step 2：建立失败测试。** 除下例外，补充注释内伪调用、变量实参、转义引号、反斜杠续行、重复原文、映射缺项与不可编码字符的样例。禁止用匹配全部引号字符串的正则替换脚本。
|
||
|
||
```python
|
||
import unittest
|
||
from script_text import patch_display_calls
|
||
|
||
class ScriptTextTests(unittest.TestCase):
|
||
def test_only_display_literals_change(self):
|
||
source = b'DisplayMessage("Help", "Move");\r\nEnableEvent("Move");\r\n'
|
||
actual = patch_display_calls(source, {'Help': '帮助', 'Move': '移动'})
|
||
expected = 'DisplayMessage("帮助", "移动");\r\nEnableEvent("Move");\r\n'.encode('gb2312')
|
||
self.assertEqual(actual, expected)
|
||
```
|
||
|
||
- [ ] **Step 3：运行测试并确认失败原因。** `python -m unittest discover -s tools -p test_script_text.py -v`。
|
||
- [ ] **Step 4：实现字节扫描器。** 逐字节维护注释/字符串/转义/括号状态，只标记允许调用的字面量范围；按原范围倒序替换。输出前检查原文命中、GB2312、占位符与控制符；原文件其他字节全部保留。
|
||
- [ ] **Step 5：翻译第一组实机可达提示。** 先做 Tutorial、Camera rotation、Center the camera、Zoom、Flight 及其重复任务说明。表达简洁，键位说明准确，不擅自改变操作要求。
|
||
- [ ] **Step 6：执行测试与构建。** 使用上述测试命令和 CLI；核对所有改动仅在提取的字面量跨度中，备份哈希与输入一致。
|
||
- [ ] **Step 7：完成其余教程显示文本。** 用同一映射、同一规则补齐；控制符 `\a/\f/\n` 与格式参数单独检查。记录保留英文的专名及理由。
|
||
- [ ] **Step 8：退出游戏后部署教程副本。** 依次验收镜头旋转、镜头回正、缩放、飞行及后续教程步骤；检查提示显示和下一事件触发，保存实机截图与结果。中途恢复旧教程后验证哈希一致，再装回新版。
|
||
- [ ] **Step 9：提交独立变更。** `git add tools/script_text.py tools/test_script_text.py tools/tutorial_cn.json docs/DEVLOG.md`；`git commit -m "feat: translate tutorial display text without changing events"`。
|
||
|
||
**完成门槛：** 显示文本中文、脚本逻辑字节不变、教程触发链实机通过，已有字体回归仍通过。仅文件成功生成不算教程已验收。
|
||
|
||
## Task 2: 8 张 2× 贴图试做，先评估再扩大
|
||
|
||
**Files:**
|
||
- Create: `tools/hd_pilot.json`（本轮选择及源文件哈希）。
|
||
- Create: `tools/hd_pilot.py`（选图、对比页、构建清单）。
|
||
- Create: `tools/test_hd_pilot.py`（尺寸、通道、清单与误选保护）。
|
||
- Create: `docs/hd-pilot-review.md`（每张在游戏中的结论）。
|
||
- Existing inputs: `report/upscale_plan.csv`、`report/textures_report.csv`、`png/`、`original/`。
|
||
- Local outputs: `build/hd-pilot/`；原图不覆盖。
|
||
|
||
**首批候选（已在当前资源清单中核对存在）：**
|
||
|
||
| 素材 | 原尺寸 | 用途 |
|
||
|---|---|---|
|
||
| `BigRock.tga` | 128×128 | 简单 TGA 回灌验证 |
|
||
| `Black_stone.tga` | 128×128 | 石材细节对比 |
|
||
| `creatures\amfibrahiy1.dds` | 256×128 | 不透明 DXT1 生物样本 |
|
||
| `creatures\Beatle.dds` | 256×256 | 不透明 DXT1 生物样本 |
|
||
| `buildings\arka.dds` | 256×128 | 建筑边缘细节 |
|
||
| `buildings\bochka01.dds` | 256×256 | 常见道具细节 |
|
||
| `buildings\brev-tor.dds` | 128×128 | 木材端面 |
|
||
| `buildings\brev.dds` | 128×256 | 木材表面 |
|
||
|
||
候选名称仅用于定位；先在游戏中确认可见场景。难以找到的素材换成同组、已确认可见的条目，并更新清单。自动分类可能遗漏平铺用途，实际出现接缝的样本移入后续专项。
|
||
|
||
**Interfaces:**
|
||
- `validate_size(original: tuple[int, int], result: tuple[int, int]) -> None`：只接受精确 2×，否则抛出 `ValueError`。
|
||
- `hd_pilot.json` 每项：`name`、`source_sha256`、`scale: 2`、`alpha_policy: "preserve"`。
|
||
- 每张比较原图、Lanczos 2× 基线、可用模型 2× 候选；尚无模型时先完成基线/回灌，不宣称 AI 高清化完成。
|
||
|
||
- [ ] **Step 1：记录源素材并建清单。** 核对原尺寸、通道、FourCC 和 mipmap；排除字体、UI 图集、烘焙文字、透明特效与已知平铺纹理。
|
||
- [ ] **Step 2：添加失败测试。**
|
||
|
||
```python
|
||
import unittest
|
||
from hd_pilot import validate_size
|
||
|
||
class PilotTests(unittest.TestCase):
|
||
def test_preserves_aspect_ratio_at_exact_two_times(self):
|
||
validate_size((256, 128), (512, 256))
|
||
with self.assertRaises(ValueError):
|
||
validate_size((256, 128), (512, 512))
|
||
```
|
||
|
||
- [ ] **Step 3：运行失败测试。** `python -m unittest discover -s tools -p test_hd_pilot.py -v`。
|
||
- [ ] **Step 4：实现构建约束。**
|
||
|
||
```python
|
||
def validate_size(original, result):
|
||
if result != (original[0] * 2, original[1] * 2):
|
||
raise ValueError('pilot texture must be exactly 2x with unchanged aspect ratio')
|
||
```
|
||
|
||
- [ ] **Step 5：先完成两张 TGA 的原比例/放大对比。** Pillow 生成 Lanczos 基线；若已有可用超分模型，再生成模型版，保留三个版本。不要将普通插值称为新增细节。
|
||
- [ ] **Step 6：验证 DDS 写回。** 先做原尺寸 decode/encode 对照，核对 DXT1、通道与 mipmap；确认工具链后再做六张 DDS 的 2×。若编码或材质兼容未通过，本轮仅交付已通过的 TGA 结果，并在审查文档标记 DDS 阻塞原因。
|
||
- [ ] **Step 7：逐张回灌。** 优先使用已验证的松散文件覆盖方式；有打包加载差异再以现有 `replace_res_entries` 工具重建副本，逐条核对非目标资源哈希。单独保存每个被覆盖文件及是否原本存在。
|
||
- [ ] **Step 8：同存档同视角截图比较。** 记录正常距离的观感、边缘光晕、纹理游动、接缝、加载耗时和帧率；帧率在同一场景预热后测三次。若中位帧率下降超过 5%，调查原因并暂不扩大批次。
|
||
- [ ] **Step 9：恢复验证与小批次结论。** 恢复原文件并验哈希；只重新部署“正常视距可见改善、无明显副作用”的样本。逐张标记通过/维持原版/需专项处理。
|
||
- [ ] **Step 10：提交工具与结果文档。** `git add tools/hd_pilot.py tools/test_hd_pilot.py tools/hd_pilot.json docs/hd-pilot-review.md`；`git commit -m "feat: add validated two-times texture pilot"`。
|
||
|
||
**完成门槛：** 至少 2 张实机效果优于原图且可完整恢复。即使模型版更锐，也允许选择观感更自然的基线或原版。
|
||
|
||
## 后续队列的启动条件
|
||
|
||
- **Task 3：20–50 张高清小批次。** 第 2 项确认至少一种素材类别收益稳定后再编写该批实施清单。优先玩家常见生物、建筑、道具；按清单逐张记录，不把全部 1195 张自动纳入。
|
||
- **Task 4：主线首章汉化。** 第 1 项显示文本工具和事件回归验收后，以 `MainMission.dsc` 的实际显示调用清单确定章节边界，再单独编写实施计划。未证实的调用不加入自动替换白名单。
|
||
|
||
## 每项交付时报告
|
||
|
||
报告本项改了什么、实机看到的收益、验证结果、已知未完成点和恢复方式。
|
||
每项单独提交；没有明确收益的试验及时止步，不因已经生成文件就继续批处理。
|
||
|
||
## 2026-09-20 分批执行进度
|
||
|
||
按用户“一步一步尝试汉化”将 Task 1 的首次实机批次缩小为开场、旋转镜头、镜头回正、缩放，飞行留待下一批。
|
||
|
||
- [x] 固定原始备份与 SHA256，建立独立工作区。
|
||
- [x] 文本扫描器和 14 项测试；首批 9 条映射、12 处显示文字。
|
||
- [x] 非显示字节逐段核对；原有 16 项字体回归通过。
|
||
- [x] 在独立副本执行恢复并核对原始哈希；生成差异和验证记录。
|
||
- [x] 游戏退出后部署，重读游戏文件并通过校验。
|
||
- [ ] 用户实机验证首批中文显示和教程事件推进。
|
||
- [ ] 首批确认后继续飞行及后续教程；Task 1 整体验收仍未完成。
|