Arknights Text Mod Guide

明日方舟文本替换 Mod 配置说明

这份文档面向文本 Mod 作者，说明 mod.ini 的字段含义、分组 .txt 的写法、文本 dump 的使用方式，以及剧情、语音文案与档案文本的替换规则。 实际制作时，通常只需要先 dump、再修改 dump 出来的文件、最后配好对应的 mod.ini 即可。

推荐结论

  • 先用 Ctrl+T 开启文本 dump，再打开对应界面，让程序自动把文本分组导出来。
  • 一个文本 Mod 目录只放一种 text_type，不要把剧情、语音、档案混在同一个 mod.ini 里。
  • 发布给别人时，优先保持 text_root 和 [map] 都使用相对路径。

注意事项

  • 当前文本替换配置按 INI 风格解析，不是完整 TOML。
  • 替换文件只支持 UTF-8 文本 .txt 分组文件。
  • src 既是参考原文，也可在开启源文本校验时参与匹配验证。

1. 推荐目录结构

建议把不同类型的文本拆成独立 Mod 目录，每个目录只保留一个 mod.ini 和一种 text_type。直接基于 dump 结果制作时，最省事的做法就是把 dump 出来的子目录和文件名一并保留下来。

mods/
├─ StoryText_Grani/
│  ├─ mod.ini
│  └─ text/
│     └─ story/
│        └─ activities_a001_level_a001_01_beg.txt
├─ VoiceText_Amiya/
│  ├─ mod.ini
│  └─ text/
│     └─ voice/
│        └─ char_002_amiya.txt
└─ ArchiveText_Amiya/
   ├─ mod.ini
   └─ text/
      └─ archive/
         └─ char_002_amiya.txt
同一个 mod.ini 只能声明一个 text_type。如果同时需要做剧情、语音和档案文本，请拆成多个文本 Mod 目录。

2. 不同类型文本的 mod.ini 规范

三种文本类型的基础字段是一致的，核心区别主要在 text_type。建议每种类型单独建立一个文本 Mod。

2.1 剧情文本 story

[mod]
type = text
text_type = story
text_root = text
auto_map_by_stem = true
priority = 0

如果剧情文件名和故事分组名不一致，也可以显式写 [map]：

[mod]
type = text
text_type = story
text_root = text
auto_map_by_stem = false
priority = 10

[map]
activities_a001_level_a001_01_beg = 自定义剧情文本.txt

剧情文本这样写是可以的：左边使用 dump 文件主名 activities_a001_level_a001_01_beg，右边指向你自己的文本文件。 只要文本文件里保留 dump 头部的 # group = activities/a001/level_a001_01_beg， 程序就会按文件头里的真实剧情分组去匹配。

2.2 语音文本 voice

[mod]
type = text
text_type = voice
text_root = text
auto_map_by_stem = true
priority = 0

如果你想手动指定某个文本文件，也可以这样写：

[mod]
type = text
text_type = voice
text_root = text
auto_map_by_stem = false
priority = 0

[map]
char_002_amiya = 自定义语音文本.txt

语音文本也推荐这样写：左边使用 dump 文件主名 char_002_amiya，右边指向你自己的文本文件。 实际命中仍然看文件里的 char_word_id，所以最稳妥的方式仍然是直接从 dump 文件改起。

对于 voice 类型，[map] 左边的名字更像“文件分组标签”。 实际命中仍然由文件内的 char_word_id 决定，所以请以 dump 结果中的 char_word_id 为准。

2.3 档案文本 archive

[mod]
type = text
text_type = archive
text_root = text
auto_map_by_stem = true
priority = 0

如果档案文件名和档案分组名不一致，可以这样手动映射：

[mod]
type = text
text_type = archive
text_root = text
auto_map_by_stem = false
priority = 5

[map]
char_002_amiya = 自定义档案文本.txt

档案文本同样推荐这样写：左边使用 dump 文件主名 char_002_amiya，右边写你自己的文本文件名。 只要文件里保留 dump 生成的 bar、entry、role 等字段，就能正常匹配。

大多数情况下，作者只需要把 dump 生成的文件复制出来，创建一个对应类型的 mod.ini，然后修改文件里的 text 内容即可开始制作文本 Mod。

3. 字段说明

type
固定写 text，表示这是文本替换配置。
text_type
补充：当前还支持 direct_match。它不依赖剧情命令、语音 id 或档案条目身份，而是在最终显示阶段按文本内容直接匹配替换。
文本类型。当前支持 story、voice、archive、direct_match。 其中 voice 实际覆盖的是首页看板与预览相关的语音文案文本，direct_match 用于最终显示文本的直接匹配替换。
text_root
文本文件扫描目录。通常写成 text，表示扫描当前 Mod 目录下的 text 文件夹。也兼容写作 scan_root。
auto_map_by_stem
是否按文件名主干自动建组。开启后会递归扫描 text_root 下所有 .txt 文件，并使用文件名主干作为默认分组 key。
priority
冲突优先级。多个文本 Mod 命中同一条 key 时，优先级更高的条目会覆盖更低的条目。
match_mode
仅对 text_type = direct_match 生效。支持 strict 和 contains。strict 要求整段文本与 src 完全一致；contains 会把当前显示文本里命中的 src 子串替换为 text。
[map]
补充：对 direct_match 来说，[map] 左侧 key 只作为文件标签，真正参与匹配的是文件里的 src 与 match_mode。
手动映射表。作者使用时可以统一理解为“左边写 dump 文件主名，右边写你自己的文本文件”。 对于 story，如果文件头里保留了 dump 的 # group，程序会按文件头里的真实剧情组匹配； 对于 voice，实际匹配仍以文件内的 char_word_id 为准； 对于 archive，则依赖文件里的 bar、entry、role 等字段。

4. 分组文本文件格式

文本替换文件使用分组 .txt 格式，每个文件可包含一个或多个 [entry]。

# Arknight Mod grouped text dump
# bucket = story
# group = activities/a001/level_a001_01_beg

[entry]
cmd = dialog@18[content]
src <<<
这女人，还不肯说吗？
>>>
text <<<
这女人，还不肯说吗？
>>>

[entry]
cmd = dialog@18[name]
src <<<
赏金猎人
>>>
text <<<
赏金猎人
>>>

通用字段说明如下：

剧情文本文件可以在头部保留 # group = activities/a001/level_a001_01_beg 这类分组信息。最稳妥的做法是直接沿用 dump 生成的文件名和头部字段，只改 text 块里的内容，不要手工改出新的 group 规则。

5. 剧情文本示例

text_type = story 主要用于 AVG / 剧情对白替换。关键身份字段是 cmd。下面示例来自 dump\text\story\activities_a001_level_a001_01_beg.txt。

[mod]
type = text
text_type = story
text_root = text
auto_map_by_stem = true
priority = 0
# bucket = story
# group = activities/a001/level_a001_01_beg

[entry]
cmd = dialog@109[content]
src <<<
好了，他们一时半会还醒不过来，我们赶紧离开这里。
>>>
text <<<
好了，他们暂时醒不过来，我们先离开这里。
>>>

[entry]
cmd = dialog@158[name]
src <<<
格拉尼
>>>
text <<<
格拉尼
>>>

[entry]
cmd = dialog@158[content]
src <<<
嘿~！
>>>
text <<<
嘿，走吧！
>>>

剧情文本通常会在下一次文本触发时使用最新内容。热刷新后不会倒回已经播完的当前句。

6. 语音文本示例

text_type = voice 用于首页语音文案和部分预览文本。实际匹配的核心字段是 char_word_id。下面示例来自 dump\text\voice\char_002_amiya.txt。

[mod]
type = text
text_type = voice
text_root = text
auto_map_by_stem = true
priority = 0
# bucket = voice
# group = char_002_amiya

[entry]
char_word_id = char_002_amiya_CN_001
voice_id = CN_001
word_key = char_002_amiya
char_id = char_002_amiya
src <<<
博士，您工作辛苦了。
>>>
text <<<
博士，您辛苦了。
>>>

[entry]
char_word_id = char_002_amiya_CN_042
voice_id = CN_042
word_key = char_002_amiya
char_id = char_002_amiya
src <<<
欢迎回家，博士！
>>>
text <<<
欢迎回来，博士！
>>>
voice_id、word_key、char_id 更像是辅助参考信息。 当前文本匹配的主键仍然是 char_word_id，所以做首页文本时请以 dump 结果里的 char_word_id 为准。

7. 档案文本示例

text_type = archive 用于档案页面文本。关键字段通常包括 bar、entry、role。下面示例来自 dump\text\archive\char_002_amiya.txt。

[mod]
type = text
text_type = archive
text_root = text
auto_map_by_stem = true
priority = 0
# bucket = archive
# group = char_002_amiya

[entry]
bar = 0
entry = 0
role = title
entry_title = 基础档案
src <<<
基础档案
>>>
text <<<
基础档案
>>>

[entry]
bar = 0
entry = 0
role = detail
entry_title = 基础档案
src <<<
【代号】阿米娅
【性别】女
【战斗经验】三年
【出身地】雷姆必拓
【生日】12月23日
【种族】卡特斯/奇美拉
【身高】142cm
【矿石病感染情况】
体表有源石结晶分布，参照医学检测报告，确认为感染者。
>>>
text <<<
【代号】阿米娅
【性别】女
【战斗经验】三年
【出身地】雷姆必拓
【生日】12月23日
【种族】卡特斯/奇美拉
【身高】142cm
【矿石病感染情况】
体表有源石结晶分布，参照医学检测报告，确认为感染者。
>>>

8. 文本 dump 与热刷新

文本 Mod 的推荐工作流是：

文本 dump 默认写入 config.ini 中 dump_dir 对应的目录下。 例如配置里你设置了 mod 目录为 mod_base_dir = C:\Users\xxx\game\Arknight\mod， dump_dir = dump，因此文本 dump 的默认实际目录就是 C:\Users\xxx\game\Arknight\mod\dump\text。 

C:\Users\xxx\game\Arknight\mod
└─ dump
   └─ text
      ├─ archive
      │  └─ char_002_amiya.txt
      ├─ story
      │  └─ activities_a001_level_a001_01_beg.txt
      └─ voice
         └─ char_002_amiya.txt
文本 dump 开启后的游戏内提示图
按下 Ctrl+T 后，游戏内会出现类似上图的提示。看到提示后，直接打开对应界面即可自动开始 dump 当前命中的文本，默认会写进配置的 dump_dir 下的 text 目录。
文本替换均建议直接基于 dump 结果制作，因为对应的字段较多，手工猜测 char_word_id、bar、entry 很容易写错。对作者来说，最省事的流程就是“Ctrl+T 开启 dump -> 打开对应界面 -> 修改 dump 文件 -> 配好 mod.ini”。

8.1 直接文本匹配示例

text_type = direct_match 适合做最终显示文本的直接替换。它走的是最终显示入口，不依赖剧情/语音/档案上下文，因此更适合零散 UI 文案、按钮文本、提示文本等。

[mod]
type = text
text_type = direct_match
text_root = text
auto_map_by_stem = true
priority = 0
[entry]
match_mode = strict
src <<<
公开招募
>>>
text <<<
公开招募·改
>>>

[entry]
match_mode = contains
src <<<
理智
>>>
text <<<
Sanity
>>>
strict 表示整段文本必须完全一致才替换；contains 表示只要当前显示文本里包含 src，就会把命中的子串替换成 text。为了避免误伤，推荐优先使用 strict。

9. 常见问题

Q：为什么我把文件放进 text 目录后没有生效？

A：先检查 mod.ini 里的 type = text 和 text_type 是否写对，再确认文件扩展名是 .txt，并且条目身份字段来自实际 dump 结果。

Q：src 和 text 有什么区别？

A：text 才是最终替换文本；src 是原文参考。若全局开启 text_source_validation = true，程序还会用 src 去校验当前原文是否匹配。

Q：我可以把剧情、语音、档案全写进一个文本 Mod 吗？

A：不推荐。当前一个 mod.ini 只对应一个 text_type，最好拆成多个文本 Mod 目录分别维护。

Q：auto_map_by_stem = false 时会怎样？

A：不会再按文件名自动建组，只有 [map] 中显式列出的文件会被读取。

Q：同一条文本被多个 Mod 同时替换时谁生效？

A：优先级更高的 priority 会优先生效。若优先级相同，通常建议避免不同 Mod 对同一 key 重复覆盖。

当前文档适用于本项目现有的文本替换实现。若后续新增独立文本说明页、扩展字段或调整 dump 格式，本文档也应同步更新。