原创 开源 工具 ⚡ KaMenu⚡ - 全新菜单插件 | 对话框界面 | 探索无限可能 | 实现各种复杂逻辑 | 丰富交互体验 [1.21.6＋] 2.1.0

[MD] ### 菜单依赖检查顺序修复 - `Settings.need_placeholder` 现在会在 `Events.Open` 之前检查。 - 缺少必需的 PlaceholderAPI 扩展时，菜单不会再提前执行 Open 事件中的数据写入、扣款、物品或指令动作。 - Paper、Spigot 和 Floodgate 表单入口使用一致的检查顺序；强制重开路径仍保留依赖检查作为安全兜底。 ### Paper Dialog 解析统一 - Paper Dialog 改为使用与 Spigot、Floodgate 相同的共享菜单编译器，不再由平台入口单独解析 YAML。 - `Title`、`Settings`、`Body`、`Inputs`、`Bottom`、条件、变量、repeat、分页、输入清理和按钮定义先编译为统一模型，再由 Paper 原生渲染器显示。 - 修复 `Body.item.material` 未识别 `stock:<保存物品名>` 的问题；现在会读取 KaMenu 保存物品库中的完整 ItemStack，并按 `amount` 配置覆盖数量。 - Paper 按钮继续使用原生一次性 callback，并保留 actions、输入捕获、客户端 URL/复制动作、`Settings.lifetime`、菜单任务和生命周期行为。 - 非法 Dialog 参数仍会阻止菜单打开并保留底层异常，便于定位错误配置，现有菜单格式无需修改。 [/MD]

[MD] ### Geyser/Floodgate 基岩版按钮图标 - `Bottom` 普通按钮和 `repeat.item` 动态按钮新增可选的 `icon` 配置。 - 支持 `url` 网络图片和 `path` 基岩版资源包路径，URL 也可直接使用字符串简写。 - `repeat.item.icon` 支持 `{item.xxx}`、PlaceholderAPI 和 KaMenu 内置变量，可为每个动态项目生成不同图片。 - Floodgate 玩家打开无输入组件且至少含一个有效图标的菜单时，KaMenu 会发送带图标的基岩版 `SimpleForm`。 - Java 玩家、没有图标的菜单及带 `Inputs` 的菜单保持原有 Java Dialog/Geyser 转换路径，不改变现有行为。 [/MD]

[MD] ### Folia 关服修复 - 修复 Folia 核心关闭服务器时调用 Bukkit 全局任务取消接口导致的 `UnsupportedOperationException`。 - 关闭插件时改为使用 KaMenu 自身的调度任务清理逻辑，避免触发 Folia 不支持的全局调度器操作。 ### repeat 动态按钮矩阵补齐 - `type: repeat` 会按当前页实际渲染的动态按钮数量和 `columns` 自动补齐矩阵。 - 当按钮数量无法被 `columns` 整除时，追加空白按钮，使动态按钮区域保持完整对齐。 - 空白按钮没有显示文本，不执行 `item.actions` 或其他业务动作，点击后仅执行 `reset`。 - 如果 `item.width` 已配置，空白按钮会复用该宽度，保持整个动态按钮矩阵对齐。 - 上一页、下一页等普通分页按钮不计入动态按钮补齐数量，仍会在补位按钮后按配置顺序追加。 - Paper 与 Spigot 的 Dialog 渲染路径均保持一致。 [/MD]

本次更新主要兼容Spigot核心，无新增内容和改动。

[MD] ## 资源包插件字形兼容 ### ItemsAdder - 动态 Dialog 文本现在会主动调用 ItemsAdder API 解析 `:font_image:` - 支持 ItemsAdder `:offset_N:` 像素偏移符 - 解决 ItemsAdder 内部占位符在 Paper Dialog 中原文显示的问题 ### Oraxen - 支持 `<glyph:id>` 与短写 `<g:id>` - 同一 Oraxen 原始文本行支持 `<shift:N>` 像素偏移，可点击文本拆分后仍保持解析上下文 - 使用当前玩家的 Oraxen Resolver，保留字形字体、颜色、阴影和权限检查 - 只在文本出现 Oraxen glyph 标签时启用 Oraxen shift，避免与 CraftEngine 标签冲突 ### CraftEngine - 兼容 `<image:namespace:id>` 与 `<shift:N>` - 字形继续由 CraftEngine 的 Dialog 数据包拦截器处理，KaMenu 不重复转换 - 使用时需保持 CraftEngine `network.intercept-packets.dialog: true` [/MD]

[MD] ### 新增 ESC 暂停菜单入口 KaMenu 现在可以通过原版数据包，在客户端 ESC 暂停菜单中注册一个自定义入口按钮： 编辑 `plugins/KaMenu/pause_menu.yml` 执行: ```bash /km pause register ``` [/MD]

[MD] ## 新增功能 ### 1. 可点击文本支持 ItemStack 悬浮 可点击文本新增 `hover_item` 参数，鼠标悬停时可以展示完整 ItemStack，包括名称、Lore、附魔、模型和其他数据组件： ```yaml text: - '当前武器：<text="&6[主手]";hover_item=hand>' - '奖励预览：<text="&d[神奇之剑]";hover_item="stock:神奇之剑">' ``` 支持以下来源： - `hand`、`offhand` - `slot:<槽位>` - `armor:helmet`、`armor:chestplate`、`armor:leggings`、`armor:boots` - `stock:<保存物品名>` - `material:<材质ID>` 有效的 `hover_item` 优先于普通 `hover`；物品不存在时仍可使用 `hover` 文字作为回退。 ### 2. 新增 `checkitem` 物品属性变量 新增统一的物品属性查询能力。菜单内部使用大括号变量，其他插件通过 PlaceholderAPI 调用： ```text {checkitem:[hand;name]} %kamenu_checkitem_[hand;name]% ``` 支持的物品来源： - `hand`：主手物品 - `offhand`：副手物品 - `slot:<索引>`：玩家背包槽位 - `stock:<名称>`：KaMenu 保存物品 支持的属性： - 基础属性：`type`、`amt`、`name` - Lore：`lore`、`lore:<行号>`；行号从 `1` 开始 - 附魔：`enchants`、`ench:<附魔ID>` - 模型：`model` / `item_model` - 自定义模型 ID：`cmd` / `custom_model_data` / `custom_model_id`，默认按整数输出 - 耐久：`dmg`、`dura`、`dura_pct` `name` 和 Lore 默认输出纯文本，也可使用第三个参数 `fmt:legacy` 或 `fmt:mini`。`fmt` 仅影响名称和 Lore 文本。`lore` 返回 JSON 字符串数组，`enchants` 返回包含 `key` 和 `level` 的 JSON 对象数组，可直接作为 repeat 数据源。 原版附魔 ID 可省略 `minecraft:`；自定义附魔必须提供完整命名空间。 保存物品名包含分号时，使用反引号包裹内部名称，例如 ``{checkitem:[stock:`活动;长剑`;name]}``，避免与 YAML 外层引号冲突。 ### 3. `hasItem` 支持自定义模型 ID 原有 `hasItem` 条件和 `%kamenu_hasitem_[...]%` 数量变量现在可以分别判断 ItemModel 与整数 CustomModelData： ```yaml condition: 'hasItem.[mats=PAPER;amount=1;model=custom:magic_scroll]' condition: 'hasItem.[mats=PAPER;amount=1;custom_model_id=10001]' ``` - `model` / `item_model`：匹配 NamespacedKey 类型的 ItemModel - `cmd` / `custom_model_data` / `custom_model_id`：匹配整数 CustomModelData 两类模型条件可以同时填写，此时物品必须同时满足。`hasItem` 与 `checkitem` 现已共用模型属性读取逻辑，避免两套功能对同一物品给出不同结果。同时修复主手快捷栏物品可能被重复计数的问题。 [/MD]

[MD] ## ✨ 新增功能 ### 1. 新增菜单存在时间上限 `Settings` 新增 `lifetime`，用于限制 Dialog 菜单的最大存在时间，单位为秒，默认值为 `300`（5 分钟）： ```yaml Settings: lifetime: 300 ``` 该值同时控制 Paper callback 的有效期和 KaMenu 服务端的菜单关闭定时器。 达到时间上限后，KaMenu 会： - 确认玩家仍处于原菜单会话，避免旧定时器关闭后来打开的新菜单 - 主动关闭已超时的 Dialog - 停止该菜单的 `Events.Tasks` - 清理 repeat 分页状态 - 执行 `Events.Close`，用于完成菜单清理逻辑 超时属于硬性上限，`Events.Close` 中的 `return` 不会阻止菜单关闭。`lifetime` 小于或等于 `0` 时会回退到默认的 300 秒。 `reset` 或打开其它菜单会替换原菜单会话并重新计时；旧菜单的超时任务不会误关新菜单。 --- ## 问题修复 ### 1. 修复菜单内 JavaScript 包被错误识别为全局包 修复菜单 UI 字段和条件化配置在解析 `{js:[name]}` 时丢失当前菜单配置的问题。 例如菜单已经定义： ```yaml JavaScript: player_name: | player.getName(); Body: info: type: message text: '&a{js:[player_name]}' ``` 旧版本可能跳过菜单内的 `JavaScript.player_name`，错误地只检查 `plugins/KaMenu/js/player_name.js`，并输出类似警告： ```text JavaScript package 'player_name' not found (checked global js/player_name.js) ``` 现在条件值解析器会保留当前 `YamlConfiguration` 上下文，恢复正确的查找顺序： 1. 当前菜单的 `JavaScript.<name>` 2. 全局 JavaScript 包 `plugins/KaMenu/js/<name>.js` 修复范围包括： - `Title` 条件值 - `Body` 文本和物品描述 - `Inputs` 文本与默认值 - `Bottom` 按钮文本和 tooltip - 条件化字符串、字符串列表和类型字段 - 条件值内部使用的菜单 JavaScript 包 现有 `{js:[name]}` 语法无需修改。 [/MD]

初步支持Folia核心

[MD] ## 问题修复 ### 1. 修复 JavaScript 延迟调度错误 修复 JavaScript 内置辅助方法在调用 Bukkit 延迟任务时可能出现的参数类型不匹配问题： ```text NoSuchMethodException: CraftScheduler.runTaskLater(...) ``` 该问题可能在 JavaScript 包或菜单内脚本使用延迟执行逻辑时触发。现在延迟 tick 参数会正确转换为 Bukkit 调度器需要的 `Long` 类型，并将 JavaScript 回调包装为 Java `Runnable`，避免 Nashorn 对方法重载解析失败。 同时更新了 JavaScript 文档中的延迟执行示例，避免继续推荐不适合当前独立执行上下文的旧写法。 ### 2. 修复自定义指令重载后 TAB 补全不立即刷新 修复新增、删除或修改 `custom-commands` 后，在线玩家需要退出重进服务器才能获得最新 TAB 补全的问题。 现在执行以下重载后，会主动刷新所有在线玩家的客户端命令树： - `/kamenu reload config` - `/kamenu reload all` 这样自定义指令重新注册完成后，在线玩家可以立刻使用新的命令补全。 ### 3. 支持播放资源包自定义音效 `sound:` 动作现在会在原版声音 Registry 查找失败时，自动使用字符串 sound key 转发给客户端播放。 这意味着可以直接播放资源包 `sounds.json` 中定义的自定义声音，例如： ```yaml - 'sound: mypack:ui.click;volume=1.0;pitch=1.0;category=ui' ``` 同时修复了原版声音 ID 使用下划线风格时的兼容问题，例如 `ENTITY_PLAYER_LEVELUP` 会尝试转换为 `entity.player.levelup`。 [/MD]