AuroraUI 开发者 Wiki

面向服务端的 Minecraft 界面框架。用 YAML 描述「画布」，由服务端向单个玩家私有地渲染文字、图片、物品、方块、矩形、边框与折线，并通过屏幕对齐的「命中区」接管点击、悬浮提示与导航。

本 Wiki 面向开发者：讲清 YAML 菜单格式、动作/条件语言、坐标几何、占位符、资源包管线、配置项、命令权限，以及给第三方插件使用的公开 API。 Java 21Paper / MC 1.21.xFabric 单人

下载与获取

AuroraUI 有两种运行形态，二者共用同一套菜单格式、动作/条件语言与编辑器协议：

AuroraUI · 服务端插件版

装在 Paper 服务器上，面向多人联机；菜单由服务端权威渲染给每个玩家。

AuroraUIEditor · Fabric 模组版

装在客户端，供单人游戏使用；AuroraUIEditor 0.2.0 引入单人游戏与 Fabric 服务器的 UI 创建与读取，担任了 Fabric 模组版本的 AuroraUI 功能。

资源	获取
AuroraUI（Paper 插件）	MineBBS → · 爱发电 →
AuroraUIEditor（可视化编辑器）	MineBBS → · Modrinth → · 爱发电 →

编辑器只讲使用方法，见 AuroraUIEditor 使用 Wiki。

单人游戏（Fabric）

Fabric 模组版（AuroraUIEditor）把 AuroraUI 跑在单人存档的集成服务器上，因此行为与服务端插件版一致：菜单仍然由服务端权威渲染，只是这个「服务端」就在你本地。AuroraUIEditor 0.2.0 引入了单人游戏与 Fabric 服务器的 UI 创建与读取功能。

安装：Fabric Loader + Fabric API，把 AuroraUIEditor 模组放进 mods/，进入任意单人存档即生效。
数据目录：配置与菜单位于游戏实例的 config/auroraui/（ui/、templates/、images/ 等），结构与第 2 节一致。
命令与权限：命令与权限节点同服务端版（/auroraui，别名 /aurora）；单人存档默认拥有管理权限。
编辑器联动：安装 AuroraUIEditor 后，在单人游戏里执行 /auroraui edit <菜单ID> 即可打开可视化编辑器，改动直接写回本地菜单文件。

编辑器只依赖「当前连接是否支持编辑通道」，所以它在单人集成服务器上与在 Paper 服务器上用法完全相同。

1. 它是什么

AuroraUI 不是传统的「箱子菜单」插件，而是一个服务端驱动的 UI 框架：

画布 canvas

固定在玩家视野前方的逻辑平面，坐标以逻辑像素为单位，原点在画布中心，X 向右、Y 向上。

前端 frontend

画布上的视觉节点树（可嵌套分组），只对目标玩家可见，纯展示。

后端 backend

屏幕对齐、不继承任何前端变换的矩形命中区，负责点击动作、悬浮提示、条件与拒绝动作。

动作 / 条件 DSL

一套文本 DSL，用于点击行为、打开/关闭菜单、状态读写、经济/物品操作等。

资源包管线

把 plugins/AuroraUI/images 下的 PNG 自动打包成资源包与位图字体。

公开 API — 全新的 DSL 入口 `AuroraUI` 单例；声明锚点、打开菜单、路由分发全部通过 `AuroraUI.declare / AuroraUI.show / AuroraUI.route` 完成。

服务端权威：菜单始终由服务端渲染与判定。多人服里玩家无需安装任何客户端模组；单人游戏则安装 Fabric 模组版（见上文「单人游戏（Fabric）」）。可选的 Fabric 编辑器只用于管理端可视化编辑。

2. 运行时数据目录

插件首次启用会在 plugins/AuroraUI/ 下创建/释放（单人 Fabric 版对应游戏实例的 config/auroraui/，结构相同）：

plugins/AuroraUI/
├─ config.yml            # 主配置
├─ offset.yml            # 屏幕全局摆放
├─ tooltip.yml           # tooltip 样式
├─ animations.yml        # 动画时间线
├─ ui/                   # 菜单文档（v2 主格式 *.html，v1 兼容 *.yml）
│  ├─ example.html
│  ├─ details.html
│  ├─ m4-resources.html
│  └─ m5-animation.html
├─ templates/            # 可复用节点模板（*.yml）
├─ languages/            # 语言文件
├─ images/               # 资源包源图片（仅小写路径）
│  ├─ example.png
│  ├─ mouse/{mouse,choose}.png
│  └─ ce/{topaz_background,topaz_frame}.png
└─ generated/            # 自动生成，勿手改
   ├─ auroraui-resourcepack.zip
   ├─ images.index       # 稳定码位表
   └─ resourcepack/      # 解包目录

3. 命令与权限

主命令：/auroraui（别名 /aurora）。

普通用户（`auroraui.use`，默认所有玩家）

命令	说明
`/aurora open <菜单ID> [参数...]`	打开菜单
`/aurora close`	关闭当前菜单
`/aurora mode <touch\|mouse>`	切换输入模式（别名 `crosshair`/`cursor`）
`/aurora animate <轨道ID>`	播放动画
`/aurora stop-animation <轨道ID>`	停止动画
`/aurora pointer`	查看指针诊断

管理员（`auroraui.admin`，默认 OP）

命令	说明
`/aurora edit <菜单ID>`	打开可视化编辑器
`/aurora preview <菜单ID> [frontend\|backend]`	只读预览
`/aurora reload [all]`	重载菜单/动画/配置（`all` 同时重建资源包）
`/aurora validate`	仅校验菜单，不应用
`/aurora resources`	重建资源包
`/aurora list` / `templates` / `animations`	列出菜单/模板/动画
`/aurora performance [reset]`	性能统计
`/aurora status`	插件总览状态

自定义打开命令：菜单的 open-commands 会注册成独立命令（不带 /），注册时若与已有命令冲突会报错。

快捷开关：默认 Shift+F 切换唯一的主菜单（config.yml → shortcuts.shift-f）。

4. HTML 菜单格式（v2 主格式）

AuroraUI v2 菜单以 HTML 作为主格式，放在 ui/*.html 里。v1 YAML 继续兼容，老服务器的 menus/*.yml 会在启动时自动迁移到 ui/。编辑器支持一键 YAML→HTML 转换。

解析器使用 XML 模式读取菜单，所有标签必须闭合（自闭合用 />）。自定义标签（frame、item、block 等）在浏览器里无效，但在游戏里由 AuroraUI 解释。

4.1 文档结构

一个完整的 v2 菜单长这样：

<!doctype html>
<html>
<head>
  <title>example</title>
  <meta name="aurora:schema" content="2"/>
  <meta name="aurora:id" content="example"/>
  <meta name="aurora:permission" content="auroraui.use"/>
  <meta name="aurora:open-commands" content="aui"/>
  <meta name="aurora:main-menu" content="true"/>
  <meta name="aurora:canvas-width" content="320"/>
  <meta name="aurora:canvas-height" content="180"/>
  <meta name="aurora:pixels-per-block" content="42.7"/>
  <meta name="aurora:events-open" content="sound: BLOCK_CHEST_OPEN-1-1"/>
  <meta name="aurora:events-close" content="sound: BLOCK_CHEST_CLOSE-1-1"/>
</head>
<body>
  <!-- 前端视觉节点（只会被渲染，不会被当作 HTML 显示）-->
  <section id="viewport-content" sx="0.427" sy="0.427">
    <rect id="background" width="320" height="180" color="#182031" opacity="235"/>
    <text id="title" font-size="12" y="58" z="1" content="&fAuroraUI - %player_name%"/>
  </section>
  <!-- 后端交互区域（屏幕对齐，不继承前端变换）-->
  <region id="action" x="0" y="0" width="100" height="40"
      data-actions="right: close"
      data-tooltip="&7右键关闭"/>
</body>
</html>

4.2 元数据（`<meta name="aurora:*">`）

meta 键	类型	说明
`aurora:schema`	常量	必须为 `2`
`aurora:id`	字符串	菜单 ID，正则 `[a-z0-9][a-z0-9_-]*`；也可由 `<title>` 自动派生
`aurora:permission`	字符串	可选，额外权限节点
`aurora:open-commands`	逗号分隔	注册为独立命令；必须小写、不含 `/`、不重复、≤ 64 字符
`aurora:main-menu`	布尔	整组菜单里有且仅有一个为 `true`
`aurora:canvas-width` / `aurora:canvas-height`	正数	逻辑画布尺寸，默认 320 × 180
`aurora:pixels-per-block`	正数	每方块像素数，默认 100
`aurora:distance`	正数	设计距离（方块），默认 3
`aurora:events-open`	动作字符串	菜单打开时执行
`aurora:events-open-conditions`	条件字符串	打开事件前置条件
`aurora:events-close`	动作字符串	菜单关闭时执行
`aurora:events-close-conditions`	条件字符串	关闭事件前置条件

4.3 前端视觉元素

所有前端元素都支持通用变换属性：

属性	类型	说明
`id`	字符串	节点 ID，在前端+后端+嵌套组内全局唯一
`x` / `y` / `z`	浮点数	相对父级的平移偏移（逻辑像素），默认 0
`rx` / `ry` / `rz`	浮点数	旋转（弧度）；也可写 `rotation-x-deg` 等度制属性，自动转弧度
`sx` / `sy`	浮点数	缩放，两轴均不能为 0，默认 1
`visible`	布尔	是否可见；隐藏请用此项而不是把缩放设为 0

各类型专有属性：

标签	专有属性	说明
`<section>` / `<div>`	（无）	分组；子元素嵌套在内部
`<rect>`	`width`, `height`, `color`, `opacity`	实心矩形
`<line>`	`width`, `thickness`, `color`, `opacity`	线条
`<frame>`	`width`, `height`, `thickness`, `color`, `opacity`	边框；要求 `thickness*2 < min(width,height)`
`<text>`	`font-size`, `font`, `content`, `opacity`, `line-width`, `text-align`, `update`	文本；`content` 为空时取元素内文本
`<image>`	`src`, `width`, `height`, `opacity`, `update`	资源包图片；`src` 必须为 `/xxx.png` 形式
`<item>`	`material`, `context`	原版物品展示
`<block>`	`block-data`	原版方块展示

属性细节：

color：#RRGGBB（不区分大小写）；透明度单独用 opacity（0–255，默认 255）。
text.font：namespace:path，默认 minecraft:default。
text.text-align：left / center / right，默认 center。
image.src：虚拟根 / 下的 PNG 路径，如 /ui/logo.png；% 变量路径允许大写（用于动态贴图）。
item.context：GUI（默认）/ HEAD / FIXED / GROUND / NONE / FIRSTPERSON_LEFTHAND / FIRSTPERSON_RIGHTHAND / THIRDPERSON_LEFTHAND / THIRDPERSON_RIGHTHAND。
update：每节点的周期刷新（tick）。-1 不刷新；>0 为间隔；0 非法。用于 <text> / <image> 内容刷新与后端 tooltip。

前端示例（与第 1 节 README 里的 YAML 等价）：

<body>
  <section id="viewport-content" sx="0.427" sy="0.427">
    <rect id="background" width="320" height="180" color="#182031" opacity="235"/>
    <text id="title" font-size="12" y="58" z="1" update="20" content="&fAuroraUI - %player_name%"/>
    <item id="sword" material="minecraft:diamond_sword" context="GUI"
        x="72" y="0" z="2" sx="40" sy="40"/>
    <block id="block" block-data="minecraft:grass_block[snowy=false]"
        x="120" y="48" z="2" rx="-20" ry="35" sx="30" sy="30"/>
  </section>
</body>

4.4 后端交互区域

后端区域是独立的、屏幕对齐的矩形，不继承任何前端变换。坐标 x/y 以画布中心为原点、+x 向右、+y 向上；width/height 是完整边长（命中判定为 x ± width/2、y ± height/2）。

<region id="card-area" x="-27.755" y="-2.135" width="46.97" height="23.485"
    priority="0"
    data-tooltip="&f独立对齐的矩形命中区&#10;&7玩家: %player_name%"
    update="20"
    data-condition="perm auroraui.use"
    data-actions="right: sound: UI_BUTTON_CLICK-1-1, right: open: details"
    data-deny="tell: &c无权限"/>

属性	说明
`x` / `y`	中心坐标，默认 0
`width` / `height`	完整边长，必填，正数
`priority`	命中优先级，越大越先命中，默认 0
`data-tooltip`	悬浮提示；用 ` ` 换行，支持占位符
`update`	tooltip 周期刷新（tick），同前端 update 规则
`data-condition`	命中前置条件（见第 6 节）
`data-actions`	点击动作（见下方 ClickTrigger 前缀）
`data-deny`	condition 不满足时执行的动作

ClickTrigger 前缀分组：data-actions 里可以用 all:、left:、right:、shift:、shift-left:、shift-right: 前缀把不同触发键的动作分开。无前缀的动作归入 all：

data-actions="right: close, left: sound: UI_BUTTON_CLICK-1-1, all: refresh"
data-actions="right: play-animation: card-bob, play-animation: card-scale"
data-actions="close"   <!-- 单个动作，ALL 触发器 -->

命中顺序：先按 priority 降序，再按文档顺序取第一个命中的区域。

常见坑：把前端视觉元素（<rect>/<item>/<text>）写进 <region> 的父级不会自动变成前端显示——后端区域只负责命中。要让玩家看到按钮，需要单独写前端元素，后端只写命中区；或者把视觉元素写在锚点元素（<a>/<button>）的子节点里。

4.5 v1 YAML 兼容

老版本的 schema-version: 1 YAML 菜单继续被 MenuCatalog 加载（自动识别 .yml / .yaml 文件），完整字段规范见存档版文档。升级到 v2 后，编辑器可以一键把旧 YAML 转成 HTML：

/aurora convert-ui <旧菜单ID>

转换结果写到 ui/<菜单ID>.html，原 YAML 保留（可手动删除）。

5. 动作语言（Action DSL）

在 HTML 菜单里，动作写在 <region data-actions="..."> 或 <meta aurora:events-open="..."> 里。单个动作就是一个字符串；多项动作用 , 分隔（或用 ClickTrigger 前缀分组）：

<!-- 所有触发键都执行 -->
<region data-actions="tell: &aHello, sound: UI_BUTTON_CLICK-1-1"/>

<!-- ClickTrigger 前缀分组（推荐）-->
<region data-actions="right: sound: UI_BUTTON_CLICK-1-1,
                      all: condition: 'perm auroraui.use' && tell: &aHello
                      all: deny: tell: &c无权限"/>

v1 YAML 菜单里动作仍然可以写成结构化的 actions: {all: ..., right: ...} 映射，两套写法最终归一到同一条 ActionLanguage 解析路径。

5.1 点击触发键

all（别名 any）、left、right、shift（左右 Shift 点击都算）、shift-left、shift-right。

运行时中，非潜行时主键为右键，潜行时使用 Shift+右键；左键通过捕获实体由攻击事件触发。

5.2 条件动作组

一个组的可用键（含别名）：priority（priority/pri/pris）、condition（condition/require/req…）、actions（actions/list/click/execute/cmd…）、deny（deny/deny-list…）。每组至少要有一个 actions 或 deny。

5.3 内置动作（规范名）

规范动作	说明	参数格式
`tell`	发消息（支持 `&` 颜色、`\n` 换行）	文本
`tellraw`	富文本（JSON 或 `<文本@hover=..@command=..>` 标签）	文本
`command`	以玩家身份执行命令（`;` 分隔多条）	命令（可带 `/`）
`console`	控制台执行命令（`;` 分隔）	命令
`op`	临时 OP 后以玩家执行	命令
`chat`	让玩家发送聊天	文本
`actionbar`	动作栏文本	文本
`title`	标题/副标题	反引号分词：title `副标题` fadeIn stay fadeOut（tick，默认 15/20/15）
`bossbar`	Boss 栏	`文本颜色样式持续tick`（默认 white / solid / 15）
`sound`	音效（`;` 分隔多条）	`名称[-volume-pitch]`，如 `UI_BUTTON_CLICK-1-1`
`open`	打开菜单	`菜单ID [参数...]`
`open-app`	打开第三方应用（仅规范写法）	`namespace:path [参数...]`
`connect`	切换到子服（BungeeCord）	服务器名
`refresh`	刷新动态节点/tooltip	可选目标（`;` 分隔），空/`*` 表示全部
`play-animation`	播放动画轨道	轨道 ID
`stop-animation`	停止动画轨道	轨道 ID
`delay`	延迟（tick）	数字
`set-meta`	写入临时状态（`;` 分隔 `key value`）	`key value`
`remove-meta`	删除状态（正则）	正则
`set-data` / `remove-data`	玩家持久状态	同上
`set-global-data` / `remove-global-data`	全局状态	同上
`set-arg` / `clear-arg`	设置/清空菜单参数	空白分隔
`reload-inv`	刷新玩家背包	—
`give-money` / `take-money` / `set-money`	Vault 经济	数值
`give-points` / `take-points` / `set-points`	PlayerPoints	数值
`give-item` / `take-item` / `repair-item` / `enchant-item`	物品操作	规格字符串
`retype`	重新触发当前菜单	—
`close`	关闭	—
`back`	返回上一级（历史栈）	—
`return`	终止当前动作序列	—

大量 TrMenu 风格别名会被自动归一化，例如 sendtitle→title、playsound→sound、setdata→set-data、opengui→open、silentopen/forceopen→open、iconrefresh→refresh 等。注意：open-app 不接受别名，必须写规范名。

5.4 序列与内联选项

序列分隔：_||_ 或 &&&。序列内选项最多的那条的选项会共享给全部。

内联选项（写在动作末尾）：

选项	语法	含义
延迟	`<delay=20>` / `<wait:20>`	tick
概率	`<chance=0.5>` / `<rate:0.5>`	`0..1`
条件	`{condition=...}` / `{requirement: ...}`	条件表达式
目标玩家	`<players>`（全体在线）/ `<players=条件>`	条件筛选

<region data-actions="right: sound: UI_BUTTON_CLICK-1-1 _||_ delay: 10 _||_ open: details,
                      right: command: give %player_name% diamond 1 <chance=0.3>"/>

5.5 输入捕获（Catcher）

跨版本目前支持 CHAT 类型：玩家点击后开始捕获聊天输入。v1 YAML 仍可用结构化映射，v2 HTML 里把整个动作序列塞进 data-actions：

<!-- v1 YAML 写法 -->
actions:
  right:
    - input-catcher:
        stage-id:
          type: CHAT
          start: [...]     # 开始阶段（别名 before）
          cancel: [...]    # 取消阶段
          end: [...]       # 结束阶段（别名 after）

<!-- v2 HTML 里等价的写法（input-catcher 作为规范动作名，内嵌结构用 JSON/YAML 片段或留空让 Java API 处理）-->
<region data-actions="right: input-catcher" data-catcher-type="CHAT" data-catcher-stage="stage-id"/>

SIGN / ANVIL / BOOK 需要额外的版本输入适配器，当前不受支持。

6. 条件语言（Condition DSL）

条件为字符串，可组合：

true / false
perm <节点> / permission <节点>（* 前缀会被忽略）
not <条件> / !<条件>
A && B、A || B、( ... )
all[a; b] / any[a, b]（分隔符 ; 或 ,，支持嵌套括号）
比较：check 前缀可选；左侧/右侧支持占位符展开
- is（等于）、is not（不等）、contains（包含）
- >=、<=、>、<、==、!=
- 两侧都能解析为数字时按数字比较，否则忽略大小写按字符串比较
真值判定：包含 % 的表达式，或以 * / 反引号 / " / ' 开头者，按真值处理（true/yes/on/非 0 数字为真）

condition: 'perm auroraui.use && check %player_world% is world'
condition: 'any[perm vip; perm staff]'

7. 坐标与几何

逻辑画布：单位 px，原点在中心，+x 右、+y 上、+z 朝向观察者。
像素/方块：canvas.pixels-per-block 决定逻辑像素与世界方块的换算；MenuPlane.project 把玩家视线射线投影到画布得到逻辑坐标，toWorld 反之。
前端变换顺序（Transforms.local，自内而外）：translate(offset) → rotateZ → rotateX → rotateY → scale(sx, sy, 1)。
后端命中：与前端视觉/深度/变换完全无关；命中判定为矩形半宽/半高包含，按 priority 降序、文档顺序取首个命中。
画布锚定：首次打开时固定世界锚点与坐标轴（遵循 offset.yml），后续切换路由复用同一平面，不随视角漂移；传送/跨维度/重生会重新锚定。

由于前端分组可带 scale，样板示例中 viewport-content 组用了 scale: 0.427，因此后端命中区坐标 ≈ 前端坐标 × 0.427。

8. 占位符

在动作、content、tooltip、condition 等文本位置均可使用：

语法	含义
`{meta:key}` / `{m:key}`	临时状态（会话级）
`{data:key}` / `{d:key}`	玩家持久状态
`{globaldata:key}` / `{gdata:key}` / `{g:key}`	全局状态
`{0}`、`{1}` …	菜单参数（`open`/命令传入）
`%auroraui_meta_KEY%`	同上（命名式）
`%auroraui_data_KEY%`	持久状态
`%auroraui_globaldata_KEY%`	全局状态
`%auroraui_args_N%`	第 N 个参数
`%player_name%`	玩家名
`%player_uuid%`	UUID
`%player_world%`	世界名
`%player_x%` / `%player_y%` / `%player_z%`	坐标（保留 2 位小数）
`%...%`	若安装 PlaceholderAPI，则交给其解析

规则：未能解析的占位符会替换为字符串 null（便于调试与条件判定）。

9. 资源包管线

来源目录：plugins/AuroraUI/images（路径必须全小写）。构建产物：generated/auroraui-resourcepack.zip，同时解包到 generated/resourcepack/。

贴图落位：assets/auroraui/textures/images/<相对路径>
位图字体：assets/auroraui/font/images.json，字体键 auroraui:images，height=8、ascent=4
私用区码位：每个图片分配一个 0xE000–0xF8FF 的唯一码位，记录在 generated/images.index，保证跨次构建稳定
pack.mcmeta：pack_format: 34，supported_formats 34–84
限制：图片数 ≤ 4096；单图尺寸 ≤ 4096×4096；单文件 ≤ 16 MiB；总量 ≤ 128 MiB
热构建保护：已发布图片不能在热构建中删除，需先移除引用再完整重启

九宫格 tooltip 皮肤

tooltip.yml 的 skin 使用 background + 可选 frame 合成九宫格，字体键 auroraui:tooltip_slices（ascent=2）：

background 与 frame 的 PNG 尺寸必须相同
border > 0 且 border*2 < PNG 宽/高
生成的切片写入 /_generated/nine_slice/*.png

CraftEngine

CraftEngine 作为自定义内容集成：资源包 zip 会通过 CraftEngine 的缓存事件合并；打包版 CraftEngine 缺失时可自动释放（见第 11 节配置）。

11. 配置项

11.1 config.yml

language:
  default: zh_CN           # 控制台/日志语言
  follow-player-locale: true
shortcuts:
  shift-f: true            # Shift+F 切换主菜单（false 则不干预副手交换）
embedded-craftengine:
  auto-install: true
  file-name: CraftEngine.jar
mouse:
  policy: player-choice    # player-choice | force-touch | force-mouse
  default: touch
  cursor:
    sensitivity-x: 2.0
    sensitivity-y: 2.0
    clamp-margin: 3.0
    size: 5.0
    z: 5.0

11.2 offset.yml（屏幕全局摆放）

touch / mouse 各含 distance（眼到屏幕距离，方块）与 offset{x,y,z}（屏幕本地平移，方块；x 右、y 上、z 朝向观察者）。编辑器中默认走 mouse 模式。

11.3 tooltip.yml

touch / mouse 各含 offset、anchor（四角）、wrap、size、line-width、background，以及 skin（九宫格）：background、frame、border、padding、min-size、size-adjust、offset、scale、text-offset、seam-overlap、glyph-offset、column-offset、row-offset。

11.4 animations.yml

schema-version: 1
transitions:
  my-slide:
    enter:  {duration: 8, easing: ease-out, offset: {x: -36, y: 0, z: 0}, scale: {x: 0.9, y: 0.9}}
    exit:   {duration: 6, easing: ease-in,  offset: {x: 0, y: -28, z: 0}, scale: {x: 0.92, y: 0.92}}
    switch: {duration: 7, easing: ease-out, offset: {x: 36, y: 0, z: 0}, scale: {x: 0.94, y: 0.94}}
tracks:
  model-spin:
    target: spinner            # 前端节点 ID
    property: rotation         # rotation | content | opacity | offset | scale
    duration: 60
    easing: linear
    loop: repeat               # repeat | ping-pong
    trigger: open              # open | api
    keyframes:
      - {at: 0, value: {x: -15, y: 0, z: 0}}
      - {at: 1, value: {x: -15, y: 360, z: 0}}
menus:
  m5-animation:
    transition: my-slide
    tracks: [model-spin]

transitions：菜单 enter/exit/switch 过渡。
tracks：可复用的节点轨道；trigger: open 随菜单打开播放，trigger: api 需通过 play-animation/API 触发。
menus：把某菜单绑定到某 transition，并列出随菜单激活的 tracks。

12. 编辑器协议

protocol 模块提供无第三方依赖的通信契约（EditorProtocol.VERSION），由服务端与 Fabric 编辑器共享。/aurora status 会显示当前协议版本。编辑器通过 mouse 模式打开，属管理端工具，玩家端不需要安装。

编辑器的安装、打开方式、界面布局、快捷键与常见问题，见 AuroraUIEditor 使用 Wiki。

13. 加载期校验与常见错误

严格字段：任何未知字段（如把 label 写进 backend）都会导致 不支持的字段 并拒绝加载该菜单。
ID 唯一：节点 ID 在前端+后端+嵌套组内必须唯一。
唯一主菜单：main-menu: true 有且仅有一个。
open 目标必须存在：open: 指向的菜单 ID 必须已定义，或为 namespace:path 扩展路由；动态目标（含 %/{）豁免。
refresh 目标必须存在：refresh 的参数必须是本菜单内某动态文字节点或后端区域 ID。
open-commands 冲突：自定义命令不得与已注册命令重名。
图片路径：仅小写、.png、虚拟根 / 下；不存在于资源包会渲染失败。

调试流程：先 /aurora validate 校验，再 /aurora reload all 应用并重建资源包。

14. 更多文档

文档	内容
AuroraUIEditor 使用 Wiki	可视化编辑器的安装、使用与常见问题
AuroraUI · MineBBS	AuroraUI 服务端插件下载页
AuroraUIEditor · MineBBS	编辑器 MineBBS 下载页
AuroraUIEditor · Modrinth	编辑器 Modrinth 下载页
`README.md`	Markdown 版本文档
`docs/第三方应用API.md`	应用 API 详解
`docs/总技术规划书.md`	总体技术规划
`docs/M3-可视化编辑器.md`	编辑器设计
`docs/M4-资源与模板.md`	资源与模板
`docs/M5-动画与API.md`	动画与 API
`docs/M6-版本与体验.md`	版本与体验
`docs/Tooltip配置与微调.md`	Tooltip 配置与微调
`docs/TrMenu-M2-兼容表.md`	TrMenu 兼容对照