d2r-mobile 仓库内容边界:DERIVED.md 全面解析——仓库里有什么、没什么、为什么必须带
d2r-mobile 仓库内容边界:DERIVED.md 全面解析——仓库里有什么、没什么、为什么必须带
导读
docs/DERIVED.md 是 d2r-mobile 项目对外声明「不含、也不分发任何游戏内容」的精确化说明。本文以此文档为骨架,逐一拆解仓库中十类「与游戏有关但并非游戏内容」的记录——从着色器对照表、图形接口声明到 800 余处 main+0x… 地址——并深入到 dm/tools/patch_nso.py、dm/gfx/nvn/ 与 dm/verify/ 的源码与数据文件,说明这些记录各自在构建链路与验证链路中的实际用途、数据格式与规模。读完你将明白:为什么一个「不含游戏内容」的仓库,恰恰必须携带这二十余个文件,才能让玩家用自己的 Switch 版游戏文件在 iPhone / iPad / Mac 上还原出完整可玩的《暗黑破坏神 II:狱火重生》(术士君临)。
一句话原则:事实记录可以带,游戏内容坚决不带
d2r-mobile 首页声明「contains none and distributes none」。DERIVED.md 的第一价值是把这句话说准确:游戏内容本身(程序、美术、音频、文字、数据表、着色器、存档)一样都不进仓库;但要让玩家「用自己的游戏文件」在 Apple 设备上跑起来,仓库又必须携带一批关于游戏的事实记录(records of facts about the game)——没有它们,即便你手里有合法游戏文件,也做不出能跑的安装包。
这两类东西的边界在构建与发布时是被机器强制执行的:
- 导出放行检查:每次导出公开仓库时,都有一道工具拿真实的游戏文件,到整棵仓库树里逐字节搜索,任何一处命中就阻止导出。这意味着仓库里出现任何一段游戏程序、贴图、字符串或着色器字节,都会在发布环节被拦截。
- 版本一致性断言:dm/tools/patch_nso.py 里所有改写规则在应用前都要求「原指令字节逐条相等,不符即中止」(文件头注释明确写着「改写前逐条断言原字节,不符即中止」),例如第 241 行的
assert len(ob) == len(nb) and IMG[off:off + len(ob)] == ob。原指令字不是写给游戏用的,而是用来**核对「确实是这一版、确实是这个位置」**的证据。
仓库里没有的:五类内容全部在你机器上现做
DERIVED.md 明确列出的「仓库里没有的」清单如下,本文补充其对应生成环节与出处:
| 仓库里没有的 | 说明 |
|---|---|
| 游戏程序 | 主程序与系统库的任何一段代码。改写器 patch_nso.py 输出的是由你的 main 等 NSO 文件当场生成的补丁映像,不随仓库分发 |
| 美术、音频、过场 | 界面新面板复用的原版贴图也不进仓库,只带路径名(见下文 borrowed_paths.tsv 一节) |
| 游戏的文字与数据表 | 物品名、技能名、对话等各语言字符串表均不在仓库 |
| 着色器 | 原版着色器包,以及由它翻译出的 Metal 源码与编译产物(metallib)都不带;翻译只在你自己机器上进行 |
| 存档 | 见下文「预置存档」说明,仓库只带一个由游戏文件派生、由构建工具生成的种子 |
这些内容全部在玩家自己的机器上、用玩家自己的游戏文件现做出来——对应的就是 docs/GAME_FILES.md 描述的三步流程:放置游戏文件 → ./setup.sh 改写程序并翻译着色器 → 构建安装包。
另有几样「自用但不随仓库分发」的派生物
DERIVED.md 还点出了三样项目自用、但不带进公开仓库的派生物,并给出了实测数据:
- 启动预取清单(startup prefetch list):每一行携带一个原版资源块的开头字节,用于启动时提前解码(实际实现见 dm/host/hle_tact.c 的
tact_prefetch_start,产物为构建输出目录中的bootlist.tsv,缺省开启、DM_TACT_PREFETCH=0可关,见 dm/host/main.c 与 dm/host/hle_tact.c 的注释)。文档给出的实测:在 Mac 上运行 iOS 包,带清单到选角页 2.8 秒,不带则 3.3–4.0 秒(各两局,手机未实测)。换言之,不带这条清单只是少一步提前解码、启动稍慢,游戏依然能跑。 - 共享仓库的预置存档(seed save):不带时游戏照原版自己生成一份空的,行为一致(iOS 宿主缺省开、
DM_STASH_SEED=0关,见 dm/host/hle_fs.c 的注释)。 - 界面绑定测试的两份夹具:从运行中的游戏内存捕获;不带时读它们的三个测试会自动跳过。
这三样与下表「仓库里带着的」形成清晰对比:前者是游戏资源的字节本身(派生物),后者是游戏的事实描述(记录)。
仓库里带着的:十类「事实记录」逐一拆解
DERIVED.md 用一张四列清单(位置 / 大小 / 是什么 / 为什么必须带)回答「带着什么、为什么必须带」。下表为原文骨架的完整继承:
| 位置 | 大小 | 是什么 | 为什么必须带 |
|---|---|---|---|
| dm/gfx/nvn/shader_map.tsv | 1.33 MB | 原版每个着色器变体的编号与校验值,以及它们之间的对应关系。不含任何着色器代码 | 翻译着色器时要靠它认出「这是哪一个」 |
| dm/gfx/nvn/shader_facts.tsv | 1.13 MB | 每个着色器的接口描述:用到哪几个贴图槽、各是什么类型、输出几路 | 翻译时需要这些事实;它们原本要从 PC 版游戏文件里查,而绝大多数人手里只有 Switch 版 |
| dm/gfx/nvn/pso_manifest.tsv | 177 KB | 游戏会用到的渲染管线状态组合的清单 | 启动时提前建好管线,免得第一次用到时卡顿 |
| dm/gfx/nvn/names.txt、dm/gfx/nvn/nvn_slots.tsv | 16 KB、24 KB | 主机图形接口的 523 个函数名,以及游戏主程序里存放它们的位置 | 宿主要按名字接管这些函数 |
| dm/gfx/nvn/include/nvn.h | 89 KB | 主机图形接口的声明。第三方作品,MIT 许可,作者见文件头 | 图形层照它实现 |
| dm/ios/tools/touchrectv1_patch.json | 28 KB | 对原版手柄界面布局的一份改动描述,带原版布局里的控件名与数值 | 触屏界面是在原版布局上改出来的 |
| dm/data/casc_overlay/borrowed_paths.tsv | 2 KB | 6 条原版贴图的路径名 | 我们的新面板借用了这几张原版贴图 |
| dm/verify/logicself/*.json、dm/verify/touchcases/tests/fixture/、dm/verify/shotgate_pages/ | 共约 200 KB | 验证用基线:运行原版时逐拍记录的状态校验值、少量操作指令字节、各界面截图的比对规格 | 用来证明改写后的程序与原版行为一致 |
源码里的 main+0x… 地址(约 800 处,分布在 59 个文件里)与对应说明 |
— | 游戏主程序内部函数、数据结构的位置,及其作用描述 | 宿主与触屏层要在这些位置上与游戏对接;只对 3.3.94012 这一版成立 |
| dm/tools/patch_nso.py 里的改写规则 | — | 每条规则写着「原来的指令字 → 改成的指令字」 | 这就是改写器的工作内容 |
| 源码里点名的少量游戏内部名字 | — | 例如刷怪积分牌要认的约 70 个怪物的内部名、功能代码要找的物品与界面控件的键名 | 功能要靠这些名字找到对应的东西 |
下面按「图形构建链路」与「行为验证链路」两大用途分组深入。
图形构建链路:四张表让「翻译」与「预热」成为可能
这一组记录服务的是 dm/gfx/README.md 描述的离线着色器翻译链:Switch 着色器 → PC DXBC → PC 链 MSL(metallib)。
shader_map.tsv——谁是哪一个。 文件头注释(# kind: evidence Switch 着色器变体 → PC DXBC → PC 链 metallib)与生成脚本 dm/gfx/tools/shader_map.py 说明其依据:两侧 data/hd/shaders 各有 162 个同名 SHAD 包,每包一条 BTCD 记录,记录数逐包相等(共 10847 条),记录头除尺寸外只差平台号(PC 3 / Switch 5)、没有排列键,于是按包内序号一一对应。运行期游戏通过 nvnProgramSetShaders 拿到的是控制段指针,因此键取 sha256(控制段)[:16];PC 链缓存文件名则是 sha256(DXBC)[:16].metallib。表里每行记录 package / index / stage / dm_ctl_sha16 / pc_dxbc_sha16 / metallib / pc_outputs / dm_outputs / dm_ubo / dm_tex / dm_samp / dm_ssbo / subset_ok 等字段。值得注意的细节:键冲突有 15 例(同一 Switch 控制段对应多份 PC DXBC,文件头 # 键冲突…:15),选择规则写在该表注释里——与 Switch 实际用到的输出数 / cb / t / s 差异最小者,并列取最简、再并列取 DXBC 哈希最小(确定性),选择与理由同时写进同目录的 shader_map.tsv.conflicts.tsv。程序本体内嵌的着色器(不在包里)也有 10 个控制段,其中前 6 个图形着色器与 PC D2R.exe 内嵌的 6 个 DXBC 同序一一对应。
shader_facts.tsv——接口长什么样。 这是翻译查询的作答表(生成自 dm/gfx/tools/dmsh_facts.py 的 --freeze,文件头注明「勿手改」)。每行格式为「键 <TAB> 事实 JSON」,JSON 内含 attr(顶点属性槽)、fout(输出)、tex(贴图槽及类型)等字段,例如某条事实是 "tex":{"10":"2d",…,"34":"cube","45":"3d","48":"3d","8":"buffer"}——即该着色器用到的贴图槽 10 为 2D、34 为 cube、45/48 为 3D、8 为 buffer。文档点出它存在的关键理由:这些接口事实原本要从 PC 版游戏文件里查,而绝大多数玩家只有 Switch 版——所以项目把 PC 版里查到的答案固化成表带进仓库,让只有 Switch 文件的人也能完成翻译。
pso_manifest.tsv——渲染管线状态组合清单。 文件头注释称它为「预热种子清单」,行格式为 S<TAB>着色器键<TAB>阶段 / R<TAB>渲染管线键(pso_skey 十六进制)/ C<TAB>计算着色器键。它由 DM_PSO_RECORD 重录并按行去重而来:画面闸门 17 页主机 / 掌机各一轮,再加 cvd5 营地主机、掌机、局内两个方向切换各一局,并按行序(= 录制时的首次使用顺序)建预热管线,启动最先要用的最先就绪;真机追加了 102 行与 32 行(重场面「亡者大殿二层」等)的补充。这正是文档「启动时提前建好管线,免得第一次用到时卡顿」的实现落点。
names.txt 与 nvn_slots.tsv——宿主按名字接管图形接口。 names.txt 含 523 个函数名(nvnDeviceBuilderSetDefaults、nvnDeviceInitialize、nvnDeviceGetProcAddress…),nvn_slots.tsv 则是「main NVN 取址槽与静态调用点」(生成自 dm/gfx/tools/nvn_slots.py),记录每个函数名对应的取址槽地址(如 nvnDeviceBuilderSetDefaults → 槽 320e910)、使用次数与首次使用点。宿主图形层(dm/gfx/nvn/)就是按这些名字接管游戏调用的。而 dm/gfx/nvn/include/nvn.h 是这套接口的声明头——文件头注明第三方作品、MIT 许可、作者 h1k421,图形层照它实现。
行为验证链路:基线文件证明「改写后 = 原版」
这一组记录来自 dm/verify/,目标是把「改写后的程序与原版行为一致」变成可机器判定的命题:
- 逐拍状态校验值:dm/verify/logicself/touch.json 记录每一服务端拍(tick)下 5 类单位表与全局种子的 FNV-1a 64 校验值序列(JSON 里
ticks<a href="https://link.gitcode.com/i/14fc1049c6fc45cc6153e79daf91a544" target="_blank">].n与ticks[].h字段)。提取口径见 [dm/verify/oracle/swtick.py:每拍入口(Game.nss+0x5d3bc0)取 5 类单位表pGame+{0x2230,…,0x2e30},按(类型, id)排序后逐类哈希。同目录的3.3.94012-r23-touch.json表明基线按游戏版本与规则域组织。 - 操作指令字节:dm/verify/touchcases/tests/fixture/ 的
c2s.jsonl、state.jsonl、ticks.jsonl、uimsg.jsonl记录了回放用的客户端命令包(如{"tick":2,"unit":7,"len":2,"pkt":"1900"})与 UI 消息流,配合 dm/verify/README.md 与回归脚本 dm/verify/regress.sh 做脚本化走查回归。 - 界面截图比对规格:dm/verify/shotgate_pages/ 下 17 个页面(
charselect.json、inventory.json、stash.json、skilltree.json等)各含触发条件、视口、遮罩与比对区域定义(如选角页「OpenPanel:MainMenuButtonRibbon 后第 150 帧」、viewport<a href="https://link.gitcode.com/i/e0c64aa367462b5d51a0a3e5f223d927" target="_blank">0.21, 0.0, 1.0, 0.88]),配合截图闸门 [dm/verify/shotgate.py 使用。
这三类基线加起来约 200 KB,共同构成「画面、状态、指令流」三个层面的行为等价证明。项目 README 也强调:每次改动都必须通过回归闸门(make -C dm/host/tests run、make -C dm/gfx/tests run、dm/verify/regress.sh)。
触屏与界面侧:原版布局的「改动描述」与「贴图路径名」
touchrectv1_patch.json(28 KB)是对原版手柄界面布局的一份改动描述,带原版布局里的控件名与数值——触屏界面不是凭空画的,而是在原版布局基础上改出来的,改动本身作为记录随仓库携带。borrowed_paths.tsv(2 KB)记录 6 条原版贴图的路径名(如data/hd/global/ui/PANEL/HUD_02/BugBTN.sprite),供gen_romfs_overlay.py等工具在生成界面覆盖层时按路径借用。文件头注释解释了为什么要「借路径」:给原包 TVFS 路径表加新路径时游戏解析器会无限递归,所以先把新贴图写进没人读的旧路径;并给出了两条借路判据(① 在main/sdk/subsdk0的字符串里查不到该文件名;② 用带 1 MB 间隔的覆盖层跑三局,DM_FSLOG显示该窗口被读 0 次),以及「已借 / 可借 / 禁借」三种状态标注——注意表中有一条quest_button.sprite因「每局都被读」被标为禁借,说明这套借用机制是经过实测验证的。
main+0x… 地址:只对 3.3.94012 这一版成立
源码里散布约 800 处 main+0x… 地址,分布在 59 个文件,每处附有对函数 / 数据结构的文字说明。例如 patch_nso.py 第 637 行这类注释(obs.append((0x442bc0, 15, "a9ba6ffc", "client event-message entry …"))。它们是宿主与触屏层与游戏对接的落点,因此只对 3.3.94012 这一版本成立。与之配套,patch_nso.py 中所有规则表按 NSO 构建号(db0507f36b84200ac05f75d76ed5026f)限定,构建号不符会直接中止——这既是版本保证,也是「绝不静默产出坏包」的工程约束。
改写规则本体:patch_nso.py 与「原指令字」的三种角色
文档说「每条规则写着『原来的指令字 → 改成的指令字』」,本文从源码把「原指令字」拆出三种角色:
- 版本与位置核对:改写前逐条断言原字节(见上文第 241 行 assert),这是文档所述「核对确实是这一版、确实是这个位置」的直接实现。
- 改写器的工作清单:重写内容覆盖 x18 / tpidr_el0 / tpidrro_el0 的读写(改写为经
tpidrro_el0取线程槽)、svc #n与mrs cntpct_el0(改为宿主门,进 C 后按返回点查gates.tsv),以及按构建号限定的「剪口」(CUTS)与「观测门」(OBS)。每个剪口都带中文理由注释,例如:显存分配器预算 260 MB → 512 MB(对应 iPhone 高分辨率渲染目标)、离线放行窗口(30 天)、开场 Logo 与「按 A 开始」剪掉直达主菜单、Granny 段解码改走宿主libdeflate、进局出生点落在城镇小站旁等。 - 规则域区分:通过
DM_RULESET环境变量区分native(Mac 对原版真值的闸门域)与touch-run-v4(触屏版规则域),部分剪口标注「仅宿主」(真值模拟器不应用)。
关于离线运行的那 7 处改写:来源与边界
DERIVED.md 专门澄清:patch_nso.py 的改写规则里有 7 处的作用是让游戏不联网也能运行(原版在启动时会联网检查)。这 7 处的来源是:
取自社区已有的离线修复补丁(LFS Mod Offline Fix),不是本项目原创。 项目没有首发地或作者的确切记录,知道者可在仓库开 Issue,项目会补上署名。
源码侧(patch_nso.py 头注释)给出的细节与文档完全一致:该补丁「for v2228224,与官方 94012 main 只差这 7 个字」,即 7 处改动即可让网络检查放行;注释还补充了实测结论——系统服务层(nifm 无网 / DNS 黑洞 / 账号服务)绕不过去,因为游戏自己直接发 Battle.net 请求、按「上次在线」时间放行离线,所以必须在游戏本体层面改。其中一处典型实现是把只读字串 "User Last Online" 替换为 "VoiceLanguage"(第 64 行的 (0x1d53e80, …, '55736572204c617374204f6e6c696e6500', '566f6963654c616e676561676500000000', …)),并配合「当前时刻 − 上次在线 < 30 天」判断的 lt→gt 翻转,让差值恒超 30 天从而恒放行。
需要特别指出:本项目完全离线,不涉及联网对战。这些改动是让游戏能离线运行的必要工程,而不是任何形式的在线功能。
附录:如何核对本文引用
- 文档原文: docs/DERIVED.md(英文版)/ docs/DERIVED.zh-CN.md(中文版),项目首页对其的引用见 README.md。
- 配套的「游戏文件从哪来」: docs/GAME_FILES.md——本文所有「你机器上现做」的生成环节都需要先按该文档放置 Switch 版 1.0.34.0(对应 PC 3.3.94012)的
ExeFS(main/sdk/subsdk0,约 26 MB)与RomFS/data(约 8.4 GB)。 - 关键源码与数据: dm/tools/patch_nso.py、dm/gfx/tools/shader_map.py、dm/gfx/tools/dmsh_facts.py、dm/gfx/nvn/shader_map.tsv、dm/gfx/nvn/shader_facts.tsv、dm/gfx/nvn/pso_manifest.tsv、dm/gfx/nvn/names.txt、dm/gfx/nvn/nvn_slots.tsv、dm/gfx/nvn/include/nvn.h、dm/verify/oracle/swtick.py、dm/verify/logicself/touch.json、dm/verify/shotgate_pages/charselect.json。