二次开发 工具 【1.13-1.21.X】WarZEasyKits —— 兼容 EasyKits 的现代化礼包插件，支持 Folia / 双存储 / 自动迁移 1.0.1

[MD] # WarZEasyKits `WarZEasyKits` 是基于旧版 `EasyKits-v2.0.5` 使用习惯重制的现代礼包插件。 当前版本已经完成以下核心方向： - 保留旧命令入口：`/kit`、`/k`、`/easykits` - 保留核心礼包功能：创建、删除、冷却、次数、价格、首登礼包、告示牌、书本菜单、预览菜单、管理员发放、重置玩家进度 - 同时兼容新旧权限树：`WarZEasyKits.*` 与 `EasyKits.*` - 支持 `SQLITE / YAML` 双后端 - 自动迁移旧 `plugins/EasyKits` 配置与 SQLite 数据 - 默认中文消息、中文帮助、中文迁移报告 - 兼容 `Paper / Spigot / Bukkit`，并内置 `Folia` 调度适配层 --- ## 1. 兼容范围 - 运行目标：`1.13+` - 兼容环境：`Spigot`、`Paper`、`Folia` - 旧版 `1.7 - 1.12.2`： - 不作为新版运行目标 - 仅作为旧数据迁移来源 经济系统说明： - 若服务器安装了 `Vault`，礼包价格功能会正常扣费 - 若服务器未安装 `Vault`，带价格的礼包会被视为“可免费领取” Java 说明： - 请使用与你当前服务端版本匹配的 Java 运行环境 - 高版本 Paper / Folia 通常需要 Java 17 或更高 --- ## 2. 安装方法 1. 将插件 JAR 放入服务端 `plugins` 目录。 2. 启动服务器一次。 3. 插件会生成： - `plugins/WarZEasyKits/config.yml` - `plugins/WarZEasyKits/messages.yml` 4. 如果服务器中存在旧目录 `plugins/EasyKits`，插件首次启动时会尝试自动迁移。 --- ## 3. 命令说明 主命令： - `/kit` - `/k` - `/easykits` ### 3.1 玩家常用命令 | 命令 | 说明 | 权限 | | --- | --- | --- | | `/kit <礼包名>` | 直接领取礼包 | `WarZEasyKits.kits.<礼包名>` 或 `WarZEasyKits.kits.*` | | `/kit list` | 玩家打开分页礼包列表 GUI；控制台执行时输出文本列表 | `WarZEasyKits.cmd.list` | | `/kit view <礼包名>` | 打开礼包预览界面 | `WarZEasyKits.cmd.view` | | `/kit book` | 获取礼包书本，右键打开礼包列表 | `WarZEasyKits.cmd.book` | | `/kit help` | 查看帮助 | 无强制权限 | ### 3.2 管理员命令 | 命令 | 说明 | 权限 | | --- | --- | --- | | `/kit create <礼包名>` | 以当前玩家背包和护甲创建礼包 | `WarZEasyKits.cmd.create` | | `/kit remove <礼包名>` | 删除礼包 | `WarZEasyKits.cmd.remove` | | `/kit cooldown <礼包名> <时间>` | 设置礼包冷却 | `WarZEasyKits.cmd.cooldown` | | `/kit limit <礼包名> <次数>` | 设置礼包次数限制 | `WarZEasyKits.cmd.limit` | | `/kit price <礼包名> <价格>` | 设置礼包价格 | `WarZEasyKits.cmd.price` | | `/kit reset cooldown <礼包名> <玩家>` | 重置目标玩家的冷却 | `WarZEasyKits.cmd.reset` | | `/kit reset limit <礼包名> <玩家>` | 重置目标玩家的剩余次数 | `WarZEasyKits.cmd.reset` | | `/kit give <礼包名> <玩家>` | 给玩家发放礼包 | `WarZEasyKits.cmd.give` | | `/kit reload` | 重载配置、消息和存储连接 | `WarZEasyKits.cmd.reload` | ### 3.3 命令细节说明 - `/kit create` 只能由玩家执行，控制台不能执行 - `/kit book`、`/kit view` 只能由玩家执行 - `/kit give` 目标玩家必须在线 - `/kit reset cooldown|limit` 目标玩家必须在线 - `/kit list` 控制台可执行，但只会输出文字列表，不会打开 GUI 时间格式说明： - 冷却支持旧格式，例如： - `0` - `30m` - `2h` - `1d,2h,30m` - `2w` --- ## 4. 权限节点 ### 4.1 礼包领取权限 | 权限节点 | 说明 | | --- | --- | | `WarZEasyKits.kits.*` | 可领取所有礼包 | | `WarZEasyKits.kits.<礼包名>` | 可领取指定礼包 | 示例： - `WarZEasyKits.kits.starter` - `WarZEasyKits.kits.vip` ### 4.2 命令权限 | 权限节点 | 说明 | | --- | --- | | `WarZEasyKits.cmd.list` | 使用 `/kit list` | | `WarZEasyKits.cmd.view` | 使用 `/kit view` | | `WarZEasyKits.cmd.book` | 使用 `/kit book` | | `WarZEasyKits.cmd.create` | 使用 `/kit create` | | `WarZEasyKits.cmd.remove` | 使用 `/kit remove` | | `WarZEasyKits.cmd.cooldown` | 使用 `/kit cooldown` | | `WarZEasyKits.cmd.limit` | 使用 `/kit limit` | | `WarZEasyKits.cmd.price` | 使用 `/kit price` | | `WarZEasyKits.cmd.reset` | 使用 `/kit reset` | | `WarZEasyKits.cmd.give` | 使用 `/kit give` | | `WarZEasyKits.cmd.reload` | 使用 `/kit reload` | ### 4.3 告示牌权限 | 权限节点 | 说明 | | --- | --- | | `WarZEasyKits.sign.use` | 使用礼包告示牌 | | `WarZEasyKits.sign.create` | 创建礼包告示牌 | | `WarZEasyKits.sign.remove` | 移除礼包告示牌 | ### 4.4 绕过权限 | 权限节点 | 说明 | | --- | --- | | `WarZEasyKits.bypass.cooldown` | 绕过礼包冷却 | | `WarZEasyKits.bypass.limit` | 绕过礼包次数限制 | | `WarZEasyKits.bypass.price` | 绕过礼包价格检查 | ### 4.5 旧权限兼容 当 `config.yml` 中的： ```yml Compatibility: Legacy-Permissions: true ``` 开启时，以下旧权限也继续有效： - `EasyKits.kits.*` - `EasyKits.kits.<礼包名>` - `EasyKits.cmd.*` - `EasyKits.sign.*` - `EasyKits.bypass.*` --- ## 5. 配置文件说明 主配置文件： - `plugins/WarZEasyKits/config.yml` 消息文件： - `plugins/WarZEasyKits/messages.yml` 迁移报告： - `plugins/WarZEasyKits/migration-report.yml` ### 5.1 config.yml ```yml Storage: type: 'SQLITE' sqlite-file: 'data.db' Config: Debug: false Default-Cooldown: '0' Default-Kit-Limit: 0 Default-Price: 0.0 New-Player-Kit: 'starter' Sign-Action: 'view' Give-Bypass-Restrictions: true Compatibility: Legacy-Permissions: true Migration: Auto-Import-Legacy: true Backup-Legacy-Files: true ``` #### Storage - `Storage.type` - 可选：`SQLITE` 或 `YAML` - `Storage.sqlite-file` - 当后端为 `SQLITE` 时使用的数据库文件名 #### Config - `Debug` - 调试日志开关 - `Default-Cooldown` - 新礼包的默认冷却 - `Default-Kit-Limit` - 新礼包的默认次数限制，`0` 表示无限制 - `Default-Price` - 新礼包的默认价格 - `New-Player-Kit` - 玩家首次进服自动发放的礼包名称 - 若对应礼包不存在，则不会发放 - `Sign-Action` - `view`：点击告示牌打开礼包预览 - `obtain`：点击告示牌直接尝试领取礼包 - `Give-Bypass-Restrictions` - `true`：`/kit give` 绕过权限、冷却、次数、价格 - `false`：`/kit give` 严格按普通领取规则执行 #### Compatibility - `Legacy-Permissions` - 是否启用旧版 `EasyKits.*` 权限兼容 #### Migration - `Auto-Import-Legacy` - 是否自动检测并迁移 `plugins/EasyKits` - `Backup-Legacy-Files` - 迁移前是否先完整备份旧目录 ### 5.2 messages.yml `messages.yml` 用于自定义全部中文消息和 GUI 标题。 支持颜色代码： - `&a` - `&c` - `&6` - `&7` - 其他 Bukkit 常用颜色代码 支持占位符： - `%K`：礼包名 - `%P`：玩家名 - `%M`：金额 - `%T`：冷却剩余文本 - `%L`：剩余次数 ### 5.3 PlaceholderAPI 变量 如果服务器安装了 `PlaceholderAPI`，`WarZEasyKits` 会自动注册一组前缀为： - `%warzeasykits_*%` 的自定义变量。 说明： - 变量中的 `<礼包名>` 需要替换成真实礼包名 - 支持礼包名包含下划线，例如 `newbie_kit` - 大多数变量支持离线玩家读取 - 若礼包不存在，返回空文本 可用变量如下： | 变量 | 说明 | 返回示例 | | --- | --- | --- | | `%warzeasykits_kit_name_<礼包名>%` | 礼包显示名 | `starter` | | `%warzeasykits_kit_exists_<礼包名>%` | 礼包是否存在 | `true` | | `%warzeasykits_kit_cooldown_<礼包名>%` | 礼包配置中的原始冷却格式 | `1d,2h` | | `%warzeasykits_kit_cooldown_seconds_<礼包名>%` | 礼包总冷却秒数 | `93600` | | `%warzeasykits_kit_price_<礼包名>%` | 礼包价格 | `100.00` | | `%warzeasykits_kit_max_limit_<礼包名>%` | 礼包最大领取次数 | `3` | | `%warzeasykits_kit_unlimited_<礼包名>%` | 是否为无限次数礼包 | `true` / `false` | | `%warzeasykits_kit_remaining_limit_<礼包名>%` | 当前剩余领取次数；无限制时返回 `-1` | `2` | | `%warzeasykits_kit_used_limit_<礼包名>%` | 当前已使用次数；无限制时返回 `0` | `1` | | `%warzeasykits_kit_remaining_cooldown_<礼包名>%` | 当前剩余冷却中文文本 | `3小时12分钟` | | `%warzeasykits_kit_remaining_cooldown_seconds_<礼包名>%` | 当前剩余冷却秒数 | `11520` | | `%warzeasykits_kit_on_cooldown_<礼包名>%` | 当前是否仍在冷却 | `true` / `false` | | `%warzeasykits_kit_obtained_before_<礼包名>%` | 玩家是否曾领取过该礼包 | `true` / `false` | | `%warzeasykits_kit_last_obtained_at_<礼包名>%` | 上次领取时间的毫秒时间戳；未领取过则为 `0` | `1719150000000` | 示例： - `%warzeasykits_kit_remaining_limit_starter%` - `%warzeasykits_kit_remaining_cooldown_starter%` - `%warzeasykits_kit_max_limit_newbie_kit%` --- ## 6. 存储系统 ### 6.1 SQLite 后端 默认使用 `SQLite`。 数据库文件默认路径： - `plugins/WarZEasyKits/data.db` 当前使用的主要表： - `kits` - `player_kits` 适合： - 大多数单服环境 - 不想管理大量 YML 文件的服主 ### 6.2 YAML 后端 当 `Storage.type: YAML` 时，插件使用： - `plugins/WarZEasyKits/kits/<kit>.yml` - `plugins/WarZEasyKits/players/<uuid>.yml` 适合： - 喜欢直接手动查看和备份单个礼包文件 - 不想使用数据库文件的环境 ### 6.3 切换存储后端注意事项 当前版本支持切换后端，但不提供“SQLite 与 YAML 之间的自动互转工具”。 这意味着： - 改 `Storage.type` 后，插件会按新后端重新读取数据 - 旧后端中的礼包和玩家进度不会自动复制过去 如果你已经正式开服，切换前请先完整备份旧数据。 --- ## 7. GUI、书本与告示牌 ### 7.1 `/kit list` - 玩家执行时打开分页 GUI - 支持超过 54 个礼包 - 当前每页展示 45 个礼包 ### 7.2 `/kit view <礼包名>` - 打开礼包预览界面 - 保留“立即领取”和“返回列表”按钮 ### 7.3 `/kit book` - 给玩家一本礼包书本 - 右键书本会打开礼包总览 - 同时兼容旧 `EasyKits` 书本名称识别 ### 7.4 告示牌 创建方法： 第一行输入： ```text [Kit] ``` 第二行输入礼包名称，例如： ```text starter ``` 创建成功后，插件会自动把第一行转换为蓝色 `[Kit]` 标识。 --- ## 8. `give` 与首登礼包的行为说明 ### 8.1 `/kit give` 当 `Config.Give-Bypass-Restrictions: true` 时： - 不检查领取权限 - 不检查冷却 - 不检查次数 - 不检查价格 - 不扣费 - 不写入冷却 - 不减少次数 - 仍然检查背包空间 当 `Config.Give-Bypass-Restrictions: false` 时： - 完整走普通领取流程 - 会检查权限、冷却、次数、价格 - 会正常扣费 - 会正常写入冷却和次数 - 仍然检查背包空间 ### 8.2 首登礼包 首登礼包通过： ```yml Config: New-Player-Kit: 'starter' ``` 控制。 首登礼包当前行为： - 仅首次进入服务器时触发 - 不检查权限 - 不检查冷却 - 不检查次数 - 不检查价格 - 不扣费 --- ## 9. 迁移旧版 EasyKits ### 9.1 自动迁移触发条件 插件首次启动时，如果同时满足以下条件，就会尝试迁移： - `Migration.Auto-Import-Legacy: true` - 存在旧目录 `plugins/EasyKits` - 新目录下还没有 `.migration-complete` 标记文件 ### 9.2 迁移流程 1. 先检测旧版 `plugins/EasyKits` 2. 若开启备份，则完整备份到： - `plugins/WarZEasyKits/migration-backup/EasyKits` 3. 读取旧版 `config.yml` 4. 导入旧版 `Messages` 到新 `messages.yml` 5. 读取旧版 `data.db` 6. 导入旧版 `kits` 表 7. 导入旧版“每玩家一张表”的领取进度 8. 生成： - `migration-report.yml` 9. 写入一次性迁移标记： - `plugins/WarZEasyKits/.migration-complete` ### 9.3 物品兼容迁移说明 旧版 `1.7 - 1.12.2` 数据中的物品会按“尽力迁移”处理： - 能成功反序列化的槽位会导入 - 失败槽位会留空 - 礼包整体仍会创建成功 - 失败原因会记录进 `migration-report.yml` ### 9.4 迁移报告 迁移报告文件： - `plugins/WarZEasyKits/migration-report.yml` 报告中会记录： - 执行步骤 - 警告信息 - 错误信息 - 生成时间 ### 9.5 是否可以强制重跑迁移 技术上删除 `.migration-complete` 后可以再次触发检测。 但不建议直接这么做，因为： - 你当前的新数据可能会和旧数据混在一起 - 可能覆盖或重复导入部分内容 如果你确实要重跑，请先完整备份当前 `plugins/WarZEasyKits`。 --- ## 10. 自定义事件 当前插件提供以下事件，均在 `com.crazyjky.warzeasykits.event` 包下： | 事件类 | 触发时机 | 是否可取消 | | --- | --- | --- | | `WarZKitCreateEvent` | 创建礼包前 | 是 | | `WarZKitRemoveEvent` | 删除礼包前 | 是 | | `WarZKitClaimEvent` | 玩家通过命令 / GUI / 告示牌 / 管理员发放进入真正发放前 | 是 | | `WarZKitCooldownUpdateEvent` | 写入冷却时间前 | 是 | | `WarZKitLimitUpdateEvent` | 写入剩余次数前 | 是 | | `WarZKitChargeEvent` | 扣费前 | 是 | 这些事件都继承自： - `AbstractCancellableKitEvent` 可用于： - 二次权限控制 - 自定义日志 - 额外经济逻辑 - 拦截礼包发放 --- ## 11. Folia 兼容说明 插件内置了 `PlatformScheduler` 抽象层，并提供： - `BukkitPlatformScheduler` - `FoliaPlatformScheduler` 启动时会自动识别当前环境： - 普通服端：`Bukkit / Spigot / Paper` - Folia：启用 `GlobalRegionScheduler / RegionScheduler` 反射适配 你会在控制台启动横幅中看到当前识别到的运行平台。 --- ## 12. 推荐使用流程 ### 12.1 创建一个新手礼包 1. 用管理员账号把要保存的物品放到背包和护甲栏 2. 执行： ```text /kit create starter ``` 3. 设置冷却： ```text /kit cooldown starter 0 ``` 4. 设置次数： ```text /kit limit starter 1 ``` 5. 设置价格： ```text /kit price starter 0 ``` 6. 给玩家权限： ```text WarZEasyKits.kits.starter ``` ### 12.2 设置首登礼包 在 `config.yml` 中： ```yml Config: New-Player-Kit: 'starter' ``` 然后执行： ```text /kit reload ``` ### 12.3 创建告示牌 先确保礼包已存在，然后放置告示牌： ```text [Kit] starter ``` --- ## 13. 常见问题 ### Q1：为什么礼包价格没生效？ 可能原因： - 服务器没有安装 `Vault` - 玩家有 `WarZEasyKits.bypass.price` - 使用的是 `/kit give` 且 `Give-Bypass-Restrictions: true` ### Q2：为什么礼包冷却或次数没扣？ 可能原因： - 玩家拥有 `WarZEasyKits.bypass.cooldown` 或 `WarZEasyKits.bypass.limit` - 使用的是首登礼包 - 使用的是 `/kit give` 且开启了绕过模式 ### Q3：为什么玩家明明有礼包权限，却无法领取？ 请检查： - 是否有足够背包空间 - 礼包是否还在冷却中 - 次数是否已用尽 - 是否需要支付价格 ### Q4：为什么改了 `Storage.type` 后看不到原来的礼包？ 因为当前版本不提供 `SQLITE <-> YAML` 自动互转。 你切换的是“读取后端”，不是“自动迁移后端数据”。 ### Q5：为什么首登礼包没有发？ 请检查： - `Config.New-Player-Kit` 对应的礼包是否真实存在 - 该玩家是否已经进入过服务器 ### Q6：为什么迁移只执行一次？ 因为插件会写入： - `plugins/WarZEasyKits/.migration-complete` 这是故意设计，用来避免重复覆盖新数据。 --- ## 14. 联系方式 - 插件技术交流群：`398893720` - 末日类服务器交流群：`1063544727` - 插件定制开发：`QQ 1285988665` - 支持作者：`https://afdian.com/a/sunjood` [/MD]