功能介绍

插件介绍

liShop 是一个面向生存服、RPG 服和多玩法服务器的通用 GUI 商店插件。

商店内容没有写死在代码中。普通商品放在 shops/，菜单布局放在 menus/，服主可以自由创建矿物、建筑、食物、装备、活动兑换或农作物商店。插件自带的农作物商店仅为配置示例，不需要时可以直接删除或替换。

除了基础购买与回收，liShop 还提供游戏内可视化编辑、每日随机商品、个人每日回收额度、动态价格、礼包商城和玩家交易所。管理员不必长期手写 YAML，也能直接把背包中的原版或 CraftEngine 物品放入商店。

兼容环境

• 当前版本：1.9.0
• 目标服务端：Paper / Leaf 26.1.2
• API 基线：Bukkit / Paper 1.21
• Java：21
• Folia：支持，插件描述中已声明 folia-supported: true
• 可选依赖：Vault、PlayerPoints、CraftEngine
• 扩展支持：PlaceholderAPI、Citizens、Redis
• Jar 不打包外部依赖

核心功能

通用 GUI 商店

• 商店数据与菜单布局分离，支持创建任意类型的商店。
• 菜单支持 1-6 行自定义大小、装饰物、跳转按钮和执行指令。
• 商品数量超过当前菜单容量时自动分页。
• 普通菜单与编辑器均提供上一页、下一页按钮。
• 左键购买、右键出售。
• Shift+左键/右键 后可在聊天中输入本次交易数量。
• 支持购买价、回收价、单次数量、库存和自动补货。
• 可按权限组设置不同的每日购买与回收上限。

游戏内编辑器

• 游戏内创建商店及对应菜单文件。
• 直接点击背包物品，将物品加入商店。
• 点击商品编辑购买价格、回收价格、数量和库存。
• 支持增加、删除和分页管理商品。
• 支持编辑普通商店、每日规则商店和独立每日随机商品池。
• 分页工具栏槽位会被保护，不会被误当成商品槽位。

CraftEngine 物品

• 编辑器保存完整 ItemStack，保留自定义名称、Lore、模型和 PDC 数据。
• 商店展示时保留 CraftEngine 物品本身的名称，不用原版材料名覆盖。
• 玩家购买后获得原始 CE 物品。
• 服务端启动完成后会延迟重新加载 CE 商品，减少插件加载顺序影响。

每日随机与每日回收

• 每天从商品池抽取指定数量的商品。
• 可设置每日商品价格、单次数量和库存。
• 管理员可强制刷新当天结果。
• 每日回收额度按玩家独立计算，不使用全服共享数量。
• 一个每日回收商店中的全部商品可以共用个人总额度。
• 玩家出售越多，回收比例逐步降低，并可配置最低比例。
• 状态按钮集中显示今日已出售、剩余额度和当前回收比例。

动态价格与防囤货

• 商品库存变化会影响购买价与回收价。
• 购买热度和出售数量会参与价格计算。
• 可配置最低、最高价格倍率和成交影响强度。
• 材料价值表可为未单独填写回收价的物品提供基础价值。
• 每日购买上限用于限制大量扫货。
• 每日回收上限和递减价格用于限制集中倾销。

玩家交易所

• 玩家可上架主手物品并输入出售总价。
• 提供市场、我的上架和过期领取箱。
• 支持取消上架、过期返还和批量领取。
• 默认按单件价格从低到高排列。
• 支持最新上架、总价从高到低等排序方式。
• 可搜索商品名称、材料名、Lore 和卖家名称。
• 显示整组价格、单件价格、近期成交均价与剩余时间。
• 同一上架记录使用独立交易锁，避免重复购买。

礼包商城与货币

• 礼包支持每日限购和永久限购。
• 支持购买成功后全服广播。
• 支持 Vault 金币和 PlayerPoints 点券。
• Vault 不可用时可启用 liShop 内置余额作为兜底。

性能与数据安全

liShop 自 1.7.0 起对交易热路径进行了重新设计：

• 普通库存、每日库存、礼包限购、每日额度、动态价格统计和补货时间保存在并发内存状态中。
• 玩家点击购买或出售时不会同步保存 runtime.yml。
• 自动保存会将所有运行状态合并为一个快照，避免多个管理器重复写盘。
• runtime.yml 与 exchange.yml 由专用后台线程保存。
• 保存时先写入临时文件，再原子替换正式文件。
• 连续保存请求会合并为最新快照。
• 插件关闭和执行重载前会等待待写数据完成。
• Vault 交易会检查 EconomyResponse，入账失败时不会删除玩家出售的物品。

数据库、Redis 与外部插件

• 支持 YAML、SQLite、MySQL 主存储及三者之间的双向迁移。
• JDBC 驱动按需下载到 plugins/liShop/lib/，通过 SHA-256 后才会加载。
• 支持 Redis 分布式交易锁，连接异常时自动降级本地公平锁。
• 支持 Citizens 原生 NPC 右键事件，可绑定菜单、每日商店、礼包、交易所或玩家指令。
• 安装 PlaceholderAPI 后自动注册余额、限购、回收额度、交易所和存储状态变量。

常用指令

指令	说明
/shop	打开种子、每日收购、农作物道具与交易所总菜单
/shop open <菜单ID>	打开指定菜单
/shop list	查看已加载菜单
/shop daily	打开独立每日随机商店
/shop bundle	打开礼包商城
/shop exchange	打开玩家交易所
/shop exchange sell <价格>	上架主手物品
/shop exchange mine	查看自己的上架
/shop balance	查看余额
/shop createshop <商店ID> [1-6行]	创建商店和菜单
/shop editor normal <商店ID>	编辑普通商店
/shop editor daily <商店ID>	编辑每日规则商店
/shop editor daily random	编辑每日随机商品池
/shop daily refresh	强制刷新每日随机结果
/shop reload	重载插件配置
/shop npc bind <ID> <动作>	绑定 Citizens NPC
/shop migrate <来源> <目标>	迁移并切换数据存储

主指令、子指令、菜单 ID、商店 ID、玩家名和常用参数均提供 Tab 补全。

主要权限

权限	默认	说明
lishop.use	所有玩家	使用商店、每日商店和交易所
lishop.bundle	所有玩家	打开礼包商城
lishop.admin	OP	创建、编辑、重载和管理余额
lishop.purchase.<组名>	按配置	使用对应权限组的每日购买上限
lishop.recycle.<组名>	按配置	使用对应权限组的每日回收上限

权限组名称、权限节点和具体额度可在 config.yml 中自定义。

配置结构

plugins/liShop/
├─ config.yml                 # 经济、交易、限购和动态价格
├─ messages.yml               # MiniMessage 提示文本
├─ advanced.yml               # 数据库、Redis、NPC 与市场规则
├─ bundles.yml                # 礼包商城
├─ daily-random.yml           # 每日随机商品池
├─ item-values.yml            # 材料基础价值
├─ shops/                     # 普通商店商品
├─ menus/                     # GUI 菜单布局
└─ datas/
   ├─ runtime.yml             # 余额、库存和每日计数
   └─ exchange.yml            # 玩家交易所数据

所有默认 YAML 均包含中文注释。菜单标题、按钮和提示消息支持 MiniMessage 渐变色与 RGB 颜色。

安装方法

1. 使用 Java 21 运行 Paper、Leaf 或兼容服务端。
2. 将 liShop-1.9.0.jar 放入服务器的 plugins/ 目录。
3. 根据需要安装 Vault、经济插件、PlayerPoints 或 CraftEngine。
4. 启动服务器，让插件生成默认配置。
5. 修改 shops/、menus/ 或直接使用游戏内编辑器。
6. 执行 /shop reload 重新加载配置。

当前说明

• Redis 分布式锁提供跨服互斥；完整快照型数据库存储不等同于跨服实时库存同步。
• 除 CraftEngine 外，配置中列出的其他物品源仍需要对应的专属解析器才能通过物品 ID 直接创建。
• 当前版本已经通过 Maven 编译和 Jar 结构检查，正式部署前建议在测试服验证数据库、Redis、经济插件、Citizens 和现有菜单配置。

适用场景

• 生存服系统商店与回收商店。
• RPG 服材料、装备和点券商城。
• 农业服种子、作物与工具商店。
• 活动服限时礼包和每日随机商品。
• 需要玩家自由定价的服务器交易市场。

liShop 的目标不是提供一套写死的商品，而是让服主通过配置和游戏内编辑器建立自己的完整经济商店体系。