宝箱配置

宝箱配置文件放在插件数据目录的 chest/ 文件夹中，每个 YAML 文件代表一个抽奖宝箱。宝箱负责定义打开方式、抽奖条件、普通奖池、稀有奖池、稀有触发机制、抽奖记录和累计抽奖奖励。

插件会读取配置中的 id 作为宝箱标识。宝箱配置修改后，需要通过插件重载使配置重新读取。默认示例宝箱在每次重载时可能被覆盖，制作新宝箱时应复制示例文件并修改副本。

基础结构

id: "示例宝箱"
title: "&6示例宝箱"
match-item-name:
  - "&6示例宝箱"
  - "&6这是第二个示例宝箱"
condition:
  1-120:
    - "item:{物品名#1}|&7需要扣除 {item}x{amount}"
normal-reward: "示例奖池"
rare-reward: "示例奖池"
lottery-log-amount: 0
trigger-rare-chance: 0.01
max-trigger-rare-reward-count: 3

配置	说明
id	宝箱唯一标识，同时用于关联奖池、玩家数据和变量。
title	抽奖界面的标题，支持使用 & 颜色代码。
match-item-name	可打开该宝箱的物品显示名称列表。玩家手持显示名称匹配的物品右键空气或右键方块时，会打开该宝箱界面。
condition	按当前抽奖次数匹配的抽奖条件。没有匹配到条件时，无法继续抽奖。
normal-reward	普通奖池的 id。每次抽奖默认从该奖池中抽取。
rare-reward	稀有奖池的 id。留空、删除或找不到对应奖池时，不启用稀有奖池。
lottery-log-amount	保存该宝箱抽奖记录的条数。大于 0 时启用记录，0 时不记录。
trigger-rare-chance	每次抽奖触发稀有奖池的随机几率。
max-trigger-rare-reward-count	该宝箱最多触发稀有奖池的次数，填写 -1 表示不限制。

宝箱也可以绑定到方块作为入口。原有绑定功能通过 /lycj addblock [宝箱id] 开始绑定，随后右键目标方块即可保存绑定；已绑定方块右键时会打开对应宝箱界面。绑定数据保存在插件目录的 chestblock.yml 中。

打开方式

手持物品打开

玩家手持物品右键空气或右键方块时，插件会检查物品显示名称是否匹配任意宝箱的 match-item-name。匹配成功后会取消原交互并打开对应抽奖界面。

匹配使用物品的显示名称，不是物品类型、物品数量或物品 Lore。配置中的 & 颜色代码会转换为游戏内颜色。

方块入口

绑定方块后，插件按世界名称和方块坐标识别入口。方块绑定关系包括以下信息：

信息	说明
宝箱 id	右键该方块时打开的宝箱。
世界名称	方块所在世界。
x、y、z	方块坐标。

一个方块只能绑定一次。删除绑定后，该方块恢复普通交互。

抽奖界面

抽奖界面为 54 格容器界面，主要区域如下：

槽位	功能
0 至 35	奖励预览区域，每页最多展示 36 个奖励。
37	上一页。
39	单次抽奖。
41	十连抽奖。
43	下一页。
45 至 53	累计抽奖奖励。

界面内的点击和拖拽会被拦截。十连抽是连续尝试最多 10 次抽奖；任意一次不满足条件、没有可用奖励或达到抽奖上限时，会停止后续抽取。

玩家数据尚未加载时，无法打开抽奖界面或进行抽奖。打开界面本身有 1 秒间隔限制，单抽和十连抽按钮还会使用 config.yml 中的 click-cooldown 进行点击冷却。

抽奖条件

condition 下的键表示适用的抽奖次数，可以写单独次数，也可以写连续范围。

condition:
  1-120:
    - "item:{物品名#1}|&7需要扣除 {item}x{amount}"
    - "papi:{%player_level% >= 0}|&7需要等级大于0"
    - "permission:{vip.1}|&7需要 vip.1 权限"
    - "nopermission:{vip.1}|&7不能拥有 vip.1 权限"
    - "eco:{1}|&7需要扣除 {amount} 金币"
    - "point:{1}|&7需要扣除 {amount} 点券"
    - "lyshop:{货币id#1}|&7需要 1 个商店货币"
    - "cx:{变量id#1}|&7需要 1 个 CraftX 变量"

条件格式	说明
item:{物品名#数量}	检查并扣除指定物品。分隔数量的字符默认是 #，可通过 config.yml 的 condition-item-key 修改。
papi:{表达式}	使用 PlaceholderAPI 变量进行条件判断。
permission:{权限}	要求玩家拥有指定权限。
nopermission:{权限}	要求玩家没有指定权限。
eco:{数量}	使用 Vault 扣除金币。
point:{数量}	使用 PlayerPoints 扣除点券。
lyshop:{货币 id#数量}	扣除离渊商店货币。
cx:{变量 id#数量}	扣除 CraftX 变量。

每一行条件都使用 | 分隔实际判断内容和不足时的提示文本：

- "item:{物品名#1}|&7需要扣除 {item}x{amount}"

| 左侧用于判断并在抽奖成功后扣除，右侧用于显示条件提示。条件中的数字部分支持使用 <> 包裹运算公式，例如：

- "eco:{<1+2>}|&7需要扣除 {amount} 金币"

抽奖时会先检查所有条件和奖池是否可用，确认可以抽取后才会扣除条件资源。当前抽奖次数从 1 开始匹配对应条件；如果没有匹配到任何键，则无法继续抽奖。

普通与稀有奖池

普通奖池由 normal-reward 指定，稀有奖池由 rare-reward 指定：

normal-reward: "示例奖池"
rare-reward: "示例奖池"

如果 rare-reward 未配置、为空或对应奖池不存在，稀有奖池功能停用。配置了稀有奖池后，插件会先根据低保规则判断，再根据 trigger-rare-chance 进行随机判断。成功触发稀有奖池后，本次抽奖从稀有奖池中抽取，并增加该宝箱的稀有抽奖次数；否则从普通奖池中抽取。

稀有奖池触发次数达到 max-trigger-rare-reward-count 后，不再触发稀有奖池。填写 -1 时不限制触发次数。

稀有抽奖触发时会发送稀有抽奖消息，并播放 config.yml 中配置的稀有奖励音效；音效配置为空时不播放。

稀有低保

lowest-rare-count 用于配置达到指定累计抽奖次数后，必定触发稀有奖池。

lowest-rare-count:
  1: "60"
  2: "100"
  3: "120"
  4-10: "50*{count}"

配置部分	说明
左侧键	第几次稀有奖池触发，支持单独次数和范围。
右侧值	达到该稀有触发次数所需的累计抽奖次数，支持 PlaceholderAPI 和运算公式。
{count}	本次需要判断的稀有触发次数。

低保判断使用宝箱的累计抽奖次数和稀有奖池触发次数。触发稀有奖池不会清空普通抽奖累计次数，因此右侧通常应填写累计抽奖次数。

当同一个键使用范围写法时，例如 4-10，表示第 4 至第 10 次稀有触发都使用该规则。

抽奖记录

lottery-log-amount: 10

配置	说明
0	关闭该宝箱的抽奖记录。
大于 0	保存指定数量的最近抽奖记录。新记录会排在最前面，超过数量后删除较旧记录。

抽奖记录通过变量 %lycj_log_宝箱id% 获取。记录格式由 config.yml 的 lottery-log-format 设置，支持以下占位符：

占位符	说明
{time}	抽奖记录时间，格式为 MM-dd HH:mm。
{name}	抽中奖励的展示名称或物品类型名称。
{amount}	抽中奖励数量。

抽奖记录会增加玩家数据读写量。如果不需要在界面或消息中展示记录，建议保持为 0。

累计抽奖奖励

accumulated-count-of-rewards 的数字节点表示累计抽奖次数。达到次数后，玩家可以在抽奖界面底部领取对应奖励。

accumulated-count-of-rewards:
  10:
    item: "CHEST:0"
    name: "&6累计抽奖{now_count}/{need_count}次礼包"
    lore:
      - ""
      - "{status}"
    slot: 1
    give-item:
      - "MM4@累计10次礼包#1"
    commands:
      - "[console]tell %player_name% 你领取了累计10次礼包"

配置	说明
数字节点	领取该奖励所需的累计抽奖次数。
item	累计奖励在界面中显示的物品。
name	显示名称。
lore	显示 Lore。
slot	领取奖励前需要的空背包格数量。
give-item	领取时发放的物品列表。格式为 插件标识@物品 id#数量。
commands	领取成功后执行的指令列表。

give-item 中的物品通过插件标识和物品 id 获取。示例配置中使用了 MM4；项目示例同时注明可使用 MM4、MM5、NI 和 SI，奖品物品还支持 SX2 展示物品格式。具体物品是否存在取决于对应插件的物品配置。

commands 支持使用 [console] 前缀执行控制台指令，示例中的 %player_name% 会传递玩家名称变量。

累计奖励占位符

name 和 lore 支持以下占位符：

占位符	说明
{now_count}	当前宝箱累计抽奖次数。
{need_count}	当前累计奖励要求的抽奖次数。
{status}	当前领取状态。

{status} 的内容由 config.yml 控制：

状态配置	默认显示	触发条件
reward-status-shortage	&7不满足要求	当前抽奖次数未达到要求。
reward-status-clickable	&a<可领取>	已达到要求且尚未领取。
reward-status-clicked	&7<已领取>	该累计奖励已经领取。

每个累计奖励只能领取一次。领取时会依次检查是否重复领取、累计次数是否达标和背包空位是否足够；任一检查失败都不会发放奖励。

玩家数据与存储

插件会保存以下宝箱相关玩家数据：

数据	说明
抽奖次数	每个宝箱独立统计。
稀有抽奖次数	用于稀有触发上限和低保判断。
奖励抽中次数	用于判断奖池奖励的最大抽取次数。
累计奖励领取记录	用于防止同一累计奖励重复领取。
抽奖记录	仅在 lottery-log-amount 大于 0 时使用。

默认使用 YAML 保存玩家数据。将 config.yml 的 mysql.enable 设置为 true 后，玩家数据会改用 MySQL 保存；数据库配置修改后需要重启服务器。

使用 MySQL 存储时，必须安装 LyMySQLCore，并且 LyMySQLCore 成功连接数据库后，相关玩家数据加载与保存功能才会生效。若数据库连接失败，不能视为 MySQL 存储已经正常启用。

相关依赖

以下功能使用对应插件提供的接口：

功能	依赖
papi:{...} 条件和变量替换	PlaceholderAPI
eco:{数量} 金币条件	Vault
point:{数量} 点券条件	PlayerPoints
lyshop:{...} 商店货币条件	离渊商店相关插件
cx:{...} 变量条件	CraftX
MySQL 玩家数据存储	LyMySQLCore，并且必须成功连接数据库
DragonCore 抽奖结果界面同步	DragonCore；同时需要在配置中启用 dragoncore-enable

配置中使用了未安装依赖提供的条件或功能时，对应功能无法正常使用；普通 YAML 玩家数据存储不要求启用 MySQL。

注意事项

• normal-reward 必须填写已加载的奖池 id，否则普通抽奖无法获得可用奖池。
• rare-reward 不是必填项；不配置时，trigger-rare-chance 和 lowest-rare-count 不会触发稀有奖池。
• condition 没有匹配当前抽奖次数时，抽奖会被判定为达到次数上限，无法继续抽取。
• 抽奖会先确认奖池中存在可抽取奖励，再扣除物品、金币或其他条件资源。
• 奖池奖励达到自身 max-count 后，不会继续出现在可抽取奖励中；奖池全部没有可用奖励时无法抽奖。
• lottery-log-amount 越大，玩家数据中的抽奖记录越多；不需要记录时应关闭。
• 默认示例配置会在重载时覆盖，正式配置不要直接修改默认示例文件。