福利·自选礼包 LyKit
LyKit 是一款自选礼包插件。玩家主手持有指定名称的礼包物品时，可以右键打开领取界面，在必得奖励、随机奖励和自选奖励之间完成选择。领取成功后，插件发放奖励并扣除一个匹配名称的礼包物品。
插件信息
| 项目 | 说明 |
|---|---|
| 插件名称 | LyKit |
| 插件版本 | 1.0.0 |
| 插件用途 | 创建带界面的必得、随机和自选礼包 |
| Java 版本 | Java 8 |
| 编译接口 | Paper API 1.16.5-R0.1-SNAPSHOT |
| 礼包目录 | plugins/LyKit/kit |
| 主配置 | plugins/LyKit/config.yml |
玩法机制
- 玩家将礼包物品拿在主手。
- 玩家右键空气或方块。
- 插件按照物品显示名称匹配礼包配置中的
match-item-name。 - 匹配成功后打开 36 格礼包界面。
- 玩家查看必得奖励和随机奖励，并在自选奖励区域选择指定数量的物品。
- 玩家点击领取按钮。
- 插件检查背包空位、自选数量和礼包物品是否仍然存在。
- 检查通过后发放必得、随机和自选奖励，执行奖励指令，并扣除一个礼包物品。
礼包匹配只比较物品的显示名称，不比较材质、Lore、附魔或其他物品数据。名称需要与 match-item-name 完全一致，包括颜色代码转换后的结果。
功能概览
- 支持必得奖励、随机奖励、自选奖励三类礼包内容。
- 支持通过主手物品显示名称打开对应礼包。
- 支持为不同礼包分别设置界面标题和领取所需背包空位。
- 支持 MythicMobs 4、MythicMobs 5、NeigeItems、SX-Item 物品。
- 支持每项奖励同时发放物品并执行多条指令。
- 支持关闭单项奖励的物品发放，只执行配置的指令。
- 随机奖励在单次领取中不会重复抽取同一个配置项。
- 支持限制玩家必须选择的奖励数量。
- 支持左键选择、右键取消自选奖励。
- 支持使用附魔光效和额外 Lore 标记已选中的奖励。
- 支持自定义界面分类物品、填充物品、领取按钮、名称和 Lore。
- 支持自定义背包不足、未选满、超出选择数量和领取成功消息。
- 支持在奖励指令中解析 PlaceholderAPI 变量。
- 支持递归读取
kit目录及其子目录中的.yml礼包文件。 - 支持通过命令重载主配置和全部礼包文件。
奖励分类
| 分类 | 配置节点 | 领取规则 | 界面位置 |
|---|---|---|---|
| 必得奖励 | must-item | 领取时执行全部奖励 | 第 1 行 |
| 随机奖励 | random-item | 从奖励池中无重复随机抽取 | 第 2 行 |
| 自选奖励 | select-item | 玩家选择指定数量后领取 | 第 3 行 |
每类奖励在界面中最多显示 8 项。礼包配置中即使写入更多项目，超出的项目也不会显示。建议每个分类最多配置 8 项，避免奖励显示与实际处理不一致。
奖励物品来源
奖励物品使用 来源@物品ID 格式填写。
| 来源标识 | 对应插件 | 示例格式 | 说明 |
|---|---|---|---|
MM4 | MythicMobs 4 | MM4@物品ID | 从 MythicMobs 4 物品管理器读取物品 |
MM5 | MythicMobs 5 | MM5@物品ID | 从 MythicMobs 5 物品管理器读取物品 |
NI | NeigeItems | NI@物品ID | 根据领取玩家生成 NeigeItems 物品 |
SI | SX-Item | SI@物品ID | 根据领取玩家生成 SX-Item 物品 |
item 必须包含来源标识和物品 ID，并使用 @ 分隔。配置错误、来源插件未安装或物品 ID 不存在时，插件无法发放对应物品，并会向玩家发送物品不存在的错误消息。
依赖说明
| 依赖 | 类型 | 用途 |
|---|---|---|
| PlaceholderAPI | 软依赖 | 解析奖励指令中的 PlaceholderAPI 变量，并注册 lkit 变量扩展 |
| MythicMobs 4 | 按需安装 | 使用 MM4@物品ID 奖励时需要 |
| MythicMobs 5 | 按需安装 | 使用 MM5@物品ID 奖励时需要 |
| NeigeItems | 按需安装 | 使用 NI@物品ID 奖励时需要 |
| SX-Item | 按需安装 | 使用 SI@物品ID 奖励时需要 |
PlaceholderAPI 在 plugin.yml 中声明为软依赖。奖励指令会调用 PlaceholderAPI 解析变量，因此使用指令奖励时应安装 PlaceholderAPI。
插件当前注册了标识为 lkit 的 PlaceholderAPI 扩展，但项目代码没有实现可用的 LyKit 专属变量。不要依赖 %lkit_变量名% 获取礼包数据。
支持版本
项目使用 Java 8，并以 Paper API 1.16.5 作为编译接口。
代码包含旧版数字材质 ID、旧版材质名称和新版材质名称的兼容处理，例如 160:0 与新版英文材质名称。项目文件没有声明完整的 Minecraft 支持版本范围，因此除 Paper 1.16.5 外的服务端版本需要自行测试，不能仅根据材质兼容代码判断为完整支持。
指令
| 指令 | 使用条件 | 说明 |
|---|---|---|
/lkit | OP | 查看插件版本和可用指令提示 |
/lkit reload | OP | 重载 config.yml、选择标记和 kit 目录中的礼包文件 |
插件没有声明独立权限节点。指令通过玩家或命令发送者的 OP 状态判断是否允许使用，非 OP 执行时不会获得管理功能。
/lkit reload 同时会检查并释放默认的 kit/示例礼包.yml。如果文件已经存在，插件不会覆盖现有文件。
礼包配置
每个礼包使用一个 .yml 文件保存，放入 plugins/LyKit/kit 或其子目录。插件重载时会递归加载目录中的所有 .yml 文件。
基础设置
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
id | 字符串 | 无 | 礼包内部 ID，也是插件保存礼包数据时使用的键 |
match-item-name | 字符串 | 空字符串 | 用于匹配礼包物品显示名称，支持 & 颜色代码 |
need-slot | 整数 | 1 | 点击领取时要求玩家背包至少拥有的空槽数量 |
title | 字符串 | id 的值 | 当前礼包的界面标题，支持 & 颜色代码 |
random-item-amount | 整数 | 1 | 单次领取需要从随机奖励池抽取的数量 |
select-item-amount | 整数 | 0 | 玩家领取前必须选择的自选奖励数量 |
id 应在所有礼包文件中保持唯一。相同 id 的礼包会写入同一个数据键，最终保留哪一个取决于文件加载顺序。
奖励项目
must-item、random-item 和 select-item 下的每个子节点都使用相同结构。
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
item | 字符串 | 空字符串 | 奖励物品，格式为 来源@物品ID |
amount | 整数 | 1 | 实际发放的物品数量 |
give | 布尔值 | true | 是否发放 item 对应的物品 |
command | 字符串列表 | 空列表 | 领取该奖励时执行的指令 |
当 give: false 时，插件仍会执行 command，但不会发放物品。奖励仍然需要正确填写 item 才能在礼包界面中显示。
奖励指令
奖励项目的 command 支持三种执行方式。
| 写法 | 执行身份 | 说明 |
|---|---|---|
[console]指令 | 控制台 | 删除 [console] 标记后由控制台执行 |
[op]指令 | 临时 OP 玩家 | 执行期间临时给予玩家 OP，完成后恢复原状态 |
指令 | 玩家 | 直接由领取礼包的玩家执行 |
指令内容会先经过 PlaceholderAPI 解析。指令中不需要填写开头的 /。
使用 [op] 会临时修改玩家的 OP 状态。除非确有需要，优先使用 [console] 执行管理类指令。
主配置
选择标记
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
selected-enchant-enable | 布尔值 | true | 是否为已选中的自选奖励添加幸运附魔光效 |
selected-extra-lore | 字符串列表 | 空列表 | 追加到已选中奖励末尾的 Lore，支持 & 颜色代码 |
选择标记只影响礼包界面中的显示物品，不会修改最终发放给玩家的奖励物品。
消息
| 配置项 | 可用变量 | 触发条件 |
|---|---|---|
message.empty-slot | {amount} | 玩家背包空槽少于礼包的 need-slot |
message.no-select | {amount} | 玩家选择数量少于 select-item-amount |
message.beyond-select | {amount} | 玩家尝试选择超过 select-item-amount 的奖励 |
message.success | 无 | 礼包奖励发放并扣除礼包物品后 |
消息支持使用 & 颜色代码。配置值为 null 时，对应消息不会发送。
界面设置
| 配置项 | 类型 | 可用变量 | 说明 |
|---|---|---|---|
gui.fill-item | 字符串 | 无 | 底部填充物品的材质或兼容数字 ID |
gui.fill-name | 字符串 | 无 | 填充物品名称 |
gui.item-name-format | 字符串 | {name}、{amount} | 奖励物品在界面中的名称格式 |
gui.must-item | 字符串 | 无 | 必得奖励分类提示物品 |
gui.must-name | 字符串 | 无 | 必得奖励分类名称 |
gui.must-lore | 字符串列表 | 无 | 必得奖励分类 Lore |
gui.random-item | 字符串 | 无 | 随机奖励分类提示物品 |
gui.random-name | 字符串 | {amount} | 随机奖励分类名称 |
gui.random-lore | 字符串列表 | {amount} | 随机奖励分类 Lore |
gui.select-item | 字符串 | 无 | 自选奖励分类提示物品 |
gui.select-name | 字符串 | {amount} | 自选奖励分类名称 |
gui.select-lore | 字符串列表 | {amount} | 自选奖励分类 Lore |
gui.button-item | 字符串 | 无 | 领取按钮物品 |
gui.button-name | 字符串 | 无 | 领取按钮名称 |
gui.button-lore | 字符串列表 | 无 | 领取按钮 Lore |
主配置中虽然存在 gui.title，但当前界面创建逻辑直接使用礼包文件中的 title，没有读取 gui.title。修改 gui.title 不会改变礼包界面标题。
界面材质支持数字 ID、带数据值的数字 ID和服务端可识别的英文材质名称，例如 160:0。无法识别的材质可能回退为石头，因此修改界面物品后需要确认材质在当前服务端版本中有效。
领取规则
- 必得奖励会按配置顺序全部处理。
- 随机奖励会复制当前奖励池后再抽取，不会修改全局礼包配置。
- 单次随机抽取不会重复选中同一个奖励配置项。
- 当
random-item-amount大于随机奖励池数量时，实际发放数量会限制为奖励池数量。 - 玩家只能选择
select-item-amount个自选奖励。 - 左键用于选择奖励，右键用于取消选择。
- 玩家必须选满指定数量才能领取。
- 点击领取时，插件只统计玩家背包前 36 个存储槽中的空槽。
need-slot检查的是空槽数量，不会计算奖励是否能堆叠到已有物品中。- 点击领取时，插件会再次检查背包中是否存在匹配名称的礼包物品。
- 领取成功后会从背包前 36 个槽位中扣除一个匹配名称的物品。
- 如果玩家在领取前移除了礼包物品，界面会直接关闭，不会发放奖励。
- 关闭礼包界面后，当前选择记录会被清除。
界面布局
礼包界面固定为 36 格。
| 槽位 | 内容 |
|---|---|
0 | 必得奖励分类提示 |
1 至 8 | 必得奖励，最多显示 8 项 |
9 | 随机奖励分类提示 |
10 至 17 | 随机奖励，最多显示 8 项 |
18 | 自选奖励分类提示 |
19 至 26 | 自选奖励，最多显示 8 项 |
27 | 领取按钮 |
28 至 35 | 填充物品 |
注意事项
- 礼包物品通过显示名称识别，同名普通物品也会被视为礼包物品。
match-item-name留空时，正常物品无法匹配该礼包。- 奖励的
item使用错误格式时，可能因为缺少@分隔符而导致礼包加载或界面打开异常。 - 礼包文件加载失败时，控制台会显示对应文件名和异常信息。
- 使用某种物品来源前，必须安装对应的物品插件，并确保物品 ID 存在。
- 配置中的颜色代码使用
&，插件读取后会转换为 Minecraft 颜色字符。 - 礼包界面中的物品堆叠数量不会超过该物品的最大堆叠数量，但名称中的
{amount}会显示配置的实际奖励数量。 need-slot应根据礼包可能产生的物品种类设置，避免奖励发放时背包空间不足。