Hynfinity欢迎

HynfinityMenu

Hytale 服务器 2026.03.26 或更高版本

一款为 Hytale 服务器设计的可配置游戏内菜单系统，自带基于 Web 的可视化编辑器。设计菜单、页面、按钮和操作——然后在浏览器中像素级精确的 Hytale UI 复刻版中预览它们。

快速开始

1. 从 Releases 页面下载最新的 HynfinityMenu-*.jar
2. 将其放入服务器 mods/ 目录
3. 启动服务器
4. 在游戏中使用 /menu 打开菜单

功能特性

游戏内菜单

• 完全可配置的菜单，支持页面、按钮和连锁操作
• 首次加入时自动打开（可配置）
• 随时使用 /menu 命令重新打开
• 8 种操作类型：message、command、open_url、open_page、open_menu、status、close、noop
• closeBefore / closeAfter 标志位，实现精细控制

Web 构建器

• 可视化拖拽式菜单编辑器，访问地址 http://你的服务器IP:8180/builder/
• 使用真实 Hytale UI 纹理进行实时预览（像素级精确的 DecoratedContainer）
• 内联本地化编辑——在工具栏切换语言即可翻译
• 操作模拟——在预览中点击按钮查看各操作效果
• 撤销/重做、导入/导出、无需重启即可在游戏中重新加载
• 基于令牌的身份验证，带暴力破解防护

本地化

• 内置语言包：en、fr、es
• 每位玩家的语言偏好持久化存储
• 点号标记法翻译键，带回退链：玩家语言 → 默认语言 → menus.json 中的基础文本
• 将 <语言代码>.json 文件放入 lang/ 目录，即可添加自定义语言

命令

命令	描述	权限
/menu	打开默认菜单	hynfinity.menu
/menu <菜单ID>	打开指定菜单	hynfinity.menu
/menu <菜单ID> <页面ID>	打开指定页面	hynfinity.menu
/menu lang	显示当前语言和可用语言代码	hynfinity.menu
/menu lang <语言代码>	更改你的语言	hynfinity.menu
/menu reload	从磁盘重新加载配置	hynfinity.menu.admin

别名：/welcome。

权限

权限	描述
hynfinity.menu	使用 /menu 和 /welcome 的权限
hynfinity.menu.admin	重新加载配置

LuckPerms 示例：

lp group default permission set hynfinity.menu true

配置

menus.json

菜单配置在插件数据文件夹首次运行时创建：

mods/com.hynfinity_menu/menus.json

结构：

{
  "localization": {
    "defaultLanguage": "en",
    "enabledLanguages": ["en", "fr", "es"]
  },
  "command": {
    "name": "menu",
    "aliases": ["welcome"]
  },
  "messages": { ... },
  "firstJoin": {
    "enabled": true,
    "menu": "welcome",
    "page": "home"
  },
  "commandMenu": {
    "menu": "welcome",
    "page": "home"
  },
  "menus": [
    {
      "id": "welcome",
      "title": "Server Welcome",
      "subtitle": "",
      "defaultPage": "home",
      "pages": [
        {
          "id": "home",
          "title": "Welcome",
          "lines": ["Line 1", "Line 2"],
          "status": "Status text",
          "hint": "Hint text",
          "buttons": [
            {
              "label": "Button",
              "actions": [
                { "type": "message", "text": "Hello!" }
              ]
            }
          ]
        }
      ]
    }
  ]
}

操作类型

类型	字段	描述
close	—	关闭菜单
message	text	向玩家发送聊天消息
command	command 或 commands	执行服务器命令
open_url	url、text	打开 URL（发送可点击消息 + 原始 URL）
open_page	page	导航到同一菜单中的另一个页面
open_menu	menu、page	打开其他菜单（可选指定页面）
status	text	更新状态栏文本
noop	—	无操作（占位符）

除 close 和 noop 外，所有操作类型都支持可选的 closeBefore 和 closeAfter 布尔标志位。

builder.json

Web 构建器配置在 menus.json 旁边首次运行时创建：

mods/com.hynfinity_menu/builder.json

{
  "enabled": false,
  "httpPort": 8180,
  "httpHost": "0.0.0.0",
  "threadPoolSize": 2,
  "authToken": ""
}

设置	默认值	描述
enabled	false	启用 Web 构建器服务器
httpPort	8180	Web 服务器端口
httpHost	0.0.0.0	绑定地址
threadPoolSize	2	HTTP 工作线程池大小
authToken	""	身份验证令牌；首次运行时若为空则自动生成（打印到控制台）

设置 "enabled": true 并重启服务器。生成的令牌会打印在服务器日志中——使用该令牌登录 http://你的服务器IP:8180/builder/。

本地化文件

内置语言包在首次运行时解压到：

mods/com.hynfinity_menu/lang/

文件：en.json、fr.json、es.json。

翻译键使用与配置文件结构匹配的点号标记法：

menus.{菜单ID}.title
menus.{菜单ID}.pages.{页面ID}.title
menus.{菜单ID}.pages.{页面ID}.lines.{索引}
menus.{菜单ID}.pages.{页面ID}.buttons.{索引}.label
messages.playerOnly
messages.noPermission
...

回退顺序：玩家语言 → 默认语言 → menus.json 中的基础文本。

Web 构建器 API

构建器提供 REST API（所有路由需要 Authorization: Bearer <令牌> 头）：

方法	端点	描述
POST	/builder/api/auth	验证令牌
GET	/builder/api/config	读取 menus.json
PUT	/builder/api/config	写入 menus.json（保存前验证）
GET	/builder/api/lang	列出可用语言文件
GET	/builder/api/lang/:语言代码	读取语言文件
PUT	/builder/api/lang/:语言代码	写入语言文件
POST	/builder/api/reload	在游戏中重新加载配置

数据文件

玩家状态存储在：

mods/com.hynfinity_menu/welcomed.json

• welcomed：已看到首次加入菜单的玩家的 UUID 列表
• languages：每位玩家的首选语言代码

构建

./gradlew shadowJar

输出：releases/HynfinityMenu/HynfinityMenu-<版本号>.jar

需要 Kotlin 1.9.x、Java 21，以及 Hytale 服务器 JAR 文件（位于 resources/server-jars/ 目录中）。