Shopkeepers Addon 拓展插件

Shopkeepers Addon - Navigation & Economy
Shopkeepers Addon 为广受欢迎的 Shopkeepers 插件提供高级经济系统与直观 GUI 导航，让玩家不再需要在茫茫市场中费力搜寻心仪物品。
作者：\_w41k3r（SnowCutieOwO）
许可证：MIT（免费、开源、可商用）
前置依赖：Shopkeepers v2.23.9+（必需）、ProtocolLib v5.1.0+（必需）
可选依赖：Vault + 任意经济插件（EssentialsX / CMI 等，v2.25.0+ 后 Vault 为软依赖）
下载渠道：SpigotMC / Modrinth / GitHub Releases
官方 Wiki：snowcutieowo.github.io/ShopkeepersAddon

概述

Shopkeepers Addon 不是一个独立的商店插件，它只能与 Shopkeepers 配合使用，为其添加两大核心能力：
GUI 导航系统 —— 通过图形界面浏览所有商店、按物品搜索、一键传送
经济系统 —— 将 Shopkeepers 原本的以物易物交易升级为支持 Vault 经济插件（金币/货币）的交易模式
特别鸣谢 blablubbabc 开发了卓越的 Shopkeepers 本体插件。
核心优势
为 Shopkeepers 增加 Vault 经济支持，交易直接用金币结算
GUI 导航菜单，玩家无需满地图找商店
支持 玩家商店 与 管理员商店 分类浏览
一键 传送至商店，支持传送预热防 PVP 逃逸
自定义 价格格式（美式/欧式/自定义货币符号）
支持 Shift+点击批量交易，自动校验余额
玩家可通过 /setshop 自行设置商店位置
支持 物品黑名单，禁止在玩家商店中出售特定物品
每日交易限额 系统，可配置提醒消息
高性能异步处理，轻松应对 1000+ 商店
MIT 协议，免费商用

版本与兼容性

| 项目 | 说明 |
| :--- | :--- |
| Minecraft 版本 | 1.16.x – 1.21.11 |
| 服务端平台 | Paper / Purpur / Spigot / Bukkit（Folia 兼容性待验证） |
| Java 版本 | Java 17+ |
| Shopkeepers 版本 | v2.23.9 或以上 |
| ProtocolLib | v5.1.0 或以上（必需） |
| Vault | v2.25.0+ 后为软依赖，缺失时经济功能自动禁用 |
v2.25.0 是一个重要分水岭：此版本将经济系统从"命令解析模式"迁移为"原生 Vault API 直连"，性能大幅提升，不再需要配置复杂的命令与正则。

核心功能详解
经济系统集成

Shopkeepers Addon 接管 Shopkeepers 的交易处理逻辑，将原本的"物品换物品"升级为"金币买卖"模式：
购买：玩家支付金币 → 从商店获得物品
出售：玩家交出物品 → 获得金币
自动校验 买家余额 与 卖家（商店主）余额，余额不足时自动锁定交易槽
支持 Shift+点击批量购买/出售，每次操作后实时刷新余额
商店主资金不足时，防止玩家向其出售物品（可配置关闭）
GUI 导航系统

通过 /shops 命令打开主菜单，玩家可以：
浏览 所有玩家商店 列表（按头颅/图标展示）
浏览 所有管理员商店 列表
搜索 指定物品 在哪个商店有售
点击图标 直接传送 到对应商店位置
点击管理员商店图标可 远程打开交易界面（无需走过去）
传送系统
/setshop —— 玩家为自己商店设置传送锚点
点击 GUI 中的商店图标即可传送
支持 传送预热（warmup），预热期间受到伤害会取消传送，防止 PVP 逃逸
可配置预热时长
价格格式自定义

支持 DecimalFormat 语法，可配置：
美式格式：1,000,000.00
欧式格式：1.000.000,00
自定义货币符号：$100 或 100$
自定义小数/千分位分隔符
物品黑名单

管理员可在配置中指定禁止在玩家商店出售的物品（如基岩、刷怪蛋等）：

playerShops:
itemBlacklist:
- BEDROCK
- COMMAND_BLOCK
每日交易限额

可为玩家商店配置每日收入上限，达到限额后交易自动锁定，并发送可自定义的提醒消息（支持 %remaining% 占位符显示剩余额度）。
自定义标价物品

商店中的"价格标签"可以自定义：
材质（如金粒、绿宝石）
自定义名称格式（支持 %price% 变量）
Lore 描述
自定义模型数据（Custom Model Data）

安装步骤
第一步：安装前置插件

确保服务器已安装并正常运行以下插件：
Shopkeepers v2.23.9+（在 plugins/ 目录下确认 jar 文件存在）
ProtocolLib v5.1.0+（同样确认 jar 文件存在）
Vault + 任意经济插件如 EssentialsX（可选但推荐）
第二步：下载 Shopkeepers Addon

从 SpigotMC 或 Modrinth 下载最新版 jar 文件。
第三步：放入插件目录

将 ShopkeepersAddon-x.x.x.jar 放入服务器的 plugins/ 文件夹。
第四步：重启服务器

完整重启（不要使用 /reload），启动日志中应看到 Shopkeepers Addon 成功启用。
第五步：验证安装
执行 /plugins 确认插件状态为 enabled
执行 /shops 确认 GUI 菜单能正常打开
检查控制台是否显示 Economy provider set to: xxx
第六步：按需配置

编辑 plugins/ShopkeepersAddon/config.yml，调整经济设置、价格格式、传送预热等参数，保存后执行 /sna reload 生效。

与 Shopkeepers 本体的关系

| 功能 | Shopkeepers（本体） | Shopkeepers Addon（本插件） |
| :--- | :--- | :--- |
| 创建/编辑商店 | ✅ 核心功能 | ❌ 不提供 |
| 以物易物交易 | ✅ 原生支持 | 由 Addon 接管升级为金币交易 |
| 金币买卖 | ❌ 不支持 | ✅ 核心功能 |
| GUI 导航菜单 | ❌ 无 | ✅ 核心功能 |
| 商店传送 | ❌ 无 | ✅ 核心功能 |
| 商店列表/搜索 | 基础命令 | ✅ 图形化搜索 |
| 批量交易 | ❌ 无 | ✅ Shift+点击 |
| 每日限额 | ❌ 无 | ✅ 可配置 |
| 物品黑名单 | ❌ 无 | ✅ 可配置 |
简单来说：Shopkeepers 负责"建商店"，Addon 负责"用金币买卖 + 找商店更方便"。两者缺一不可。