常见问题

插件支持哪些版本？

项目使用 Java 8 编译，并依赖 paper-api:1.16.5-R0.1-SNAPSHOT。项目同时包含旧版数字物品 ID、英文材质名和跨版本材质兼容处理，但项目文件未明确声明完整的服务器版本范围。

打不开宝箱

可以按以下顺序检查：

1. 确认宝箱配置文件已加载，且 id 与使用的宝箱 ID 完全一致。

2. 使用指令打开时，确认执行者是玩家，并使用：

   /lycj open <宝箱id>

3. 如果使用手持物品右键打开，确认物品显示名与宝箱配置中的 match-item-name 完全匹配。配置中的 & 颜色代码会按颜色代码进行匹配，不是按物品材质匹配。

4. 如果使用绑定方块打开，确认方块已经通过 addblock 绑定到该宝箱，且绑定的宝箱 ID 仍然存在。

5. 检查是否正在执行 /lycj reload。重载期间应等待重载完成后再测试。

右键方块没有打开宝箱

绑定方块需要由 OP 执行：

/lycj addblock <宝箱id>

执行后，使用同一名玩家右键一个方块完成绑定。绑定成功后会保存方块位置，玩家右键该方块即可打开对应宝箱。

如果该方块已经绑定过宝箱，不能重复绑定。可以先执行：

/lycj removeblock

然后右键已绑定的方块删除绑定，再重新绑定。

手持物品右键没有打开宝箱

检查以下内容：

• 玩家手持物品必须有显示名称。
• 物品显示名必须与 match-item-name 中的某一项匹配。
• 颜色代码必须一致，例如配置中的 &6示例宝箱 需要对应金色显示名。
• 右键空气和右键方块都可以触发手持物品匹配，但物品本身必须存在于主手。

插件按显示名匹配手持物品，不会根据物品材质或 Lore 判断是否为开箱物品。

提示“不满足抽奖条件”

检查宝箱配置中的 condition：

• 当前抽奖次数必须落在已配置的次数段内。
• 物品、权限、金币、点券或变量条件必须全部满足。
• permission 表示玩家必须拥有权限。
• nopermission 表示玩家不能拥有该权限。
• item 条件按物品显示名统计数量。
• 条件通过后，item、eco、point、lyshop 和 cx 类型会执行对应扣除。
• papi 只用于判断变量表达式，不会作为扣费条件自动扣除数值。

如果当前抽奖次数没有匹配到任何次数段，会被当作达到抽奖上限处理，而不是继续使用最后一个次数段。

条件中的数字或公式没有生效

宝箱条件和奖品权重支持使用尖括号包裹运算公式，例如：

condition:
  1-120:
    - 'eco:{<1+2>}|需要扣除 {amount}金币'

项目确认支持整数、小数以及 +、-、*、/ 和括号运算。公式必须是合法的四则运算表达式，不能包含无法识别的字符。

item 条件中的物品名与数量使用分隔符连接，默认格式为：

item:{<物品名>#<数量>}

如果物品名本身需要使用 #，请修改 config.yml 中的 condition-item-key，并同步修改条件写法。

papi 条件判断失败

确认已安装并启用 PlaceholderAPI。papi 条件会先解析 PlaceholderAPI 变量，再判断表达式结果。

支持的判断形式包括：

• 数值比较：>、>=、<、<=
• 相等和不相等：==、!=
• 多个条件同时满足：&&
• 多个条件满足其一：||
• 布尔值：true 或 false

示例：

- 'papi:{%player_level% >= 0}|需要等级大于0'

如果变量未安装、变量未解析或表达式格式错误，条件不会满足。

物品条件找不到物品

item 条件按物品显示名匹配，不按 Lore 匹配。检查：

• 配置中的颜色代码是否正确。
• 物品是否确实拥有显示名称。
• condition-item-key 是否与条件中的分隔符一致。
• 物品是否在玩家主背包中。

如果服务器启用了 YeeCore、LyLootsWareHouse 或 LyWarehouse，插件还会从这些插件提供的物品存储中统计和扣除符合名称的物品。

金币或点券条件不生效

金币条件使用 Vault 经济接口，点券条件使用 PlayerPoints 接口：

- 'eco:{1}|需要扣除 {amount}金币'
- 'point:{1}|需要扣除 {amount}点券'

请确认对应插件已经安装并启用。项目只将 Vault、PlayerPoints 声明为软依赖，未安装时对应功能无法正常使用。

LyMySQLCore 数据没有保存

如果启用了 MySQL 存储，必须安装 LyMySQLCore，并且数据库连接成功后，相关功能才会生效。

需要检查：

• mysql.enable 是否已开启。
• LyMySQLCore 是否已安装并正常加载。
• mysql.ip、mysql.port、mysql.databasename、mysql.username 和 mysql.password 是否正确。
• 控制台是否显示数据库连接成功。
• 修改数据库开关后是否重启服务器。数据库开关需要重启服务器才能生效。

数据库连接失败时，玩家数据无法按 MySQL 流程正常加载或保存。未启用数据库时，插件使用 YAML 保存玩家数据。

玩家数据丢失或保存不及时

插件会在玩家加入、退出和被踢出服务器时加载或保存玩家数据，并按 auto-save-interval 定时自动保存。

默认配置为：

auto-save-interval: 3

该值单位为秒。YAML 保存使用临时文件、备份文件和替换机制；玩家数据文件损坏时会尝试从 .bak 备份文件恢复。

如果启用了 MySQL，请先确认 LyMySQLCore 已安装且数据库连接成功，否则 MySQL 相关保存功能不会生效。

稀有奖池没有触发

确认宝箱配置了 rare-reward，并且该奖池 ID 存在：

rare-reward: '稀有奖池ID'

然后检查：

• trigger-rare-chance 是否大于 0。
• lowest-rare-count 是否配置了当前稀有触发次数对应的保底抽奖次数。
• max-trigger-rare-reward-count 是否已经达到上限。
• 当前抽奖次数是否已经达到条件范围上限。

max-trigger-rare-reward-count 达到上限后不会继续触发稀有奖池，设置为 -1 时不限制触发次数。

通过概率触发稀有奖池后，也会增加稀有奖池触发次数。保底触发不会清空累计抽奖次数。

没有配置稀有奖池时会怎样？

如果宝箱没有配置 rare-reward，或者该字段为空，宝箱不会触发稀有奖池，也不会执行稀有奖池相关逻辑。

奖池为空

通常有以下原因：

• 奖池中的所有奖励都已达到 max-count。
• 奖励条件使最终权重变为 0。
• 奖池配置文件没有正确加载。
• 宝箱中的 normal-reward 或 rare-reward ID 不存在。

检查奖池内每个奖励的：

• weight
• condition
• max-count
• show-item
• 奖励是否仍可被抽取

当奖励达到 max-count 后，抽奖界面不会继续展示该奖励。max-count: -1 表示不限制被抽中次数。

奖励显示了，但没有获得物品

show-item 只负责抽奖界面中的展示物品，give-item 才负责实际给予玩家物品。

如果 give-item 留空或删除，抽中后不会给予对应物品，但仍可以执行 command、发送 server-message 或 player-message。

奖励物品 ID 的格式由对应物品插件决定。项目示例中确认支持：

• MM4
• MM5
• NI
• SI
• SX2

使用这些物品类型时，还需要安装并启用对应的物品插件。

奖品权重不符合预期

每个奖励先使用 weight 作为基础权重，再按 condition 从上到下计算额外权重。每个条件单独判断，符合条件时会将加成累加到当前权重。

如果最终权重为 0，该奖励不会参与本次抽奖。

条件中的权重表达式可以使用：

• {weight}：当前权重
• {count}：当前奖池的抽奖次数
• |上限：限制本次加成后的权重上限

示例：

condition:
  - 'papi:{%player_level% >= 0}|{weight}+10|200'
  - 'nopermission:{lcj.示例奖池.奖励1}|{weight}*2'

累计奖励不能领取

领取累计奖励需要同时满足以下条件：

1. 玩家在对应宝箱中的抽奖次数达到该奖励档位。
2. 该累计奖励尚未领取。
3. slot 指定的背包空位数量满足要求。
4. 奖励配置仍然存在且格式正确。

例如：

accumulated-count-of-rewards:
  10:
    slot: 1

表示玩家需要至少有 1 个背包空位。已领取的累计奖励不能重复领取。

累计奖励状态显示错误

累计奖励 Lore 中的 {status} 会根据领取状态替换为以下消息：

reward-status-shortage: '&7不满足要求'
reward-status-clickable: '&a<可领取>'
reward-status-clicked: '&7<已领取>'

如果玩家已达到次数但仍显示“不满足要求”，优先检查背包空位和该档位是否已经领取。

十连抽没有完成十次

十连抽只是尝试连续进行最多十次抽奖，不保证一定完成十次。

只要中途不满足抽奖条件、达到抽奖次数上限、奖池为空或其他抽奖条件不再满足，连续抽奖就会停止。

抽奖按钮点击没有反应

检查 click-cooldown。该配置单位为毫秒，默认值为 300：

click-cooldown: 300

短时间内重复点击会收到冷却提示：

click-cooldown: '&7对不起, 操作过快, 请稍后尝试.'

如果连续点击过快，等待冷却时间结束后再操作。

抽奖记录没有显示

宝箱必须配置大于 0 的 lottery-log-amount 才会记录抽奖记录：

lottery-log-amount: 10

记录变量格式为：

%lycj_log_<宝箱id>%

记录显示格式由 config.yml 中的 lottery-log-format 控制：

lottery-log-format: '&7[{time}] &f{name}x{amount}'

如果 lottery-log-amount 为 0，该宝箱不会启用抽奖记录。抽奖记录会产生额外数据读写，启用后玩家进出服务器时的数据量会增加。

变量显示错误或没有解析

确认已安装并启用 PlaceholderAPI。项目提供以下变量：

变量	说明
%lycj_log_<宝箱id>%	指定宝箱的抽奖记录
%lycj_lottery_count_<宝箱id>%	指定宝箱的累计抽奖次数
%lycj_rare_count_<宝箱id>%	指定宝箱的稀有奖池抽中次数
%lycj_count_reward_max_<宝箱id>%	指定宝箱累计奖励的最大档位

将 <宝箱id> 替换为实际宝箱 ID。将宝箱 ID 写为 current 时，变量会读取玩家当前打开的抽奖界面对应的宝箱。

使用 current 时，玩家必须正在打开抽奖界面；没有当前抽奖界面时无法解析对应宝箱。

重载后配置被覆盖

默认示例宝箱和示例奖池文件会在每次重载时覆盖。项目示例文件明确说明：需要创建新配置时，应复制示例文件后再修改，不要直接把默认示例文件当作正式配置使用。

如果不希望加载默认示例配置，可以关闭：

load-default-config: false

修改该配置后重新加载插件，并确认正式配置文件的 ID 不重复。

如何重载插件？

OP 可以执行：

/lycj reload

重载成功后会收到“重载成功”提示。数据库开关不是普通重载项，修改 mysql.enable 后需要重启服务器。

如何清空玩家的抽奖数据？

OP 可以执行：

/lycj clear <宝箱id> <玩家>

该指令会清除指定玩家对应宝箱的：

• 普通奖池和稀有奖池相关抽奖次数数据。
• 宝箱累计抽奖次数。
• 稀有奖池抽中次数。
• 抽奖记录。

目标玩家必须在线，宝箱 ID 必须存在。

如何让玩家直接抽奖？

OP 可以执行：

/lycj try <宝箱id> <玩家>

目标玩家必须在线，且玩家数据已加载。该指令会控制目标玩家进行一次抽奖，仍会按照宝箱本身的抽奖逻辑处理。

指令没有显示或无法使用

项目中未配置独立权限节点。指令权限主要通过 OP 身份判断：

指令	执行限制
/lycj reload	OP
/lycj addblock <宝箱id>	OP，且执行者必须是玩家
/lycj removeblock	OP，且执行者必须是玩家
/lycj clear <宝箱id> <玩家>	OP
/lycj open <宝箱id>	必须是玩家
/lycj try <宝箱id> <玩家>	OP

控制台不能执行必须由玩家执行的 open、addblock 和 removeblock 操作。

稀有奖励音效没有播放

检查 rare-reward-sound 是否配置了有效的 Bukkit 音效名称：

rare-reward-sound: 'ENTITY_PLAYER_LEVELUP'

该配置留空时不会播放稀有奖励音效。实际音效名称需要与服务器版本支持的 Bukkit Sound 名称一致。

玩家中奖后没有收到消息

插件区分全局玩家消息和奖励独立消息：

global-player-message:
  - '&a恭喜你中奖了!'

如果某个奖励配置了 player-message，则使用该奖励自己的玩家消息，不再发送全局玩家消息。奖励还可以单独配置 server-message 向全服发送公告。

检查奖励配置中的 player-message、server-message 是否为空，以及消息中的颜色代码是否正确。

奖励指令没有执行

奖励指令支持以下前缀：

前缀	执行方式
[console]	由控制台执行
[op]	临时以 OP 身份执行
无前缀	由玩家执行

奖励指令会先解析 PlaceholderAPI 变量，再执行。例如：

command:
  - '[console]bc 恭喜%player_name%抽中了测试奖品'

确认指令本身可以由对应执行者执行，并确认所使用的变量已由 PlaceholderAPI 提供。

配置文件修改后没有生效

检查以下内容：

• YAML 缩进是否正确。
• 配置键名称是否与示例文件一致。
• 宝箱 ID 和奖池 ID 是否存在且没有重复。
• 是否执行了 /lycj reload。
• 是否修改了默认示例文件，导致重载时被覆盖。
• 数据库开关修改后是否已经重启服务器。

项目配置文件使用 YAML 格式，建议保留字符串中的引号，尤其是包含颜色代码、运算符、占位符或特殊字符的配置值。