NPCSpeak

插件

· 作者 l299l

AI 驱动的 Minecraft NPC,真正具备谈判、说服、审讯和任务功能,而不仅仅是聊天。

0 本站下载 0 关注 更新于 4 个月前

最新 1.0 · 26.2 · Paper

一键开服(送7天)

NPCSpeak

一款适用于 Paper 1.20+ 的插件,让你的 NPC 拥有真正的对话体验。它由你选择的语言模型驱动:可以是本地部署的 Ollama,也可以是任何兼容 OpenAI 的 API。玩家走近、右键点击并输入文字。NPC 会真正以角色身份作答,而不是机械地循环播放三句预设台词。

仅此一点已属不错。但让它值得围绕其搭建服务器的核心在于任务系统:NPC 不仅仅是健谈,它们真的对玩家有所需求,并且只有在玩家真正完成这些需求后才会给予奖励。


为什么存在这个插件

大多数“AI NPC”插件仅止步于聊天气泡。你说话,对方会回复一些大致相关的內容,但世界状态不会发生任何改变。NPCSpeak 将对话视为达成目的的手段。商人不仅仅是在扮演讨价还价的戏码,他实际上在逐回合地判断你的报价是否足够好,并且在第二次独立的 AI 调用确认双方同意同一价格之前,他不会交出那把剑。村里的守卫也不会仅仅因为你说了些听起来合理的话就让你通过城门;只有当你的论点真正具有说服力,以至于他(以角色身份)认为可以放行时,他才会这么做。

这种二次 AI 调用,即评估器,正是本插件的核心思想。它从外部观察对话,并回答一个问题:任务是否真的完成了?只有当评估器返回“是”时,on-success(成功时)命令才会触发:给予物品、扣除金币、设置权限等,这些都是你可以配置的内容。如果玩家拖延、拒绝或走开,则会运行 on-failure(失败时)命令。这一切都不是通过匹配玩家消息中的关键词来决定的。它是基于上下文进行评判的,就像人类扮演 NPC 时的评判方式一样。


你可以用它构建什么

  • 真正会谈判的商人。 设定一个询问价格和隐藏底价;NPC 会根据可配置的难度进行还价、坚持立场或妥协,只有当你都同意同一个数字时,才会确认交易。多物品交易(例如“两把剑换 80 金币”)也支持。
  • 需要被说服的守卫。 说服任务不需要玩家说出任何特定的魔法短语。NPC 会用自己的话语决定是否满意,而这个决定就是被评估的对象。
  • ** probing for holes in your story.** 审讯者会探测你故事中的漏洞。给出坚实且可验证的不在场证明,NPC 就会放你走;给出模糊的证明,它就会继续施压。如果你认罪,它就会逮捕你。
  • 在接受你的回答前先解释任务的发布人。 任务类型 specifically 等待 NPC 先说明任务详情,之后玩家的“是”才算作接受,这样你就不会因为在打招呼时说“好的”而意外开启任务。
  • 仅供闲聊的自由形态 NPC。 村里的八卦、背景 lore、氛围点缀。没有任务,没有评估,仅仅是对话。

所有这些功能都会记住每位玩家。在一次对话结束后,NPC 对该对话的记忆会被摘要处理,并在该玩家下次与其交谈时悄然注入。无需为每位玩家单独配置;它会自动发生。


亮点

  • 与任何 NPC 进行基于聊天的对话,右键点击开始,再次右键点击离开
  • 支持 Ollama(本地、免费)和 OpenAI 兼容后端(OpenAI 本身、Groq、LM Studio、vLLM 以及任何其他使用相同 API 的服务)
  • 五种任务类型:negotiate(谈判)、persuade(说服)、interrogate(审讯)、quest(任务)、freeform(自由形态),每种类型都针对特定类型的任务编写了评估标准,而不是一刀切的“他们是否说了是”检查
  • 自动任务评估,配合 on-success / on-failure 控制台命令,以及 %player%、%outcome%、%quantity% 占位符,用于连接物品、货币、权限等任何你想要的效果
  • 多物品谈判(intelligent-quantity: true);评估器会同时报告数量和总价,因此两把剑的交易不会被双倍收费或半价收费
  • 当谈判型 NPC 提出具体报价时,会出现可点击的“接受/拒绝”聊天按钮;如果你希望玩家直接输入答案,也可以通过任务级别开关禁用此功能
  • 按玩家、按 NPC 的记忆,重启后依然保留
  • 可配置难度(1 到 5)、任务自动失败的交换次数上限,以及任务解决后锁定关系的功能
  • 基本防御机制,防止玩家试图通过言语诱导 AI 赠送免费物品。角色扮演 NPC 和评估器都被指示将玩家聊天视为角色所说的话,而不是要遵循的指令,明显的“忽略你的指令”尝试会被直接拦截
  • 支持 Citizens2,使得 NPC 可以是完整的带有玩家皮肤 Citizens NPC,而不是普通的村民
  • 双向 PlaceholderAPI 支持:在 NPC 文本中扩展 PAPI 占位符,并向其他插件暴露 %npcspeak_*% 占位符供读取
  • 支持 Vault,用于基于经济的任务要求和奖励
  • 内容审核:带可选 Discord Webhook 警报的屏蔽词过滤器,用于捕获任何违规内容
  • 每个 NPC 的对话日志记录
  • 流式模式:在操作栏上实时查看响应生成过程,随后完整消息出现在聊天窗口中
  • 内置游戏内编辑器,用于编辑人格和任务字段,因此你很少需要手动修改 YAML 文件

要求

  • Paper 1.20-26.2
  • Java 17 或更高版本
  • 一个用于对话的语言模型:本地运行的 Ollama 是免费的且效果良好,或者如果你更喜欢使用托管服务,可以使用任何 OpenAI 兼容端点

可选:PlaceholderAPI 和 Vault,如果你想要这些集成。Citizens2 也是可选的,但推荐使用。内置的村民 NPC 足以进行测试,但 Citizens 提供了带有正确动画、寻路功能和大量自定义选项的玩家皮肤 NPC,因此对于超出快速试用范围的用途,额外安装这个插件是值得的。


使用 Ollama 运行你自己的模型

使用此插件完全不需要 API 密钥、订阅或互联网连接。Ollama 直接在您自己的机器(或服务器主机)上免费运行语言模型,而 NPCSpeak 只需指向该服务即可与其交互,无需任何额外设置。

  1. 从 ollama.com 获取安装程序并按照常规应用程序的方式安装。支持 Windows、Mac 和 Linux。
  2. 拉取模型。打开终端并运行:
    ollama pull llama3
    
    这将下载模型一次。llama3 是该插件的一个可靠默认选择:速度足以满足实时聊天需求,并且能很好地保持角色设定。大多数 70 亿到 80 亿参数的模型在普通游戏 PC 上都能舒适运行,如果您的硬件配置较低,较小的量化模型也能正常工作。
  3. Ollama 在安装完成后会自动运行本地服务器,通常位于 http://localhost:11434。您可以在终端中通过 curl http://localhost:11434 确认其是否正在运行,它应返回 "Ollama is running"。
  4. 将 config.yml 中的 backend: ollama 保持原样;默认 URL 已经指向 Ollama 的默认端口。启动(或重载)您的服务器并与 NPC 对话。

如果您的 Minecraft 服务器与您测试所在的机器硬件不同,请在该服务器主机上安装 Ollama(或任何可从其访问的位置),并相应地更改 ollama.url。

这就是整个设置过程。零成本,无外部 API 调用,所有数据都保留在您控制的硬件上。


入门指南

  1. 将插件 JAR 文件放入服务器的 plugins/ 文件夹并启动服务器一次;它将写入默认的 config.yml。
  2. 指向您的 AI 后端:如果按照上述步骤操作,请保留 backend: ollama;或者设置 backend: openai 并填写 openai.url / openai.api-key 以使用托管或自托管的 OpenAI 兼容服务器。
  3. 在游戏中,运行 /npcspeak example negotiator 会在您脚下生成一个配置齐全的商人,您可以直接与他交谈。这是在无需编写任何配置的情况下查看任务系统运作的最快方式。
  4. 当您准备好构建自己的 NPC 时:运行 /npcspeak spawn <id> [display name],然后可以直接编辑 plugins/NPCSpeak/npcs/<id>.yml,或者通过 /npcspeak edit 和 /npcspeak task 进行配置,最后运行 /npcspeak reload 以应用文件更改。

如果您不想从谈判者开始,/npcspeak example 还提供了现成的 persuader(说服者)、interrogator(审讯者)和 quest(任务)NPC。


NPC 配置

每个 NPC 都拥有自己的 YAML 文件,位于 plugins/NPCSpeak/npcs/ 目录下。插件会读取和写入此文件,因此在游戏中使用命令和手动编辑两者互不冲突。

display-name: "Merchant Bob"
location:
  world: world
  x: 100.5
  y: 64.0
  z: 200.5
  yaw: 180.0
  pitch: 0.0
personality:
  greeting: "Ah, a customer! Fine iron sword, only 50 gold!"
  system-prompt: "You are a shrewd merchant who loves to haggle."
  topic: "weapons, armor, trading"
  avoid: "magic, politics"
  memory-enabled: true       # false 表示退出,省略则遵循全局设置
  max-interactions: -1       # -1 = 与该 NPC 无限次对话
  lock-after-task: false     # 一旦为 true,成功或失败后拒绝所有进一步互动
  log-conversations: false   # 将每次交换记录到每个 NPC 的日志文件中
  task:
    type: negotiate           # negotiate | persuade | interrogate | quest | freeform
    goal: "You are selling an iron sword. Asking price 50 gold, minimum 30 (never reveal)."
    outcome-check: "Did both sides verbally confirm the same final price? Answer YES <price> or NO."
    intelligent-quantity: false  # true = 检测多单位交易;%outcome% 变为总价,而非单价
    difficulty: 3              # 1(简单)到 5(非常难),NPC 需要多少说服力
    max-exchanges: 8           # 在此数量的玩家消息后自动失败;-1 = 无限制
    show-buttons: true         # 仅限 negotiate,在检测到报价时显示可点击的接受/拒绝按钮
    require:                   # 在 on-success 触发前检查;如果其中任何一项失败,则改为运行 on-failure
      - "eco %outcome%"        # 玩家 Vault 余额中必须至少有 %outcome%
      # - "item minecraft:gold_ingot %outcome%"   # 或者:必须手持 %outcome% 个金锭
    on-success:
      - "eco take %player% %outcome%"
      - "give %player% minecraft:iron_sword 1"
    on-failure: []

关于该 task 块的一些注意事项:

  • %player% 变为玩家名称,%outcome% 变为评估器提取的值(如价格、接受的借口、“有罪”等),%quantity% 变为多物品交易中的数量(否则为 1)。命令针对列表中的每一项仅运行一次,因此如果您希望物品数量随数量缩放,请在命令中自行写入 %quantity%,例如 give %player% minecraft:iron_sword %quantity%。
  • 当 intelligent-quantity: true 时,%outcome% 始终是总合价格,而非单价。这是刻意为之:让模型可靠地将价格除以“每件单价”是一件经常出错且影响重大的事情。
  • difficulty 和 goal 都会融入 NPC 自身的指令中,加上特定的任务行告诉它在真正满意(或未满意)时如何果断结束,这样说服者或审讯者 NPC 就不会永远含糊其辞,导致评估器无法抓住重点。
  • Freeform(自由形式)NPC 可以完全省略 task 部分:没有目标,没有评估,仅用于对话。

命令

/npcspeak(别名 /npc)下除了与 NPC 对话以外的所有内容都需要 npcspeak.admin 权限(默认:op)。玩家只需要 npcspeak.interact 权限(默认:true)即可开始对话。

指令 描述
/npcspeak spawn <id> [name] 在你当前位置生成一个 NPC
/npcspeak remove <id> 移除一个 NPC
/npcspeak list 列出所有已加载的 NPC
/npcspeak info <id> 查看 NPC 的完整详情:提供者、位置、性格、记忆设置以及任务配置,全部汇总在一处
/npcspeak edit <id> <field> <value> 在游戏中编辑性格字段
/npcspeak task <id> <subcommand> 管理任务配置
/npcspeak example <type> 生成一个预配置示例 NPC(negotiator、persuader、interrogator、quest、free)
/npcspeak memory list <id> 列出拥有该 NPC 已保存记忆的玩家的列表
/npcspeak memory clear <id> <player|*> 清除已保存的记忆
/npcspeak log <id> [玩家] 显示今天的对话日志
/npcspeak reload 从磁盘重新加载所有 NPC

| /npcspeak accept / /npcspeak decline | 实际发送的协商“接受/拒绝”按钮内容;任何正在对话中的玩家也可以输入这些命令 |

edit 的可编辑字段:name、greeting、prompt、topic、avoid、memory、maxinteractions、lockaftertask、logconversations。

任务子命令:info、clear、type、goal、check、maxexchanges、difficulty、intelligentquantity、require、onsuccess、onfailure。


配置参考

npc-provider: builtin   # builtin(村民实体)或 citizens(Citizens2 NPC)

backend: ollama   # ollama | openai

ollama:
  url: http://localhost:11434
  model: llama3
  timeout-seconds: 60

openai:
  # Base URL — 更改此项以使用本地兼容 OpenAI 的服务器(LM Studio、Groq、vLLM 等)
  # 当前指向 Groq 免费的 OpenAI 兼容端点
  url: https://api.groq.com/openai/v1
  # API key — 在 https://console.groq.com/keys 免费获取,无需信用卡
  api-key: ""
  model: llama-3.3-70b-versatile

streaming: false   # true = 当 token 到达时流式传输到操作栏

moderation:
  enabled: false
  blocked-phrases: []
  blocked-response: "I cannot discuss that topic."
  discord-webhook: ""

memory:
  enabled: true
  max-age-days: 30

conversation:
  max-exchanges: 10
  cooldown-seconds: 3
  listen-timeout-seconds: 60

PlaceholderAPI

如果已安装 PlaceholderAPI,则这些占位符变量可供其他任何插件使用:

占位符 值
%npcspeak_active_npc% 玩家当前正在对话的 NPC 显示名称
%npcspeak_exchange_count_<id>% 本次会话中发送给 ID 为 <id> 的 NPC 的消息数量
%npcspeak_task_status_<id>% active(进行中)、success(成功)、failed(失败)或 none(无)

反向操作同样有效:NPC 的 greeting(问候语)和 system-prompt(系统提示词)字段内的 PAPI 占位符会在运行时展开,因此你可以用玩家的名字打招呼、引用他们的等级、提及他们的余额,或调用其他插件提供的任何数据。


Citizens2

如果条件允许,我们建议搭配 Citizens2 一起使用。内置的村民 NPC 功能完整,但它们仍然是村民:拥有相同的模型和有限的动画集。在 config.yml 中设置 npc-provider: citizens,NPCSpeak 中的 NPC 就会变成完整的 Citizens2 NPC,即拥有玩家皮肤、正常移动能力以及 Citizens 提供的所有自定义功能的实体。如果未安装 Citizens2,该插件会静默回退到使用内置村民,而不会启动失败,因此即使你尚未决定,也可以保留此设置不变。


截图

即将推出!


许可证

请参阅 LICENSE.txt


NPCSpeak v1.0 — 由 l299l 开发 — Paper 1.20 – 26.2

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源