BudPlugin - 为你的冒险准备的伙伴们！

Hytale 伙伴插件

模板由 Up 提供，经 Kaupenjoe 稍作修改。
灵感来源于 LukeysMods 的 MyFriends。

🌟 概览

这是一个针对 Hytale 的概念验证 (PoC) 插件，它集成了大型语言模型 (LLM)，旨在创建真正交互式的 RPG 风格伙伴。这些"伙伴"不仅仅是跟随你——它们会交谈、对世界做出反应，并且能记住你经历的战斗。

更新信息

如果你有旧版本的插件，请删除 /prompts 文件夹，或者在添加新版本后使用 /bud prompt reset 命令更新它。 为了彻底清理此插件，你可以删除你世界模组文件夹中的旧插件文件夹。

1.9.0 版本新内容

新增

• 用于召唤/解散伙伴的卡牌物品：新增卡牌物品，无需使用命令即可召唤/解散你的伙伴。这些卡牌可以在奥术工作台上制作。

修复

• 现在禁用了伙伴的友军伤害。
• 伙伴现在会攻击攻击玩家的敌对生物，并且在被攻击后的一小段时间内协助玩家战斗。
• 记忆相关命令：查看所有当前记忆/传奇记忆。

(更多更改请参见 GitHub 仓库中的 CHANGELOG.md)

发布版趣闻

在敲击草地后…… Gronkh：

草地？Og Og——那个傻瓜怎么了，竟然去打碎像花一样娇嫩的东西？弱到连我石锤的尊重都配不上。

认识你的伙伴

图片	介绍
	### 🦊 Veri 一个有点孩子气、但极其好奇且友好的 Feran 伙伴。Veri 行动敏捷，使用匕首在战斗中支持你。 Veri 与你同行，寻找罕见的解药，以治疗他那被有毒的 Skarak 感染而患病的族人。
	### 👹 Gronkh 一个起初可能看起来脾气暴躁，但极度忠诚且强壮的 Trork 伙伴。他是一个强力角色，使用一把沉重的狼牙棒支持你。 Gronkh 执行着一项保护北方部落免受冰冷'白色流浪者'侵扰的任务，并且正在训练，以粉碎威胁他们土地的亡灵力量。
	### 🍃 Keyleth 一个非常聪明但有点害羞的 Kweebec 伙伴。她更喜欢保持距离，使用弓在远处支持你。 Keyleth 正在执行一项任务，在失落的神庙中发掘古老的知识。她想通过连接古老神庙来击败暗影骑士和黑暗军团，从而恢复平衡。

🎴 伙伴卡牌

使用物品而非聊天命令来召唤和遣散你的伙伴。每个伙伴都有自己的卡牌，可以在奥术工作台的 奥术杂项 类别下制作。

图片显示了包含所有配方的奥术工作台杂项菜单：

卡牌	配方
Keyleth	铁短弓、健康作物 x3、纤维 x50、天蓝树干木材 x20、金锭 x20、南瓜 x10、浓缩生命精华
Veri	铁匕首、耐力作物 x3、解毒药水 x10、银锭 x30、金锭 x30、火焰精华 x10、浓缩生命精华
Gronkh	铁狼牙棒、魔力作物 x3、冰岩 x30、苔藓圆石 x90、银锭 x20、寒冰精华 x10、浓缩生命精华

制作好后，只需将卡牌握在手中：

• 左键（主手）：在你旁边召唤对应的伙伴。如果伙伴已存在，则将其重召唤。
• 右键（副手）：将该伙伴重新解散。

每张卡牌只能召唤/解散其自己的伙伴，因此你可以携带所有三张卡牌，自由搭配你活跃的伙伴。

🚀 功能特性

🤖 智能交互

• 动态模式：在防御型（攻击）、被动型（跟随）和坐下型（原地停留）之间切换。
• 世界感知：伙伴每隔几分钟会发送聊天消息，告知当前世界信息（区域、生物群系、时间、天气）。
• 战斗交互：你的伙伴会对最近的战斗做出情境感知的对话反应。
• 方块交互：你的伙伴会对最近放置或破坏的方块做出反应。
• 物品交互：你的伙伴会对最近收集的物品做出反应。
• 天气交互：如果天气变化，你的一位伙伴会用情境感知的对话做出反应。
• 心情系统：你的伙伴拥有会随时间变化的心情，影响他们的对话和反应。（目前每3分钟随机变化一次）
• 最喜爱日：每个伙伴都有一个一周中最喜爱的日子，并在那一天表现出过度积极的状态。
• 发现新区域反应：当你第一次进入一个新区域时，你的伙伴会根据该区域的特征，用独特的对话对发现做出反应。
• 合成反应：当你合成一个物品时，你的伙伴会对合成事件做出反应，并根据合成的物品类型（例如工具、武器、盔甲等）提供反馈。
• 玩家聊天反应：伙伴可以对你的聊天消息做出反应。提及一个或多个伙伴名字（例如 "veri", "gronkh", "keyleth"）来直接定位他们；如果没有提及，则由一个随机伙伴回应。

记忆系统

• 记忆存储：伙伴会记住与玩家的过往交互，从而能够基于之前的事件提供情境感知的回应和交互。
• 记忆优先级：记忆会根据其重要性进行优先级排序，越重要的事件保留时间越长，并对伙伴行为产生更强的影响。
• 记忆淘汰：记忆的优先级会随时间衰减，当记忆容量达到上限时，较不重要的记忆将被淘汰。
• 传奇记忆：某些重大事件可以被标记为"传奇"，从而确保它们在记忆中被保留更长时间。

🎮 命令

此插件主要通过简单的聊天命令进行控制：

• /bud - 显示所有命令。

创建命令

• /bud create - 一次性创建所有三个伙伴（Veri, Gronkh, Keyleth）。
• /bud create [--veri|--gronkh|--keyleth] - 指定召唤或传送特定的伙伴。
• /bud reset - 重新创建你所有的伙伴。

删除命令

• /bud delete - 一次性删除所有三个伙伴（Veri, Gronkh, Keyleth）。
• /bud delete [--veri|--gronkh|--keyleth] - 删除特定的伙伴。
• /bud delete --world - 删除所有世界中的所有伙伴。

状态命令

• /bud state - 将所有活跃伙伴的行为模式切换到下一个状态。
• /bud state --defensive - 将所有活跃伙伴的行为模式改为防御型。
• /bud state --passive - 将所有活跃伙伴的行为模式改为被动型。
• /bud state --sitting - 将所有活跃伙伴的行为模式改为坐下型。

提示词命令

• /bud prompt - 无需重启服务器即可重新加载丢失的 LLM 提示配置。
• /bud prompt --reset - 将所有 LLM 提示配置重置为默认值（谨慎使用，请先备份你的自定义提示词！）。

调试命令

• /bud debug - 显示可用的调试标志。
• /bud debug --componentData - 在聊天中显示玩家当前及持久化的伙伴数据。
• /bud debug --mood - 在聊天中显示每个活跃伙伴的当前心情及其最喜爱日。
• /bud debug --weather - 在聊天中显示当前天气。
• /bud debug --time - 在聊天中显示当前时间和星期几。
• /bud debug --world - 在聊天中显示当前区域和生物群系。

⚙️ 配置（LLM）

要启用 AI 功能，请编辑服务器模组文件夹中的 LLM.json：

LLM 配置

设置	描述	默认值
EnableLLM	启用/禁用 LLM 功能	true
UsePlayer2API	启用/禁用使用 Player2 API 作为 LLM （EnableLLM 必须为 true）	false
Url	你的 LLM API 端点	v1/chat/completions
Model	AI 模型标识符	mistralai/ministral-3-3b
ApiKey	你的 LLM 服务的 API 密钥	not_needed
MaxTokens	限制 AI 响应的长度	100
Temperature	控制随机性 (0.0 - 1.0)	0.9

反应配置

设置	描述	默认值
EnableCombatReactions	启用或禁用战斗反应消息	true
EnableBlockReactions	启用或禁用方块反应消息	true
EnableItemReactions	启用或禁用物品反应消息	true
EnableDiscoverReactions	启用或禁用发现反应消息	true
EnableCraftingReactions	启用或禁用合成反应消息	true
EnableWorldReactions	启用或禁用世界反应消息	true
WorldReactionPeriod	世界反应消息的间隔（秒）	60L
EnableWeatherReactions	启用或禁用天气反应消息	true
WeatherReactionPeriod	天气反应消息的间隔（秒）	5L
EnableMoodReactions	启用或禁用心情反应消息	true
MoodReactionPeriod	心情反应消息的间隔（秒）	180L
EnablePlayerChatReactions	启用或禁用玩家聊天反应消息	true

编排配置（仅在需要进行性能调优时更改）

设置	描述	默认值
OrchestratorGlobalCooldownMs	编排操作的整体冷却时间（毫秒）	3000L
OrchestratorChannelCooldownMs	编排操作的频道特定冷却时间（毫秒）	5000L
OrchestratorMaxQueueDepth	编排操作的最大队列深度	3
OrchestratorTickIntervalMs	编排操作的节拍间隔（毫秒）	1000L
OrchestratorEntryTtlMs	编排条目的存活时间（毫秒）	60000L

调试配置

设置	描述	默认值
EnablePlayerInfo	记录玩家信息用于调试	false
EnableBudDebugInfo	记录伙伴信息用于调试	false
EnableMoodChangeDebugInfo	聊天消息中的心情变化信息用于调试	false

对话配置

设置	描述	默认值
EnableConversationMemory	启用对话记忆	true
ConversationMemoryDepth	对话记忆深度	8
ConversationMemoryDecayFactor	对话记忆衰减因子	0.9
ConversationMemoryMinImportance	对话记忆的最低重要性	4
EnableLegendaryMemory	启用传奇记忆	true
LegendaryMemorySlotsPerBud	每个伙伴的传奇记忆槽位数	3
EnableDialogMode	启用对话模式	true
DialogModeIdleSeconds	对话模式的空闲时间（秒）	180L
DialogModeActiveSeconds	对话模式的活跃时间（秒）	30L
DialogModeTurnIntervalSeconds	对话模式的轮换间隔（秒）	8L

LLM 使用：

• 你可以使用自己的本地 LLM 客户端（如 LM Studio）。
• 或者使用 API 提供商，例如 DeepSeek、Qwen 等。请确保在配置中设置了正确的 Url、Model 和 ApiKey。
• 或者通过启用 UsePlayer2API 并遵循 Player2 API 设置说明来支持 Player2 API。

🧠 提示词管理

LLM 提示词现在存储在模组文件夹中的外部 YAML 文件中。这使得无需修改代码即可更轻松地编辑和自定义 NPC 个性。每个伙伴都有自己的提示词文件，并且还有用于世界交互的提示词。

在服务器首次启动时，默认提示词会从资源复制到模组文件夹。随后，你可以编辑这些文件来自定义伙伴的行为和个性。

注意：命令 /bud prompt reset 会使用资源中的默认提示词覆盖现有的提示词文件。使用此命令前，请务必备份你的自定义提示词。

⚠️ LLM 性能说明（推理模型）

如果你正在使用推理模型（例如 DeepSeek-R1、Qwen-Reasoning）：

• 禁用"思考"： 这些模型会生成大量 <think> 标记，可能导致延迟或消息被截断。建议使用没有"思考"阶段的模型，或者在你的 API 提供商设置中禁用它。
• 令牌限制： 如果消息被截断，请在配置中将 MaxTokens 增加到至少 200。
• 过滤： 插件会自动尝试过滤 <think> 标签，但原生"不思考"模型能提供最佳体验。

🗺️ 开发路线图

• 2.0.0：伙伴间交互 (Bud-2-Bud Interactions) - 如果可能：伙伴与世界交互，例如如果玩家要求，伙伴可以挖一些石头 - 或者你有其他想法？

已知问题

• 玩家传送后，伙伴常常会损坏并变为"隐形"。临时解决方法：使用 "/bud" 或 "/bud reset" 命令重新生成它们。

📜 变更历史

有关所有更改和版本历史的详细信息，请参见 CHANGELOG.md。

"这个模组在没有 LLM 的情况下也能工作，但主要目标是拥有交互式的伙伴。"

怀着对 Hytale 社区的爱意创作