ArkPilot

主题

NPC 绑定 ​

ArkPilot 内置 NPC 绑定模块，支持将助手绑定到服务器中的 NPC 实体。玩家右键点击 NPC 即可进入与该助手的私聊对话，AI 回复可通过聊天栏或 NPC 头顶气泡显示。

支持的 NPC 插件 ​

后端插件NPC ID 格式
adyeshachAdyeshach实体 ID 或 UniqueId
citizensCitizens数字 ID 或 UUID

插件作为 softdepend 引入，未安装时自动跳过对应后端，不影响其他功能。

快速开始 ​

1. 创建 NPC ​

使用你的 NPC 插件创建一个 NPC，记下它的 ID。

Adyeshach 示例：

/adyeshach create VILLAGER my-guide-npc

Citizens 示例：

/npc create 小墨

2. 在助手配置中绑定 ​

编辑助手的 config.yml，在 interaction 段填写 NPC 信息：

yaml
interaction:
  chatTrigger: "@guide"
  npcId: "my-guide-npc"        # NPC 的 ID
  type: "adyeshach"            # NPC 后端类型（可选）
  npcGreeting: "你好呀！有什么我能帮你的吗？"  # 开场白（可选）

3. 重载配置 ​

/ark reload

现在右键点击该 NPC 即可开始对话。

助手配置字段 ​

在助手 config.yml 的 interaction 段中，以下字段用于 NPC 绑定：

字段类型默认值说明
npcIdstring""绑定的 NPC ID，留空表示不绑定
typestring""NPC 后端类型：citizens / adyeshach，留空则自动匹配所有后端
npcGreetingstring""开场白文本，非空时直接发送给玩家而不触发 AI

type 字段的作用

当你同时安装了多个 NPC 插件，且不同插件中的 NPC ID 可能冲突时，使用 type 字段明确指定后端。如果服务器只安装了一个 NPC 插件，可以留空。

对话流程 ​

玩家右键 NPC
  → 匹配绑定的助手
  → 自动进入私聊模式（DM Mode）
  → 发送开场白（如果配置了 npcGreeting）
  → 玩家后续消息直接发送给该助手

玩家走远（超出 maxDistance）/ 退出服务器
  → 自动结束对话
  → 退出私聊模式

对话期间的行为：

  • 玩家发送的所有聊天消息自动路由到绑定的助手
  • 如需发送公共聊天，使用私聊模式的公共聊天前缀（默认 !）
  • NPC 会持续面向玩家（可通过 npc.tickLookAt 关闭）
  • 玩家超出最大距离后自动结束对话

显示方式 ​

NPC 对话始终通过聊天栏发送完整的 AI 回复内容，与普通助手对话体验一致。

头顶气泡（可选） ​

开启气泡后（npc.bubble.enabled: true），AI 回复会额外以全息文字的形式显示在 NPC 头顶上方，模拟 NPC "说话" 的效果。气泡仅做预览，聊天栏始终包含完整内容。

气泡特性：

  • 流式更新，AI 生成文字时实时显示在气泡中
  • 限制最大行数（bubble.maxLines），超出时取最后 N 行，保证看到最新内容
  • 仅对话中的玩家可见，不干扰其他玩家
  • 回复完成后保持显示一段时间，然后自动消失

TIP

气泡显示基于 ArkPilot 内置的全息系统实现，不依赖任何外部全息插件，支持 1.8 ~ 最新版本。

全局 NPC 配置 ​

在 interaction.yml 中可配置 NPC 模块的全局参数：

yaml
npc:
  maxDistance: 15.0
  tickLookAt: true
  bubble:
    enabled: false
    maxLines: 5
    maxChars: 0
    durationSeconds: 8
    offsetY: 0.5
字段类型默认值说明
npc.maxDistancedouble15.0对话最大距离（方块），超出自动结束
npc.tickLookAtbooltrue对话期间 NPC 持续面向玩家
npc.bubble.enabledboolfalse是否启用头顶气泡预览
npc.bubble.maxLinesint5气泡最大行数，超出时取最后 N 行
npc.bubble.maxCharsint0气泡最大显示字符数，<= 0 不截断
npc.bubble.durationSecondsint8回复完成后气泡保持显示的秒数
npc.bubble.offsetYdouble0.5气泡相对 NPC 头顶的 Y 轴额外偏移

完整配置示例 ​

以下是一个完整的 NPC 导游助手配置：

yaml
# assistants/town-guide/config.yml
enabled: true
id: town-guide
name: "镇长"
description: "城镇导游，带你参观服务器的每个角落。"

model:
  primary: ""
  temperature: 0.8
  maxTokens: 1024

tools:
  load:
    - execute-command

executeCommand:
  whitelist:
    - "tp"
    - "warp"

skills:
  load:
    - server-wiki

interaction:
  chatTrigger: ""              # 不需要聊天触发，通过 NPC 交互
  npcId: "town-guide-npc"     # Adyeshach NPC ID
  type: "adyeshach"
  npcGreeting: "欢迎来到小镇！想去哪里逛逛？"
  responseDelay: 300
  streaming: true              # 建议开启流式，气泡效果更好

注意事项

  • 内部助手（internal: true）不能绑定 NPC
  • 一个 NPC 只能绑定一个助手，同一 npcId 不要配置到多个助手上
  • 开场白（npcGreeting）是直接发送的文本，不经过 AI 处理
  • 开启气泡时（npc.bubble.enabled: true），建议同时开启 streaming: true 以获得更流畅的气泡效果

ArkPilot — Minecraft AI Assistant Plugin