常见问题

插件支持哪些 Minecraft 版本？

项目使用 paper-api:1.16.5-R0.1-SNAPSHOT 编译，并在 plugin.yml 中声明 api-version: 1.13。项目代码同时提供旧版数字物品 ID 与新版英文物品 ID 的兼容处理。

实际运行时仍应以服务器核心、属性插件和其他前置插件的兼容情况为准。

玩家无法进入服务器，提示插件尚未加载完成怎么办？

插件会在以下情况禁止玩家登录：

插件授权尚未完成。
mysql.enable 为 true，但数据库连接尚未建立。

如果启用了 MySQL，必须安装 LyMySQLCore，并确保数据库连接成功。只有 LyMySQLCore 已安装且数据库成功连接后，玩家数据读取和相关功能才会正常生效。

`/lykp` 没有显示完整指令怎么办？

插件验证完成后才会加载完整功能。验证未完成时，帮助信息只会显示重载指令，并提示更多指令需要验证通过后显示。

完整帮助信息只会对管理员发送。当前代码没有为这些子命令注册独立的权限节点，而是通过管理员身份判断是否允许执行。

卡牌收集界面打不开怎么办？

确认执行的是以下指令：

指令	作用	执行要求
`/lykp open`	打开全部卡组收集界面	玩家执行
`/lykp open <卡组 ID>`	打开指定卡组收集界面	玩家执行，卡组 ID 必须存在

卡组 ID 使用卡组配置文件根节点的 id 值，而不是文件名或 show-name。例如示例卡组的 ID 是 四圣，对应指令为：

text

/lykp open 四圣

如果提示卡组不存在，请检查卡组文件是否放在插件目录的 cards 文件夹内，并确认 id 与指令中的内容完全一致。执行重载后，插件会重新读取卡组文件。

卡池界面打不开怎么办？

使用以下指令打开指定卡池：

text

/lykp lottery <卡池 ID>

卡池 ID 使用卡池配置文件根节点的 id 值。例如示例卡池的 ID 是 四圣：

text

/lykp lottery 四圣

如果提示卡池不存在，请检查卡池文件是否放在插件目录的 lottery 文件夹内，并确认配置中的 id 没有重复或拼写错误。

玩家抽卡提示“条件不足”怎么办？

抽奖前会依次检查卡池中的条件、物品和离渊商店货币。以下任意一项不满足，都会使用 message.not-condition：

condition 中的所有条件。
take-item 中要求的物品和数量。
lyshop 中要求的货币和数量。

示例卡池使用了以下条件：

yaml

condition:
  - 'papi:{%player_level% > 0}'
  - 'permission:{lykp.lottery.四圣}'

如果使用 permission:{...}，请确认玩家拥有配置中的权限节点。如果使用 papi:{...}，请确认已安装并启用 PlaceholderAPI，且变量返回值可以参与当前表达式判断。

抽奖时提示金币不足或点券不足怎么办？

抽奖会分别检查 vault 和 point 配置的消耗：

配置键	功能	前置
`vault`	扣除 Vault 经济余额	Vault 以及可用的经济服务
`point`	扣除 PlayerPoints 点券	PlayerPoints

对应提示信息由以下配置项控制：

配置键	默认提示
`message.not-eco`	`金币不足!`
`message.not-point`	`点券不足!`

如果没有对应前置，抽奖中使用该消耗类型时无法正常完成检查或扣除。排查时可以先将对应配置改为 0，确认卡池的其他条件和奖励配置正常后，再接入经济或点券系统。

`take-item` 明明有物品，仍然提示条件不足怎么办？

take-item 按物品显示名检查玩家背包中的物品，不是只按物品材质或数字 ID 检查。

配置格式为：

yaml

take-item:
  - '&6四圣符咒#1'

其中 # 前是物品显示名，# 后是需要的数量。请确认：

玩家背包中的显示名与配置完全一致。
颜色代码转换后的名称一致。
数量达到配置要求。
配置格式中包含数量分隔符 #。

抽奖成功后，插件会从玩家背包中扣除对应显示名和数量的物品。

抽奖结果为什么不是固定顺序？

卡池奖励使用 weight 权重随机抽取，不是按照配置文件顺序发放。每次抽取时，插件会根据可参与奖励的权重计算结果。

当 can-repeat 为 false 时，已经拥有的卡牌不会继续参与本次随机权重计算；当玩家已经拥有该卡池的全部卡牌时，插件会发送 message.lottery-empty，并禁止继续抽取。

`can-repeat` 配置的含义是什么？

can-repeat 控制卡池是否允许重复抽取：

配置值	行为
`true`	已拥有的卡牌仍可被抽中，并执行 `repeat-command`。抽中重复卡牌时，展示名称会替换 `{status}`。
`false`	已拥有的卡牌不再参与抽取。玩家收集完该卡池全部卡牌后，无法继续抽取。

卡池展示名称中的 {status} 会在重复抽中时替换为 repeat-status 的内容。

右键卡牌物品没有反应怎么办？

卡牌配置中的 use 必须为 true，并且玩家手持物品的显示名必须与卡牌的 show-name 完全一致。

示例：

yaml

card:
  '朱雀':
    show-name: '&c天地四圣 · 朱雀'
    use: true

右键时插件会检查主手物品是否有显示名，并按照显示名匹配卡牌。匹配成功后会取消交互事件、扣除一件物品并尝试给予卡牌。

如果卡牌已经拥有，还要检查 can-it-be-reused：

true：可以再次扣除物品，并执行重复获得卡牌的处理。
false：重复右键不会再次获得该卡牌，也不会继续扣除物品。

卡牌首次获得和重复获得的指令没有执行怎么办？

卡牌配置中有两组指令：

配置键	触发时机
`first-command`	玩家首次获得该卡牌时执行
`report-command`	玩家已经拥有该卡牌，再次获得时执行

指令由控制台执行，并会经过 PlaceholderAPI 变量替换。请确认：

指令内容不包含不必要的开头 /。
PlaceholderAPI 已安装并启用。
卡牌 ID 没有写错。
玩家数据已经成功加载。

共鸣属性没有生效怎么办？

先确认 resonance.<共鸣 ID>.cards 中填写的卡牌 ID 与 card 下的节点名一致。例如：

yaml

card:
  '朱雀':
    attribute:
      - '攻击力1'

resonance:
  '水火双圣':
    cards:
      - '朱雀'
      - '玄武'
    attribute:
      - '攻击力5'

共鸣只有在需求列表中的所有卡牌都已收集时才会激活。只缺少一张卡牌，共鸣属性就不会加入玩家属性列表。

共鸣首次激活时会执行 first-command。共鸣本身没有单独的重复激活指令配置。

卡牌属性没有生效怎么办？

检查 attribute-plugin 是否选择了实际安装并启用的属性系统：

值	属性系统
`0`	不选择已实现的属性接入类型
`1`	AP
`2`	SX2.0
`3`	SX3.0
`5`	ILO
`6`	AS

卡牌的 attribute 和共鸣的 attribute 会被汇总后定时同步到所选属性系统。配置中的属性格式必须能被对应属性插件识别。

如果使用 attribute-plugin: 5，代码还会读取 ilo-update-task 作为 ILO 属性更新间隔；项目示例配置未提供该键时，代码使用默认值 20。

卡牌界面中的收集状态显示不正确怎么办？

卡牌和共鸣界面的收集状态分别使用以下配置项：

配置键	用途
`status-format-collect`	已收集或已激活时显示的符号
`status-format-not-collect`	未收集或未激活时显示的符号

示例配置为：

yaml

status-format-collect: '&a√'
status-format-not-collect: '&c×'

卡牌界面会根据玩家当前数据替换卡牌信息中的 {collect}。共鸣界面会在需求卡牌全部收集后显示已激活状态。

卡牌属性已经修改，但界面没有变化怎么办？

确认修改的是正在读取的卡组文件，并执行：

text

/lykp reload

重载时会重新读取 config.yml、cards 文件夹中的卡组文件和 lottery 文件夹中的卡池文件。配置修改后建议重新打开界面，不要继续使用修改前已经打开的旧界面。

`/lykp reload` 执行后配置仍然没有生效怎么办？

按以下顺序检查：

文件是否放在插件目录下正确的 cards 或 lottery 文件夹。
YAML 缩进、引号和列表格式是否正确。
配置中的 id、卡牌 ID、共鸣需求 ID 是否一致。
控制台是否出现对应卡组或卡池的载入信息。
修改后是否重新打开卡牌或抽奖界面。

卡组和卡池只会读取文件夹中的 YAML 文件。文件内容格式错误或关键节点缺失时，可能导致对应内容无法正常载入。

玩家重进服务器后卡牌丢失怎么办？

先确认当前使用的是哪种数据存储方式：

配置	存储方式
`mysql.enable: false`	保存到插件目录下 `playerdata/<玩家 UUID>.yml`
`mysql.enable: true`	保存到 MySQL 数据库

本地 YAML 存储会在玩家加入时读取数据，退出时保存数据。代码还会为本地数据保存临时文件和备份文件，并在主文件损坏时尝试从备份恢复。

如果使用 MySQL，必须安装 LyMySQLCore，并确认数据库连接成功。数据库未连接时，插件会禁止玩家进入服务器，避免在数据未准备好时继续运行。

MySQL 开启后数据不对怎么办？

不要在服务器运行期间频繁切换 mysql.enable。切换存储方式前应先备份本地玩家数据和数据库数据，再修改配置并重启服务器。

MySQL 配置项如下：

配置键	作用
`mysql.enable`	是否启用 MySQL 存储
`mysql.databasename`	数据库名称
`mysql.username`	数据库用户名
`mysql.password`	数据库密码
`mysql.port`	数据库端口
`mysql.ip`	数据库地址

启用 MySQL 后，插件会创建以插件名称命名的数据表，并使用 player_name 和 data 保存玩家卡牌数据。必须安装 LyMySQLCore 且成功连接数据库后，这部分功能才会生效。

修改数据库配置后玩家仍然无法进入怎么办？

检查以下内容：

mysql.enable 是否确实为 true。
LyMySQLCore 是否已安装并启用。
数据库地址、端口、数据库名、用户名和密码是否正确。
数据库是否允许服务器连接。
控制台是否显示数据库连接成功。

插件在数据库模式下会检查连接状态。连接未建立时，玩家会收到“服务器未加载完成，禁止进入”的提示。

PlaceholderAPI 变量没有返回正确结果怎么办？

插件注册的变量标识符是 lykp，当前代码实现了两类变量：

变量格式	返回内容
`%lykp_state:<卡牌 ID>%`	已拥有返回 `status-format-collect`，未拥有返回 `status-format-not-collect`
`%lykp_resonance:<卡组 ID>:<共鸣 ID>%`	共鸣已激活返回 `1`，未激活返回 `0`

例如卡组文件中可以使用：

yaml

info:
  - '&c天地四圣 · 朱雀 %lykp_state:朱雀%'

如果 PlaceholderAPI 未安装或未启用，插件不会注册这些变量。变量中的卡牌 ID、卡组 ID 和共鸣 ID 必须与配置节点一致。

为什么 `%lykp_resonance:...%` 返回 `0`？

该变量返回 1 的条件是：

玩家数据已成功加载。
指定卡组 ID 存在。
指定共鸣 ID 存在于该卡组。
共鸣所需的所有卡牌都已收集。

任意条件不满足都会返回 0。共鸣 ID 只在对应卡组节点下查找，不能只填写共鸣名称而忽略卡组 ID。

卡池奖励显示名称中的 `{status}` 没有正确替换怎么办？

{status} 只用于卡池奖励的 show-name。首次抽中时会移除该占位符；重复抽中时会替换为卡池根节点的 repeat-status。

示例：

yaml

repeat-status: ' &a(已重复)'

card:
  '朱雀':
    show-name: '&c天地四圣 · 朱雀{status}'

如果卡池设置为 can-repeat: false，已拥有的奖励不会再次参与抽取，因此也不会触发重复奖励显示。

卡组或卡池物品显示异常怎么办？

物品配置支持数字 ID、数字 ID 加子 ID，以及英文材质名。项目提供了旧版数字 ID 与运行版本材质名之间的兼容转换。

例如：

yaml

item: 'BOOK:0'
show-item: '160:1'

如果物品仍然显示异常，请检查物品 ID 是否有效，并确认该物品在当前服务器版本中存在。卡牌配置中的 item 和卡池配置中的 show-item 分别控制卡牌界面与抽奖结果物品；卡池未翻开的格子使用 default-item。

玩家数据为什么在退出时保存失败？

本地 YAML 模式下，插件会在玩家退出和插件关闭时保存玩家卡牌数据。保存失败时，控制台会输出玩家本地卡牌数据保存失败的提示。

检查以下内容：

插件目录是否有写入权限。
playerdata 文件夹是否可以创建和写入。
玩家退出时插件是否被强制终止。
数据文件是否被其他程序占用。

MySQL 模式下则应优先检查 LyMySQLCore、数据库连接状态和数据库权限。

为什么抽奖界面点击后没有反应？

抽奖界面会拦截点击事件，并在点击前检查：

是否仍处于有效的抽奖界面状态。
当前点击的格子是否已经翻开。
玩家是否满足条件、物品、金币和点券要求。
卡池是否已经收集完毕且禁止重复抽取。

已经翻开的格子不能再次抽取。关闭界面后，当前界面状态会被清除。

为什么卡牌界面关闭后需要重新打开？

卡牌界面和抽奖界面状态会在关闭背包时清除。关闭后再次点击旧界面不会继续执行原来的界面操作，需要通过 /lykp open 或 /lykp lottery <卡池 ID> 重新打开。

卡牌 ID、卡组 ID 和显示名称有什么区别？

名称	来源	用途
卡组 ID	卡组文件根节点 `id`	`/lykp open <卡组 ID>`、共鸣变量
卡牌 ID	`card` 下的节点名	玩家数据、指令、共鸣需求、卡牌变量
卡组显示名称	卡组根节点 `show-name`	卡组界面标题和展示名称
卡牌显示名称	`card.<卡牌 ID>.show-name`	卡牌界面和右键物品匹配
共鸣 ID	`resonance` 下的节点名	共鸣数据和共鸣变量
共鸣显示名称	`resonance.<共鸣 ID>.show-name`	共鸣界面展示

右键使用卡牌物品时匹配的是卡牌 show-name，不是卡牌 ID。

管理员给予或扣除卡牌失败怎么办？

管理员指令如下：

指令	作用
`/lykp give <玩家> <卡牌 ID>`	给在线玩家指定卡牌
`/lykp take <玩家> <卡牌 ID>`	扣除在线玩家指定卡牌

执行要求：

发送者需要具备管理员身份。
目标玩家必须在线。
卡牌 ID 必须存在于已加载的卡组配置中。
give 不能重复给予玩家已经拥有的卡牌。
take 不能扣除玩家没有的卡牌。

首次给予、重复给予和共鸣激活时，仍会按照卡牌配置执行对应指令。

常见问题 ​

插件支持哪些 Minecraft 版本？ ​

玩家无法进入服务器，提示插件尚未加载完成怎么办？ ​

/lykp 没有显示完整指令怎么办？ ​

卡牌收集界面打不开怎么办？ ​

卡池界面打不开怎么办？ ​

玩家抽卡提示“条件不足”怎么办？ ​

抽奖时提示金币不足或点券不足怎么办？ ​

take-item 明明有物品，仍然提示条件不足怎么办？ ​

抽奖结果为什么不是固定顺序？ ​

can-repeat 配置的含义是什么？ ​

右键卡牌物品没有反应怎么办？ ​

卡牌首次获得和重复获得的指令没有执行怎么办？ ​

共鸣属性没有生效怎么办？ ​

卡牌属性没有生效怎么办？ ​

卡牌界面中的收集状态显示不正确怎么办？ ​

卡牌属性已经修改，但界面没有变化怎么办？ ​

/lykp reload 执行后配置仍然没有生效怎么办？ ​

玩家重进服务器后卡牌丢失怎么办？ ​

MySQL 开启后数据不对怎么办？ ​

修改数据库配置后玩家仍然无法进入怎么办？ ​

PlaceholderAPI 变量没有返回正确结果怎么办？ ​

为什么 %lykp_resonance:...% 返回 0？ ​

卡池奖励显示名称中的 {status} 没有正确替换怎么办？ ​

卡组或卡池物品显示异常怎么办？ ​

玩家数据为什么在退出时保存失败？ ​

为什么抽奖界面点击后没有反应？ ​

为什么卡牌界面关闭后需要重新打开？ ​

卡牌 ID、卡组 ID 和显示名称有什么区别？ ​

管理员给予或扣除卡牌失败怎么办？ ​

常见问题

插件支持哪些 Minecraft 版本？

玩家无法进入服务器，提示插件尚未加载完成怎么办？

`/lykp` 没有显示完整指令怎么办？

卡牌收集界面打不开怎么办？

卡池界面打不开怎么办？

玩家抽卡提示“条件不足”怎么办？

抽奖时提示金币不足或点券不足怎么办？

`take-item` 明明有物品，仍然提示条件不足怎么办？

抽奖结果为什么不是固定顺序？

`can-repeat` 配置的含义是什么？

右键卡牌物品没有反应怎么办？

卡牌首次获得和重复获得的指令没有执行怎么办？

共鸣属性没有生效怎么办？

卡牌属性没有生效怎么办？

卡牌界面中的收集状态显示不正确怎么办？

卡牌属性已经修改，但界面没有变化怎么办？

`/lykp reload` 执行后配置仍然没有生效怎么办？

玩家重进服务器后卡牌丢失怎么办？

MySQL 开启后数据不对怎么办？

修改数据库配置后玩家仍然无法进入怎么办？

PlaceholderAPI 变量没有返回正确结果怎么办？

为什么 `%lykp_resonance:...%` 返回 `0`？

卡池奖励显示名称中的 `{status}` 没有正确替换怎么办？

卡组或卡池物品显示异常怎么办？

玩家数据为什么在退出时保存失败？

为什么抽奖界面点击后没有反应？

为什么卡牌界面关闭后需要重新打开？

卡牌 ID、卡组 ID 和显示名称有什么区别？

管理员给予或扣除卡牌失败怎么办？