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

[MD] ### 物品显示新增 `hide_tooltip` 与 `hide_components` 容器菜单按钮与 Dialog 物品新增两个 tooltip 隐藏属性，均可用于 `display`（容器）或 `item` 主体（Dialog）。 - `hide_tooltip`：隐藏整个物品提示框。 - `hide_components`：只隐藏原版自动生成的组件行（属性、附魔、耐久、可破坏/可放置等），**保留**菜单自定义的名称与 Lore。 - Paper 上通过隐藏数据组件实现；Spigot 等非 Paper 核心退化为隐藏常见组件行的物品旗标。 - `hide_tooltip` 优先于 `hide_components`；需要 1.20.5+ 核心，旧核心会输出配置警告并跳过。 ### 物品显示新增 `color` 与 `damage`，并更新 `glow` - `color`：为皮革护甲、药水、烟花效果染色，支持 `R,G,B` 或 `#RRGGBB`。 - `damage`：设置已损失耐久（仅可损坏物品）。 - `glow` 改为三态：未设置=不处理，`true`=强制发光，`false`=取消光效。1.20.5+ 使用原版附魔光效覆盖组件；旧核心或不兼容时，`true` 回退为附魔模拟方案，`false` 在无法取消时仅记录提示。不再提供单独的 `glint_override` 键。 - 已在 Paper 26.3（build 159 BETA）验证相关属性正常加载和工作。 - 中英文 Container 按钮与 Dialog Body 文档已同步。 ### 新增 `post-effect` 动作（屏幕后期效果） 新增 `post-effect` 菜单动作，操作玩家的屏幕后期效果（全屏着色器滤镜），用于打开菜单时背景虚化、 进入场景时施加氛围滤镜等。 - 格式：`post-effect: type=add|remove|set|clear|list;effect=<namespace:name>` - 原版内置效果：`minecraft:blur`、`minecraft:creeper`、`minecraft:spider`、`minecraft:invert`、`minecraft:entity_outline`。 - 需要 Paper 26.3+；旧核心或不支持时记录警告并跳过，不影响其余动作。 - 自定义效果可由资源包在 `assets/<namespace>/post_effect/<name>.json` 提供。 - 支持目标选择器，可作用于其他在线玩家。 ### 文档同步 - 中文 `docs/modern-dialog/actions.md` 新增 `post-effect` 说明。 - 英文 `docs-en/modern-dialog/actions.md` 新增 `post-effect` 说明。 ### JavaScript `giveItem` helper 新增 `giveItem(material, amount, targetPlayer?)`，供 JavaScript 复用内置 `item: type=give` 的物品构造、背包写入、满包掉落及提示逻辑。 - 支持原版材质，例如 `minecraft:bread`。 - 支持 CraftEngine 物品，例如 `ce:customfishing:simple_bait`。 - `targetPlayer` 可选，默认使用当前脚本上下文的玩家。 - 中英文 JavaScript 文档与 KaMenu Menu Author Skill 已同步。 ### `item: type=take` 支持 `cmd` 匹配 `item: type=take` 新增整数 CustomModelData 匹配维度，与既有 `mats`、`lore`、`model` 并列，可组合使用。 - 新增参数 `cmd`（别名 `custom_model_data`、`custom_model_id`），读取物品的整数 `custom_model_data` 组件。 - `mats` 不再是必需项：可仅用 `cmd`（或 `lore`/`model`）精确定位物品，便于扣除不带 `craftengine:id` 标签的 CraftEngine `client-bound-model` 物品。 - 与 `hasItem`/`%kamenu_hasitem_%` 的 `cmd` 语义保持一致。 - 中文 `docs/modern-dialog/actions.md` 与英文 `docs-en/modern-dialog/actions.md` 的 `item` 动作说明已同步。 ### Container repeat 动态列表按钮 Container 按钮新增 `type: repeat`，将 `Layout` 中同 ID 的固定槽位作为动态列表矩阵，并为每个槽位绑定对应数据项。 - 支持 `source`、`item.display`、`item.actions`、JSON/字符串列表和 JavaScript 数据源。 - 每页容量由当前 Layout 中该按钮 ID 的槽位数决定；新增 `repeat-page: <id> next|prev|+N|-N|页码` 独立翻页，不影响 Container Layout 翻页。 - 支持 `{page:<id>}`、`{pages:<id>}`、`{total:<id>}`、`{start:<id>}`、`{end:<id>}` 分页变量。 - 空列表默认显示 AIR 且无点击动作；可用 `empty.display` 配置无动作的占位物。 - 中文/英文 Container 按钮、布局及动作文档与 KaMenu Menu Author Skill 已同步。 ### 统一物品绑定配置 物品绑定统一放在 `item_bindings.yml`，用 `item`、`trigger` 和 `actions` 分别配置匹配物品、触发手势及执行动作；打开菜单使用 `open: <菜单ID>`。`trigger.type` 支持左键、右键、F、Q，`trigger.sneaking` 区分潜行，点击可用 `trigger.target` 指定空气或方块。F 优先匹配物品绑定，Q 命中时取消丢弃；未配置冷却时默认 500ms。升级时自动迁移旧格式及 `config.yml` 中的物品监听器。详见 `docs/config/item-bindings.md`。 ### 自定义指令别名 对象式自定义指令（`menu:` 或 `actions:`）新增 `aliases` 列表，可为同一指令注册多个别名。别名共用原指令的菜单/动作定义及参数 Tab 补全；字符串简写 `command: menu/id` 不支持声明别名，需改用对象格式。详见 `docs/config/customCommands.md`。 [/MD]

[MD] ### 新增公开事件 API KaMenu 现在提供两个公开 Bukkit 事件，供其他插件（如 EcoQuests、KaScoreboard 等）监听菜单打开与数据变化，以驱动任务、统计等逻辑。事件类位于 `org.katacr.kamenu.api.event` 包。 #### `KaMenuOpenEvent` — 菜单打开事件 - 玩家打开 KaMenu 菜单时触发，在菜单真正渲染（容器菜单与 Dialog 菜单均可）前同步抛出。 - 携带字段：`menuId`（菜单 ID，如 `"主菜单/主菜单"`）、`source`（打开来源：`COMMAND` / `BUTTON` / `API` / `OTHER`）、`arguments`（传入菜单的参数列表），以及继承自事件的玩家引用。 - 覆盖全部打开入口：`MenuUI.openMenu` / `openConfig` / `forceOpenMenu` / `forceOpenConfig`（含 KaMenuAPI 与自定义指令），每个入口各触发一次，不重复。 #### `KaMenuDataChangeEvent` — 数据变化事件 - KaMenu 数据存储（`data` / `gdata` / `list` / `glist` / `meta` / 玩家临时数据）发生写入、修改、增减或删除时触发。 - 携带字段：`scope`（作用域：`PLAYER_DATA` / `GLOBAL_DATA` / `PLAYER_LIST` / `GLOBAL_LIST` / `META` / `PLAYER_TMP`）、`action`（操作：`SET` / `MODIFY` / `ADD` / `REMOVE` / `CLEAR`）、`key`、`value`（删除类操作可能为 `null`）、`player`（玩家在线时非空，全局作用域为 `null`）。 - 由异步数据库写操作触发，KaMenu 自动切回服务端主线程后再抛出，监听器内可安全调用 Bukkit API。 ### `item_bindings.yml` / `listeners.item-lore` 支持动作包 物品右键绑定现在除「打开菜单」外，还可直接执行动作列表。 - 新增字段 `actions`：要执行的动作列表，支持全局动作包调用（如 `actions: voucher/use_plot`）。 - `menu` 与 `actions` 至少配置一个；**两者同时配置时后台输出警告，并以 `menu` 为主，`actions` 被忽略**。 - 文档：`docs/config/item-bindings.md` 与 `docs-en/config/item-bindings.md` 已同步。 ### `&item:[...]` 图标强制白色 `&item:[...]` 转换为 MiniMessage `<sprite>` 后会继承周围文本颜色。现生成时强制包裹 `<white>...</white>`，确保物品图标始终为白色，不再被其他行的 `&a`/`&7` 等颜色染色。 ### 修复 `item: type=take` 无法扣除原版物品 修复了 `item: type=take;mats=<原版材质>;amount=<数量>` 无法扣除原版物品的问题。 此前扣除动作对原版物品（如骨头、钻石等）始终不生效，`give` 发放不受影响。 现在原版物品可正常扣除。 [/MD]

[MD] ### 原生 HMCCosmetics 饰品槽位引用 - `material` 新增四种 HMCCosmetics 槽位引用：`[HMCC_HAT]`、`[HMCC_BACKPACK]`、`[HMCC_OFFHAND]`、`[HMCC_BALLOON]`。与原版装备槽位一致，也可用 `[HMCC_HAT:Steve]` 或 `[HMCC_HAT:{meta:player}]` 读取指定在线玩家。 - KaMenu 通过 HMCCosmetics 公开 API 直接克隆玩家当前槽位的最终 `ItemStack`，不再需要通过 PAPI 返回的基础材质、`item_model` 或 CustomModelData 重组图标。因此会完整保留 CraftEngine 物品组件、PDC、CustomModelData，以及可染色饰品的玩家专属颜色。 - HMCCosmetics 保持软依赖：未安装、目标用户尚未初始化或槽位为空时安全回退为空槽位占位物品，不影响其他菜单。Dialog 与 Container 共用该能力。 - Lobby 的「个人信息」菜单四个 HMCCosmetics 槽位已迁移到原生引用，修复图标退化为 `PAPER` / `LEATHER_HORSE_ARMOR` 的问题。 ### 容器菜单物品小图标修正与 SX-Item 支持 - 修复 2.0.6 引入 Component 路径后容器物品名/Lore 默认显示为斜体的问题：原版 Minecraft 中通过 Component 设置的自定义物品名/Lore 默认斜体，而此前的 Legacy 字符串路径不会。现已在 Component 路径显式关闭斜体，使物品名/Lore 外观与旧版一致（Dialog 与容器标题本就走 Component 路径，不受影响）。 - 修复 `&item:[wheat]` 等既有物品态又有方块态的材质显示为方块态异常纹理的问题：Bukkit 默认将这类名称解析为方块态（如 crops 等特殊方块），现改为**优先使用物品态**（`minecraft:item/...`），仅当物品态不可用时回退方块态（`minecraft:block/...`）。 - 新增 **SX-Item** 自定义物品支持：容器菜单物品槽（`material: sxitem:<id>` 或 `sx:<id>`）与 Dialog 物品组件现在可显示 SX-Item 生成的物品，悬浮文本（显示名/Lore）随物品本体展示。同时 `&item:[sxitem:<id>]` 内联小图标也会尝试按物品自身 `item_model` 解析精灵。可点击文本中的 `hover_item=sxitem:<id>`（或 `material:sxitem:<id>`）悬浮物品组件也已支持，Paper 通过 `ItemStack.asHoverEvent()`、Spigot 通过完整组件映射传递真实外观。 ### Dialog 按钮 `tooltip` 的 `\n` 换行修正 - 修复 Dialog 按钮 `tooltip` 中字面 `\n`（反斜杠 n）不换行、直接显示为字面字符的问题。 - 原因：`tooltip` 解析路径（`ConditionValueResolver.getInlineConditionalStringList`）此前未将字面 `\n` 转换为真实换行符，而同文件的 `getString` 路径已有该转换。现已统一补上该转换，使单行 `tooltip: 'line1\nline2'` 可正常换行（列表写法 `- 'line1'` / `- 'line2'` 本就支持）。 ### 容器与 Dialog 物品支持 `tooltip_style` - 新增 `tooltip_style` 物品显示属性：容器菜单按钮槽位（`display.tooltip_style`）与 Dialog 物品组件（`item.tooltip_style`）现可设置自定义 tooltip 背景与边框样式（格式 `namespace:key`），指向资源包 `assets/<namespace>/textures/gui/sprites/tooltip/<key>_background` 与 `<key>_frame`（Minecraft 1.21.4+ 的 `minecraft:tooltip_style` 数据组件）。旧核心不支持时输出警告并忽略该字段。该属性也会随物品一并被 Dialog 悬浮（`hover_item`）与 Spigot 组件映射保留。 ### `/km item give` 给予时替换 lore 中的 `{player}` - 通过 `/km item give <物品> <玩家> [数量]` 指令给予物品时，若物品 lore 中包含字面 `{player}`，会自动替换为**被给予玩家**的名称（例如 `灵魂绑定：{player}` → `灵魂绑定：Steve`）。该替换仅发生在 `/km item give` 指令路径，菜单内 `stock-item: type=give` 动作不替换。 - 替换后物品 lore 已与数据库模板不同，因此 `stock-item: type=take`（基于 `isSimilar()` 全量比较）无法再用原始模板选中该物品；如需回收，改用 `item: type=take;lore=灵魂绑定：{player}`，其中 `{player}` 在执行 take 时会被解析为触发玩家自身名称，从而精准匹配其名下物品。 ### 修复 SX-Item 物品创建失败回退为 PAPER - 修复 `ExternalItemAdapter` 中 SX-Item 集成因调用了不存在的 `SXItem.getInstance()` 方法（Lombok `@Getter` 实际生成 `SXItem.getInst()`）导致反射失败、物品回退为 PAPER 的问题。现已改用正确的 `SXItem.getItemManager()` 静态方法获取物品管理器，`getItem(id, player, args)` 与 `getItemKey(item)` 调用保持不变。 [/MD]

[MD] ### 运行时物品判断与扣除支持 `name` 与 `item_model` - `hasItem` 条件与 `item: type=take` 扣除动作现在支持按显示名（`name`）与物品模型（`item_model`，命名空间+ID 字符串格式，非数字 `custom_model_data`）匹配。 - 匹配规则：`name` 为**包含匹配**（忽略大小写、忽略颜色码 `§`），与已有 `lore` 匹配语义一致；`item_model` 为精确匹配（忽略大小写）。 - `mats` 不再是必填：允许仅按 `name` 或仅按 `item_model` 判断/扣除物品。这覆盖了 RPG 类型服务器使用铁砧改名或自定义模型物品、并以显示名/模型作为有效识别依据的场景。 - 说明：按 `name` 判断依赖显示名文本，理论上仍可被铁砧改名绕过；这是 RPG 玩法的常见约定，KaMenu 现提供该能力，由菜单作者自行评估安全性。 ### 容器菜单迁移（TrMenu）— `item` 条件与 `take-item` 动作支持 `name` / `item_model` - TrMenu 的 `item *"amount:1,name:<名称>"` 这类仅按显示名或物品模型的判断/扣除，现可迁移为 `hasItem.[name=<名称>;amount=1]` / `item: type=take;name=<名称>;amount=1`（以及 `item_model` 等价形式），不再发 `TRM_ITEM_MATCHER_UNSUPPORTED` / `TRM_CONDITION_UNSUPPORTED`。 - 修正了迁移器词法切分：TrMenu 原始语法中 `*` 前缀紧跟引号 `*"amount:1,name:..."` 现会被正确拆分为独立 `*` 标记与后续引号内容，避免此前将整段当作单个畸形 trait 而误报 `Unknown ItemMatcher trait`。 - `data`、`head`（材质头像/纹理）仍因无便携等价而不迁移。 ### 物品模型展示与容器布局兼容性修正 - 修复 Dialog 物品组件和容器菜单 `display` 组件设置 `item_model` 后未可靠写入 Bukkit `ItemStack` 的问题；同时兼容现代核心中 `ItemMeta` 接口与具体实现类的 API 调用。 - 容器布局行现在始终归一化为容器规定的列数：不足的部分自动补为空槽，超出的部分截断，不再因列数不符禁用菜单。 - Layout 引用未定义的按钮键、Buttons 中未被 Layout 使用的键现在直接允许，不再生成 `layout.button_not_found` 或 `button.unused` 诊断。 ### 容器菜单物品小图标（`&item:[...]`）支持 - 在 1.21.9+ 服务器上，容器菜单的按钮显示名、Lore 和菜单标题现在支持 `&item:[coal]` 物品小图标语法，与 Dialog 保持一致。 - 通过反射调用 Paper 的 Adventure Component API（`ItemMeta.displayName(Component)`、`ItemMeta.lore(List<Component>)`、`InventoryView.title(Component)`）实现；旧核心自动回退到 Legacy 文本，不产生错误。 [/MD]

[MD] ### KaProxy 跨服目标选择器 - 新增 `{cross}` 标记。在动作末尾的目标选择器 `{player: 选择器}` 后追加 `{cross}`，即可通过 KaProxy 把动作转发到其他后端执行。 - 新增 KaMenu `kaproxy.enabled` 配置项。启用后自动注册 `kaproxy:main` 插件消息通道；关闭或卸载时自动注销。 - KaProxy 新增 `modules.kamenu` 模块及 `servers` 配置。列表控制可接收跨服动作的后端；设为 `all` 或 `*` 时转发到所有后端，始终排除来源服。 - 目标后端收到动作后在本地求值选择器，因此 PAPI 变量和 KaMenu 内置条件在各服均可正常使用。 - 跨服执行采用后端白名单保护，仅支持 `tell`、`actionbar`、`title`、`sound`、`hovertext`、`money`、`points`、`data`、`gdata`、`tmpdata`、`meta`、`set-data`、`set-gdata`、`set-meta`。非白名单动作会被拒绝并记录警告。 - `/kaproxy status` 现在显示 Kamenu 模块状态。 ### 文档 - 新增 KaProxy Kamenu 模块中英文文档，并补充 KaMenu 中英文动作文档与菜单编写 Skill 的跨服选择器说明。 ### 容器类多页菜单与运行时动态槽位 - **多页菜单**：KaMenu 容器类菜单现在支持原生多页布局。`Layout` 接受页数组（如 `[['A...'], ['B...']]`），`page: n` / `page: next` / `page: prev` / `page: +n` / `page: -n` 动作在会话内安全切页，不触发菜单 Open/Close，并保留参数、任务和图标状态。迁移器将 TrMenu 多页 `Layout` 与 `Default-Layout` 无损转换为 `Layout` 页数组与 `Settings.default_page`。 - **运行时动态槽位**：按钮可声明 `slot` 表达式（支持 PAPI 变量与 KaMenu 变量），在每次打开、刷新或翻页时按玩家状态解析为槽位，不再依赖静态 `Layout` 字符。例如 `slot: '%player_empty_slots%'` 让按钮随玩家空槽数量移动。 - **多副本槽位**：`slot: [8, 9, 10]`（扁平列表）表示同一按钮同时渲染在多个槽位。 - **运动帧动画**：`slot: [[8], [9], [10]]`（列表的列表）表示逐帧循环，每次刷新把按钮移动到下一帧位置，实现 TrMenu 风格的运动槽位效果。 - 点击位置优先查运行时动态槽位映射，再回退到静态布局。动态槽位与静态布局槽位冲突时跳过该动态按钮，旧槽位物品在帧切换时被自动清理。 - **运行时标题覆盖（`set-title` 动作）**：新增 `set-title: <标题>` 动作，可在点击或任务中动态覆盖当前容器会话的库存窗口标题，优先级高于配置 `Title`。覆盖值会一直生效直到会话结束，后续 `refresh: title` / `refresh: *` 与周期 `Title-Update` 都以该覆盖值刷新，因此可结合 PAPI 变量做出随状态变化的标题。该动作与 `title:`（向玩家发送淡入淡出大标题特效、不影响库存标题）相互区分。 ### 修复 - 修复 Paper 原生 Dialog 的 `Inputs` 中 `type: checkbox` 无论勾选状态如何都返回 `false` 的问题。回调现在按组件声明类型读取响应，checkbox 使用布尔值读取，不再被数值读取的默认 `0` 覆盖。 - 修复 Paper 平台上聊天可点击文本（`hovertext:` 发送、`<text=...;actions=...>`）的自定义回调在执行 `Events.Click` 动作时丢失 `contextId` 的问题。`contextId` 现已沿解析链路（`parseClickableText` → 回调 → `executeActionList`）透传，与 Spigot 路径一致，使点击回调能正确关联原菜单的参数会话与任务上下文（此前 Paper 该路径的 `contextId` 为空）。 [/MD]

[MD] ### 临时数据 tmpdata - 新增 `tmpdata:` 动作，支持带到期时间的玩家级键值对，到期后自动清空，适合冷却、限时加成、限时称号等场景。 - 数据持久化到 SQLite/MySQL，玩家下线或服务器重启后仍按原到期时间计算，不会提前失效。 - 支持 `set`、`add`、`take`、`addtime`、`taketime`、`refresh`、`delete` 七种操作类型。 - `ttl` 参数支持纯数字（按秒）与 `1d2h30m15s` 组合（d/h/m/s，不区分大小写）两种写法，`ttl=0` 可作立即作废。 ### 时间与数值边界 - `addtime` 只延长到期时间，`taketime` 提前到期；`taketime` 后剩余时间小于等于 0 时立即删除该键（扣时间溢出处理）。 - `refresh` 把到期时间重置为 now + `ttl`，不保留剩余时间。 - `add` / `take` 命中有效键时只改动数值，提供 `ttl` 时同时续期；键不存在或已过期时必须有 `ttl` 才能按新键写入。 - `addtime` / `taketime` / `refresh` 作用于不存在或已过期的键时安全跳过并输出警告，不会复活旧键。 - 到期时间戳运算使用饱和加法，极端数值不会导致 Long 溢出。 ### 读取与剩余时间展示 - 新增 `{tmpdata:键名}`（存储值）、`{tmpdata_time:键名}`（剩余秒数，纯整数，已过期返回 `0`）、`{tmpdata_time_format:键名}`（可读文本如 `1天 2时 30分 15秒`）三个内置变量，可在普通文本与条件表达式中使用。 - 新增 PAPI 占位符 `%kamenu_tmpdata_键名%`、`%kamenu_tmpdata_time_键名%`（纯数字秒数，方便其他插件直接数值判断）、`%kamenu_tmpdata_timeformat_键名%`（用户可读文本）。 - 新增 JavaScript 便捷函数 `tmpdata(key, targetPlayer)`，脚本内也可用 `kvar("tmpdata_time:key")`、`kvar("tmpdata_time_format:key")` 读取剩余时间。 - 到期值读取时立即返回空，数据库中的过期行由周期任务（`config.yml` 的 `tmpdata-purge-interval`，默认 60 秒）在异步线程物理清理。 [/MD]

[MD] ### Container 自由槽位 - 新增顶层 `Free-Slots`，可在箱子、漏斗、发射器和投掷器菜单中定义一个或多个具名真实物品槽位。 - 支持左/右键放入和取出、同类物品合并、异种交换、Shift 转移及受控拖拽；数字键、副手、双击、丢弃和创造克隆等高风险操作默认拒绝。 - 新增 `place` / `take` 开关和条件，以及 `place`、`take`、`deny_place`、`deny_take` 事务事件；拒绝操作时物品保持在原位置。 - 新增 `{free:<id>.*}`、`{free:incoming.*}`、`{free:stored.*}` 和 `{free:result.*}` 物品属性变量，支持数量、材质、名称、Lore、附魔、模型、外部物品来源等状态。 - 新增 `[FREE:<id>]` 完整 ItemStack 预览，可保留药水、书本、PDC 及 Bukkit 可访问的其他物品元数据。 ### 原子消费与返还 - 新增 `free-slot` 动作，支持单槽消费、多材料原子消费、主动返还一个或全部自由槽，以及刷新引用自由槽的按钮。 - 多材料不足、ID 无效、会话失效或背包容量不足时不执行部分修改，并中断当前动作链，避免材料不足仍发放奖励。 - 自由槽变化后自动刷新全部 Container 按钮，`variants` 可立即根据材料状态切换外观和动作。 ### 持久化托管与安全恢复 - 新增自由槽持久化托管账本和 `PREPARED`、`HELD`、`RETURN_PENDING` 等状态，SQLite 与 MySQL 写入按会话串行执行。 - 正常关闭、菜单跳转、重载和玩家退出时返还真实物品；背包不足时保留待返还记录并在玩家下次登录时重试。 - 释放示例菜单触发菜单重载前会先安全关闭活动 Container 会话，避免旧代际窗口遗留自由槽物品。 - 插件停用时保留托管记录并等待已开始的 SQL 操作，避免 Folia 玩家调度与数据库连接池关闭时序导致物品丢失。 - 修复新版 Paper 不再提供 SnakeYAML 私有 `Base64Coder` 时，自由槽首次放入物品抛出 `NoClassDefFoundError` 的问题；旧版换行 Base64 数据仍可读取。 - 优化自由槽放入、取出、交换、Shift 和拖拽的客户端同步，在玩家事件线程直接提交已校验的最终状态，避免取消原版事务后出现回滚再渲染的双重动画。 - 自由槽 SQL 托管失败时会关闭当前窗口并进入统一返还流程，避免已提交到 UI 的真实物品滞留在无可靠账本的会话中。 - Paper、Folia 与 Spigot 统一使用服务端当前槽位和玩家光标重放已取消的左右键事务，不再依赖不同核心的 `InventoryAction` 或事件光标快照，避免普通放入和取出时丢失物品。 ### 兼容性与文本图标 - 修复 Spigot Dialog 可点击文本在 `text` 或 `hover` 中包含 ItemsAdder、Oraxen、CraftEngine 字形标签时，被内部 `>` 提前截断并退化为纯文本的问题。 - 扩展 `&item:[...]` 二维图标语法，可自动解析原版材质以及 ItemsAdder、Oraxen、CraftEngine 自定义物品纹理，并支持通过根目录 `item_sprites.yml` 覆盖复杂模型的图标。 - Sprite 图标仅在 Minecraft `1.21.9+` 启用；运行于 `1.21.8` 及以下服务器时会安全隐藏标记，且不调用第三方物品 API 或读取其资源包。 ### TrMenu 迁移修复 - 修复 `action` / `actions` 被宽泛匹配为 `actionbar` 的问题；标准 YAML 锚点包装的 `actions` 列表会先展开，再逐项转换内部动作。 - 迁移器现在处理 YAML 解析后的锚点内容，不再把 `*锚点名` 当作动作文本；源锚点名称可能由输出序列化器展开或重新命名。 [/MD]

[MD] ### 容器类菜单文档重构 - 重构中英文容器类菜单文档，为 `Type`、`Title`、`Settings`、`Layout`、`Buttons`、`Properties`、刷新机制和 `Events` 增加字段一览表、逐项说明和实际案例。 - 新增从文件创建、布局设计、按钮定义到重载打开的容器类菜单新手教程，并补充常见解析错误和动态 `variants` 示例。 - 完善容器类菜单文档导航、顶层配置流程、跨版本边界和 Dialog 与容器类菜单的结构差异说明。 - 将原 TrMenu 迁移页面重构为统一迁移总览，新增 DeluxeMenus 快速迁移教程、不兼容内容列表及迁移报告和 `TRM_*` 错误代码解析。 - 补充容器类菜单 `Title` 的字符串列表轮播模式，说明 `Title-Update` 每次推进一项，以及手动刷新只重新解析当前项的区别。 ### 条件列表解析加固 - 支持在 Dialog 消息文本、Body 物品 Lore、按钮悬浮文字和容器物品 Lore 中按 YAML 顺序混写静态字符串与条件分支。 - 条件分支可在原位置插入一行或多行内容；完全由条件 Map 组成的旧配置仍保持首个非空候选语义。 - 新增行尾 `{condition: 条件}` 快捷条件，可用于上述字符串列表和所有字符串动作；条件不成立时跳过整行或整条动作。 - 统一单行动作修饰符为 `{chance: 数值}`、`{wait: tick}` 和 `{condition: 条件}`，不再使用别名、尖括号或等号格式。 - TrMenu 迁移器可将源 Lore 的行尾条件和动作概率/延迟转换为 KaMenu 标准修饰符。 ### 迁移日志输出 - `/km migrate dm` 和 `/km migrate trmenu` 的逐文件结果、完整诊断与冲突明细改为写入 `plugins/KaMenu/logs/migration/` 下的独立日志文件。 - 聊天框仅保留迁移、入口合并、运行时重载摘要和日志路径；日志写入失败时完整报告会回退到服务器控制台。 ### 菜单引用与 TrMenu node 迁移 - 新增菜单级 `References`，支持 `{ref:path}` 公共引用、`{config:path}` 当前配置引用，以及 Dialog 组件和容器按钮中的 `{self:id}` / `{self:path}` 自身引用。 - 新增 `{ref:[path;arg0;arg1]}` 参数模板与 `{refarg:n}` 占位符；支持嵌套引用、大小写不敏感路径、简单列表换行展开，并检测缺失路径、结构引用、循环和超过 16 层的递归。 - `{ref:*}`、`{config:*}` 和 `{self:*}` 可安全用于条件表达式；修复 `{self:path}`，现会返回当前组件或按钮的完整配置路径。 - TrMenu 迁移器现可将静态 `{node:*}` / `{nodes:*}` / `{n:*}` 转换为 KaMenu 引用，只按需复制实际使用的节点到 `References.trmenu`。 - 支持 TrMenu node 模板参数和图标上下文 `@iconId@`，动态路径或不可嵌入的结构会生成明确的 `TRM_NODE_*` 诊断，不会猜测转换。 [/MD]

[MD] ### Container 按钮状态变体 - 新增 `Buttons.<id>.variants`，允许同一个物理槽位根据权限、冷却、物品、数据或其他条件显示不同的完整按钮状态。 - 每个变体独立配置完整的 `display` 和 `actions`，避免为同一槽位的名称、Lore、材质和点击动作重复编写条件。 - 支持 `priority` 优先级：数值越小越优先；相同优先级保持 YAML 声明顺序。 - 当所有变体都未指定 `priority` 时，严格按照 YAML 从上到下选择第一个满足条件的变体。 - 渲染和点击时都会重新判断当前变体，避免权限或冷却变化后执行已经过期的动作。 - 保留旧版按钮格式兼容；同一个按钮不能混用 `variants` 与顶层 `display` / `actions`。 - 增加变体配置错误诊断，包括缺少 `display.material`、无效 `priority` 和混用旧格式等情况。 ### DeluxeMenus 迁移增强 - DeluxeMenus 中同一 `slot` 的多个候选物品现在会自动迁移为 KaMenu 的 `variants`。 - 迁移器按 DM 的 `priority` 升序处理，相同优先级保持源文件顺序。 - DM 未显式配置 `priority` 时，迁移器会写入 DM 的默认有效值，避免迁移后候选顺序发生变化。 - `requirements_menu.yml` 已用于实际 Paper1.16.5 测试服验证，3 个菜单成功生成，运行时菜单重载成功。 - 移除插件资源内的静态 `dm_migrated` 迁移样例，迁移结果仅在运行时输出到 `plugins/KaMenu/menus/dm_migrated`，避免将第三方菜单快照打包进插件。 ### TrMenu 迁移系统 - 新增 `/km migrate trmenu`（别名 `trm`），将 TrMenu stable-v3 经典库存菜单编译为 KaMenu V2 Container 标准 YAML；默认读取 `plugins/TrMenu/menus`，输出到 `plugins/KaMenu/menus/trmenu_migrated`。 - 迁移器不依赖 TrMenu、Kether 或 TabooLib，也不会在迁移期间执行源菜单的 JavaScript、指令和动作。 - 支持版本化正则键、单页常用容器布局、显式槽位、反引号多字符按钮 ID、嵌套图标变体、常见物品字段和跨文件菜单跳转。 - 支持常用 Kether 条件、消息/指令/音效/经济/点券/数据等动作、组合动作、延迟与概率，以及 `Events.Open`、`Events.Close` 和自动任务。 - 可静态审计的纯返回值 `Functions` 会转换为菜单 JavaScript；TrMenu 私有对象、任意 Kether 流程和动态私有物品表达式会被拒绝或明确报告。 - 普通 `Bindings.Commands` 会合并到 `custom_commands.yml`；默认保留同名指令和已有目标文件，使用 `overwrite` 才会替换。 - 可兼容的 `Bindings.Items` 会合并到独立的 `item_bindings.yml`，支持 material、lore、name、data 和 model-data，并保留 TrMenu 默认的 2000ms 绑定冷却；不安全的 trait 会跳过并输出诊断。 - 新增 TrMenu 固定 `utils` 映射：在线玩家和装备槽位条件转换为 KaMenu 原生条件，`utils.getEquipment` 转换为 `[HEAD:玩家]` 等标准物品来源；简单参数形式的 `hasMoney` 和 `hasItem` 复用现有条件。 - 新增 `set-args` 与 `del-args` 标准动作，并迁移 TrMenu 同名动作；`set-args` 替换当前菜单参数后刷新 Container 或 Dialog，`del-args` 仅清理当前参数。 - 新增结构化 WARNING/ERROR 诊断、原子写入和 KaMenu Container 二次解析校验；不支持的条件不会被静默删除后继续执行受保护动作。 - 增加中英文 TrMenu 迁移文档，并使用 stable-v3 内置样例进行批量兼容审计。 [/MD]

[MD] ### V2 容器菜单 - 新增基于 Bukkit 虚拟库存的 Container 菜单运行时，默认不依赖 ProtocolLib、PacketEvents 或 NMS 发包层。 - 支持 `CHEST`、`HOPPER`、`DISPENSER`、`DROPPER`、`FURNACE`、`BLAST_FURNACE`、`SMOKER` 和 `ANVIL` 容器类型。 - 新增 `Type`、`Layout`、`Buttons`、`Properties`、`Update`、`Title-Update` 和按钮级 `update` 配置。 - Container 菜单复用 KaMenu 的变量、PlaceholderAPI、条件、JavaScript、actions 包、生命周期事件和动作队列。 - 增加熔炉火焰/加工箭头百分比刷新，以及 `Events.Progress` 边沿触发事件。 - 增加铁砧输入、重命名结果和 `$(input)` 上下文支持。 - 所有容器交互、拖拽和快捷键库存操作均按只读菜单处理，防止展示物品进入玩家库存。 ### DeluxeMenus 迁移 - 新增 `/km migrate dm`，默认读取 `plugins/DeluxeMenus/gui_menus`，也支持手动指定源文件和目录。 - 支持 DM 菜单布局、槽位、物品显示、条件、点击动作、分页和 `open_command` 迁移。 - `open_command` 会写入 KaMenu V2 标准菜单和 `custom_commands.yml`。 - 支持 `overwrite` 覆盖目标菜单和冲突的自定义指令；默认保留现有配置并报告冲突。 ### 自定义指令独立化 - 自定义指令从 `config.yml` 独立到插件根目录的 `custom_commands.yml`。 - 新增独立文件管理器，负责默认文件释放、配置读取、保存、旧配置迁移和备份。 - `/km reload config` 和 `/km reload all` 会同步重载 `config.yml`、`custom_commands.yml` 和在线玩家的命令补全。 - 旧版 `config.yml > custom-commands` 会在启动时自动迁移，并生成 `custom_commands_legacy_backup_<时间戳>.yml`。 - 配置版本升级为 v6。 ### 兼容性边界 - 保留 Paper、Folia 和 Spigot 的现有 Dialog 支持、平台适配和生命周期清理。 - Container 菜单当前使用 Bukkit 公共虚拟库存方案，不提供后台熔炉模拟，也不包含基于 NMS 的假窗口实现。 - 公共运行时编译基线降至 Bukkit/Spigot 1.16.5，并将公共运行时字节码目标降至 Java 16；仅在现代核心上加载的 Dialog 适配器仍单独使用 Java 21。 - 构建环境仍使用 Java 21；Paper/Folia 1.21.7+ 服务端本身继续要求 Java 21。 - Paper/Folia 1.21.7+ 和 Spigot 1.21.6+ 才启用原生 Dialog；较低核心自动降级为无 Dialog 模式，Container、actions、变量、JavaScript、存储和自定义指令仍可用。 - 仅将 Libby 随插件 JAR 提供；Kotlin 会在无 Kotlin 依赖的 `onLoad` 引导段优先热加载，随后再挂载 Adventure/MiniMessage 及其他运行依赖。 - 旧版 Paper 内置的 Adventure 不满足新版 MiniMessage 时会自动回退到 Legacy 文本，避免依赖冲突导致插件无法启用；`sprite`、`head` 等现代标签仅在兼容的现代核心上生效。 - bStats 运行库通过 Libby 下载并重定位到 KaMenu 私有命名空间，避免触发 bStats 的未重定位检查，也不增加插件 JAR 体积。 [/MD]