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% 为目标：格式串、路径和空值保留其原有用途。

开始前复核

在工作目录运行：

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：建立失败测试。 除下例外，补充注释内伪调用、变量实参、转义引号、反斜杠续行、重复原文、映射缺项与不可编码字符的样例。禁止用匹配全部引号字符串的正则替换脚本。

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：添加失败测试。

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：实现构建约束。

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 的实际显示调用清单确定章节边界，再单独编写实施计划。未证实的调用不加入自动替换白名单。

每项交付时报告

报告本项改了什么、实机看到的收益、验证结果、已知未完成点和恢复方式。每项单独提交；没有明确收益的试验及时止步，不因已经生成文件就继续批处理。

11 KiB Raw Blame History Unescape Escape