- 支持核心
- Mohist/Spigot/Paper/Purpur
- 原创/转载
- 原创
- 作者
- Jens_Hon
- 前置
- ArcartX，Adyeshach
- 支持版本
- 1.20.X-1.21.X
MistInteract 插件介绍与使用说明
（插件已基本完善，遇到BUG请反馈留言）
这个插件的配置难度正常来说比Chemdah简单
如果你实在不会，丢AI让他帮你写配置也可以
F进入交互，滚轮切换（小键盘上下也可以）
新版本支持玩家客户端修改按键改绑
只有滚轮是默认强制的
【当前已对Adyeshach和Citizens添加支持，Adyeshach优先级高于Citizens】
插件文档
截图：（插件已基本完善，遇到BUG请反馈留言）
这个插件的配置难度正常来说比Chemdah简单
如果你实在不会，丢AI让他帮你写配置也可以
F进入交互，滚轮切换（小键盘上下也可以）
新版本支持玩家客户端修改按键改绑
只有滚轮是默认强制的
【当前已对Adyeshach和Citizens添加支持，Adyeshach优先级高于Citizens】
插件文档
注意：目前插件默认是打开对话后隐藏原版的状态栏等，如果你用AX修改了HUD，可以在config配置内添加上配置名，即可隐藏使用AX配置的HUD。
鸣谢：墨墨啊 提供技术支持和答疑
视频：【拍好了，还没传】
一、插件简介
MistInteract 是一个面向服务器剧情/任务场景的 NPC 对话插件，基于 ArcartX HUD 显示交互界面，并与 Adyeshach NPC 体系联动。
它可以实现“靠近 NPC -> 打开可交互列表 -> 进入分支对话 -> 执行命令/发送提示 -> 记录玩家进度”的完整链路。
二、核心特点
- 对话 HUD 与 NPC 列表 HUD 分离，交互清晰。
- 支持多分支对话（next 跳转、close 结束）。
- 支持玩家对话进度本地持久化（SQLite database.db）。
- 支持首次对话与重复对话入口分离（first / repeatFirst）。
- 支持管理员命令直接打开/中断/重置指定玩家对话。
- 支持隐藏原版 HUD 与额外 AX HUD，减少界面干扰。
- 支持键盘快捷和鼠标滚轮交互（确认/上下选择由 UI 与按键绑定协同处理）。
三、依赖与环境
- 服务端：1.20.1
- 软依赖：ArcartX、Adyeshach
- 本插件会加载 Hud.yml、DialogHud.yml、npchud/*.yml
四、安装步骤
1. 将 MistInteract-1.0.0.jar 放入服务器 plugins 目录。
2. 确认服务器已安装并正常加载 ArcartX 与 Adyeshach。
3. 首次启动后，检查 plugins/MistInteract/ 下是否生成：
- config.yml
- Hud.yml
- DialogHud.yml
- npchud/example.yml
- data/database.db
4. 按需编辑 npchud 内配置，然后执行重载命令。
五、`npchud` 对话 YAML：文件级（顶层）
每个文件对应 一个*逻辑 NPC（`npcId` 全局唯一；重复时后加载的覆盖先加载的，控制台会 warning）。
| 字段 | 是否必填 | 说明 |
npcId | 是 | 与 Adyeshach 里该 NPC 的 **id** 一致（插件用它在世界里找实体） |
displayName | 否 | 对话里展示的名字；默认等于 `npcId` | |
hudListName | 否 | NPC 列表 HUD 上显示的名称；不填则用 `displayName` |
first | 建议 | 首次进入对话时的**起始节点 id**；缺省插件内部按 `"1"` 处理 |
| repeatFirst | 否 | 满足“回访条件”时，用哪个节点替代 `first` 作为入口 |
| repeatFirstRequires | 否 | “字符串”若“非空”：仅当玩家对该 NPC 的 `setFlags` 标记集合里同时包含 此处列出的所有标记时才走 `repeatFirst`。多个标记在同一字符串里用 英文逗号 分隔，例如 `a,b,c`（不要写成 YAML 列表，否则读不到）。若留空：只要该玩家对该 NPC **`talk_count` > 0（曾经通过带非空 `next` 且 `incrementProgress: true` 的选项推进过）就走 `repeatFirst` | |
| distance | 否 | 该 NPC 交互半径（格）；不填用全局 `scanDistance` |
| dialogues | 是 | 节点字典，键为节点 id，值为节点内容（见下节） |
六、节点（`dialogues` 下的每一项）
| 字段 | 说明 |
text | 节点正文，支持 `&` 颜色代码（由客户端/AX 侧表现为准） |
| textRoll | 与 `text` 二选一或共存：有 `textRoll` 时，界面正文从列表中 按 weight 加权随机 抽一条。每项为 `{ weight: 数字, text: "..." }`，`weight` 最小按 1 计 |
options | 选项字典，键为选项 id（会发给客户端，需稳定）；值为选项配置（见下节） |
七、选项（`options` 下的每一项）
| 字段 | 说明 |
| text | 选项在对话 HUD 上显示的文字 |
| playerMessage | 选中后发给玩家聊天栏的消息；可为一条字符串或字符串列表；支持 `&` 颜色（插件会转换）；支持占位符（与 `commands` 相同，见下面第八内容） |
| commands | 命令列表，见下面第八内容 |
| next | 非空：选完后跳转到该节点 id，不关闭对话 HUD |
| close | `true`：选完后关闭对话并走正常结束流程（会执行已排队的 `afterDialogue` 命令） |
| incrementProgress | 默认` true`。为 `true` 时：若本选项 `next` 非空，选中后会对该玩家该 NPC 的 `talk_count` +1；为 `false` 则不加 | |
| setFlags | 字符串列表；选中后把这些标记名写入该玩家对该 NPC 的持久化标记（逗号拼接存储），供 `repeatFirstRequires`、`requireFlags`、`forbidFlags` 使用 | |
| requireFlags | 字符串列表；玩家必须已拥有其中全部标记，该选项才会出现在当前节点 |
| forbidFlags | 字符串列表；玩家只要拥有其中任意一个标记，该选项不出现 |
- 真正结束对话：用 `close: true`，或 `next` 留空（插件也会结束对话，但建议显式 `close`）。
- 若写 `next`，目标节点必须在同一文件 `dialogues` 里存在，否则重载 warning。
打断与延后命令：玩家被 `interrupt`、死亡、换世界、退出服务器等非正常结束时，不会执行已排队、时机为 对话结束后（`afterDialogue`）的命令。
八、占位符与 `commands` 写法
占位符（`playerMessage` 与命令里的 `run`/字符串命令都会先替换）
| 占位符 | 含义 |
| %player% | 这应该不用说了吧.....【玩家名】 |
| %uuid% | 这也应该懂的吧？【玩家 UUID 字符串】 |
| %npc% | 当前 npchud.yml 的 `displayName` |
| %npc_id% | 当前 npchud.yml 的`npcId` |
| %world% | 玩家所在世界名 |
| `%x%` `%y%` `%z%` | 玩家脚下方块整数坐标 |
| %yaw% %pitch% | 视角浮点数（两位小数） |
`commands` 两种列表项
（1）纯字符串
- 等价：控制台执行、`when` 为 点选后立即。
- 不要写开头的 `/`，例如：`minecraft:give %player% bread 3`
（2）对象（Map）
| 键 | 必填 | 说明 |
| run | 是 | 命令正文，不要开头的 `/` |
| exec | 否 | `console` / `server` / `c` → 控制台；`player` / `p` → 以玩家身份执行；`op` / `player_op` / `playerop` → 临时 OP 后代玩家执行（受 第九章 限制） |
| when | 否 | 默认点选立即。`onSelect` / `immediate` / `now` / `select` 等 → 立刻；`afterDialogue` / `after` / `end` / `onClose` 等 → 整段对话正常关闭 HUD 后再执行（可多行排队，有上限） |
同一选项内可多行命令，按列表顺序执行；`afterDialogue` 与立即执行的命令分阶段执行。
九、`config.yml` → `dialogueCommands`（全局安全）
对 **所有** 执行方式（控制台 / 玩家 / OP）在真正分发前都会做：
| 项 | 作用 |
| maxLineLength | 展开占位符后的命令最大长度，超出则拦截 |
| blockedRegex | Java 正则列表；对整条命令做 `matches` 整行匹配（不是子串 `find`）。需要“任意位置命中”请在正则里自己写 `.*...` |
| allowPlayerOp | 是否允许配置里使用 `exec: op` |
| requirePermissionForOpCommand | 为 `true` 时，OP 代执行还要求玩家拥有权限 `mistinteract.dialogue.opcommand` |
| opCommandPrefixWhitelist | 去掉前导 `/` 后转小写，命令必须以列表中某一非空前缀开头才允许 OP 执行；列表为空则不允许任何 OP 命令 |
| maxDeferredPerSession | 单次对话会话中，`afterDialogue` 最多排队条数 |
管理命令（需 `mistinteract.admin`）
- 输入 `/mistinteract` 或 `/mistinteract admin`（无子命令）会提示完整帮助
常见问题
1. 列表/对话 HUD 全无
吐槽：是否安装并加载 ArcartX；后台是否提示主界面或对话界面注册失败
2. 主界面能用、对话不能
吐槽：看后台是否提示对话 HUD 未注册；检查 `ui/DialogHud.yml` 是否存在且可被 AX 加载
3. NPC 从不进列表
吐槽： `npcId` 是否与 Adyeshach 一致；`distance` 与 `scanDistance`；Adyeshach 是否可用
4. 改 yml 不生效
吐槽：是否放在 `npchud/` 根目录且扩展名 `.yml`；是否执行 `admin reload`
5. 对话结束界面还在
吐槽：终点选项是否 `close: true`；`next` 是否指向存在节点
6. OP 对话命令不执行
吐槽：`allowPlayerOp`、`opCommandPrefixWhitelist`、玩家权限 `mistinteract.dialogue.opcommand`、`blockedRegex`
7. 正则明明写了但不拦
吐槽：当前实现是 整行 matches；旧写法若只写了 `^op\s` 需改为如 `^op\s.*` 等
