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

修复异步执行任务导致的潜在错误

新增功能​

JavaScript 功能完整支持​

功能概述​

KaMenu 现在支持在菜单中使用 JavaScript 代码，基于 OpenJDK Nashorn 15.3 引擎实现。这将极大地扩展插件的功能性和灵活性。

核心特性​

开箱即用

• 无需安装额外插件
• 首次启动时自动下载 Nashorn 依赖
• 下载完成后重启即可使用

Bukkit API 集成

• 完整访问 Bukkit API
• 支持操作玩家、世界、服务器等对象
• 所有 JavaScript 代码在服务器端执行

内置辅助函数

提供了以下便捷的辅助函数：

• tell(player, message) - 向玩家发送消息
• log(message) - 在控制台打印日志
• delay(ticks, callback) - 延迟执行回调函数（主线程）
• asyncDelay(ticks, callback) - 异步延迟执行回调函数
• getPlayer(name) - 通过名称获取玩家

​

提供了完整的 JavaScript 功能演示菜单：
/menus/example/javascript_demo.yml

修复wait动作可能会导致服务器崩溃的bug。

主要更新：
MiniMessage 完整支持 - 颜色、渐变、点击、悬停、图标、头像
颜色代码混合 - Legacy 和 MiniMessage 自由混用
动作列表复用 - 通过 `actions` 参数复用动作序列
Bug 修复 - 修复按钮无 actions 时点击出错
详情请参阅wiki

bug修复：
修复了因修改data/gdata中的值而导致的潜在崩溃问题；现在，data/gdata操作以异步方式执行。
修复了滑块组件的错误问题；现在会验证min < max，以确保滑块条的正确显示

1. 灵活的物品材质名匹配​

为物品材质名称匹配添加了智能规范化功能，支持多种格式的材质名称。此改进适用于：

• Body 组件的 item 物品展示
• condition 条件判断中的 hasItem 判断
• condition 条件判断中的 hasStockItem 判断
• actions 动作中的 item 操作
• actions 动作中的 stock-item 操作
• config 配置中的 item-lore 监听器

支持的格式：

• 标准格式：DIAMOND_SWORD
• 小写：diamond_sword
• 混合大小写：DiAMond swORd
• 短杠：Diamond-Sword
• 空格：diamond sword

规范化规则：

1. 大小写忽略：自动转换为标准大写
2. 分隔符统一：将短杠 - 和空格 替换为下划线 _
3. 多余分隔符合并：多个连续的下划线会被合并为一个
4. 首尾清理：自动去除首尾空白

---

2. MiniMessage 文本格式支持​

引入了 Minecraft 现代化的文本格式系统 MiniMessage，插件同时支持两种文本格式：

1. Legacy 颜色代码：&amp;a绿色文本
2. MiniMessage 格式：&lt;green&gt;绿色文本&lt;/green&gt;

自动检测机制：

• 检测到 MiniMessage 标签 &lt;...&gt; → 使用 MiniMessage 解析
• 未检测到 MiniMessage 标签 → 使用 Legacy 颜色代码解析
• 两种格式可以混合使用

MiniMessage 优势：

• 更现代的文本格式，支持更多样式（加粗、斜体、下划线等）
• 更清晰的标签结构，易于维护
• 与 Minecraft 官方 Adventure API 完全兼容
• 更好的国际化支持

---

3. 配置文件和语言文件自动更新机制​

实现了智能的配置文件和语言文件管理机制。

config.yml 自动更新：

• 版本检测：检查当前配置文件的 config-version 字段
• 旧版本兜底：如果配置文件中没有 config-version 字段，自动设为 0
• 更新流程：
  1. 提取用户当前配置的所有键和值
  2. 备份旧配置文件
  3. 从插件内部复制新的默认配置文件
  4. 将用户配置的值写入新的配置文件

语言文件自动更新：

• 缺失检测：当调用某个语言键但文件中不存在时自动触发
• 自动补全：从插件内部加载对应的语言文件，如果插件内部没有该语言，则使用英语作为兜底
• 自动写入：将缺失的键自动写入用户的语言文件

---

4. 新增 chat 动作​

添加了新的 chat 动作，让玩家在聊天框中发送消息。

使用场景：

• 广播消息：让玩家发送系统公告或通知
• 聊天互动：在菜单中快速发送聊天消息
• 指令执行：执行需要玩家身份的指令和一些特殊指令
• 社交功能：发送私聊、公会聊天等

1. 右键物品 Lore 打开菜单 (item-lore 监听器)​

功能说明​

添加了新的监听器功能，允许玩家通过右键持有特定材质且包含指定 Lore 文本的物品打开菜单。此功能支持：

• 物品材质（Material）匹配
• 物品 Lore（描述）文本匹配（模糊匹配）
• 可选的潜行（Shift）触发
• 支持配置多个监听器（不同物品打开不同菜单）

配置格式​

在 config.yml 的 listeners 节点下添加 item-lore 配置：

YAML：

listeners:
  item-lore:
    # 主菜单配置
    main-menu:
      enabled: true
      material: 'CLOCK'           # 物品材质
      target-lore: '菜单'         # Lore 包含的文本
      menu: 'main_menu'          # 打开的菜单
      require-sneaking: false     # 是否需要潜行

2. PlaceholderAPI 扩展依赖检查 (need_placeholder 配置)​

功能说明​

为菜单添加了 need_placeholder 配置项，用于检查菜单所需的 PlaceholderAPI 扩展是否已加载。在打开菜单前会自动验证：
此功能确保菜单中的占位符变量能正常工作，避免因扩展缺失导致的显示错误。

配置格式​

在菜单文件的 Settings 节点下添加 need_placeholder 配置：

YAML：

Settings:
  need_placeholder:
    - 'player'     # Player 扩展
    - 'server'     # Server 扩展
    - 'vault'      # Vault 扩展

1. 物品管理功能扩展​

新增条件方法​

• hasItem - 判断玩家背包中是否有足够数量的普通物品
  • 支持指定材质（Material）
  • 支持按 lore（描述）判断
  • 支持按 item_model（物品模型）判断
  • 用法：hasItem.[mats=DIAMOND;amount=10]
  • 高级用法：hasItem.[mats=DIAMOND;amount=10;lore=测试物品;model=oraxen:mana_crystal]
• hasStockItem - 判断玩家背包中是否有足够数量的保存物品
  • 适用于通过 /km item save 保存的物品
  • 用法：hasStockItem.物品名称;数量

新增动作​

• item - 普通物品给予/扣除操作
  • type=give - 给予指定材质的物品
    • 用法：item: type=give;mats=DIAMOND;amount=10
    • 支持任意数量（无64上限）
    • 背包满时自动掉落在地上
  • type=take - 从玩家背包扣除物品
    • 用法：item: type=take;mats=DIAMOND;amount=10
    • 支持按 lore 判断：lore=测试物品
    • 支持按 item_model 判断：model=oraxen:mana_crystal
    • 可同时指定 lore 和 model 进行精确判断
• stock-item - 保存物品的给予/扣除操作
  • type=give - 给予保存的物品
    • 用法：stock-item: type=give;name=物品名称;amount=16
    • 支持任意数量（无64上限）
    • 背包满时自动掉落在地上
  • type=take - 扣除保存的物品
    • 用法：stock-item: type=take;name=物品名称;amount=16

2. 按钮工具提示（Tooltip）功能​

• 为按钮添加了 tooltip 属性支持
• 鼠标悬停在按钮上时显示提示文本
• 支持多行显示（YAML 列表格式）
• 支持颜色代码
• 支持变量替换

3. Body 组件增强​

• 新增 item_model 属性支持
  • 为 Body 的 item 组件添加了 item_model 配置项
  • 支持使用命名空间格式的物品模型（namespace:key）
  • 适用于 Minecraft 1.21.7 及以上版本
  • 用于显示具有特殊外观的物品（如特殊材质的武器、道具等）

说明：

• 格式：命名空间:键名，例如 minecraft:custom_sword 或 your_plugin:special_item
• 工作原理：将模型数据存储在物品的 PersistentDataContainer 中，由 Minecraft 客户端根据模型定义渲染特殊外观
• 所有字段均支持条件判断

新增功能​

• 新增 action 指令：用于快捷测试和执行各种菜单动作，支持内置变量和PlaceholderAPI变量
  • 使用格式：/kamenu action &lt;玩家&gt; &lt;动作&gt;
  • 支持所有动作类型：tell, actionbar, title, hovertext, command, console, sound, open, close, data, gdata, meta, set-data, set-gdata, set-meta, toast, money 等
  • 支持玩家变量、全局数据、元数据以及PAPI变量
• 新增 list 指令：显示服务器内所有已加载的菜单列表
  • 支持分页显示，每页10个菜单
  • 菜单项可点击直接打开
  • 提供上一页/下一页翻页按钮
  • 使用格式：/kamenu list [页码]
• 新增 help 指令：显示插件的所有指令帮助信息
  • 包含所有指令的详细用法说明
  • 底部提供可点击的文档链接
  • 支持多语言（根据设置语言显示对应的文档链接）
• 实装自定义指令注册功能：
  • 可在菜单配置中定义自定义指令
  • 自动注册自定义指令，无需手动配置
  • 支持指令别名
  • 支持权限配置
  • 重载时自动更新自定义指令

优化改进​

• 优化 open 指令：支持为指定玩家打开菜单
  • 格式：/kamenu open &lt;菜单名&gt; [玩家]
  • 若不指定玩家则为自己打开
  • 控制台使用时必须指定玩家
• 改进控制台兼容性：action 和 open 指令支持控制台使用
• 优化日志输出：简化自定义指令注册日志
• 在启动和重载时显示已注册的自定义指令数量