新分解 LyGalaxyDecomposition
LyGalaxyDecomposition 是一款基于 YAML 规则的物品分解插件。玩家将装备或其他物品放入分解界面后，插件会先检查全局条件，再匹配全部分解规则，并根据命中的规则生成产物、执行命令，最后按配置顺序将产物发放到背包或外部仓库。
同一个物品可以同时命中多条规则。每条规则可以独立配置匹配条件、产物、数量范围、生成概率、规则命令、产物命令，以及是否实际生成产物。
插件信息
| 项目 | 内容 |
|---|---|
| 插件名 | LyGalaxyDecomposition |
| 中文名 | 新分解 |
| 项目版本 | 1.0.0 |
| 作者 | Liyuan |
| 主命令 | /lyfj |
| 配置目录 | plugins/LyGalaxyDecomposition/ |
| 规则目录 | plugins/LyGalaxyDecomposition/rule/ |
| Java 编译目标 | 插件主体为 Java 8；1.17.1 及以上 NMS 模块为 Java 17 |
| Bukkit API 版本 | 1.13 |
支持版本
项目包含以下 Minecraft 服务端版本的 NBT 适配模块：
| Minecraft 版本 | NMS 版本 | Java 编译目标 |
|---|---|---|
1.7.10 | V1_7_R4 | Java 8 |
1.8.8 | V1_8_R3 | Java 8 |
1.11.2 | V1_11_R1 | Java 8 |
1.12.2 | V1_12_R1 | Java 8 |
1.13.2 | V1_13_R2 | Java 8 |
1.14.4 | V1_14_R1 | Java 8 |
1.15.2 | V1_15_R1 | Java 8 |
1.16.5 | V1_16_R3 | Java 8 |
1.17.1 | V1_17_R1 | Java 17 |
1.18.2 | V1_18_R2 | Java 17 |
1.19.2 | V1_19_R1 | Java 17 |
1.19.4 | V1_19_R3 | Java 17 |
1.20.1 | V1_20_R1 | Java 17 |
1.20.2 | V1_20_R2 | Java 17 |
1.20.3 | V1_20_R3 | Java 17 |
未列出的服务端版本没有对应的项目内 NBT 适配证据。规则或全局条件使用 nbt()、hasnbt() 时，当前服务端必须存在可用的 NBT 适配器，否则配置无法通过重载校验。
玩法说明
分解界面固定为 54 格，包含输入区、分解按钮、产物预览区和额外按钮区。
- 玩家执行
/lyfj open打开分解界面。 - 将需要处理的物品放入上方开放的输入槽位。
- 插件从输入区开始查找第一个能够分解的物品，并在下方显示该物品的产物预览。
- 左键点击分解按钮，处理输入区内第一个可分解物品栈。
- 右键点击分解按钮，依次处理输入区内的全部可分解物品栈。
- 物品栈中的物品会逐个执行分解，每个物品独立计算产物概率和随机数量。
- 产物按
delivery-order的顺序进入玩家背包或外部仓库，仍未被接收的部分会掉落在玩家位置。
每次成功执行一个物品的分解后，插件才会从输入槽位扣除一个物品。分解被外部插件取消、产物配置错误或执行出现错误时，当前物品不会被扣除。
关闭界面或使用取回按钮时，输入区内尚未分解的物品会返还玩家背包。背包无法容纳的部分会掉落在玩家当前位置。
依赖与兼容插件
插件没有在 plugin.yml 中声明硬依赖，以下插件均为软依赖。具体功能只有在对应插件已安装、已启用且适配器初始化成功时才会生效。
物品库
实际生成分解产物时，需要至少一个受支持的物品库。规则中的每项产物必须能够从指定物品库创建，否则规则校验或分解执行会失败。
| 配置名称 | 功能 | 说明 |
|---|---|---|
MythicMobs | 创建 MythicMobs 物品 | 根据插件版本使用 MythicMobs 4 或 MythicMobs 5 接口 |
LyItemSave | 使用兼容接口创建物品 | 与 MythicMobs 配置名称互通 |
AzureFlow | 创建 AzureFlow 物品 | 创建时传入玩家上下文 |
NeonFlash | 创建 NeonFlash 物品 | 使用 NeonFlash 物品处理器构建物品 |
SX-Item | 创建 SX-Item 物品 | 配置名称包含连字符 |
NeigeItems | 创建 NeigeItems 物品 | 创建时传入玩家上下文 |
OriginAttribute | 创建 OriginAttribute 物品 | 仅在物品配置存在时创建 |
未在产物 ID 中填写物品库前缀时，插件使用 config.yml 中的 item-provider。该配置为空或缺失时，默认使用 MythicMobs。
产物可以使用 物品库@物品ID 格式明确指定来源：
yaml
result:
- 'MythicMobs@分解材料 1-2 0.5'
- 'NeigeItems@高级材料 1 1'MythicMobs 与 LyItemSave 使用同一个兼容适配器。任意一个插件可用时，这两个配置前缀都可以使用。
PlaceholderAPI
安装并启用 PlaceholderAPI 后，可以：
- 在
papi()条件中替换玩家变量并计算比较表达式。 - 替换规则执行命令中的 PlaceholderAPI 变量。
- 替换产物命令中的 PlaceholderAPI 变量。
- 替换额外命令按钮中的 PlaceholderAPI 变量。
配置使用 papi() 条件但 PlaceholderAPI 不可用时，该条件会被视为配置错误，重载不会成功。普通命令中的变量替换则会在 PlaceholderAPI 不可用时保留原文。
外部仓库
delivery-order 名称 | 依赖插件 | 玩家消息中的目标名称 |
|---|---|---|
inventory | 无 | 背包 |
LyLootsWarehouse | LyLootsWareHouse | 战利品仓库 |
LyWarehouse | LyWarehouse | 离渊仓库 |
SpaceRingPlus | YeeCore | 灵魂空间 |
StarStorage | StarStorage | DS仓库 |
插件从上到下尝试每个入库目标：
- 玩家背包可以接收部分数量，剩余数量会继续尝试下一个目标。
- 外部仓库按完整剩余物品栈尝试接收。
- 未安装、未启用、初始化失败或未能接收物品的仓库会被跳过。
- 全部目标处理后仍有剩余产物时，剩余物品会掉落在玩家位置。
delivery-order为空时默认只使用玩家背包。- 同一个入库目标不能重复配置。
- 入库目标名称匹配时忽略英文大小写，但重载后会转换为正式名称。
主要功能
多规则分解
- 规则以 YAML 文件存放在
rule目录。 - 插件会递归读取
rule目录及子目录中的.yml文件。 - 规则文件按完整路径忽略大小写排序后加载。
- 规则 ID 直接写在规则文件最外层。
- 所有规则文件中的规则 ID 必须唯一。
- 每条规则必须配置至少一行
condition。 - 一件物品可以同时匹配多条规则，并执行全部命中规则。
- 全局条件会在匹配每条规则前统一检查。
- 多行条件之间为与关系，每一行都必须成立。
- 单行条件可以使用
||连接多个或分支。 - 条件表达式前可以添加一个或多个
!进行取反。
物品匹配条件
| 条件函数 | 用途 |
|---|---|
hasname() | 判断物品是否存在自定义名称 |
haslore() | 判断物品是否存在 Lore |
name() | 匹配物品自定义名称 |
lore() | 匹配物品 Lore 中的任意一行 |
material() | 按材质名称、数字 ID 或数字 ID 与 Data 匹配 |
permission() | 判断玩家是否拥有指定权限节点 |
papi() | 替换 PlaceholderAPI 变量后计算布尔比较表达式 |
hasnbt() | 判断物品是否存在指定 NBT 路径 |
nbt() | 比较指定 NBT 路径的文本值或数值 |
名称和 Lore 条件支持：
equals：完整匹配，默认方式。contains：包含指定内容。startsWith：以指定内容开头。endsWith：以指定内容结尾。ignoreColor：移除颜色后比较，可以与其他匹配方式组合。
material() 支持材质名称、minecraft: 命名空间、纯数字 ID 和 数字ID:Data。
papi() 支持 ==、!=、>、>=、<、<=，并可以使用 && 和 || 组合表达式。范围运算符仅在两侧都能解析为数字时成立。
NBT 条件支持 equals、!=、contains、startsWith、endsWith、>、>=、<、<= 和 ignoreCase。NBT 最终节点会以字符串读取，数值比较要求实际值和目标值都能转换为数字。
完整条件语法和规则字段见分解规则。
产物生成
每项产物可以配置：
- 物品库与物品 ID。
- 固定生成数量。
- 最小值至最大值的随机数量范围。
0至1的独立生成概率。- 产物成功生成并发放后执行的一条或多条命令。
基础格式为：
text
物品ID 数量或数量范围 概率 {产物命令} {产物命令}示例：
yaml
result:
- 'MythicMobs@分解产物1 1-2 0.5 {[console]say %player_name% 获得了分解产物}'
- 'MythicMobs@分解产物2 2 1'每项产物独立计算概率。数量范围包含最小值和最大值。产物未抽中时不会创建物品，也不会执行该产物后附带的命令。
规则的 give-item 设置为 false 时，该规则不会生成或发放 result 中的产物，也不会执行产物级命令，但规则自身的 commands 仍会执行。
分解界面
| 区域 | 槽位 | 说明 |
|---|---|---|
| 输入区 | 0 至 17 | 实际开放数量由 open-decomposition-slot 控制 |
| 分隔区 | 18 至 26 | 使用填充物品锁定 |
| 分解按钮 | 22 | 左键处理首个物品栈，右键处理全部物品栈 |
| 产物预览区 | 27 至 44 | 最多展示 18 项产物 |
| 额外按钮区 | 45 至 53 | 对应额外按钮编号 0 至 8 |
界面行为：
- 界面固定为 54 格。
- 输入区可以开放
1至18个槽位。 - 产物预览来自输入区内第一个可以分解的物品。
- 预览会汇总该物品命中的全部规则。
give-item: false的规则不会产生预览物品。- 预览数量使用产物配置的最大数量，并受物品最大堆叠数量限制。
- 预览只展示配置结果，不进行概率抽取，不执行命令，也不实际发放物品。
- 预览 Lore 可以显示概率、最小数量和最大数量。
- 预览刷新检测间隔由
gui.preview-refresh-interval控制，单位为 tick，最小为1。 - 非输入槽位会被锁定，普通点击、拖拽和双击收集不能修改这些槽位。
- 分解按钮具有固定 1 秒交互冷却。
额外按钮
界面底部提供 9 个可配置槽位，编号为 0 至 8。删除 extra-button 或不配置任何按钮即可关闭全部额外按钮。
| 动作 | 功能 | 配置限制 |
|---|---|---|
put | 将玩家背包中满足按钮条件且能够分解的物品放入输入区 | 必须配置至少一行 condition，不能配置 command |
get | 取回输入区内的全部物品 | 不能配置 condition 或 command |
command | 按顺序执行按钮配置的命令 | 不能配置 condition，command 可以不填写 |
额外按钮支持左键和右键触发。每个按钮使用独立冷却，cooldown 单位为毫秒，填写 0 或不填写表示没有冷却。
命令执行身份：
| 前缀 | 执行身份 |
|---|---|
[console] | 控制台执行 |
[op] | 玩家临时获得 OP 后执行，完成后恢复原 OP 状态 |
| 无前缀 | 玩家自身执行 |
规则与产物命令
规则的 commands 会在产物处理完成后按顺序执行。产物定义中的 {命令} 会在对应产物成功生成并完成投递后执行。
两类命令均支持：
[console]控制台身份。[op]临时 OP 身份。- 无前缀玩家身份。
- PlaceholderAPI 玩家变量替换。
单条命令执行失败不会回滚已经发放的产物，失败信息会作为执行警告记录。
产物入库
- 每个实际生成的产物会独立执行入库流程。
- 玩家背包可以只接收物品栈的一部分。
- 剩余数量会继续交给后续入库目标。
- 成功接收过产物的目标会显示在玩家的结果消息中。
- 一个产物可能同时显示多个实际接收目标。
- 全部目标均未接收的剩余物品会掉落在玩家当前位置。
安全重载
/lyfj reload 会重新加载：
- 主配置及运行时默认值。
- 全局条件。
- 产物入库顺序。
rule目录中的全部规则。- 额外按钮。
- PlaceholderAPI、物品库和仓库连接状态。
插件会检查主配置字段、数据类型、条件语法、外部依赖、规则字段、规则 ID、产物格式、按钮槽位和按钮动作限制。
重载发现错误时，新配置不会替换当前运行数据，原有规则继续生效。只有警告时可以完成重载，警告会发送到控制台和指令发送者。
首次加载失败后，管理员仍可以使用 /lyfj reload 修复配置，也可以使用 /lyfj convert 转换旧版规则。其他业务指令会在 API 未就绪时被阻止。
旧版规则转换
插件可以读取 plugins/LyDecompositionReload/ 中的旧版数据：
- 主配置
config.yml。 extra目录及其子目录中的 YAML 文件。- 各文件中的
decomposition-set规则。
转换结果写入：
text
plugins/LyGalaxyDecomposition/rule/旧版转换/旧版配置转换.yml转换器会处理旧版材质 ID、名称、Lore、命令、产物数量、百分比概率和产物命令。没有物品库前缀的旧版产物会转换为 MythicMobs@物品ID。
如果目标转换文件已经存在，插件会在覆盖前创建备份。转换完成后会自动尝试重载；自动重载失败时，转换文件仍会保留，当前运行规则不会被替换。
指令与权限
插件只在 plugin.yml 中注册 /lyfj，没有声明独立的指令权限节点。普通玩家只能直接执行 /lyfj open，管理功能通过指令发送者是否为 OP 判断。
| 指令 | 使用者 | 说明 |
|---|---|---|
/lyfj open | 玩家 | 打开自己的分解界面 |
/lyfj help | OP | 查看插件指令帮助 |
/lyfj open [玩家] | OP | 为指定在线玩家打开分解界面 |
/lyfj test [玩家] | OP | 检测自己或指定在线玩家的主手物品，并列出全部命中规则 |
/lyfj list [页码] | OP | 分页查看当前加载的规则，每页显示 8 条 |
/lyfj reload | OP | 完整重载配置、规则、按钮和外部插件连接状态 |
/lyfj convert | OP | 转换旧版 LyDecompositionReload 规则并自动尝试重载 |
补充限制：
- 控制台执行
/lyfj open时必须填写在线玩家名称。 - 控制台执行
/lyfj test时必须填写在线玩家名称。 /lyfj open [玩家]和/lyfj test [玩家]只接受在线玩家。/lyfj list的页码必须是有效正整数。- 未知子指令不会执行任何业务操作。
permission()是规则条件函数，可以检查任意权限节点，但插件没有预设或注册固定的分解权限节点。
开发支持
插件提供公共 API 和分解事件，可用于：
- 判断 API 是否已经完成初始化。
- 获取全部规则、指定规则和全局条件。
- 匹配玩家物品能够触发的全部规则。
- 判断物品是否满足一组函数式条件。
- 生成不触发随机、命令和物品发放的产物预览。
- 在服务端主线程执行单个物品的分解。
- 重新加载配置并获取规则数、按钮数、警告和错误。
- 获取物品库、仓库与 PlaceholderAPI 的连接状态。
- 获取额外按钮配置。
- 通过统一物品库接口创建物品。
- 替换 PlaceholderAPI 变量。
- 按配置身份执行命令列表。
- 为玩家打开分解界面。
- 监听可取消的分解前事件和分解完成事件。
分解执行、完整重载、命令执行和打开界面等操作存在主线程要求。API 状态、返回数据和事件说明见开发接口。
注意事项
- 每条分解规则至少需要一行
condition。 - 规则 ID 不能在不同文件中重复。
- 主配置只允许
item-provider、delivery-order、global-condition、extra-button、gui、open-decomposition-slot和message根字段。 - 规则节点只允许
condition、give-item、commands和result字段。 - 主配置、规则或额外按钮包含不支持的字段时，重载会失败。
give-item: true但没有配置result时只产生警告，不会直接阻止重载。- 规则引用的物品库未安装、未启用或初始化失败时，重载会失败。
- 产物 ID 不存在时，预览可能无法展示，实际分解会返回配置错误。
papi()条件依赖 PlaceholderAPI。nbt()和hasnbt()依赖当前服务端版本的 NBT 适配器。- 外部仓库不可用时会被跳过，不会阻止其他入库目标继续处理。
- 外部插件可以通过分解前事件取消一次分解。
- 分解完成事件只会在分解执行成功后触发。
- 单个物品只有在分解执行成功后才会从输入槽位扣除。
- 关闭界面时，尚未处理的输入物品会自动返还，不会直接删除。