ErrorShop

# ErrorShop 0.18.1｜轻量系统商店 + 玩家市场 + 自定义菜单｜支持 XConomy 与群组服 (https://github.com/error0403/ErrorShop/actions/workflows/build.yml/badge.svg)](https://github.com/error0403/ErrorShop/actions/workflows/build.yml) !(https://img.shields.io/badge/version-0.18.1-orange) !(https://img.shields.io/badge/Paper-1.21.11-2f88d8) !(https://img.shields.io/badge/Java-21-ed8b00) !(https://img.shields.io/badge/license-MIT-green) > 想快速搭建官方商店、玩家自由市场、VIP/SVIP 上架额度和功能菜单，又不想从一开始就部署数据库？ErrorShop 默认使用本地 YAML 即装即用，需要群组服时再切换 MySQL + Redis。 - **当前版本：** `0.18.1` - **推荐环境：** Paper `1.21.11` + Java `21` - **实测经济：** Vault `1.7.3-b131` + XConomy Paper `2.26.3` - **开源协议：** MIT - **源码与完整手册：** <https://github.com/error0403/ErrorShop> - **云端构建：** <https://github.com/error0403/ErrorShop/actions/workflows/build.yml> - **下载方式：** MineBBS 帖子附件优先；开发构建可从 GitHub Actions 获取 --- ## 插件简介 ErrorShop 是一个面向 Paper 服务器的配置驱动商店插件，包含三部分： 1. **官方商店**：通过 `shops/*.yml` 配置商品、价格、金币/点券组合和访问权限。 2. **玩家市场**：玩家自行定价上架，支持购买、搜索、分页、税率、下架和背包满暂存。 3. **自定义菜单**：通过 `menus/*.yml` 制作主菜单、功能导航、传送入口或商店入口。 默认单服模式不需要 MySQL、Redis、Vault 或 PlayerPoints，适合先搭界面和测试流程；正式启用金币交易时，再安装 Vault 与经济插件并切换配置。 ## 为什么选择 ErrorShop | 常见需求 | ErrorShop 的处理方式 | | --- | --- | | 想快速做官方商店 | 一个商店对应一个 YAML 文件，无需写代码 | | 想让玩家自由交易 | 手持物品执行 `/errorshop sell <价格>` 即可上架 | | VIP/SVIP 需要更多摊位 | 按权限组配置不同 `slots`，匹配多个组时取最大值 | | 市场商品太多 | 每页 45 件，支持按材质、显示名和卖家搜索 | | 卖家离线或在其它子服 | 优先通过 Vault `OfflinePlayer` 入账，失败则持久化待结算 | | 买家背包满 | 商品进入待领取队列，重新登录或 `/errorshop claim` 领取 | | 两个子服同时买同一商品 | MySQL 模式先锁定商品，仅成功锁定的一方继续成交 | | 不想数据库拖慢主线程 | 市场 MySQL/YAML I/O 异步执行，背包与经济操作保持同步线程 | | 想统一服务器功能入口 | 自定义菜单支持玩家、控制台、商店、市场、菜单和消息动作 | ## 0.18.1 最近更新 - 新增 `/errorshop claim`，玩家清出背包空间后可主动领取暂存物品。 - 新增 `errorshop.market.claim` 权限，默认所有玩家拥有。 - 增加领取中、领取成功、队列为空和背包仍满等中文提示。 - 手动领取复用异步存储、同步背包操作和玩家级操作互斥，兼容本地 YAML 与 MySQL 市场。 此前 `0.18` 已完成： - 重构玩家市场成交顺序：锁定商品后扣款，再提交成交。 - MySQL 模式下，成交状态、买家待发物品和卖家税后收益在同一事务中写入。 - 增加价格上下限、小数位、税率和异常旧价格校验。 - 增加 45 格分页与 `/errorshop market <关键词>` 搜索。 - 加强重复点击、过期锁、退款、待发货和离线收益提示。 - 在 Paper `1.21.11-132`、Vault `1.7.3-b131`、XConomy Paper `2.26.3` 完成干净启动验证。 ## 核心功能 ### 1. 官方商店 - 每个 `shops/*.yml` 文件对应一个商店。 - 可配置材质、显示名、Lore、数量、金币价格、点券价格和商店权限。 - 支持 Vault 金币、PlayerPoints 点券，以及 `and` / `or` 双经济模式。 - 商品点击按配置 ID 绑定，不会仅凭相同材质误匹配其它商品。 - 可配置购买后是否关闭商店界面。 > 当前版本的官方商店实现的是**购买**。配置模型中的 `sell` 为预留字段，尚未提供玩家向官方商店回收物品的交互；`/errorshop sell` 表示上架玩家市场。 ### 2. 玩家市场 - 玩家手持物品执行 `/errorshop sell <价格>` 上架。 - 普通玩家、VIP、SVIP 可按权限设置不同上架数量。 - 54 格市场界面，其中每页展示 45 件商品。 - `/errorshop market <关键词>` 可搜索材质、显示名或卖家名。 - 买家左键购买；卖家对自己的商品在 5 秒内右键两次确认下架。 - 支持最低价格、最高价格、小数位限制和市场税率。 - 下架返还或购买发货时若背包空间不足，物品会安全进入待领取队列。 - 玩家重新上线时自动尝试发放，也可执行 `/errorshop claim` 手动领取。 ### 3. 成交安全与异常恢复 MySQL 群组市场的主要成交顺序： ```text 点击购买 → 锁定商品 → 校验价格与余额 → 扣除买家金币 → 原子提交：已售状态 + 买家待发物品 + 卖家税后收益 → 发放物品并尝试向卖家入账 → 背包满或经济服务暂不可用时保留到持久化队列 ``` - 同一商品只能由成功取得锁的一台服务器继续处理。 - 超过 `market.reservation-timeout-seconds` 的异常锁会自动回收。 - 成交尚未提交时会尝试退款；无法立即退款时写入待结算队列。 - 每名玩家同时只处理一个市场操作，降低重复点击造成的竞态。 - 本地 YAML 与 MySQL 后端都将存储 I/O 移出 Paper 主线程。 ### 4. 群组服共享市场 - 多个子服可共用同一个 MySQL 玩家市场。 - 商品、状态、离线收益和待发物品统一存储。 - Redis 作为可选市场事件总线，可广播上架、购买、下架等事件。 - `cluster.group` 用于区分服务器组，`cluster.server-id` 必须在同组内唯一。 - MySQL 是商品数据源；Redis 断开不会变成另一份商品数据库。 ### 5. 自定义菜单 - 可创建多个 `menus/*.yml`，用于主菜单、功能导航、传送入口或活动入口。 - 支持按字符布局 GUI，并分别配置左键、右键或通用动作。 - 可用动作：``、``、``、``、``、``。 - `menu.allow-console-actions: false` 可统一禁用控制台权限动作。 - 支持 MiniMessage，并兼容传统 `&` 颜色代码。 ## 兼容性与依赖 | 项目 | 状态 | | --- | --- | | 服务端 | Paper / Paper 兼容分支 | | 推荐版本 | Paper `1.21.11` | | 编译目标 | Paper API `1.21.11-R0.1-SNAPSHOT` | | Java | `21` | | Vault | 可选；启用真实金币交易时需要 | | XConomy | 可选；已验证 Paper `2.26.3` 经 Vault 接入 | | PlayerPoints | 可选；启用点券时需要 | | MySQL | 可选；群组共享市场时使用 | | Redis | 可选；群组市场事件通知时使用 | | PlaceholderAPI | 可选软依赖；当前没有 ErrorShop 自定义变量 | | License | MIT | > 插件以 Paper `1.21.11` 为当前开发和验证基线。其它 `1.21.x` 兼容分支建议先在测试服验证；升级前请备份 `plugins/ErrorShop/`。 ## 快速安装 1. 准备 Java `21` 和 Paper `1.21.11`。 2. 下载 `ErrorShop-0.18.1.jar`，放入服务器 `plugins/`。 3. 启动服务器一次，生成默认配置。 4. 编辑 `config.yml`、`shops/*.yml`、`menus/*.yml` 和 `lang.yml`。 5. 重启服务器，或执行 `/errorshop reload`。 默认单服预览配置： ```yaml currency: provider: none market: backend: local cluster: enabled: false ``` `currency.provider: none` 只适合预览与测试，不会真实扣除金币。正式服使用 XConomy 时： 1. 安装 Vault 与 XConomy。 2. 确认两者均正常启用。 3. 修改： ```yaml currency: provider: vault ``` 启动日志应出现类似： ```text Vault economy provider connected: me.yic.xconomy.depend.economy.Vault ``` ## 玩家市场配置示例 ### 单服 YAML 市场 ```yaml market: backend: local min-price: 0.01 max-price: 1000000000 price-decimals: 2 tax-rate: 0.05 reservation-timeout-seconds: 60 groups: default: slots: 9 vip: permission: "errorshop.market.vip" slots: 18 svip: permission: "errorshop.market.svip" slots: 27 ``` ### MySQL + Redis 群组市场 ```yaml market: backend: mysql fail-policy: "disable-market" reservation-timeout-seconds: 60 cluster: enabled: true group: "sur