原创 付费 工具 娱乐 YiyunKit - 功能全面专为高版本设计的礼包插件 | 支持Folia | 支持自选礼包模式 | 1.21+ v1.2.0

[MD] # YiyunKit 逸云礼包     **礼包系统 + CDK 兑换，多合一。全程 GUI 编辑，不碰配置文件。** 面向 Minecraft 1.21+ 的 Paper / Purpur / Folia 服务器。从创建礼包到上架运营、绑定地图入口、批量发兑换码、自动发新人礼——全部在游戏内界面里完成。原生支持 Folia 多区域，零 NMS，跨小版本升级零成本。 **目录**：[特性一览](#-特性一览) · [环境要求](#-环境要求) · [安装与升级](#-安装与升级) · [五分钟上手](#-五分钟上手) · [命令速查](#-命令速查) · [占位符](#-placeholderapi-占位符) · [群组跨服](#-群组跨服可选) > 📖 **详细使用手册**：[用户使用文档.md](https://docs.qq.com/aio/DVFpTRkFjV0pzSUxH) —— 玩家篇（怎么领/邮箱/权益/礼包券/CDK/新人礼/入口）+ 管理员篇（建礼包到上架、入口/粒子/全息、发放、跨服、运维排错）。本 README 只是速览。 --- ## ✨ 特性一览 **内容编辑** - **全 GUI 编辑器** —— 创建礼包、投放物品（拖进投放仓即可，原件自动退回）、设置冷却限领、上架分组，全程界面操作；编辑有未保存保护、并发冲突检测与操作审计。 - **物品与指令奖励** —— 完整 NBT 物品（附魔/头颅/潜影盒都行，支持手写 SNBT 与简易写法）、指令奖励（发金币/点券/称号），命令黑名单防注入。 - **装备自动穿戴** —— 盔甲/图腾/盾牌可指定穿戴槽位，发放时直接上身（空槽才穿，永不顶掉现有装备），即领即战。 - **奖励组** —— 把一套装备打包成一个抽奖位，抽中整组发放，分层奖池轻松搭建。 **玩家体验** - **三种领取模式** —— 全部获得 / 随机抽取（带转盘动画，结果提前锁定不可重抽）/ 玩家自选（实时空间校验、防误触二次确认）。 - **内置邮箱** —— 满背包/离线玩家的奖励自动入箱，绝不丢失；进服聊天栏提醒，逐件领取。 - **我的权益** —— 管理员授予、CDK 兑换、离线发放的自选奖励统一变成"领取权益"，兑现前永久保留，**"发了但没领"在机制上不可能丢失**。 - **新人礼包** —— 首次进服自动触发，三种发放方式，严格一生一次；自动识别历史老玩家不误发，支持按天补发与全体补发。 **地图与氛围** - **方块入口** —— 任意方块绑定成礼包入口，七类保护（防炸/防烧/防活塞/防改方块……）、定时自动修复、全息文字（内置 TextDisplay，可选委托 DecentHolograms / WooHolograms）、5 种粒子动画 **运营与安全** - **限时与限领** —— 每礼包独立冷却（支持 cron 定时刷新）、总/日/周/月限领、全服库存、限时上架窗口、PlaceholderAPI 条件门槛、可见性三档（所有人可见/凭权限可见/对玩家隐身）。 - **CDK 兑换码** —— 批量生成（千级秒出）、自定义口令码、每人限领、防撞库限速、导出文件、批次管理。 - **跨服一致（可选）** —— 开启 network-mode，多台服务器共享 MySQL，任意一台领取全网络即时生效，不会重复发放；礼包/分组配置自动同步到全群组。 - **运维工具** —— `/ykitadmin doctor` 一键体检已知坑（只读、给建议）、`selfcheck` 自检、`perf` 性能面板、SQLite→MySQL 一键迁移、管理操作全量审计日志、可选更新检查。 - **开发者 API** —— 礼包/分组/CDK/邮箱/权益/统计全套开放接口、12 个事件、第三方条件扩展点，附示例工程。 ## 📦 环境要求 | 项目 | 要求 | |---|---| | Java | **21** | | 服务端 | **Paper / Folia 1.21+** | | 可选依赖 | [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/)（条件礼包；未安装时条件按"不满足"处理） | 其他全息插件（DecentHolograms / WooHolograms）为可选项，插件内置 TextDisplay 全息，不装也能用。 ## 🚀 安装与升级 ### 全新安装 1. 下载 `YiyunKit-1.0.1.jar`，放入服务器 `plugins/` 目录； 2. 重启服务器，首次启动自动生成示例礼包 `welcome` 与默认配置； 3. 给自己权限 `yiyunkit.admin`（OP 默认已有），输入 `/ykitadmin` 开始使用。 ## 🎯 五分钟上手 ```text 1. /ykitadmin 打开管理总览 2. 礼包管理 → 新建礼包 输入一个 ID（如 daily），选个模板 3. 物品内容 → 新增物品 把背包里的物品拖进投放仓，关闭界面（原件自动退回） （想发金币/称号？→ 新增指令物品，填命令即可） 4. 保存 编辑器右下角，改完随手存 5. /ykit 切到玩家视角，点开刚建的礼包领取试试 6. /ykitadmin block set daily 准星对准一个方块执行，把它绑定成入口 潜行 + 右键该方块 打开入口设置：交互模式 / 保护 / 粒子 / 全息 ``` 完成。冷却、限领、库存、限时、跨服、运维排错等详细说明，统一见上方《用户使用文档》。 ## ⌨️ 命令速查 所有命令支持 Tab 补全（含中文子命令别名）。本节列出常用命令，完整使用流程统一见上方《用户使用文档》。 ### 玩家 | 命令 | 作用 | |---|---| | `/ykit`（别名 `/gift`） | 玩家主菜单（分组浏览、可领取的礼包发光提示） | | `/ykit preview <礼包>` | 直接预览指定礼包 | | `/ykit claim <礼包>` | 命令直领 | | `/ykit mailbox` | 我的邮箱 | | `/cdk <兑换码>` | 兑换 CDK | | `/ykit version` | 查看插件版本 | ### 管理（`/ykitadmin`，别名 `/gkadmin`） | 命令 | 作用 | |---|---| | `/ykitadmin` | 管理总览 GUI（以下子命令也都能从界面完成） | | `/ykitadmin give <礼包> <玩家> [数量] [--check]` | 强制发放（可用玩家选择器 GUI；默认绕过检查，`--check` 走完整管线） | | `/ykitadmin package create/clone/rename/delete <ID>` | 新建 / 克隆 / 重命名（数据自动迁移）/ 删除 | | `/ykitadmin block set <礼包\|group:分组\|menu>` | 准星对准方块，绑定成入口 | | `/ykitadmin cdk gen <礼包> <数量> [次数] [有效期]` | 批量生成兑换码并导出文件 | | `/ykitadmin player <玩家>` | 查询领取状态、重置冷却/次数 | | `/ykitadmin newbie backfill <天数> [--all]` | 补发新人礼包（`--all` 面向全部已知玩家） | | `/ykitadmin doctor` | 一键体检：已知坑逐项检查，只读、给可执行建议 | | `/ykitadmin stats` / `selfcheck` / `perf` | 统计面板 / 加载自检 / 性能面板（含待交付载荷） | | `/ykitadmin transfer <sqlite文件路径>` | 把单服 SQLite 数据整体迁到当前 MySQL（跨服切换用，只增不删） | | `/ykitadmin reload` | 重载 YAML 配置与语言文件（不动数据库） | ### 权限 ```text yiyunkit.use 默认所有人 玩家功能入口 yiyunkit.admin 默认 OP 管理总入口（含 package/group/block/cdk/player 子权限） yiyunkit.claim.<礼包ID> 礼包级领取权限（与礼包配置的 permission 满足其一即可） yiyunkit.bypass.cooldown / .limit / .protection 默认 OP 绕过冷却 / 限领 / 入口保护 ``` > 入口方块不受 `bypass.protection` 豁免：**创造模式 + `yiyunkit.admin.block`** 拆除即解绑，其余任何情况都拆不动。 ## 📊 PlaceholderAPI 占位符 装好 PAPI 后，其他插件可直接使用（`<id>` 换成礼包 ID）： | 占位符 | 示例 | |---|---| | `%yiyunkit_cooldown_<id>%` | `2小时13分` / `可领取` | | `%yiyunkit_cooldown_seconds_<id>%` | `7980`（剩余秒数） | | `%yiyunkit_daily_left_<id>%` | `1`（今日剩余次数；未配置日限领返回空） | | `%yiyunkit_weekly_left_<id>%` / `_monthly_left_` / `_total_left_` | 本周 / 本月 / 累计剩余 | | `%yiyunkit_stock_<id>%` | `100`（全服库存剩余） | | `%yiyunkit_claimed_total_<id>%` | `5`（已领取总次数） | | `%yiyunkit_mail_count%` | `2`（邮箱未领取件数） | | `%yiyunkit_newbie_claimed%` | `true/false`（是否已领新人礼包） | ## 🌐 群组跨服（可选） `config.yml` 中开启 `storage.network-mode: true` 后（强制要求 MySQL）： - **礼包/分组配置自动同步**：在任一台子服的 GUI/YAML 里修改，几秒内自动分发到群组内所有子服（数据库作传输层，本地 YAML 仍是每服事实文件，可继续手改/备份）；`config.yml` 与 `blocks.yml` 属各服环境配置，不参与同步； - 冷却与限领由数据库原子判定，任意一台服务器领取，全网络即时一致，多服同时领取不会重复发放； - 库存 / CDK / 邮箱 / 权益 / 新人判定本就是全库共享的，天然跨服； - **时间判定以数据库时钟为唯一权威**：各服系统时钟是否对时、时区是否一致都不再重要（建议各服配置相同的 `storage.network-timezone`）；新人礼包发"玩家第一台进入的服务器"上的配置； - 单服起家的存量数据可整体迁移：`/ykitadmin transfer <sqlite文件路径>`（只增不删）。 详细部署步骤与注意事项见上方《用户使用文档》的跨服章节。 ## 📄 许可证 **保留所有权利（All Rights Reserved）**。未经作者书面许可，禁止二次分发或商业用途。 个人服务器自由使用；问题反馈与功能建议见下方支持渠道。 ## 💬 支持与反馈 - 交流群：1093090518 - 作者：**CHL_chun** 如果插件帮到了你，欢迎给个好评和鼓励⭐ [/MD]