抽奖重置版 LyLotteryReload
LyLotteryReload 是一款基于宝箱与奖池配置的抽奖插件。每个宝箱可以独立设置打开入口、抽奖条件、普通奖池、稀有奖池、低保次数、抽奖记录和累计次数奖励。
玩家可以通过指令、右键指定名称的物品或右键已绑定的方块打开抽奖界面。界面支持奖励预览分页、单抽、十连抽和累计奖励领取。抽奖时，插件先检查当前次数段对应的条件，再根据普通奖池或稀有奖池内各奖励的最终权重随机抽取结果。
MySQL 前置要求
启用 MySQL 存储时，必须安装 LyMySQLCore，并确认它已成功连接数据库。否则本插件的 MySQL 数据读取、保存、同步和相关记录不会生效。
mysql.enable 的存储模式切换需要重启服务器。
插件信息
| 项目 | 内容 |
|---|---|
| 插件名 | LyLotteryReload |
| 插件版本 | 1.0.6 |
| 作者 | 离渊 |
| 主命令 | /lycj |
| Java 版本 | Java 8 |
| 构建目标 | Paper 1.16.5 API |
| 软依赖 | PlaceholderAPI、Vault、PlayerPoints、LyMySQLCore |
版本说明
项目文件明确使用 Paper 1.16.5 API 构建，并将 Java 代码与目标版本设为 Java 8。其他 Minecraft 服务端版本未在现有项目证据中明确确认。
玩法机制
- 玩家打开一个已配置的抽奖宝箱。
- 插件根据玩家下一次抽奖次数，读取对应的
condition次数段。 - 所有条件通过后，插件判断本次是否触发稀有奖池。
- 插件计算奖池内每个可用奖励的最终权重。
- 权重小于或等于
0、已达到抽中上限的奖励不会参与本次抽取。 - 奖池存在可用奖励时，插件扣除抽奖消耗并增加抽奖次数。
- 插件执行奖励指令、发送消息、记录结果，并按配置给予物品。
十连抽并不是一次性计算十份奖励，而是最多连续尝试执行 10 次完整抽奖。中途出现条件不足、次数达到上限、背包已满或奖池无可用奖励时，会停止后续抽取。
主要功能
| 功能 | 说明 |
|---|---|
| 多宝箱配置 | chest/ 下的每个 YAML 文件可定义一个独立宝箱 |
| 多奖池配置 | reward/ 下可建立多个奖池，并通过奖池 ID 绑定到宝箱 |
| 多入口打开 | 支持指令、指定名称物品和已绑定方块打开抽奖界面 |
| 奖励预览 | 界面同时展示稀有奖池与普通奖池奖励，稀有奖池优先排列 |
| 预览分页 | 每页最多展示 36 个奖励，可使用上一页和下一页按钮翻页 |
| 单抽与十连 | 支持单次抽奖，以及最多连续尝试 10 次抽奖 |
| 分段抽奖条件 | 可按单次次数或次数范围配置不同的抽奖条件 |
| 多种消耗方式 | 支持物品、Vault 金币、PlayerPoints 点券、权限、PAPI 表达式等条件 |
| 普通奖池 | 未触发稀有机制时，从宝箱的普通奖池抽取 |
| 稀有奖池 | 可通过随机概率或累计次数低保触发稀有奖池 |
| 稀有次数上限 | 可限制一个宝箱最多触发多少次稀有奖池 |
| 动态奖励权重 | 奖励可根据 PAPI 表达式或权限条件修改当前权重 |
| 权重计算上限 | 单条权重条件可以设置本次计算后的最大权重 |
| 奖励抽中上限 | 每个奖励可以限制单个玩家最多抽中多少次 |
| 累计次数奖励 | 玩家达到指定抽奖次数后，可在界面底部领取一次累计奖励 |
| 抽奖记录 | 可按宝箱保存指定数量的最近中奖记录 |
| 数据自动保存 | 玩家数据发生变化后，按照配置间隔自动保存 |
| YAML 安全保存 | YAML 数据保存时使用临时文件与备份文件，主文件损坏时会尝试恢复 |
| MySQL 存储 | 可将玩家抽奖数据保存到 MySQL，由 LyMySQLCore 提供连接与安全事件 |
| 点击冷却 | 单抽和十连按钮共用可配置的毫秒级点击冷却 |
| 稀有提示 | 触发稀有奖池时可发送消息并播放指定 Bukkit 音效 |
| DragonCore 兼容 | 可在抽奖完成后把结果写入指定龙核槽位并调用抽奖界面方法 |
抽奖条件
宝箱的 condition 按抽奖次数配置。每条内容由条件和提示文字组成，中间使用 | 分隔。条件类内容负责检查与扣除，右侧文字用于显示本次抽奖需求。
| 条件格式 | 用途 | 是否扣除 |
|---|---|---|
item:{物品名#数量} | 按显示名称检查物品数量 | 是 |
eco:{数量} | 检查 Vault 经济余额 | 是 |
point:{数量} | 检查 PlayerPoints 点券 | 是 |
papi:{表达式} | 判断 PlaceholderAPI 表达式 | 否 |
permission:{权限} | 要求玩家拥有指定权限 | 否 |
nopermission:{权限} | 要求玩家没有指定权限 | 否 |
lyshop:{货币ID#数量} | 检查离渊商店货币 | 是 |
cx:{变量ID#数量} | 检查 CraftX 变量数值 | 是 |
item、lyshop 和 cx 格式中的分隔字符默认是 #，可以通过 config.yml 的 condition-item-key 修改。
物品条件按物品显示名称匹配。除玩家背包外，代码还包含对 YeeCore、LyLootsWareHouse 和 LyWarehouse 存储空间的统计与扣除兼容；只有服务器实际安装并启用对应插件时才会参与处理。
稀有奖池与低保
宝箱配置了有效的 rare-reward 后，才会执行稀有奖池判断。触发方式包括：
trigger-rare-chance：每次抽奖按小数概率随机触发。lowest-rare-count：当总抽奖次数达到当前稀有触发次数对应的要求时，必定触发。max-trigger-rare-reward-count：限制稀有奖池最多触发次数，设为-1表示不限制。
概率触发和低保触发都会增加玩家在该宝箱中的稀有抽奖次数。触发稀有奖池不会清空总抽奖次数，因此低保配置使用的是累计抽奖次数。
lowest-rare-count 的键支持单次数字和范围写法，需求次数支持 +、-、*、/ 与括号运算，也可以使用 {count} 表示本次准备触发的稀有次数。
奖励机制
每个奖池包含多个奖励。抽奖时，插件会先排除已达到 max-count 的奖励，再计算剩余奖励的最终权重。
| 能力 | 说明 |
|---|---|
| 基础权重 | weight，未填写时默认为 1 |
| 条件权重 | 条件满足后，可以基于当前 {weight} 重新计算权重 |
| 抽奖次数参数 | 权重公式中可使用 {count} 读取本次抽奖前的已抽次数 |
| PAPI 参与计算 | 条件表达式和权重公式可解析 PlaceholderAPI 变量 |
| 权重上限 | 条件第三段可限制本次计算后的最大权重 |
| 无效权重排除 | 最终权重小于或等于 0 时不参与本次抽奖 |
| 抽中次数限制 | max-count 为 -1 时不限次数，其他数值表示玩家抽中上限 |
| 奖励指令 | 支持普通玩家、[op] 和 [console] 三种执行方式 |
| 奖励消息 | 支持全服消息、玩家独立消息和全局默认玩家消息 |
| 展示与发放分离 | show-item 用于界面和记录，give-item 用于实际给予物品 |
奖励展示物品支持代码中登记的 MM4、MM5、NI、SI 和 SX2 类型。累计奖励的 give-item 示例明确使用 MM4、MM5、NI 和 SI。对应物品插件未安装、物品 ID 错误或格式错误时，物品无法正常展示或发放。
玩家数据
插件会按玩家记录以下内容：
| 数据 | 说明 |
|---|---|
| 宝箱抽奖次数 | 玩家在每个宝箱中的累计抽奖次数 |
| 稀有抽奖次数 | 玩家在每个宝箱中触发稀有奖池的次数 |
| 奖励抽中次数 | 玩家在指定奖池中抽中各奖励的次数 |
| 累计奖励状态 | 玩家已经领取过的累计次数奖励 |
| 抽奖记录 | 各宝箱保留的最近中奖信息 |
未启用 MySQL 时，玩家数据保存在插件目录的 data/玩家UUID.yml。保存过程会保留 .bak 备份，主文件读取失败时会尝试使用备份恢复。
启用 MySQL 后，玩家数据会序列化后保存到数据库表中。MySQL 配置变更和存储模式切换需要重启服务器。
依赖与兼容
基础软依赖
| 插件 | 用途 | 未安装时的影响 |
|---|---|---|
PlaceholderAPI | 插件变量、PAPI 条件、公式和消息变量解析 | %lycj_...% 变量不会注册，PAPI 条件无法正常使用 |
Vault | eco 金币条件与扣款 | 金币抽奖条件无法正常使用 |
PlayerPoints | point 点券条件与扣除 | 点券抽奖条件无法正常使用 |
LyMySQLCore | MySQL 连接、安全加载与保存事件 | 启用 MySQL 后相关数据功能不会生效 |
按功能安装的插件
| 插件或类型 | 用途 |
|---|---|
DragonCore | 接收单抽或十连结果槽位，并调用龙核抽奖界面方法 |
| MythicMobs 4 | 读取 MM4 类型物品 |
| MythicMobs 5 | 读取 MM5 类型物品 |
| NeigeItems | 读取 NI 类型物品 |
| SX-Item | 读取 SI 类型物品 |
| SX-Attribute | 读取 SX2 类型物品 |
| 离渊商店 | 使用 lyshop 货币抽奖条件 |
| CraftX | 使用 cx 变量抽奖条件 |
YeeCore | 从对应空间统计与扣除名称匹配物品 |
LyLootsWareHouse | 从战利品仓库统计与扣除名称匹配物品 |
LyWarehouse | 从仓库统计与扣除名称匹配物品 |
这些兼容项只在相关配置被使用时需要安装，不应当视为所有服务器都必须安装的基础前置。
指令
插件没有在 plugin.yml 中声明独立权限节点。管理操作直接检查发送者是否为服务器 OP。
| 指令 | 使用者 | 说明 |
|---|---|---|
/lycj | OP | 显示插件指令帮助 |
/lycj reload | OP | 重载主配置、示例资源、奖池和宝箱，并重启自动保存任务 |
/lycj open [宝箱ID] | 玩家 | 打开指定宝箱界面，不要求 OP |
/lycj addblock [宝箱ID] | OP 玩家 | 进入绑定状态，将下一次右键点击的方块绑定为指定宝箱 |
/lycj removeblock | OP 玩家 | 进入移除状态，解除下一次右键点击方块的宝箱绑定 |
/lycj clear [宝箱ID] [玩家] | OP | 清空在线玩家指定宝箱的抽奖次数、稀有次数、抽奖记录及关联奖池奖励次数 |
/lycj try [宝箱ID] [玩家] | OP | 控制在线玩家对指定宝箱执行一次抽奖 |
clear 和 try 只能处理在线且数据已经加载完成的玩家。open 只能由玩家执行。
打开宝箱的方式
| 方式 | 说明 |
|---|---|
| 指令 | 玩家执行 /lycj open [宝箱ID] |
| 物品名称 | 玩家右键手持物品，显示名称与宝箱的 match-item-name 完全一致时打开 |
| 绑定方块 | OP 使用 addblock 绑定后，玩家右键该方块打开对应宝箱 |
方块绑定信息保存在插件目录的 chestblock.yml。绑定和解除操作完成后会立即保存，插件关闭时也会再次保存。
抽奖界面
插件创建一个 54 格箱子界面，并按固定区域显示内容：
| 区域 | 内容 |
|---|---|
0 至 35 | 奖励预览，每页最多 36 个 |
37 | 上一页按钮 |
39 | 单抽按钮 |
41 | 十连抽按钮 |
43 | 下一页按钮 |
45 至 53 | 累计次数奖励，最多显示 9 个 |
界面会阻止玩家拿取、放入或拖拽物品。单抽和十连按钮会显示玩家当前总抽奖次数、稀有次数以及下一次抽奖条件。
每个宝箱使用自己的 title 作为实际界面标题。config.yml 中存在 gui.title，但当前界面创建逻辑没有读取该配置项。
数据与性能提示
lottery-log-amount大于0时，插件会保存对应宝箱的中奖记录。- 抽奖记录会增加玩家数据体积和进出服务器时的读写量，不需要记录时应设为
0。 auto-save-interval的单位是秒，只保存已经发生数据变化的在线玩家。- 自动保存任务使用异步调度；插件重载时会停止旧任务并启动新任务。
- 每次实际抽奖前至少需要一个背包空位。
- 累计奖励还会按照自身
slot配置检查所需空位数量。 - 奖池内所有奖励达到抽中上限或最终权重均不大于
0时，本次抽奖无法完成。
页面索引
| 页面 | 内容 |
|---|---|
| 配置说明 | config.yml、数据库、消息、保存、界面与全局设置 |
| 宝箱配置 | chest/ 宝箱、抽奖条件、稀有奖池、低保与累计奖励 |
| 奖池配置 | reward/ 奖励物品、权重、条件、上限、指令与消息 |
| 插件变量 | PlaceholderAPI 变量及 current 宝箱参数 |
| 常见问题 | 数据加载、依赖、奖池、物品和界面问题排查 |
| 更新日志 | 文档整理记录 |