NPC 对话数据

对话文件定义文字、选项与动作，NPC 解析器决定打开哪个文件。文件位置与回退顺序也是格式的一部分；文件即使有效，也可能被更具体的路由覆盖而始终不被选中。

文件位置

使用 data/<namespace>/blabber/blabber_dialogues/<path>.json。对话 ID 为 <namespace>:<path>，不含注册表文件夹或扩展名。NPC 自动查找在 isekaiexpansion 命名空间下构造 ID；其他命名空间可通过显式引用使用，不参与自动路径回退。

整合包固定使用 Blabber 0.5.1-build36。基础对话格式由该依赖提供，下述约定已对照本地 Blabber 源码与模组自带数据核对。上游 schema 提示不保证覆盖所有本地扩展。

NPC 查找路径

NPC 类型词元由完整实体 ID 生成：转小写，将连续非字母数字字符替换为下划线，再去掉两端下划线。例如 isekaiexpansion:mahoutsukai_evelina 变为 isekaiexpansion_mahoutsukai_evelina。

解析器按下表顺序尝试每个事件的作用域路径。<gender> 使用 NPC 实际性别键；<layer> 为 simple、combat 或 base，唯一 NPC 使用独立分支。

菜单路由在 <event> 前插入 menu/<route>/。随后每个基础路径查找 relationship/<tier>/<phase>，不会回退到关系分支之外的裸阶段文件。

普通事件先尝试请求事件，不同于 interact 时再尝试 interact。已知菜单路由只采用规范事件：trade 使用 trade，下表其他路由使用 interact。自定义路由依次使用请求事件与 interact。

关系、阶段与随机变体

关系从玩家实际层级开始，按 married → trust → friendly → normal 回退。married_distance 固定为 normal，engage_confirm 固定为 trust。这是查找策略，不是权限授予。

首次见面或首次访问某菜单路由使用 initial。否则，上次对话 tick 为正且相距不超过 300 ticks（15 秒）时选择 rapid_repeat，其余为 repeat。initial 与 rapid_repeat 都可回退到 repeat。

NPC 已与其他玩家结婚时，talk、trade、farewell 及显式启用的自定义路由先查找 relationship/<tier>/is_married/<phase>。同一关系层级内，所有已婚状态的阶段回退都先于普通阶段回退；同一基础路径内，所有关系层级回退都先于下一条更通用的作用域路径。

每个候选的现有 <phase>_scenario_1 至 <phase>_scenario_5、同目录 scenario_1 至 scenario_5 与无后缀文件一起进入等概率随机池。基础文件可以缺失；同目录场景因此能满足多个阶段，不要求先找到阶段专属变体。

结构化覆盖

例如 outfit_unlock_formal 可解析到 menu/outfit_unlock/override/formal。解析器从最右侧下划线开始向左尝试分割，再按同样的类型／性别／层级／公共顺序查找；逐个尝试分隔点，因此路由和覆盖名都可以含下划线。

任务路由与结构化覆盖先于 NPC 谓词覆盖、菜单路径和普通路径。谓词覆盖可指定显式 ID，或查找 override/<key>，先在当前菜单分支内，再到分支外。候选缺失会继续回退；礼物的 exclusive 标志不会禁止回退。

隶属路径

所属玩家对话在任务覆盖之后先查找 npc/allegiance/<race>/<contract|dark_magic>/<route>/<phase>。当前阶段回退到 repeat，内容缺失时继续普通查找。见NPC 隶属。

最小示例

把下列内容放到 data/isekaiexpansion/blabber/blabber_dialogues/npc/common/female/interact/relationship/normal/repeat.json，即可提供女性 NPC 普通交互的公共回退。它不会覆盖已有的更具体文件。

{
  "start_at": "line",
  "unskippable": true,
  "states": {
    "line": {
      "text": {"translate": "dialogue.isekaiexpansion.example.line"},
      "choices": [
        {
          "text": {"translate": "dialogue.isekaiexpansion.example.leave"},
          "next": "end"
        }
      ]
    },
    "end": {"type": "end_dialogue"}
  }
}

将两个翻译键加入 language_assemble/categories/dialogues 下的英文与简体中文分类，再运行语言组装。键前缀只是约定，不会自动生成翻译；缺失翻译时可能显示原始键。

字段

对话、状态与选项

动作在选项进入的目标状态上按数组顺序执行，然后才处理该状态结果。仅选择初始状态或恢复状态不会执行其动作。因此效果应放在通过选项到达的状态上，需要时可放在结束状态。

本模组提供的动作

该模块没有注册 isekaiexpansion:add_rep。铁匠与寻路功能在各自子系统初始化时注册其他动作，使用其所属参考文档。

依赖动作与要求

整合包的 Blabber 格式提供：字符串 value 的 blabber:command、标识符字符串 value 的 blabber:redirect，以及无载荷的原版村民交易动作 blabber:open_trade。本模组 NPC 交易应使用 isekaiexpansion:open_npc_trade。

命令动作以玩家身份静默执行，权限等级为 2，属于作者编写的服务端效果。重定向选择另一个对话 ID。blabber:player_level 要求接受整数 value，检查玩家等级是否至少达到该值；其整数编解码器没有追加非负约束。

验证

检查每个起始键和目标键，保证可到达结束状态，并避免没有选项的非结束状态。依赖校验器检查通向结束的路径并警告部分不可达状态，不能替代完整悬空边检查；一个分支即使有有效路径，也仍可能含错误目标。

状态／选项的可选字段一旦填写错误会失败，不会静默采用默认值。未知对象键通常不属于声明字段，拼错的键可能被忽略而非报错。编辑器拒绝单数 action，但不能指望运行时解码自动发现它。

把选择测试与格式解析分开。事件、命名空间、关系分支或作用域写错时，文件可能成功加载却永不被选中。测试共享场景对多个阶段的影响、已与别人结婚时的回退，以及缺失的专属覆盖。效果执行时还应测试已改变的主手和当前会话目标。

重载

对话模板属于 Blabber 的同步数据注册表，随数据包重载。重载后应开启新对话测试；已有会话保留捕获的状态映射。资源／语言重载另行处理翻译文本。

仅添加对话 JSON 不会创建新的代码父菜单或动作编解码器；这些接口见运行时扩展参考。

说话者名称占位符使用当前对话标题中的称呼；尚未熟识时，这可能是职业。普通商人的开场应围绕自己的工作；唯一角色主动自我介绍时，台词直接使用该角色的作者设定姓名。标题仍遵守原有称呼规则。

相关页面

• NPC 对话运行时
• NPC 情绪
• Emoji 数据
• 铁匠委托