# AUI 页面开发与调试（AI 专用）你在为 Minecraft 模组 ApricityUI（AUI）写页面或调试运行中的页面。**本文件覆盖了写出可用页面所需的全部规则**，更细的内容在 GitHub 仓库（见第七步末尾），能获取就看，获取不到以本文件为准。先定个调：AUI 页面就是普通的 HTML/CSS/JS，浏览器常用的特性基本都能用，按正常的 web 方式写就行。只有两条：别用太冷门的特性，别把结构和样式写得过于复杂。真正要注意的是模组本身的东西——路径、页面配置、四种界面形态、容器、调试，这些和 web 经验无关，全在下面。 ## 这个模组是什么 AUI 让你用 HTML/CSS/JS 写 Minecraft 界面。它不是内嵌浏览器：HTML 解析、CSS 布局、绘制是自研引擎，页面脚本由 Rhino 执行（老派 JS 环境，写 `var` + 普通 `function` 最稳）。一个 HTML 文件解析成一个 Document，放进四种宿主之一显示。游戏内三个按键记住：F10 资源管理器（双击 HTML 可交互预览，右键 REFERENCE 生成打开代码）、F12 DevTools（页面调试器）、END 全量重载资源。 ## 第一步：你在什么环境？ ### 环境 A：Java 模组开发（AUI 作为依赖库）特征：你在模组工程里（有 build.gradle、Java 源码），AUI 是依赖。 - 统一入口 `com.sighs.apricityui.ApricityUI` 静态方法：`createDocument(path)`、`screen(path)`、`menu(player, path).bind(...)`、`createWorldWindow(path, pos, distance)`、`getDocument(path)`、`getDocumentByUUID(uuid)`； - **线程规则**：一切 DOM/宿主操作必须在客户端线程。异步回调（网络包、线程池）里先 `Minecraft.getInstance().execute(...)` 再碰页面，否则偶发崩溃； - **空值约定**：`createDocument` 资源缺失返回 null，要判空； - **刷新失效**：页面 refresh/重载会重建整个 DOM，旧 Element 引用、监听器全部失效，重新查询。 ### 环境 B：整合包 / 服务器，用 KubeJS 写 UI 特征：你在实例目录或整合包仓库里，写 `kubejs/` 下的脚本。 - 全局对象 `ApricityUI` 已注入 KJS，客户端脚本和服务端脚本的方法集**不互通**：客户端管界面（createDocument/screen/createWorldWindow），服务端管容器（menu）； - **创建≠显示**：`createDocument(path)` 建出 Overlay 立即显示；`Document.createInWorld(path)` 单独调用什么都不显示；全屏界面要 `screen(path)`；容器必须服务端 `menu(...).bind(...)`。 ## 第二步：路径规则 - 一切资源用**逻辑路径**：`screens/home.html`。不写 `assets/...` 前缀，不写磁盘路径； - 页面文件实际放在 `<游戏目录>/apricity/` 下（如 `<游戏目录>/apricity/screens/home.html`），写完按 END 让模组扫到； - 页面内引用 CSS/图片/字体用相对路径（相对当前 HTML），`/` 开头表示逻辑资源根； - 唯一例外：`` 的 src 是 MC ResourceLocation（`minecraft:textures/item/diamond.png`），不是逻辑路径。 ## 第三步：页面 meta（每个页面必须配）放在 `` 里，只在页面创建和 refresh 时读取： ```html ``` - **aui-font-mode**：`mc`（原版字体）、`web`（网页字体规则，大多数页面选它）、`web-scaled`（web + 跟随缩放）； - **aui-viewport**：`mode=browser` 跟随窗口（Screen 首选）；`mode=fixed,width=N,height=N` 固定逻辑尺寸（**WorldWindow 必须用它**，否则默认宽度上千像素，面板在世界里巨大无比）；`mode=gui` 跟随 MC GUI 缩放（兼容旧页面）。缩放参数 `zoom/min-zoom/max-zoom/zoom-step/user-scalable` 可选； - **aui-mouse-events**：写 `intercept` 页面才拦截鼠标。**页面有任何可交互元素就必须写**，否则点击落到游戏而不是页面；纯展示 Overlay 不写（让它穿透）。 ## 第四步：选宿主同一份 HTML 四种宿主通用，区别在出现在哪、谁来开： | 你要做什么 | 宿主 | 打开方式 | 要点 | | --- | --- | --- | --- | | 全屏界面：设置页、菜单 | Screen | KJS `ApricityUI.screen("screens/x.html")`；Java `Minecraft.getInstance().setScreen(new ApricityScreen(path))` | meta 按上面配 | | HUD、常驻状态、通知 | Overlay | KJS/Java `ApricityUI.createDocument("overlays/x.html")` | 创建即显示；纯展示别配 intercept | | 背包、机器——操作**真实物品** | 容器 Screen | **只能**服务端 `ApricityUI.menu(player, path).bind(...)` | 见第六步 | | 世界里的显示屏、头顶标签 | WorldWindow | `ApricityUI.createWorldWindow("world/x.html", pos, 32)`（Java 第二参数是 Vec3） | 页面必须 `mode=fixed` 视口；创建即显示 | WorldWindow 补充：`setRotation(Vec3)` 参数顺序是 `(pitch, yaw, roll)`（容易搞反）；`setFacing(true)` 面向玩家；`setFollow(true)` + `setFollowFactor(0.3)` 跟随视线（头顶标签用法）；构造参数的距离是交互射线距离，`setMaxDisplayDistance` 才是显示距离，别搞混。 **从游戏代码操作已打开的页面**：`ApricityUI.getDocument(path)` 返回**列表**（同路径可开多个实例）： ```javascript var docs = ApricityUI.getDocument("screens/hello.html"); if (docs.length > 0) { docs[0].getElementById("status").textContent = "HP: 20"; } ``` 要精确管某个实例：保存 `createDocument` 的返回对象，或 `getDocumentByUUID(uuid)`。 ## 第五步：写页面按正常 web 方式写，注意这几个模组特有的点： **没有浏览器默认样式**：`h1` 和 `div` 长得一样，`button` 没有按钮外观。要么全显式写样式，要么引 Ore 主题（推荐，见下）。 **初始化挂 DOMContentLoaded**：refresh 会重建页面，旧引用全部失效。初始化代码包进函数挂上去，每次重建重新执行： ```javascript function init() { var btn = document.getElementById("ok"); if (!btn) return; btn.addEventListener("click", function () { /* ... */ }); } document.addEventListener("DOMContentLoaded", init); ``` **JS 环境的几个差异**：键盘修饰键是 `controlKey` 不是 `ctrlKey`；事件坐标已经是页面逻辑坐标，**不要乘**任何缩放系数；`fetch(url)` 只支持单参数 GET，`response.json()` 在 then 里同步调用；没有 WebGL/XHR/WebSocket/完整 Promise。DOM 查询修改、事件捕获冒泡、localStorage、Canvas 2D、定时器、ResizeObserver/MutationObserver 这些都有。 **扩展元素**（标准标签之外的 MC 向标签，都是普通 DOM 元素，都必须给 CSS 宽高）： | 需求 | 写法 | 要点 | | --- | --- | --- | | 游戏纹理 | `` | src 是 ResourceLocation；`blur="true"` 模糊 | | 图集帧动画 | `` | src 是逻辑路径；direction 是图集排布方向 | | 本地化文本 | `item.minecraft.diamond` | 跟随游戏语言；无参数插值 | | 矢量图标 | `` | 支持基本形状和 path；无渐变/defs/transform | | 脚本绘制 | `