LyCard
MySQL 前置要求
启用 MySQL 存储时，必须安装 LyMySQLCore，并确认 LyMySQLCore 与本插件均已成功连接数据库。否则玩家数据加载、保存、同步及相关记录不会生效，数据库未连接完成时玩家也会被阻止进入服务器。
LyCard 是一款卡牌收集与翻牌抽取插件。玩家可以查看全部卡组或指定卡组，通过翻牌卡池、管理指令或手持卡牌物品收集卡牌。已收集的卡牌可以提供属性，多张指定卡牌全部收集后还会激活卡组共鸣与额外属性。
插件支持本地 YAML 与 MySQL 两种玩家数据存储方式，并提供卡组 GUI、分页浏览、权重抽取、重复卡牌处理、首次收集指令、共鸣激活指令和 PlaceholderAPI 变量。
插件信息
| 项目 | 内容 |
|---|---|
| 插件名 | LyCard |
| 版本 | 1.1.0 |
| 作者 | Liyuan |
| 主命令 | /lykp |
| Java 目标版本 | Java 8 |
| 插件接口版本 | api-version: 1.13 |
| 编译使用的服务端 API | Paper 1.16.5-R0.1-SNAPSHOT |
| 支持平台 | Bukkit / Spigot / Paper 系服务端 |
| 数据存储 | 本地 YAML、MySQL |
版本说明
项目使用 Bukkit 1.13 插件接口声明，并包含旧版数字物品 ID与新版英文材质名的兼容处理。现有项目证据只能确认其以 Paper 1.16.5 API 编译，无法据此保证所有 Minecraft 版本均可正常运行。
主要玩法
- 服务器配置一个或多个卡组，每个卡组包含独立卡牌与共鸣组合。
- 玩家通过
/lykp open浏览卡组，在界面中查看卡牌介绍、收集状态和共鸣状态。 - 玩家可以进入翻牌卡池，点击界面中的未翻开位置并支付配置的消耗。
- 卡池按卡牌权重抽取结果，获得的新卡牌会写入玩家数据。
- 收集卡牌后，插件定时汇总单卡属性；满足共鸣要求时，再加入对应共鸣属性。
- 首次获得卡牌、重复获得卡牌、首次激活共鸣以及翻牌结果均可触发控制台指令。
核心功能
| 功能 | 说明 |
|---|---|
| 多卡组管理 | 从 cards 目录加载多个卡组文件，并按照卡组的 index 排序。 |
| 卡组总览 | 使用 54 格 GUI 展示所有卡组，每页最多展示 45 个卡组。 |
| 卡组详情 | 在同一界面中展示卡牌与共鸣，已收集或已激活的项目会附加附魔光效。 |
| 分页浏览 | 卡组总览与卡组详情均提供上一页、下一页按钮。 |
| 卡牌收集 | 玩家数据记录已拥有的卡牌 ID，给予卡牌时会判断卡牌是否存在以及玩家是否已经拥有。 |
| 卡牌属性 | 已拥有卡牌的 attribute 会定时加入玩家属性数据。 |
| 卡组共鸣 | 玩家拥有共鸣配置要求的全部卡牌后，自动加入共鸣属性。 |
| 首次触发 | 首次获得卡牌时执行卡牌的 first-command；新卡牌补齐共鸣要求时执行共鸣的 first-command。 |
| 重复获得 | 玩家已经拥有卡牌时，给予操作返回失败，并执行该卡牌的 report-command。 |
| 翻牌卡池 | 使用 54 格 GUI 填充未翻开的卡牌位置，玩家点击后按权重抽取卡牌。 |
| 多种抽卡消耗 | 支持 Vault 金币、PlayerPoints 点券、指定名称物品，以及 LyShop 或 LyShopReload 商店货币。 |
| 重复抽取处理 | 卡池可以允许抽到已有卡牌，也可以只在玩家尚未拥有的卡牌中按剩余权重抽取。 |
| 抽卡结果指令 | 每次翻中卡牌执行 command；翻中已有卡牌时额外执行 repeat-command。 |
| 本地数据保护 | 本地玩家数据使用 UTF-8 读取，保存时生成备份并优先尝试原子替换；主文件损坏时会尝试从 .bak 恢复。 |
| MySQL 存储 | 开启后通过数据库表保存玩家名称与卡牌列表，并使用 LyMySQLCore 的安全加载、保存事件。 |
| PlaceholderAPI | 提供卡牌收集状态和卡组共鸣状态变量，卡牌说明及执行指令也支持 PlaceholderAPI 解析。 |
| 跨版本材质 | 卡组和卡池物品支持数字 ID、数字 ID 加子 ID，以及运行版本可识别的英文材质名。 |
依赖与功能联动
plugin.yml 将以下插件声明为软依赖，但具体功能仍需要对应插件正常加载。
| 插件或接口 | 用途 | 使用条件 |
|---|---|---|
PlaceholderAPI | 注册 %lykp_...% 变量，并解析卡牌说明和触发指令中的变量 | 使用变量、GUI 说明或变量指令时需要 |
LyMySQLCore | 提供 MySQL 玩家安全加载与保存事件 | 开启 mysql.enable 时必须安装 |
Vault | 扣除翻牌所需金币 | 使用卡池功能时需要可用的 Vault 经济服务 |
PlayerPoints | 扣除翻牌所需点券 | 使用卡池功能时需要正常加载 |
DZ_Status | 插件声明的软依赖之一 | 项目未提供独立配置说明 |
LyShop / LyShopReload | 扣除 lyshop 配置的商店货币 | 仅配置商店货币消耗时需要对应插件 |
| 属性插件 | 接收卡牌与共鸣产生的属性文本 | 由 attribute-plugin 选择 AP、SX2.0、SX3.0、ILO 或 AS |
卡池依赖
当前翻牌处理会读取 Vault 余额与 PlayerPoints 点券，因此使用卡池前应同时确认 Vault 经济服务和 PlayerPoints 已正常工作。仅将对应消耗配置为 0，不代表相关接口一定不会被调用。
卡牌与共鸣机制
卡牌获得
给予一张尚未拥有的有效卡牌时，插件会依次处理以下内容：
- 执行卡牌的
first-command。 - 检查该卡牌是否刚好补齐某个共鸣的全部要求。
- 对新激活的共鸣执行
first-command。 - 将卡牌 ID 加入玩家数据。
如果玩家已经拥有该卡牌，则不会再次写入数据，而是执行卡牌的 report-command。
手持物品获得
玩家右键时，插件会比较主手物品显示名称与卡牌的 show-name。名称完全一致时，可以消耗一件物品并尝试获得对应卡牌。
use 配置现状
示例卡组提供了 use 配置，但当前右键监听代码没有读取该配置。也就是说，实际判断依据是物品显示名称是否与卡牌 show-name 完全一致，而不是 use 是否为 true。
can-it-be-reused 控制玩家已有卡牌时是否继续消耗同名物品并触发重复获得逻辑：
| 配置值 | 已拥有卡牌时的处理 |
|---|---|
true | 消耗一件物品，并执行该卡牌的 report-command。 |
false | 不消耗物品，也不会再次给予卡牌。 |
属性刷新
插件会定时扫描在线玩家已收集的卡牌：
- 汇总所有已拥有卡牌的
attribute。 - 检查每个共鸣要求的卡牌是否全部拥有。
- 将已激活共鸣的
attribute一并汇总。 - 使用固定标识
LyCard更新到选定的属性插件。
玩家退出服务器后，插件会清理其缓存的属性数据。
翻牌卡池
每个卡池由 lottery 目录中的一个 YAML 文件定义。打开卡池后，54 个槽位都会显示 default-item。玩家每点击一个尚未翻开的槽位，插件会检查并扣除配置的资源，然后抽取一张卡牌并替换该槽位物品。
| 能力 | 说明 |
|---|---|
| 权重抽取 | 使用每张卡牌的 weight 参与随机抽取，没有保底机制。 |
| 单槽限制 | 同一次打开的卡池中，已经翻开的槽位不能再次翻开。 |
| 金币消耗 | 通过 Vault 扣除 vault 配置的金额。 |
| 点券消耗 | 通过 PlayerPoints 扣除 point 配置的点券。 |
| 物品消耗 | 按显示名称和数量检查 take-item，格式为 物品显示名#数量。 |
| 商店货币 | lyshop 使用 货币ID#数量，支持 LyShop 与 LyShopReload。 |
| 重复标记 | 抽到已有卡牌时，将 repeat-status 替换进结果名称的 {status}。 |
| 奖励指令 | 抽中后执行 command；已有卡牌还会额外执行 repeat-command。 |
条件配置现状
示例卡池包含 condition，并展示了 PAPI 表达式与权限条件格式，但当前 LotteryData 和翻牌监听没有读取或执行该配置。不要依赖 condition 限制玩家抽卡。
数据存储
| 模式 | 启用方式 | 数据位置与行为 |
|---|---|---|
| 本地 YAML | mysql.enable: false | 玩家数据保存到 plugins/LyCard/playerdata/玩家UUID.yml，字段为 data。保存时会维护 .bak 备份，并在文件损坏时尝试恢复。 |
| MySQL | mysql.enable: true | 使用名为 LyCard 的数据表，按玩家名称读取和保存 data 字段。需要安装 LyMySQLCore 并保证数据库连接成功。 |
玩家卡牌列表在存储时使用 @ 分隔。正常情况下应通过插件功能管理数据，不建议直接修改该字段。
指令
插件没有在 plugin.yml 中声明独立权限节点。管理指令直接检查执行者是否为 OP；界面与卡池指令必须由在线玩家执行。
| 指令 | 执行者 | 要求 | 说明 |
|---|---|---|---|
/lykp | 任意命令发送者 | OP | 显示插件指令帮助。非 OP 执行时不会显示帮助。 |
/lykp reload | 任意命令发送者 | OP | 重载主配置、卡组配置和卡池配置。 |
/lykp open | 玩家 | 无独立权限检查 | 打开全部卡组的收集界面。 |
/lykp open [卡组ID] | 玩家 | 无独立权限检查 | 打开指定卡组的卡牌与共鸣界面。 |
/lykp lottery [卡池ID] | 玩家 | 无独立权限检查 | 打开指定翻牌卡池。 |
/lykp give [玩家] [卡牌ID] | 任意命令发送者 | OP，目标玩家在线 | 给予目标玩家指定卡牌。玩家已有卡牌或卡牌不存在时返回失败。 |
/lykp take [玩家] [卡牌ID] | 任意命令发送者 | OP，目标玩家在线 | 扣除目标玩家指定卡牌。玩家没有卡牌或卡牌不存在时返回失败。 |
参数说明
[卡组ID]、[卡池ID] 和 [卡牌ID] 使用配置中的原始 ID，不是 GUI 显示名称。
可用变量
安装 PlaceholderAPI 后，插件注册变量标识 lykp。
| 变量 | 返回值 |
|---|---|
%lykp_state:卡牌ID% | 已收集时返回 status-format-collect，未收集时返回 status-format-not-collect。 |
%lykp_resonance:卡组ID:共鸣ID% | 共鸣已激活返回 1，否则返回 0。 |
完整格式与注意事项见插件变量。
API 能力
插件公开的 LyCardAPI 接口包含以下方法：
| 方法 | 用途 |
|---|---|
isCard(String cardId) | 检查卡牌 ID 是否存在于已加载配置。 |
hasCard(Player player, String cardId) | 检查玩家是否拥有指定卡牌。 |
giveCard(Player player, String cardId) | 给予卡牌，并处理首次指令、重复指令及共鸣首次激活指令。 |
takeCard(Player player, String cardId) | 扣除玩家指定卡牌。 |
isActivateResonance(Player player, String resonanceId) | 检查玩家是否激活共鸣。共鸣 ID 最好不要在不同卡组中重名。 |
页面导航
| 页面 | 内容 |
|---|---|
| 配置说明 | 主配置、卡组配置、卡池配置、属性模式和抽卡消耗 |
| 插件变量 | 卡牌收集状态与共鸣激活状态变量 |
| 常见问题 | 插件加载、卡池依赖、属性刷新和数据存储排查 |
| 更新日志 | 文档与版本变更记录 |