KaMenu 菜单插件介绍

KaMenu 插件介绍
概述

KaMenu 是一款面向现代 Minecraft 服务端的原生 Dialog 菜单插件，由 Katacr（小晓_）开发。它彻底抛弃传统的箱子（Inventory/箱子 GUI）菜单模式，转而采用 Paper 1.21.6+ 的原生 Dialog API，为玩家提供包含文本输入、数值滑块、下拉选择框、复选框等丰富交互组件的现代化对话框界面。所有菜单通过 YAML 文件配置，开箱即用，无需编写代码。
插件名称：KaMenu
开发者：Katacr（小晓_）
最新版本：1.7.3
许可协议：GPL-3.0（开源免费）
兼容版本：Minecraft Java Edition 1.21.6+（原生 Dialog）；容器菜单模式可向下兼容 1.16.5+
运行平台：Paper、Folia、Purpur、Pufferfish、Spigot（v1.7.0+ 起完全支持标准 Spigot 1.21.7+）
项目地址：
SpigotMC：https://www.spigotmc.org/resources/133736/
MineBBS：https://www.minebbs.com/resources/15814
GitHub：https://github.com/Katacr/KaMenu
官方文档：提供英文 Wiki 与简体中文文档
核心特性
现代化 Dialog 界面
基于 Paper 1.21.6+（Spigot/Bungee 1.21.7+）原生 Dialog API 构建，彻底告别传统箱子菜单。新版 UI 更流畅、更现代，为玩家带来接近原生的操作体验。在服务端版本低于原生 Dialog 所需版本时，KaMenu 会自动禁用 Dialog 菜单与 ESC 对话框入口，但容器菜单、动作、变量、JavaScript、存储与自定义命令等功能依然可用。
丰富的交互组件
支持文本输入框、数值滑块、下拉选择框、复选框等多种交互组件，配合物品展示（item 组件，支持 item_model 命名空间模型）与纯文本消息，可构建功能强大的菜单界面。所有文本字段均支持条件判断。
零代码 YAML 配置
完全基于 YAML 配置文件，无需任何编程知识。语法简洁直观，新手也能快速上手创建复杂菜单。内置示例菜单，安装后执行 /kamenu guide 即可打开内置设置引导并释放示例菜单。
强大的动作系统
支持 10+ 种动作类型：tell、actionbar、title、hovertext、command、console、sound、open、close、wait、set-data、url、copy、toast、money、server（跨服传送，如 server: lobby）等，满足各种场景需求。所有动作均支持目标选择器（Target Selector），可按权限、条件表达式筛选作用玩家。
智能条件逻辑
在任何文本字段与动作列表中均可使用条件语句，兼容 PlaceholderAPI 变量、比较运算符与逻辑运算符，实现动态分支逻辑。
内置数据存储
支持 SQLite（默认）与 MySQL 5.7+ 两种数据库后端，提供按 UUID 存储的玩家数据与全局数据存储，并通过 PlaceholderAPI 自定义变量暴露。
灵活的界面定制
三种底部按钮布局模式（notice / confirmation / multi，可自定义列数与按钮排列）；可配置 ESC 退出模式与点击后客户端行为（CLOSE / WAIT_FOR_RESPONSE / NONE）；按钮支持 Tooltip 悬停提示（多行、颜色代码、变量替换）。
事件、周期任务与 JavaScript
内置 Open / Close 事件触发器，支持菜单打开前与关闭后执行自定义动作；支持周期任务；内置 JavaScript 引擎（基于 OpenJDK Nashorn 15.3），可在菜单中使用 JS 代码完成复杂运算与逻辑。
持久化存储与动态列表
提供玩家数据（按 UUID）与全局数据持久化存储，并支持动态列表，结合 PlaceholderAPI 自定义变量实现数据驱动菜单。
可选软依赖集成
软依赖（非必需）：PlaceholderAPI、Vault、ItemsAdder、Oraxen、CraftEngine。其中 PlaceholderAPI 可解锁大量占位符变量；ItemsAdder/Oraxen/CraftEngine 配合可实现材质包相关的优质案例展示。
Geyser/Floodgate 兼容
支持 Geyser + Floodgate，Dialog 菜单会自动转换为 Bedrock 表单（Form），基岩版玩家也可正常使用。
安装方法
环境要求
服务端：Paper / Folia 1.21.7+（推荐，获得最佳体验）；或 Spigot / Folia 1.21.7+；向下兼容容器菜单模式可至 1.16.5+
Java：Java 21（Paper/Folia 1.21.7+ 服务端本身要求）；共享运行时目标 Java 16 字节码
首次启动需联网：首次启动时自动下载 Kotlin、Adventure 等运行时依赖库
数据库：SQLite 默认即可；跨服或集中存储可使用 MySQL 5.7+
标准安装
从 SpigotMC / MineBBS / GitHub Releases 下载 KaMenu-X.X.X.jar。
将 JAR 文件放入服务端的 plugins/ 目录。
启动或重启服务器，插件会自动生成配置文件与示例菜单。
（可选）安装 PlaceholderAPI、Vault 等软依赖以解锁扩展功能。
安装后执行 /kamenu guide 打开内置设置引导并释放示例菜单，按需编辑菜单 YAML 后重载即可。
适用场景
希望告别箱子 GUI、为玩家提供现代化 Dialog 交互界面的高版本 Paper/Purpur/Folia 服务器
需要零代码、YAML 驱动快速搭建复杂交互菜单（商店、表单、任务、设置面板等）的场景
依赖 PlaceholderAPI/Vault/ItemsAdder 等生态、需要数据驱动动态菜单的运营活动
使用 Geyser/Floodgate 同时服务 Java 版与基岩版玩家的混合服务器
需要跨服传送（server 动作）、条件分支、JavaScript 复杂逻辑的高级菜单需求
相关链接
SpigotMC 资源页：https://www.spigotmc.org/resources/133736/
MineBBS 项目页：https://www.minebbs.com/resources/15814
GitHub 源码：https://github.com/Katacr/KaMenu
官方文档：英文 Wiki / 简体中文文档（详见 SpigotMC 资源页内链接）
问题反馈：GitHub Issues / Discord