商店配置
商店文件放在插件目录的 shop/ 目录下。每个 YAML 文件对应一个商店，文件名不作为商店 ID，实际 ID 由文件中的 id 字段决定。
商店数据会根据
id保存。商店正式开放后不要修改id，否则可能导致已有购买数据无法对应。
文件结构
商店配置主要由以下部分组成：
- 商店基础字段：商店标题、权限、界面大小、全局折扣和打开/关闭界面时执行的指令。
items：商品列表，每个键对应一个商品。- 商品购买条件、货币、限购、时间、奖励物品和购买后指令均在商品节点中配置。
商店基础字段
| 配置键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
id | 字符串 | 无 | 商店 ID，用于打开商店、购买商品和保存数据。不能为空，正式使用后不要修改。 |
name | 字符串 | 无 | 商店界面标题。不能为空，支持 & 颜色代码。 |
permission | 字符串 | 未限制 | 打开该商店所需的权限。删除该键后不限制权限。 |
size | 整数 | 6 | 商店行数。实际会限制在 1-12 之间，每行 9 个槽位。 |
discount | 字符串列表 | 空列表 | 商店全局折扣条件。 |
open-shop-command | 字符串列表 | 空列表 | 打开商店界面时执行的指令。 |
close-shop-command | 字符串列表 | 空列表 | 关闭商店界面时执行的指令。 |
当 size 大于 6 时，界面会超过 Minecraft 原版常见容器大小，使用前应确认服务端和客户端能够正常显示。
全局折扣
折扣格式为：
yaml
discount:
- 'permission:{lshop.buy.7}<->0.12'格式说明：
text
判断条件<->折扣倍率判断条件支持 PlaceholderAPI 表达式和权限判断。倍率 1 表示原价，0.5 表示五折，0.12 表示按原价的 12% 计算。
商店全局折扣会与商品自身的 discount 一起计算。多个条件同时满足时，使用更低的折扣倍率。购买货币最终数量会按折扣计算后向上取整。
打开和关闭指令
指令前缀决定执行身份：
yaml
open-shop-command:
- '[console]spawn %player_name%'
- '[op]spawn %player_name%'
- '[player]spawn %player_name%'
close-shop-command:
- '[console]spawn %player_name%'
- '[op]spawn %player_name%'
- '[player]spawn %player_name%'[console]：以控制台身份执行。[op]：以玩家临时拥有 OP 权限的身份执行。- 无前缀或
[player]：以玩家身份执行。
打开或关闭指令如果会直接打开新界面，可能与当前界面切换产生冲突。
商品配置
商品配置位于 items 下。商品键是商品内部名称，商品实际显示位置由 slot 决定。
yaml
items:
'商品1':
slot: 0
show-item: 'MythicMobs#测试'商品字段
| 配置键 | 类型 | 默认值 | 说明 |
|---|---|---|---|
slot | 整数 | 无 | 商品所在槽位，从 0 开始。第一行是 0-8，第二行是 9-17，依此类推。缺少该键的商品不会载入。 |
show-item | 字符串或物品节点 | 无 | 商品在商店界面中显示的物品。 |
give-item | 字符串 | 空字符串 | 购买成功后发放给玩家的物品。删除或留空时不发放物品。 |
amount | 整数 | 1 | 展示物品数量以及购买后发放物品的数量。 |
force-need-slot | 布尔值 | true | 是否要求玩家背包至少有一个空槽位。 |
show-condition | 字符串列表 | 空列表 | 商品显示条件。不满足时商品不会显示，也不能通过购买流程购买。 |
buy-condition | 字符串列表 | 空列表 | 购买前置条件。不满足时不能购买。 |
buy-currency | 字符串列表 | 空列表 | 购买时消耗的货币或物品。 |
buy-success-message | 字符串列表 | 使用全局消息 | 购买成功后发送给玩家的消息。配置为空列表时不会回退到全局成功消息。 |
buy-fail-message | 字符串列表 | 使用全局消息 | 购买失败后发送给玩家的消息。配置为空列表时不会回退到全局失败消息。 |
discount | 字符串列表 | 空列表 | 当前商品的折扣条件，会与商店全局折扣共同计算。 |
buy-command | 字符串列表 | 空列表 | 购买成功后执行的指令。 |
weight-command | 节点 | 空节点 | 购买成功后按权重随机执行的指令组。每个分组最多随机执行一个配置项。 |
continuous-buy-command | 字符串列表 | 空列表 | 连续购买完成后执行的指令，可使用 {count} 获取本次成功购买次数。 |
right-click-max-buy-count | 整数 | config.yml 中的 default-right-buy-count | 普通右键一次最多连续购买次数。 |
shift-left-click-max-buy-count | 整数 | config.yml 中的 default-shift-left-buy-count | Shift+左键一次最多连续购买次数。 |
shift-right-click-max-buy-count | 整数 | config.yml 中的 default-shift-right-buy-count | Shift+右键一次最多连续购买次数。 |
player-limit-tag | 节点 | 空节点 | 个人限购标记及该商品的购买上限。标记必须先在 config.yml 的 player-tag 中注册。 |
server-limit-tag | 节点 | 空节点 | 全服限购标记及该商品的购买上限。标记必须先在 config.yml 的 server-tag 中注册。 |
extra-lore | 字符串列表 | 空列表 | 追加到商品展示物品 Lore 的内容。 |
can-be-purchased-time-start | 字符串 | 无限制 | 商品开始允许购买的时间。 |
can-be-purchased-time-end | 字符串 | 无限制 | 商品结束允许购买的时间。 |
every-day-open-time | 字符串 | 00:00-23:59 | 每天允许购买的时间段。 |
展示物品
物品节点
show-item 可以写成物品节点，并配置物品 ID、名称和 Lore：
yaml
show-item:
id: '160:0'
name: '&a按钮'
lore:
- ''
- '&7这是一个简单的按钮'物品节点支持以下字段：
| 字段 | 说明 |
|---|---|
id | 原版物品 ID 与数据值，格式如 160:0。 |
name | 展示名称，支持 PlaceholderAPI 和 & 颜色代码。 |
lore | 展示 Lore 列表，支持 PlaceholderAPI 和 & 颜色代码。 |
物品库格式
当使用物品库物品时，可以直接把 show-item 和 give-item 写成字符串：
yaml
show-item: 'MythicMobs#测试'
give-item: 'MythicMobs#测试'项目中确认支持的物品库前缀包括：
MythicMobs#NeigeItems#SX-Item#
是否能够正常生成物品取决于对应物品库是否已安装并正常运行。
追加 Lore
extra-lore 的普通文本会追加到展示物品 Lore 中，支持 & 颜色代码。以下占位内容会被替换为对应信息：
| 占位内容 | 说明 |
|---|---|
{物品信息} | 追加原展示物品已有的 Lore。 |
{购买条件} | 追加 buy-condition 中 <-> 前的显示文本。 |
{购买货币} | 追加购买货币及折扣后的实际需求数量。 |
{限购信息} | 追加个人限购、全服限购和商品时间信息。 |
yaml
extra-lore:
- ''
- '{物品信息}'
- '{购买条件}'
- '{购买货币}'
- '{限购信息}'
- '&e左键购买 &a右键连续购买'显示条件与购买条件
条件写法
项目中确认的条件写法如下：
| 写法 | 说明 |
|---|---|
papi:{%player_level% >= 0} | 使用 PlaceholderAPI 表达式判断。 |
permission:{lshop.buy} | 判断玩家是否拥有权限。 |
nopermission:{lshop.buy} | 判断玩家是否没有权限。 |
使用 PlaceholderAPI 条件时，需要安装并成功启用 PlaceholderAPI。插件会在 PlaceholderAPI 可用时注册自身变量。
show-condition
show-condition 用于控制商品是否显示。商品载入后，打开或刷新商店界面时会重新判断条件；不满足条件的商品不会显示，也不会进入购买流程。
yaml
show-condition:
- 'papi:{%player_level% >= 0}'
- 'permission:{lshop.show.1}'buy-condition
每一项最多由三段组成，使用 <-> 分隔：
text
显示文本<->判断条件<->失败提示yaml
buy-condition:
- '&7需要: 等级大于3级才可购买<->papi:{%player_level% > 3}<->&c购买失败! 你需要等级大于3级才可购买!'
- '&7需要: 拥有lshop.buy权限<->permission:{lshop.buy}<->&c购买失败! 你需要拥有lshop.buy权限!'- 第一段会在
{购买条件}中显示。 - 第二段是实际判断条件。
- 第三段为条件不满足时发送给玩家的提示，可省略。
购买货币
buy-currency 默认使用冒号 : 分隔字段。分隔符可以通过 config.yml 的 currency-split-key 修改；修改后所有货币配置都必须使用新的分隔符。
购买数量支持 PlaceholderAPI 变量和四则运算表达式，例如：
yaml
buy-currency:
- 'point:<1+(%player_level%*5)>'折扣计算后，货币数量会向上取整。项目中确认支持以下货币或消耗类型：
| 写法 | 说明 | 依赖或数据来源 |
|---|---|---|
vault:1 | 消耗 Vault 经济余额。 | Vault 及可用经济插件 |
point:1 | 消耗 PlayerPoints 点券。 | PlayerPoints |
coupon:1 | 消耗优惠券数量。 | 优惠券 API |
id:1:0:1 | 按原版物品 ID、数据值和数量消耗背包物品。 | 无额外插件 |
item:&6测试:2 | 按物品名称消耗背包物品。 | 无额外插件 |
item:&6测试:&7这是lore:2 | 按物品名称和 Lore 消耗背包物品。 | 无额外插件 |
item::&7这是lore:2 | 仅按 Lore 消耗背包物品。 | 无额外插件 |
item:contain@物品名:contain@lore:2 | 按名称和 Lore 关键词匹配。 | 无额外插件 |
item:equals@物品名:equals@lore:2 | 按名称和 Lore 完全匹配。 | 无额外插件 |
tpoint:1 | 消耗 tEconomy 点数。 | tEconomy |
tmoney:1 | 消耗 tEconomy 金钱。 | tEconomy |
tylb:1 | 消耗 tEconomy 余额类型 YLB。 | tEconomy |
nye_货币类型:1 | 消耗 NyEconomy 中指定类型的余额。 | NyEconomy |
注册货币 ID:1 | 消耗在 config.yml 的 register-currency 中注册的插件货币。 | LyShopReload |
cx:变量id:数量 | 读取并扣除 CraftX 数字变量。 | CraftX |
物品名称匹配
item 类型中，名称或 Lore 前可以使用以下匹配前缀：
| 前缀 | 说明 |
|---|---|
contain@ | 关键词匹配，包含指定文本即可。 |
equals@ | 完全匹配指定文本。 |
| 不填写前缀 | 按完全匹配处理。 |
prohibited-as-lore-for-materials 可以排除包含指定 Lore 的背包物品，使其不被统计为购买材料。该配置只对玩家背包内物品生效，不处理战利品仓库中的物品。
折扣配置
商品自身可以配置独立折扣：
yaml
discount:
- 'permission:{lshop.buy.5}<->0.5'商品折扣和商店全局折扣的判断方式相同。所有满足条件的折扣中，取最低倍率。购买货币按折扣后数量扣除，计算结果向上取整。
限购配置
限购标记必须先在插件 config.yml 中注册，再在商品中引用。
个人限购
yaml
player-limit-tag:
个人每周限购标记1: 1数字表示该玩家最多可以购买的次数。购买成功后，对应个人标记增加；标记刷新时重置为 0。
全服限购
yaml
server-limit-tag:
全服每周限购标记1: 1数字表示全服所有玩家共享的购买上限。购买成功后，对应全服标记增加；标记刷新时重置为 0。
个人标记和全服标记不能使用相同的标记 ID。全服限购商店不应同时对多个服务器开放，否则各服务器缓存可能不一致。
在 extra-lore 中使用 {限购信息} 时，插件会从 config.yml 对应标记的 display 配置读取显示文本，并替换：
| 占位符 | 说明 |
|---|---|
{now} | 当前已购买次数。 |
{max} | 当前商品配置的购买上限。 |
购买时间
商品支持三种时间限制，可以单独使用，也可以同时配置。
| 配置键 | 格式 | 说明 |
|---|---|---|
can-be-purchased-time-start | 年-月-日-时-分-秒 | 到达该时间后才允许购买。 |
can-be-purchased-time-end | 年-月-日-时-分-秒 | 到达该时间后不再允许购买。 |
every-day-open-time | HH:mm-HH:mm | 每天指定时间段内允许购买。 |
yaml
can-be-purchased-time-start: '2022-12-3-5-25-20'
can-be-purchased-time-end: '2032-12-3-6-25-20'
every-day-open-time: '00:00-23:59'can-be-purchased-time-start 和 can-be-purchased-time-end 的时间格式需要包含年、月、日、时、分、秒六段。every-day-open-time 使用 24 小时制；删除该配置时默认全天开放。
时间信息可以通过 {限购信息} 显示。显示文本由 config.yml 中以下配置控制：
lore-replace.open-timelore-replace.can-be-purchased-time-startlore-replace.can-be-purchased-time-end
购买后奖励
发放物品
配置 give-item 后，购买成功时会生成并发放指定物品；amount 控制发放数量。
yaml
give-item: 'MythicMobs#测试'
amount: 1成功与失败消息
yaml
buy-success-message:
- '&a购买成功。'
buy-fail-message:
- '&c购买失败。'当商品没有配置对应消息节点时，使用 config.yml 中的全局消息：
message.购买成功message.购买失败message.连续购买message.上限
如果商品显式配置为空列表，则不会使用对应的全局消息。
普通购买指令
yaml
buy-command:
- '[console]spawn %player_name%'
- '[op]spawn %player_name%'
- '[player]spawn %player_name%'指令会先处理 PlaceholderAPI 占位符，再处理计算片段。支持以下计算片段：
| 写法 | 说明 |
|---|---|
eval:{表达式} | 计算表达式并替换为结果。 |
ceil:{表达式} | 计算表达式并向上取整。 |
floor:{表达式} | 计算表达式并向下取整。 |
表达式可以使用 ~ 指定 Java 格式化模板，例如 eval:{1+2~%.0f}。指令执行是否同步由 config.yml 的 sync-command 控制。
权重指令
weight-command 可以配置多个独立分组。每个分组根据数字权重随机选择一条或一组指令执行；不同分组分别进行随机选择。
yaml
weight-command:
权重组1:
- '30#[console]tell %player_name% 权重组1的指令1'
- '30#[op]tell %player_name% 权重组1的指令2'
- '30#[player]tell %player_name% 权重组1的指令3'每项格式为：
text
权重#[执行身份]指令连续购买指令
普通右键、Shift+左键或 Shift+右键触发连续购买时，插件会在连续购买结束后执行 continuous-buy-command。其中 {count} 会替换为本次实际成功购买的次数。
yaml
continuous-buy-command:
- '[console]tell %player_name% 本次购买了{count}次'点击购买
商品界面支持以下点击方式：
| 操作 | 说明 |
|---|---|
| 左键 | 购买一次。 |
| 右键 | 连续购买，次数上限由 right-click-max-buy-count 控制。 |
| Shift+左键 | 连续购买，次数上限由 shift-left-click-max-buy-count 控制。 |
| Shift+右键 | 连续购买，次数上限由 shift-right-click-max-buy-count 控制。 |
连续购买会在任意一次购买失败时停止；如果之前已经成功购买过，则按实际成功次数执行连续购买消息和 continuous-buy-command。
所有商品界面点击都受 config.yml 中 click-cooldown 的毫秒级冷却限制。
数据保存与 MySQL
插件默认使用 YAML 保存玩家货币和限购数据。启用 config.yml 中的 mysql.enable 后，玩家货币、个人限购标记和全服限购标记会改为使用 MySQL 保存。
使用 MySQL 存储时，必须安装 LyMySQLCore，并且 LyMySQLCore 成功连接数据库后，相关功能才会生效。MySQL 连接失败时，插件会自动卸载；服务器初始化完成前，玩家登录也可能被拒绝。
MySQL 配置修改后需要重启服务器：
yaml
mysql:
enable: false
databasename: mc2
username: mc2
password: mc1234
port: 3306
ip: 127.0.0.1无论使用 YAML 还是 MySQL，插件都会保存注册货币和限购标记数据，并在玩家重新进入服务器时加载。限购刷新时间支持秒级配置；服务器检查存在时间跳过时，会根据时间戳补偿刷新点。
相关依赖
插件清单中声明的可选对接插件包括：
- PlaceholderAPI
- Vault
- NeigeItems
- SX-Item
- MythicMobs
- LyMySQLCore
- SX-Attribute
不同货币类型和物品格式需要对应插件正常运行。未安装对应插件时，相关货币、变量或物品无法正常处理。