[!TIP] 受众：想做或正在做 D2R mod 的开发者、想让 AI 帮你改 mod 的玩家、以及任何被"改了不显示、启动就闪退"折磨过的 D2R modder。 核心目标：把已验证的 D2R mod 制作经验固化为可复用标准，让你（和 AI）不再凭直觉翻车。 完整知识库：GitHub - d2r-modding-guide

为什么需要这套指南？

D2R mod 看起来就是改几个 json 文件——但实际藏着无数"凭直觉必翻车"的坑：

  • 改了物品名 → 进游戏还是原版 😤
  • 加了个彩色 loot 简称 → 暗金名字被染黄了 🤔
  • 重启游戏 → 卡"正在读取"4 分钟不动 💀
  • 启动 ~20 秒 → 毫无征兆闪退，没有日志 🫠
  • 特殊符号全变空白方块 □

这套指南把我亲自踩过的、验证过的规律固化成铁律，共 9 章 + 工具集。

三条最重要的铁律

入手 modding 之前先记住这三条，能避免 80% 的无谓排查：

  1. 改对文件：CN 客户端不同显示内容读不同文件——名字可能走 bnet.json、描述走 item-modifiers.json、其余走 item-names.json。改错文件 = 白改。
  2. 绝不猜代码/ID：物品代码反直觉（如无瑕宝石多数是 gl* 不是 gz*）；缺 id 字段会让游戏启动 ~20 秒后无日志闪退。永远从权威源 grep+提取。
  3. 每条字符串必须带 id，简中写 zhCN：国服客户端读 zhCN——“必须写 sgCN/bnCN 三字段"的说法已被实测推翻。原版数据里根本没有这两个字段。

知识库章节概览

01 · Mod 全景图

从零看懂一个 D2R mod 的全部内容。Mod 由三层结构组成：

层内容关键文件
文本层所有"文字”item-names.json、item-modifiers.json、bnet.json
UI 层界面/交互/HUD_profilehd.json、hudpanelhd.json
美术层字体/贴图/特效fonts/*.ttf、sprites/、overlays/
逻辑层数值与规则excel/*.txt

核心认知：Mod 的 <名字>.mpq 是文件夹，不是压缩包。改完 json 不需要重新打包，完全重启客户端即可生效。

02 · 铁律（动手前必读）

违反就翻车的硬规则：

  • 国服读取不是"只读某一个文件"：品质标签和部分宝石名被 bnet.json 抢显示，改 item-nameaffixes 无效时要查 bnet.json。
  • 简中字段就是 zhCN：旧说"CN 读 sgCN/bnCN"已被实证推翻。国服原版数据（CASC 提取）根本没有这两个字段。SU 系 mod 的 sgCN/bnCN 是防御性注入，不是必须。
  • 防闪退三大故障模式：缺 id 字段（~20s 无日志崩溃）、texture_desc_cache.json（卡"正在读取"）、引用国服和谐资产（DX12 DeviceLost）。

03 · 标准数据获取流程

永远不要凭记忆或直觉写物品代码。详细记录了：

  • 完整的物品代码/ID 对照表
  • 从 .txt 文件 grep 提取代码的标准操作
  • 反直觉怪癖（如无瑕宝石 gl*、完美宝石 gp* 等）

04 · 颜色语义 & 安全符号

D2R 文本颜色控制码全表（ÿc0 ~ ÿcM，含 DLC 新增色值），以及：

  • 颜色语义规范（符文统一橙、套装绿、暗金淡金…）
  • 字体安全符号白名单：不是所有 Unicode 符号都能在 D2R 自带的 AR 字体中显示
  • loot 简称染色的复用法则
  • 多行渗色修复：每行行首自带色码 + 行尾 ÿc0 封口

⚠️ ÿcT 被社区三表互抄误标为天蓝色，实际是回音室谬误。

05 ·《术士君临》DLC 参考

2026 年新 DLC 的系统性变更：

  • 新职业「术士」及其技能/符文之语
  • 魔典系统与新增物品体系
  • 适配新版本的注意事项

06 · 国服完全指南（最重要的实战章）

国服(bnCN) modding 的所有坑都在这：

  • 三大故障模式精确归因：卡"正在读取"/20s 无日志闪退/DX12 DeviceLost
  • 被纠正的错误结论：sgCN/bnCN 回音室谬误的完整翻案过程
  • 国服和谐机制：运行时按字符串 Key 拦截，不是数据字段层
  • 文件安全表：哪些文件可以改、哪些改了必炸
  • 国际 → 国服转换 SOP

07 · UI 手册

面板/HUD/按钮/消息路由的全部细节：

  • 面板注册真相：_profilehd.json 是面板注册总表
  • 消息路由机制
  • Widget 与 Panel 的区别
  • 信息展示与覆盖特效
  • 多 mod 兼容性：多个 mod 同装时谁生效

08 · 从零搭建新 Mod

最小可用的 mod 骨架，包含完整的目录结构、modinfo.json 模板、启动参数、字符串面板自动注册方法、验证清单。15 分钟搭建一个能进游戏、不崩溃、中文正确显示的空白 mod。

09 · 游戏机制参考

FCR/FHR 断点表、打孔规则、超强物品机制、CB/DS/破免概率——支撑 loot 染色和平衡决策的数据基础。

写入纪律（防回音室）

这套指南经历过两次"未验证结论被当铁律转抄"的事故，因此建立了严格的写入纪律：

  • 任何"铁律"必须指向原始证据：截图或 vanilla 提取件。指不出 = 标"待验证"。
  • 社区资料仅在数字码层面可参考；字母色码、新版本特性以游戏实测为唯一权威。
  • 参考 mod 不等于 vanilla：引用为官方证据前，必须回到 CASC 原版提取件核对。
  • 每条结论标证据级：✅游戏实测 / 🔬生产性实证 / 📐文件结构事实 / ⚠️未验证（禁产）。

适用声明

  • 面向 D2R 国服（NetEase/bnCN）+ 国际版 双端，重点在国服特殊性
  • 知识来自实战验证（截至 2026-06），D2R 版本含 3.x《术士君临》
  • 本库是通用知识，不含任何本机路径或私有信息，可直接同步分享

获取完整知识库

全套 9 章 + 工具脚本，永远开源免费：

→ GitHub: d2r-modding-guide

无论是否捐助，欢迎提 Issue / PR 一起把这套知识补得更全——把你踩过的坑也留给下一个人，就是最好的回馈。