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 只需指向该服务即可与其交互,无需任何额外设置。
- 从 ollama.com 获取安装程序并按照常规应用程序的方式安装。支持 Windows、Mac 和 Linux。
- 拉取模型。打开终端并运行:
ollama pull llama3
这将下载模型一次。llama3 是该插件的一个可靠默认选择:速度足以满足实时聊天需求,并且能很好地保持角色设定。大多数 70 亿到 80 亿参数的模型在普通游戏 PC 上都能舒适运行,如果您的硬件配置较低,较小的量化模型也能正常工作。
- Ollama 在安装完成后会自动运行本地服务器,通常位于
http://localhost:11434。您可以在终端中通过 curl http://localhost:11434 确认其是否正在运行,它应返回 "Ollama is running"。
- 将
config.yml 中的 backend: ollama 保持原样;默认 URL 已经指向 Ollama 的默认端口。启动(或重载)您的服务器并与 NPC 对话。
如果您的 Minecraft 服务器与您测试所在的机器硬件不同,请在该服务器主机上安装 Ollama(或任何可从其访问的位置),并相应地更改 ollama.url。
这就是整个设置过程。零成本,无外部 API 调用,所有数据都保留在您控制的硬件上。
入门指南
- 将插件 JAR 文件放入服务器的
plugins/ 文件夹并启动服务器一次;它将写入默认的 config.yml。
- 指向您的 AI 后端:如果按照上述步骤操作,请保留
backend: ollama;或者设置 backend: openai 并填写 openai.url / openai.api-key 以使用托管或自托管的 OpenAI 兼容服务器。
- 在游戏中,运行
/npcspeak example negotiator 会在您脚下生成一个配置齐全的商人,您可以直接与他交谈。这是在无需编写任何配置的情况下查看任务系统运作的最快方式。
- 当您准备好构建自己的 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
NPCSpeak
A Paper 1.20+ plugin that gives your NPCs real conversations, powered by a language model of your choice: a local Ollama install or any OpenAI-compatible API. Players walk up, right-click, and type. The NPC actually answers, in character, instead of cycling through three canned lines.
That alone is a nice trick. What makes it worth building a server around is the task system: NPCs that aren't just chatty, but actually want something from the player, and only reward them once they've genuinely gotten it.
Why this exists
Most "AI NPC" plugins stop at the chat bubble. You talk, something vaguely on-topic comes back, and nothing changes in the world. NPCSpeak treats the conversation as a means to an end. A merchant isn't just roleplaying haggling, he's actually deciding, turn by turn, whether your offer is good enough, and he won't hand over the sword until a second, independent AI call confirms both of you agreed on the same price. A village guard won't wave you through the gate just because you said something plausible-sounding either; he'll only do it once your argument is genuinely convincing enough that he, in character, says so.
That second AI call, the evaluator, is really the core idea of the plugin. It watches the conversation from the outside and answers one question: did the task actually get completed? Only when it says yes do the on-success commands fire: give the item, take the gold, set the permission, whatever you've configured. If the player stalls, refuses, or wanders off, on-failure commands run instead. None of this is decided by pattern-matching keywords in the player's message. It's judged in context, the same way a human running the NPC would judge it.
What you can build with it
- A merchant who actually negotiates. Set an asking price and a hidden minimum; the NPC counters, holds firm, or folds depending on a configurable difficulty, and only confirms a sale once you've both said yes to the same number. Multi-item deals ("two swords for 80 gold") work too.
- A guard who has to be convinced. Persuasion tasks don't need the player to say any magic phrase. The NPC decides, in its own words, whether it's satisfied, and that decision is what gets evaluated.
- An interrogator who probes for holes in your story. Give a solid, verifiable alibi and the NPC lets you go; give a vague one and it keeps pressing. Confess, and it arrests you instead.
- A quest-giver who explains before accepting your answer. The quest task specifically waits for the NPC to lay out what's involved before a player's "yes" counts as acceptance, so you won't accidentally start a quest because you said "sure" to a greeting.
- A freeform NPC that's just there to talk. Village gossip, lore, flavor. No task, no evaluation, just conversation.
Every one of these remembers the player, too. At the end of a conversation, the NPC's own memory of it gets summarized and quietly injected the next time that player talks to it. Nobody has to configure that per player; it just happens.
Highlights
- Chat-based conversation with any NPC, right-click to start, right-click again to leave
- Ollama (local, free) and OpenAI-compatible backends (OpenAI itself, Groq, LM Studio, vLLM, and anything else that speaks the same API)
- Five task types: negotiate, persuade, interrogate, quest, freeform, each evaluated against criteria written for that specific kind of task, not a one-size-fits-all "did they say yes" check
- Automatic task evaluation with
on-success / on-failure console commands, and %player%, %outcome%, %quantity% placeholders to wire in items, currency, permissions, whatever you want
- Multi-item negotiation (
intelligent-quantity: true); the evaluator reports quantity and total price together, so a two-sword deal doesn't get double- or half-charged
- Clickable Accept / Decline chat buttons when a negotiate NPC makes a concrete offer, with a per-task toggle if you'd rather players just type their answer
- Per-player, per-NPC memory that survives restarts
- Configurable difficulty (1 to 5), max exchanges before a task auto-fails, and lock-after-task to end a relationship once it's resolved
- Basic defenses against players trying to talk the AI into giving them free stuff. Both the roleplay NPC and the evaluator are told to treat player chat as what a character said, never as instructions to follow, and obvious "ignore your instructions" attempts are caught outright
- Citizens2 support, so NPCs can be full player-skin Citizens NPCs instead of villagers
- PlaceholderAPI support both ways: expand PAPI placeholders inside NPC text, and expose
%npcspeak_*% placeholders for other plugins to read
- Vault support for economy-based task requirements and rewards
- Content moderation: a blocked-phrase filter with optional Discord webhook alerts for anything caught
- Per-NPC conversation logging
- Streaming mode, watch the response build on the action bar as it's generated, then the full message lands in chat
- An in-game editor for personality and task fields, so you rarely need to touch YAML by hand
Requirements
- Paper 1.20-26.2
- Java 17 or newer
- A language model to talk to: Ollama running locally is free and works well, or any OpenAI-compatible endpoint if you'd rather use a hosted one
Optional: PlaceholderAPI and Vault, if you want those integrations. Citizens2 is optional too, but recommended. Built-in villager NPCs work fine for testing, but Citizens gives you player-skin NPCs with proper animations, pathing, and a lot more customization, so for anything beyond a quick trial it's worth the extra plugin.
Running your own model with Ollama
You don't need an API key, a subscription, or an internet connection at all to use this plugin. Ollama runs a language model directly on your own machine (or on your server box) for free, and NPCSpeak talks to it with zero extra setup beyond pointing at it.
- Grab the installer from ollama.com and install it like any other app. Windows, Mac, and Linux are all supported.
- Pull a model. Open a terminal and run:
ollama pull llama3
This downloads the model once. llama3 is a solid default for this plugin: fast enough for real-time chat and good at staying in character. Most 7 to 8 billion parameter models run comfortably on a normal gaming PC, and smaller quantized models work fine too if your hardware is more modest.
- Ollama runs a local server automatically once it's installed, normally at
http://localhost:11434. You can confirm it's up with curl http://localhost:11434 in a terminal, it should respond with "Ollama is running".
- Leave
backend: ollama in config.yml as-is; the default URL already points at Ollama's default port. Start (or reload) your server and talk to an NPC.
If your Minecraft server runs on different hardware than the machine you're testing on, install Ollama on that box instead (or anywhere reachable from it) and change ollama.url accordingly.
That's the whole setup. No cost, no external API calls, and everything stays on hardware you control.
Getting started
- Drop the plugin JAR into your server's
plugins/ folder and start the server once; it'll write a default config.yml.
- Point it at your AI backend: leave
backend: ollama if you followed the steps above, or set backend: openai and fill in openai.url / openai.api-key for a hosted or self-hosted OpenAI-compatible server.
- In-game, run
/npcspeak example negotiator to drop a fully-configured merchant at your feet and just talk to him. It's the fastest way to see the task system in action without writing any config yourself.
- When you're ready to build your own:
/npcspeak spawn <id> [display name], then either edit plugins/NPCSpeak/npcs/<id>.yml directly or configure everything through /npcspeak edit and /npcspeak task, followed by /npcspeak reload to pick up file changes.
/npcspeak example also has ready-made persuader, interrogator, and quest NPCs if you'd rather start from one of those instead of a negotiator.
NPC configuration
Each NPC lives in its own YAML file under plugins/NPCSpeak/npcs/. The plugin reads and writes this file, so in-game commands and hand-editing both work without stepping on each other.
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 to opt out, omit to follow the global setting
max-interactions: -1 # -1 = unlimited conversations with this NPC
lock-after-task: false # once true, refuse all further interaction after success/failure
log-conversations: false # write every exchange to the per-NPC log file
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 = detect multi-unit deals; %outcome% becomes the TOTAL price, not per-unit
difficulty: 3 # 1 (easy) to 5 (very hard), how much convincing the NPC needs
max-exchanges: 8 # auto-fail the task after this many player messages; -1 = no limit
show-buttons: true # negotiate only, show clickable Accept/Decline buttons on detected offers
require: # checked right before on-success fires; on-failure runs instead if anything here fails
- "eco %outcome%" # player must have at least %outcome% in their Vault balance
# - "item minecraft:gold_ingot %outcome%" # or: must be holding %outcome% gold ingots
on-success:
- "eco take %player% %outcome%"
- "give %player% minecraft:iron_sword 1"
on-failure: []
A few things worth knowing about that task block:
%player% becomes the player's name, %outcome% becomes whatever value the evaluator extracted (a price, an accepted alibi, "guilty", and so on), and %quantity% becomes the number of units in a multi-item deal (1 otherwise). Commands run exactly once per list, so if you want an item count to scale with quantity, write %quantity% into the command yourself, e.g. give %player% minecraft:iron_sword %quantity%.
- With
intelligent-quantity: true, %outcome% is always the total combined price, never a per-unit figure. That's deliberate: asking the model to reliably divide a price down to "per item" was the one thing it got wrong often enough to matter.
difficulty and goal both get woven into the NPC's own instructions, along with a task-specific line telling it how to conclude decisively once it's actually satisfied (or not), so a persuade or interrogate NPC doesn't just hedge forever with nothing for the evaluator to latch onto.
- Freeform NPCs can omit the
task section entirely: no goal, no evaluation, just conversation.
Commands
Everything under /npcspeak (alias /npc) except talking to an NPC requires npcspeak.admin (default: op). Players just need npcspeak.interact (default: true) to start a conversation.
| Command |
Description |
/npcspeak spawn <id> [name] |
Spawn an NPC at your position |
/npcspeak remove <id> |
Remove an NPC |
/npcspeak list |
List all loaded NPCs |
/npcspeak info <id> |
Full NPC details: provider, location, personality, memory settings, and task config all in one place |
/npcspeak edit <id> <field> <value> |
Edit personality fields in-game |
/npcspeak task <id> <subcommand> |
Manage task configuration |
/npcspeak example <type> |
Spawn a pre-configured example NPC (negotiator, persuader, interrogator, quest, free) |
/npcspeak memory list <id> |
List players with saved memory for an NPC |
/npcspeak memory clear <id> <player|*> |
Clear saved memory |
/npcspeak log <id> [player] |
Show today's conversation log |
/npcspeak reload |
Reload all NPCs from disk |
/npcspeak accept / /npcspeak decline |
What the negotiate Accept/Decline buttons actually send; anyone mid-conversation can type these too |
Editable fields for edit: name, greeting, prompt, topic, avoid, memory, maxinteractions, lockaftertask, logconversations.
Task subcommands: info, clear, type, goal, check, maxexchanges, difficulty, intelligentquantity, require, onsuccess, onfailure.
Config reference
npc-provider: builtin # builtin (villager entities) or citizens (Citizens2 NPCs)
backend: ollama # ollama | openai
ollama:
url: http://localhost:11434
model: llama3
timeout-seconds: 60
openai:
# Base URL — change this for local OpenAI-compatible servers (LM Studio, Groq, vLLM, etc.)
# Currently pointed at Groq's free OpenAI-compatible endpoint
url: https://api.groq.com/openai/v1
# API key — get one free at https://console.groq.com/keys, no credit card required
api-key: ""
model: llama-3.3-70b-versatile
streaming: false # true = stream tokens to the action bar as they arrive
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
If PlaceholderAPI is installed, these become available to any other plugin:
| Placeholder |
Value |
%npcspeak_active_npc% |
Display name of the NPC the player is currently talking to |
%npcspeak_exchange_count_<id>% |
Number of messages sent to NPC <id> this session |
%npcspeak_task_status_<id>% |
active, success, failed, or none |
The reverse also works: PAPI placeholders inside an NPC's greeting and system-prompt fields get expanded at runtime, so you can greet players by name, reference their rank, mention their balance, or pull in anything else another plugin exposes.
Citizens2
We'd recommend running this alongside Citizens2 if you can. Built-in villager NPCs are fully functional, but they're still villagers: same model, same limited animation set. Set npc-provider: citizens in config.yml and NPCSpeak NPCs become full Citizens2 NPCs instead, player-skin entities with proper movement and all the customization Citizens offers on top. If Citizens2 isn't installed, the plugin quietly falls back to built-in villagers instead of failing to start, so it's safe to leave the setting as-is even if you haven't decided yet.
Screenshots
Coming soon!
License
See LICENSE.txt
NPCSpeak v1.0 — Developed by l299l — Paper 1.20 – 26.2
评论 0
登录后参与评分
还没有评论,来抢沙发吧