d2r-mobile 参与开发指南:从测试闸门、三条代码规矩到提交流程的完整实操手册
d2r-mobile 参与开发指南:从测试闸门、三条代码规矩到提交流程的完整实操手册
本篇指南围绕 d2r-mobile 仓库的 CONTRIBUTING.zh-CN.md 展开,面向想要为这个 iOS / macOS 兼容层项目提交代码的开发者。你将掌握:改动代码前必须跑通的完整测试矩阵(含不需要游戏文件的静态闸门与需要游戏文件的重型回归)、仓库对「不提交游戏内容、注释中英双语、屏上文字进中英表」三条规矩的底层实现与执行依据,以及符合规范的提交说明与问题报告格式。文中所有命令均在仓库根目录执行,每项检查都配有对应的源码与测试依据。
改动之前:先跑通测试,再谈改代码
d2r-mobile 把「可验证性」当成项目的头等大事:玩家看到的不是模拟器,而是被改写后原生执行的 Switch 版游戏程序,因此每一次改动都可能影响与原版的行为一致性。仓库的测试体系分两档——不需要游戏文件的静态检查,以及需要游戏文件与备好工作区的重型验证。参与开发的第一步,就是先在未改动的代码上把能跑的都跑通,改完再跑一遍。
不需要游戏文件的检查:两条文字闸门
这两条命令只读源码,有 python3 就能跑,是所有贡献者最低的门槛:
| 命令 | 验什么 |
|---|---|
python3 dm/i18n/scan_literals.py |
字面量闸门:玩家看得到的中文有没有绕过中英表,详见 dm/i18n/README.zh-CN.md |
python3 dm/ios/tools/dm_i18n.py --check |
中英表 dm/i18n/ui_text.tsv 每一行合不合规则,入库的 dm/host/dm_i18n_tab.h 是不是由当前的表生成的 |
第一条 scan_literals.py 是 i18n 体系的核心闸门。从源码(dm/i18n/scan_literals.py)可以看到它的工作方式:
- 扫描范围:
C_FILES覆盖dm/host/*.c、dm/host/*.m、dm/ios/Sources/*.m、dm/ios/Sources/*.c;PY_FILES覆盖会把内容写进游戏的布局与素材生成脚本(touch_layout.py、wide_stash.py、pouch_layout.py、gen_romfs_overlay.py、gen_hud_v4.py、touch_strings.py等)。脚本头注释明确说明:新加这类脚本时要把它加进PY_FILES,否则闸门扫不到。 - 豁免规则:注释、Python 文档串、以及最内层调用是
SINK名单里函数(LOG、NSLog、fprintf、printf、die、print、dm_log、boot_log、各类断言与异常)的字面量——因为它们只进日志、报错,不上屏。 - 判定:剩下的每一条中文字面量都必须在白名单 dm/i18n/literal_whitelist.tsv 里有一行,否则报红。白名单「匹配」列有四种写法:一段文字、
=加整个字面量(完全相等)、@加函数名(最内层调用)、*(整个文件)。 - 结果:通过时打印
I18N OK:中文字面量 N 条全在白名单(M 行),其余走中英表;不通过则以I18N 红开头逐条列出文件、行号与字面量。--list参数可列出全部命中与最内层调用,供写白名单时参考。
第二条 dm_i18n.py --check 核对两件事:表里每一行是否符合规则(键以 dm 开头、只能字母数字、占位符中英个数与顺序一致、EN_LIMITS 英文字数上限等),以及 dm/host/dm_i18n_tab.h 是否由当前表生成。通过时打印 dm_i18n OK <条数> 条,头文件过期时它直接给出重出的命令。
需要游戏文件与备好的工作区:重型测试套件
前提:你自己的游戏文件已放到位,./setup.sh 已跑完(它建好 Python 环境、出好改写产物、翻译好着色器),并且已经进入那个 Python 环境:
source ~/dm-work/build/cache/dm/venv/bin/activate
(设了 DM_ROOT 就把 ~/dm-work 换成它。缺什么用 ./setup.sh check 查。)
完整测试矩阵如下:
| 命令 | 验什么 | 额外前提 |
|---|---|---|
make -C dm/host/tests run |
宿主单元测试。同时跑上面两条文字检查,以及两条只读源码的扫描:不许写原版界面控件(native_write_scan.py)、触屏 / 手柄两种模式的登记(mode_scan.py) |
其中几项直接读游戏的程序文件与资源目录 |
make -C dm/gfx/tests run |
图形层单元测试,在本机的 Metal 上真跑 | 其中几项读 ./setup.sh 翻译出的着色器缓存 |
make -C dm/ios/tests test |
触摸判定、技能绑定解析等 iOS 外壳的单元测试,不需要设备,也不启动 App | 技能索引不进仓库,缺了会从游戏文件现生成 |
dm/verify/regress.sh |
改写等价回归:改写器的输出结构对不对,每一处改写与原指令行为是否一致,宿主门功能是否正常。末行 REGRESS OK 或 REGRESS FAIL |
llvm-objdump 与 llvm-objcopy,目录用 LLVM_BIN 指定 |
cd dm/ios && ./run.sh build |
iOS 包能不能编出来(只构建,不碰设备) | Xcode,dm/ios/local.env 里的签名配置 |
dm/ios/tools/smoke_mac.sh 1 |
冒烟:把 iOS 包放在 Mac 上真起一遍,读档进局、有声音、日志里没有带「【红】」的行。末行 SMOKE-MAC OK 或 SMOKE-MAC RED |
先跑一次 dm/ios/tools/make_fixture.sh 生成冒烟存档 |
dm/ios/tools/check_hud_gen.sh |
由游戏文件生成的东西有没有被加进 git;本机有游戏文件时再把底部界面实际生成一遍 | 在 git 仓库里执行 |
宿主单测的构成:make -C dm/host/tests run 的依赖与执行顺序写在 dm/host/tests/Makefile 里。run 目标先编出 main.orig.bin、subsdk0.orig.bin(用 nso.py 从 $DM_ROOT/data/switch/3.3.94012/Update/ExeFS 解出),再依次编出 t_altstack、t_audio、t_fs、t_hid_receipt、t_i18n、t_rift_clock、t_textbox、t_touch、t_widget 等三十余个测试程序,最后执行四条只读扫描:
python3 native_write_scan.py --selftest ..
python3 mode_scan.py ../..
python3 ../../ios/tools/dm_i18n.py --check
python3 ../../i18n/scan_literals.py
注意 t_i18n 会按 en zh none sysen systw tags game 七种语言模式各跑一遍,t_audio / t_condvar 等编译时链接 AudioToolbox 或注入 DM_TEST_HOOKS 宏,说明宿主测试是对真实系统框架与游戏程序文件(main、subsdk0)的深度验证。
改写等价回归的内部结构:dm/verify/regress.sh 依次跑三样东西(源码):
| 工具 | 验什么 |
|---|---|
structck.py |
结构核对,不执行代码,逐字核对改写器的输出:除登记过的剪口外,非代码段与原映像逐字节相同;代码段里被改的字恰好是登记的改写点;用独立反汇编器(llvm-objdump)重数一遍该改的指令,一条不漏、一条不多;补丁区里不再出现原来不能执行的指令;每个宿主门、参数门、观测门的字节等于模板,并与门表一一对上 |
equiv.py |
逐处等价:用 Unicorn(CPU 模拟库)对每一处改写,以多组随机状态分别执行「原指令」与「补丁块」,比较全部通用寄存器与向量寄存器、标志位、栈指针、内存写入、结束地址与访存异常。带变异自检:故意把一批补丁块改坏,必须全部被判出不等价 |
gatefn/ |
门功能:用宿主现行的 dm/host/entry.S 现编一个测试台,逐个门执行,核对寄存器回写的约定 |
--struct-only:只跑结构核对与门功能,不跑equiv.py(给touch出包产物用,因等价试验与keypage共用改写路径)。--fresh:先用本工作树的改写器重出一份到$DM_ROOT/run/verify/dm/fresh/再验,并与给定目录逐文件比对——改过改写器dm/tools/patch_nso.py时必须用这个选项,用来发现共用的产物是否过期。- 环境变量:
DM_PY、DM_NSO_DIR(缺省$DM_ROOT/data/switch/3.3.94012/Update/ExeFS)、SEED、JOBS、LLVM_BIN(缺省/opt/homebrew/opt/llvm@23/bin,不存在时设LLVM_BIN=$(brew --prefix llvm)/bin)。 - 输出:末尾一张汇总表,每个模块「结构」「等价」各一行;末行
REGRESS OK|FAIL <产物名>,任何一项失败退出码 1。日志在$DM_ROOT/run/verify/dm/regress_<时刻>.log。
冒烟测试的判据:smoke_mac.sh 是在 Apple 芯片 Mac 上把 iOS 包真起一遍——读档进局 N 次 + 玩家路径一局(真出声、读得到玩家状态、无红线)+ 触摸玩家路径一局(只用触点脚本建角进局)。末行 SMOKE-MAC OK <成功数>/<次数> 或 SMOKE-MAC RED …。判据、可调变量(SMOKE_KEYS、SMOKE_PLAYER=0、SMOKE_TOUCH=0 等)详见 dm/ios/README.zh-CN.md 的冒烟一节。
你跑不了的那部分:依赖真值的整套验收
整套验收 dm/verify/accept.sh 里的存档对拍、画面闸门、逻辑闸门要用「真值数据」——原版游戏的运行记录。这些数据不在仓库里,也不会放进来;录制它们用的模拟器驱动脚本同样不随仓库提供。
真值来自打了几处补丁的 Ryujinx 模拟器跑原版游戏:让它能直接加载解包的游戏目录、能被脚本喂按键与截图、能在指定位置读出游戏内部状态(逐拍状态 ticks.jsonl、命令包 c2s.jsonl、UI 消息 uimsg.jsonl、meta.json、save_after/ 存档、shots/ 截图)。仓库里只留下读取这一侧的最小部件 dm/verify/oracle/swgdb.py、swtick.py,以及三种记录文件的格式说明(tick_state_format.zh-CN.md、command_packet_format.zh-CN.md、ui_message_stream.zh-CN.md)。
accept.sh 会串起 bootchk.sh(启动块清单)、regress.sh(改写等价)、host_savecmp.sh(存档逐字节对拍)、rulegate.sh(规则闸门)、logicself.sh(逻辑自比基线)、shotgate.sh(画面闸门,共 17 页,规格见 screenshot_gate.zh-CN.md)、三个单测套件、iOS 构建、touchchain.sh 触屏用例等十余项,--fast 与 --full 两档,任一项红即整体红。它还按改动范围自动少跑(只动 dm/ios 与文档时只跑启动块清单与 iOS 构建),ACCEPT_ALL=1 可强制全量。所以对贡献者来说:提交改动时写明你实际跑了哪些、结果如何;没跑的直接说没跑,这是仓库明确要求的诚实约定。
三条规矩
规矩一:不提交游戏内容
仓库不含、也不分发任何游戏内容:游戏程序、美术、文字、着色器、存档,以及由它们生成的图、表、代码,都不进仓库。这些东西在每个人自己的机器上、用自己的游戏文件现做出来。
仓库里带着的是为适配而记录的接口信息——着色器的接口描述、图形接口函数表、程序内的地址等,逐项列在 docs/DERIVED.zh-CN.md。例如 dm/gfx/nvn/shader_map.tsv(原版每个着色器变体的编号与校验值)、shader_facts.tsv(每个着色器的接口描述)、nvn_slots.tsv(主机图形接口 523 个函数名及存放位置)、patch_nso.py 里的改写规则(每条写着「原来的指令字 → 改成的指令字」,原指令字用来核对版本与位置)。DERIVED 文档还特别说明:导出公开仓库时有一道工具拿真实的游戏文件到整棵树里逐字节搜一遍,搜到就不放行——这是硬性门禁,不只是约定。
下面这些是构建时生成的,已经写在各目录的 .gitignore 里,不要强行加进来:
| 位置 | 是什么 |
|---|---|
dm/host/dm_vault_tab.h、dm/host/dm_hud_exp.h、dm/host/dm_bright_levels.inc |
由游戏的数据表生成的表头(dm/host/Makefile 构建时生成) |
dm/ios/Gen/ |
iOS 包的生成物:由游戏文件做出的界面图、内嵌的游戏程序、覆盖层 |
dm/ios/Sources/TouchArt/dm_native_*.png、dm/ios/Sources/dm_touch_native_art.c |
技能图集与技能索引 |
dm/ios/DmIOS.xcodeproj/、dm/ios/Sources/Info.plist、dm/ios/Sources/DmIOS.entitlements、dm/ios/RomfsDownloader/ 下的 Info.plist 与 RomfsDownloader.entitlements |
由 dm/ios/project.yml 生成的工程与配置 |
dm/ios/local.env |
你自己的签名配置 |
dm/host/dmhost、*.dSYM/、*.bin、*.pkl、__pycache__/、各 tests/ 下编出的测试程序 |
编译产物与中间文件 |
.iosdd/、.iosdd_mac/、.iosdd_*/ |
Xcode 的派生数据目录 |
另有三个文件在仓库里,但 ./setup.sh 会按你本机的工具改写它们:dm/gfx/tools/dmsh_chain.lock、dm/gfx/nvn/dmsh_chain.h、dm/gfx/nvn/c1_full.tsv。这是预期的,不要提交这些改动。工作区 $DM_ROOT(缺省 ~/dm-work)下的东西——游戏文件、改写产物、缓存、运行日志——都在仓库之外,本来就不会进来。
报问题和提改动时同样:不贴游戏文件、密钥,不上传自己做出来的安装包(安装包内含游戏内容,带这些内容的问题会被直接删除)。
规矩二:注释中英双语
代码里的注释都是中文、英文各一份,内容相同。现有两种写法,照现有的写:
-
文件开头和成段的注释:先写中文各行,紧接着写英文各行。例如 dm/host/dm_i18n.c 的文件头注释,先是中文的「我们自己加的界面文字取串(英文版:语言跟原版设置走……)」整段,紧接着是英文的
String lookup for the UI text we added ourselves (English version: ...)整段,内容一一对应。 -
行尾注释,以及 Python 文档串里的单行:同一行里中文在前、英文在后,中间用
|隔开。实际例子散落在各源码中,如:int dm_lang_zh(void); // 1 = 我们的字用中文 | 1 = our text uses Chinese// 语言开关(键 lang_en)在设置文件里写着的值:-1 没写过(不动原版设置)/ 0 简中 / 1 英文;hle_fs.c 挂存档时读 | Value of the language switch (key lang_en) as written in the settings file: -1 never written (original settings left alone) / 0 Simplified Chinese / 1 English; read by hle_fs.c at save mount
每个源文件开头有一段注释,说明它做什么、依据是什么;dm/host 里的功能文件还写明用到游戏程序里的哪些地址(都是 3.3.94012 原映像的偏移,约 800 处分布在 59 个文件里,见 docs/DERIVED.zh-CN.md)。新文件照此写。说明文档同样中英各一份:README.md 是英文,README.zh-CN.md 是中文。dm/third_party/ 下是别人的代码,保持上游原样,不适用这一条。
规矩三:屏上新增的文字进中英表
玩家看得到的、我们自己加的文字,一律登记在 dm/i18n/ui_text.tsv(键 / 中文 / English / 用在哪),代码里只写键,不写字面量。这张表是「我们加的界面文字的唯一来源」,实际内容如:
键 中文 English 用在哪
dmPauseRestart 一键重开 Quick Restart 暂停菜单按钮(touch_layout.py)
dmVaultStored 存着 Stored 编年史格子下的状态(dm_vault_ui.c)
读表的是 dm/ios/tools/dm_i18n.py,它用表做两件事:游戏里画的字(构建覆盖层时把每一行追加进游戏的字符串表,布局里写 @键,宿主里用 dm_str 按键取)与游戏外画的字(生成 dm/host/dm_i18n_tab.h 编进程序,用 dm_ui 按键取,接口在 dm/host/dm_i18n.h)。
加一条文字的标准步骤(详见 dm/i18n/README.zh-CN.md):
-
在
ui_text.tsv里加一行,四列都填。表头规则由dm_i18n.py把关:键以dm开头、后面只能字母数字(下划线会让布局里的@键断开)、不能与游戏原有键重名;中英都不能空、英文里不能有中文字符;占位符(%d、%s)中英两列必须个数、顺序、类型相同;要换行写\n两个字符;秘境面板、秘境提示等部分键有英文字数上限(上限表是dm_i18n.py里的EN_LIMITS)。 -
重出生成头文件,并把它和表一起提交:
python3 dm/ios/tools/dm_i18n.py --header > dm/host/dm_i18n_tab.h -
在代码里用键,不写字面量:布局脚本里写
@键;宿主里游戏内的字用dm_str(main_base, "键"),游戏外的字用dm_ui("键")。 -
跑两条检查(即第一节的两条静态闸门)。
字面量闸门的边界:它只认含中文的字面量,直接写死的英文它拦不住,同样要进表。只进日志、不上屏的中文不用进表,但要在 literal_whitelist.tsv 里登记理由——例如 host/crash.c 的白名单行写的是「崩溃与看门狗现场,只进日志」,host/front_mac.m 是「Mac 开发宿主窗口,不进 iOS 产品」。白名单里不再匹配到任何字面量的行同样报红,要删掉(防止过期)。
提交改动
提交时遵循四条:
- 说明里写清改了什么、为什么。
- 写明跑了上面哪些测试、结果如何。
- 屏上有可见变化的,附改动后的截图。
- 确认没有带进任何游戏内容。
仓库的提交模板会列出这几项。实用的自查顺序是:先在未改动的代码上把两条静态闸门和能跑的测试跑通(建立基线)→ 改代码 → 再跑一遍对比 → 改了 patch_nso.py 就用 dm/verify/regress.sh --fresh → 屏上文字变动就重出 dm_i18n_tab.h 并跑 dm_i18n.py --check 与 scan_literals.py → 最后写提交说明并逐项核对上述四条。
报问题
用 Issue 模板。要附的东西:
- 哪一步出的问题:准备游戏文件、
./setup.sh、./run.sh build、不用 Xcode 的工具、装机、启动,还是游戏里。这一步定位很关键,因为工具链各环节(改写、翻译着色器、生成资源、签名)的前提各不相同。 - 你的环境:电脑与系统、Xcode 版本、手机型号与系统版本、签名用的账号类型(付费 / 免费 / 自签工具)、仓库的提交号。
./setup.sh check的完整输出。这个命令是「体检」:逐项报告这台电脑、工具、游戏文件、签名配置的状态,缺的每一项都给出去哪拿和下一步命令,不做任何改动。附上它能让维护者快速判断是不是环境问题。- 发生了什么:报错原文、屏上看到的字、能复现的步骤。
- 日志:游戏里暂停菜单 →「分享诊断日志」导出的文件。贴之前看一眼,去掉不想公开的东西(设备名、文件路径里的用户名)。
两条红线:不要贴游戏文件、密钥,也不要贴它们的下载地址;不要上传你做出来的安装包(里面有游戏内容)。带这些内容的问题会被直接删除。「怎么拿到游戏文件」这一步项目方帮不了——那要用你自己的主机和你自己买的游戏。
小结:贡献流程一图流
参与 d2r-mobile 开发的完整链路可以概括为:环境就绪(游戏文件放到位 + ./setup.sh 跑完 + 进入 venv)→ 静态闸门(scan_literals.py + dm_i18n.py --check,无需游戏文件)→ 重型回归(宿主单测、图形层单测、iOS 单测、regress.sh 改写等价、iOS 构建、Mac 冒烟、check_hud_gen.sh,视改动范围取舍)→ 遵守三条规矩(不提交游戏内容、双语注释、新文字进中英表)→ 如实写明测试结果并提交。这套流程的每一个环节都在仓库里有对应的可执行脚本与可核对的判据,这也是项目「稳定不是靠运气」的工程基石——相关细节可继续阅读 dm/verify/README.zh-CN.md(各项判据、输出位置与环境变量)、dm/README.zh-CN.md(宿主各文件与常用命令)与 dm/ios/README.zh-CN.md(出包、冒烟与单测)。