KaMenu

插件

· 作者 Katacr

一个专为现代 Minecraft Paper 服务器设计的 GUI 插件。

0 本站下载 0 关注 更新于 3 周前

最新 2.1.0 · 26.3 · Folia / Paper

一键开服(送7天)

KaMenu - 原生对话框菜单构建器

使用 YAML 创建现代 Minecraft 对话框:表单、动态按钮、操作工作流、持久数据以及可选的 JavaScript。

KaMenu animated preview

KaMenu 是一款基于 Minecraft 原生对话框系统构建的菜单插件。它不通过模拟物品栏界面来呈现,而是允许你使用清晰且结构化的 YAML 创建真正的客户端原生对话框。

可用于服务器导航、商店、传送点、好友列表、玩家个人资料、每日奖励、表单、管理工具,甚至具有实时状态和定期刷新功能的游戏界面。基础菜单无需编程即可使用。当项目需要更高级的逻辑时,可提供条件判断、操作包、JavaScript 以及外部 API。

快速链接

  • Wiki:
  • GitHub:
  • Issues:
  • Discord:

界面预览

KaMenu screenshot 1 KaMenu screenshot 2 KaMenu screenshot 3 KaMenu screenshot 4 KaMenu screenshot 5 KaMenu screenshot 6

为什么选择 KaMenu?

原生对话框而非物品栏 GUI

KaMenu 直接使用 Minecraft 的对话框系统。玩家可以在一个屏幕中阅读文本、检查物品、输入文字、移动滑块、切换选项并点击按钮,而无需使用物品栏物品来模仿表单。

优先使用 YAML,JavaScript 可选

常规菜单仅需 YAML。标题、正文内容、输入框、按钮和操作都使用清晰的配置部分。JavaScript 是可选的,旨在用于计算、实时状态和可复用的高级逻辑。

完整的菜单生命周期

KaMenu 的功能不止于打开界面。它可以在打开前验证权限或数据,在点击后执行有序的操作队列,在菜单关闭时清理状态,并在菜单保持活动状态时运行周期性任务。

组件系统

正文组件

  • message: 单行或多行内容,支持旧版颜色、MiniMessage、变量和条件文本。
  • item: 原版物品、玩家装备槽位、第三方物品、名称、描述、附魔、耐久度、模型和玩家头像。
  • 可点击文本支持悬停文本、物品悬停数据、URL、剪贴板复制、命令以及 KaMenu 操作回调。
  • 来自 ItemsAdder、Oraxen 和 CraftEngine 的原版精灵图和符号。
  • 条件可以动态显示或隐藏各个组件。

输入组件

  • input: 单行或多行文本字段。
  • slider: 数值滑块,支持配置范围和步长。
  • dropdown: 单选按钮,点击时在选项间循环切换。
  • checkbox: 复选框和确认输入。

捕获的值可在操作、条件、命令或 JavaScript 中使用 $(input_id) 引用。输入清理可以全局或按菜单配置地修剪周围空白字符并移除配置的字符。

底部布局

  • notice: 单个操作按钮。
  • confirmation: 确认和拒绝按钮。
  • multi: 可配置的按钮网格,带有一个可选的退出按钮。
  • repeat: 根据运行时列表数据生成和分页按钮。
  • 无按钮对话框、自定义宽度、工具提示和条件标签。

动态列表与分页

玩家数量、好友列表和传送点数量并非预先可知。repeat 可在运行时从简单的字符串、JavaScript 数组或对象列表中生成按钮。

  • 针对值(如 player1,player2,player3)的自定义分隔符。
  • 通过 {item.name}、{item.id} 等变量访问对象字段。
  • {item.index}、{item.number}、{item.page_index} 和 {item.page_number}。
  • 默认每页 20 条条目,范围可从 1 到 99 配置。
  • 内置 list 和 glist 存储,支持添加、删除、唯一性、清空和持久化操作。

典型用途包括:

  • 在线玩家列表
  • 好友和被屏蔽玩家
  • 玩家传送点
  • 商品、任务和奖励
  • 数据库记录浏览器

操作体系

按钮、可点击文本、自定义命令、事件和操作包共享同一套操作语法。

类别 常用操作
消息 tell, actionbar, title, toast, hovertext
命令 command, console, chat
菜单 open, reset, close, force-open, force-close
游戏内 sound, tppos, server, money, item, stock-item
存储 data, gdata, list, glist, meta
流程 wait, return, run-task, stop-task, stop-current-task
复用 actions 包和 js 包

操作按顺序执行,支持延迟、条件、目标玩家选择器和参数。操作包使用 {arg:0}、{arg:1} 等读取参数。

条件与变量

条件不仅可以控制操作分支,还可以控制标题、正文内容、输入默认值、按钮标签和组件可见性。

  • 比较:==, !=, >, >=, <, <=。
  • 逻辑:&&, || 和嵌套括号。
  • 权限和物品:hasPerm, hasItem。
  • 列表:inList, inGlist。
  • 字符串:isNull, isPass, isTrue, getLength。
  • 存储:{data:key}, {gdata:key}, {list:key}, {glist:key}。
  • 参数:{arg:0}, {arg:1}。
  • 输入:$(input_id)。
  • PlaceholderAPI:%player_name% 及已安装扩展中的占位符。

{checkitem:[slot;property;format]} 还可以显示物品名称、描述(lore)、附魔、耐久度、item_model 以及自定义模型 ID。

事件、任务与生命周期

  • Events.Open: 在菜单打开前运行,并可选择通过 return 阻止菜单打开。
  • Events.Click: 可复用且带参数的菜单动作组。
  • Events.Close: 当菜单生命周期结束时运行。
  • Events.Tasks: 在菜单活跃期间定期执行。
  • Settings.lifetime: 主动关闭过期的菜单并停止其任务。
  • Settings.can_escape: 控制 ESC 键关闭功能及其退出行为。
  • Settings.after_action: 配置点击后的客户端行为。

周期性任务支持自动或手动启动、有限或无限循环、完成时动作以及通配符停止。KaMenu 会按玩家追踪活跃任务,以防止在菜单刷新时出现重复的生命周期任务。

JavaScript 与可复用包

  • 菜单局部 JavaScript:用于特定于菜单的逻辑。
  • plugins/KaMenu/js/:每个 .js 文件对应一个全局 JavaScript 包。
  • plugins/KaMenu/actions/:每个 .yml 文件对应一个全局动作包。
  • 菜单局部的定义优先于同名的全局包。
  • 每次执行都有独立的绑定,防止不同玩家之间的状态泄漏。
  • 内置 PAPI 和 KaMenu 变量解析,以及 delay() 等辅助函数。
  • 调用包时,参数之间可用空格或逗号分隔。

数据存储

KaMenu 包含 SQLite 和 MySQL 存储功能,无需额外安装数据库插件。

  • data: 按 UUID 的每位玩家独立键值存储。
  • gdata: 全服务器共享的键值存储。
  • list: 每位玩家独立的列表存储。
  • glist: 全服务器共享的列表存储。
  • 支持已存储的值、列表内容以及列表大小的 PAPI 占位符。
  • 内置 %kamenu_online_players% 在线玩家列表。

自定义命令与 API

在 config.yml 中注册面向玩家的命令:

  • 直接打开某个菜单。
  • 执行完整的动作队列。
  • 通过 {arg:0} 及后续索引读取参数。
  • 根据 PAPI、list 或 glist 中的值配置静态或动态 Tab 补全。
  • 重载后为在线玩家刷新命令树。

外部插件可通过 KaMenu API 实现以下功能:

  • 从 menus/ 目录打开基于文件的菜单。
  • 渲染 YAML 字符串或内存中的 YamlConfiguration 对象。
  • 注册自定义动作处理器。
  • 检查可用性并获取插件实例。

ESC 暂停菜单入口

pause_menu.yml 可编译为原版数据包中的 Dialog,并作为自定义条目添加到客户端的 ESC 暂停界面中。该条目可包含正文内容、输入框以及按钮网格,用于打开常规 KaMenu 菜单或执行动作。

/km pause register

注册后请完全重启服务器。

快速示例

创建 plugins/KaMenu/menus/welcome.yml:

Title: '&bServer Welcome Menu'

设置: can_escape: true lifetime: 300 after_action: CLOSE

主体: welcome: type: message width: 320 text: - '&f欢迎,&a%player_name%&f!' - '&7输入昵称并选择一个操作。'

输入项: nickname: type: input text: '&e昵称' default: '%player_name%' max_length: 16

底部: type: multi columns: 2 buttons: hello: text: '&a打招呼' tooltip: '&7发送问候语' actions: - 'tell: &a你好,$(nickname)!' - 'sound: entity.experience_orb.pickup;volume=1.0;pitch=1.3' examples: text: '&b打开示例' actions: - 'open: example/main_menu' exit: text: '&c关闭' actions: - 'close'


然后运行:

```text
/km reload menu
/km open welcome

安装与首次使用

  1. 将 KaMenu JAR 文件放入 plugins/ 目录。
  2. 启动服务器并等待第一个依赖下载完成。
  3. 运行 /kamenu guide 以打开内置的设置指南。
  4. 选择一种语言并发布对应的示例菜单。
  5. 运行 /km open example/main_menu。

常用命令

/km guide
/km list
/km open <menu-id> [player]
/km examples [zh_CN|en_US] [overwrite]
/km language <language-id>
/km reload [all|menu|config|actions|js|lang]
/km pause <register|unregister|info>

管理命令默认使用 kamenu.admin 权限。

要求

项目 要求
Java 21+
Minecraft 1.21.7+
服务器 Spigot/Paper/Folia 1.21.7+
数据库 默认为 SQLite,或 MySQL 5.7+

首次启动需要访问 Maven 以下载运行时库。下载的库存储在服务器缓存中。

可选依赖

  • PlaceholderAPI:第三方及 KaMenu 占位符。
  • Vault:经济相关操作。
  • ItemsAdder:自定义物品、图像符号和像素偏移。
  • Oraxen:自定义物品、符号和位移。
  • CraftEngine:自定义物品和 Dialog 符号包拦截。

所有集成均为软依赖。

使用说明

  • after_action: NONE 和 WAIT_FOR_RESPONSE 下的客户端回调是一次性的。按钮操作应使用 close、reset 或 open,以避免留下无法再次响应的缓存屏幕。
  • 在 Folia 上使用自定义 JavaScript、外部动作处理程序和第三方 PAPI 扩展时,必须遵守相关的线程规则。
  • 少数完全依赖于平台特定服务器 API 的操作可能会有所不同。建议使用最新的 Paper 构建以获得最广泛的功能覆盖。

支持与指标

报告问题时,请包含完整的服务器版本、KaMenu 版本、相关的菜单 YAML 以及完整的堆栈跟踪。

  • GitHub Issues:
  • Discord:

KaMenu 基于 GPL-3.0 许可证免费且开源。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源