NPC 对话运行时与交互菜单

NPC 对话将服务端准入、路由选择与 Blabber 会话组合起来。本页说明内部交互钩子和事务执行顺序；对话 JSON 与文件查找规则另行说明。

它做什么

NpcInteractionManager 处理交互菜单和赠礼，NpcDialogueManager 把请求路由交给 Blabber，NpcDialogueHandler 选择已存在的对话。这些实现类型不是公共 API 门面。模组为 BaseNpcEntity 注册该处理器，并为村民注册另一套处理器。

主手交互先检查契约卷轴，再检查睡眠与对话准入，随后依次处理任务交付、礼物和普通父菜单。副手交互直接放行。父菜单未能打开时回退到普通对话；交互被接管不代表对话一定成功启动。

运行时模型

准入与占用

普通对话拒绝死亡或睡眠中的 NPC。默认跟随者准入只允许其跟随的玩家，并要求 NPC 已空闲 20 ticks（1 秒）；其他玩家不能启动该跟随者的对话。自定义 NPC 可追加准入限制。

NPC 被另一名正在使用受支持交互界面的玩家占用时，解析器拒绝对话；没有此类界面的旧占用会被释放。非战斗简单 NPC 记有攻击目标时拒绝对话；战斗 NPC 正在攻击有效目标时同样拒绝，但信任的对话玩家可通过。

交互任务要求 NPC 存活、玩家使用受支持界面且距离不超过 4 格（距离平方 16）。接触水或受到外部速度修改时任务不能启动；惊慌会使其停止。任务停止寻路并注视说话者，结束时清除行走／注视记忆及实体占用。它与各动作自身的距离检查不是同一项校验。

DialogueFacing 仅处理匹配的活动会话，战斗或场景占用期间暂停，跳过死亡、睡眠、已移除及跨世界的角色。镜头会话启停由 Blabber 事件连接，不根据界面是否可见推测。

路由交接与选择

待处理路由以玩家 UUID 为键，记录 NPC UUID，并在 160 ticks（8 秒）后过期。读取时先删除，再检查目标和期限，因此交给错误 NPC 也会消耗该记录。恰好到期的 tick 仍可使用，更晚则拒绝；此映射没有定时清扫。

选择依次尝试：

1. 菜单路由对应的任务对话。
2. 按种族、类型、入口与阶段查找所属玩家的隶属对话。
3. 编码在菜单路由中的覆盖候选。
4. 按注册顺序执行的 NPC 谓词覆盖。
5. 菜单路由对话路径。
6. 普通事件对话路径。

当前层级找不到已注册对话才继续。谓词异常会记录并跳过该覆盖；第一个谓词匹配且候选文件存在的覆盖胜出。谓词为真但没有文件不会阻止后续选择。显式覆盖 ID 优先于生成路径。

静态 startDialogue 重载仅在原始 menuRouteKey 参数为 null 时检查普通准入。传入非 null 路由即可绕过，包括随后被规范化为空的空白字符串；死亡／睡眠与处理器检查仍然执行。应把它视为内部可信入口，调用前自行满足跟随者或自定义准入条件。

选中对话后，在返回 Blabber 启动结果前记录开始 tick、场景、点分隔对话路径、total_talks、事件计数，以及见面／关系／层级／对话标志。菜单和谓词覆盖还记录对应计数与标志。选择记录不是完成凭据，选择之后失败不会回滚这些值。

父菜单

公共父菜单延迟注册一次。唯一 NPC 菜单按规范化实体类型缓存，并带关系与任务高亮变体。原型 NPC 的自定义钩子在注册时执行，不是每次点击时执行；不要把原型捕获为最终交互目标。

菜单默认不可跳过。任务聊天标记添加 (!)，并经过优先任务对话选择。跟随模式在响应对话之前改变；缺少响应文件不会撤销模式变化。

交流奖励、恋爱与婚姻状态

选中的 bond 菜单对话会记录待发奖励。同一对话自然关闭时，如果 NPC 仍在玩家服务端世界内存活、未与别人结婚，且本计算日尚未奖励，则给予 25 好感经验。强制关闭没有奖励；选中非 bond 对话会清除待发状态。

奖励日采用 floorDiv(6000 + timeOfDay, 24000) + 1，再映射到正整数计数空间。它依据世界日内时间，不是现实时间。存储的计数阻止同一计算日重复奖励。

关系解析仅返回快照。NpcRelationships 管理显式婚姻绑定，最高好感不会创建或替换配偶。隶属权限由 NpcAccessPolicy 单独判断，见关系运行时。

约定

赠礼处理

确认时重新读取当前主手。空栈或非礼物转到 gift_confirm_invalid；婚姻距离拒绝不消耗物品。成功结果把消耗数限制在现有栈内，先扣除物品，再调用物品接受与 NPC 收礼钩子，增加非负好感、更新情绪，最后解析响应路由。这条路径没有创造模式免消耗分支。

只有实际消耗为正才调用两个钩子；任何接受结果都会处理好感和情绪。接受／收礼钩子的异常没有回滚封装，物品此时可能已经扣除。

NpcGiftItem 的规则由代码定义，没有 JSON 赠礼规则加载器。

构建器辅助方法 overrideNpc 与 overrideNpcIdentity 的优先级分别为 100、200，均默认消耗整栈并设置 exclusive 标志。通用 overrideWhen 接受显式优先级、谓词、数量和路由；更高优先级的自定义规则可覆盖上述辅助规则。

服装礼物要求目标 NPC 类型匹配、服装存在且可选、玩家尚未解锁。消耗 1 件后，在 onGiftAccepted 中重新校验并提交解锁。响应路由为 outfit_unlock_<outfitId>，不会自动穿上服装。

恋爱属于 NPC 关系系统。EngageRingItem 通过誓约之戒处理求婚：有效求婚在解析结果时就设置最高好感并绑定配偶，随后返回消耗 1、好感收益 0；这些修改早于公共扣物阶段。好感阈值由 IsekaiCore 等级存储依赖提供。

NPC 已有其他配偶、已达最高好感或未达可结婚条件时，戒指返回拒绝。最高好感但无配偶时不会修复绑定。已有隶属时拒绝求婚，需先解除隶属。求婚对话反馈结果，关系修改由物品负责。玩家操作见 NPC 好感与恋爱。

扩展钩子

开启 hasDialogueOverrides 并填充 registerNpcDialogueOverrides，即可提供每次交互的谓词。NpcDialogueContext 包含 NPC、玩家、事件、关系层级、阶段及可空菜单路由；hasEloquence／hasCharm 按实时属性执行包含边界的最低值比较。NpcDialogueOverride.forMenu 将路由相等条件与可选谓词／显式 ID 组合，of 支持通用谓词。

唯一 NPC 可覆盖 customizeRootParentMenu、customizeCommandsParentMenu、customizeGiftParentMenu。上下文包含 ROOT／COMMANDS／GIFT、可选关系层级、NPC 类型和性别。标签及拒绝文字在 build 时计算，要求谓词与动作在交互时接收真实玩家／NPC。

选项键允许重复，因此替换／删除可能留下后面的同名项。键规范化会转小写并把非法字符替换为下划线，空键回退为 choice。构建器回调没有通用异常隔离。

父菜单文字前缀为 menu.isekaiexpansion.npc.parent.，唯一 NPC 插入 unique.<npcType>.；公共 NPC 礼物文字可使用 gift.gender.<gender>.。这些构建器直接输出选定翻译键，不检查公共回退键，因此唯一 NPC 的键必须完整。指令反馈另有显式回退机制。

若自定义路由需要查找“已与其他玩家结婚”分支，应加入 isAdditionalMarriedAwareMenuRoute；它只改变查找，交互资格仍须单独约束。

对话姓名

对话标题与 {name} 标记在打开会话时，按当前玩家的信任状态求值。信任之前显示职业或类型，信任后显示全名；普通对话与父对话采用同一规则。自定义名称和隶属归属不会绕过判断。命名 API提供第三方职业／信任解析器，以及可翻译元数据的约定。

会话元数据

NpcFavorDialogueMetadata 仅为基础 NPC 提供有类型的好感、情绪、性格、模式和队伍槽元数据。HUD 读取会话元数据，不直接访问服务端 NPC 字段。完整约定见NPC 情绪与情绪运行时，这些不是对话 JSON 字段。

扩展方式

区分准入、文件选择与效果。可变玩家／NPC 状态应通过真实回调参数获取，不要使用缓存原型。若效果必须依赖响应路由存在，应显式检查；当前赠礼与模式管线不会把内容查找纳入事务。

新动作需在公共初始化中注册编解码器及命名空间 ID。执行动作时校验当前会话目标，以及所需距离／信任条件。对话文件或客户端按钮存在，不代表效果已获得授权。

验证

在各关系层级测试初次、重复、快速重复对话，并逐项移除回退文件。加入谓词为真但文件缺失的覆盖和抛错谓词，确认后续候选仍可用。检查路由过期、错误目标消耗和两名玩家争用同一 NPC。

先后在同类型的两个唯一 NPC 实例上打开菜单，确认回调使用当前目标。菜单打开时改变好感、礼物栈和跟随者归属，检查运行时门槛与原型捕获问题。

赠送整栈、限制数量的自定义礼物、已解锁服装礼物，并测试戒指各拒绝分支。分别核对库存、好感、婚姻绑定与路由，包括响应缺失和钩子失败。同日自然与强制关闭交流对话，再跨越计算日边界测试。

在所属及旁观客户端检查唯一／公共菜单翻译、禁用选项说明、动作表情、emoji、好感元数据、对话朝向与场景交接。

相关页面

• 对话数据与路由

• 对话对象与界面

• 对话工具

• NPC 基础

• NPC 跟随者

• NPC 情绪

• 人形预设与 NPC 服装