制作第一个界面 ​

这篇教程将带你从空白页面开始，制作一个可以在游戏中正常打开的欢迎界面。最终页面包含半透明背景、标题、说明文字和带悬浮效果的按钮；点击按钮后，页面会自动关闭。

整个过程都在 ChaUI 游戏内编辑器中完成，不需要手写页面 yml。

完成后的效果 ​

最终界面包含以下内容：

• 一个位于屏幕中央的半透明面板；
• 标题“欢迎来到服务器”；
• 说明文字“这是使用 ChaUI 制作的第一个界面”；
• 一个“开始冒险”按钮；
• 鼠标悬浮按钮时切换图片；
• 左键点击按钮后关闭当前页面。

开始前，请先完成服务端安装与客户端安装，并确认管理员客户端能够正常进入 ChaUI 编辑器。

第一步：准备按钮素材 ​

准备两张尺寸相同的按钮图片：

悬浮图片可以在普通图片的基础上提高亮度、增加描边或改变颜色，让玩家能清楚感受到按钮已经被选中。

将两张图片放到当前客户端的以下位置：

当前游戏版本目录/
└─ resourcepacks/
   └─ ChaUI/
      └─ gui/
         └─ tutorial/
            ├─ button.png
            └─ button_hover.png

稍后在编辑器中填写的是相对路径：

• 普通图片：gui/tutorial/button.png
• 悬浮图片：gui/tutorial/button_hover.png

第二步：创建空白页面 ​

通过服务端提供的页面编辑入口创建页面，将页面 ID 设置为 welcome。页面不存在时，ChaUI 会自动为它准备空白模板并打开编辑器。

页面 ID 是页面的唯一名称，保存后的文件名也会使用它。建议使用简短、容易识别的英文、数字、下划线或中文，不要加入空格、点号和路径符号。

/chaui editor welcome

第一次进入编辑器时，可以先认识五个主要区域：

1. 顶部工具栏：保存、撤销、重做、网格、吸附、坐标模式、外置和预览。
2. 左侧面板：在“组件库”添加组件，在“页面组件”查看当前页面层级。
3. 中央画布：拖动、缩放和预览页面元素。
4. 右侧属性面板：修改页面或当前选中组件的属性。
5. 底部状态栏：显示选中状态、保存结果和操作提示。

第三步：设置页面属性 ​

切换左侧面板到“页面组件”，点击第一行的“页面变量”。右侧会显示页面本身的设置。

按下表填写或切换：

输入布局公式时，要等公式完整且合法后再离开输入框。半截公式不会写入页面，避免编辑过程中让画布异常。

第四步：添加背景面板 ​

⚠️为了防止误触/游戏崩溃等导致页面进度丢失，可以多多使用【保存】按钮⚠️

回到左侧“组件库”，在“组件”分组中点击“矩形”。新组件会出现在画布中央并自动选中。

在右侧属性面板中填写：

这里的 X 与 Y 会先找到窗口中心，再减去面板宽高的一部分，使面板保持在屏幕中央。颜色统一填写六位 #RRGGBB；#202730 是深灰蓝。透明度单独使用 0 到 1，0.88 表示略微透明。

pointerEvents: block 让面板成为遮挡层。以后在它上方弹出对话框时，玩家点击空白区域不会穿透到面板后方的按钮或物品槽。

第五步：添加标题和说明文字 ​

添加标题 ​

在“组件库”中点击“文本”，将新文本设置为：

添加说明文字 ​

再次点击“文本”，将第二个文本设置为：

如果需要文字居中可以点击【对齐】选项，变成center，在这种情况下，文字会根据组件的【宽】来水平居中，如果仍有偏移，可以尝试调整文字组件的【宽】和背景的【宽】数值一致

第六步：添加开始按钮 ​

在“组件库”中点击“按钮”，然后填写以下属性：

源图选区字段保持空白即可，表示使用整张按钮图片。GIF 相关设置也不需要调整，因为本教程使用的是 PNG。

如果按钮显示为缺失素材，先不要继续测试脚本。请回到第一步，检查文件位置、文件名大小写和相对路径是否完全一致。

完成后鼠标移动到按钮上可以看到按钮状态变化

按钮位于背景面板上方，所以会成为当前唯一目标。后续如果添加弹窗，可以给弹窗遮罩设置更高的 z 和 pointerEvents: block，给弹窗按钮再设置更高的 z；普通页面和编辑器预览都会使用相同的防穿透结果。

第七步：设置按钮点击事件 ​

继续向下滚动右侧属性面板，找到“触发”区域。在“左键脚本”中填写：

关闭()

其他触发项保持空白。这个脚本表示玩家左键点击按钮时关闭当前页面。

编辑模式只用于调整组件，不会直接执行事件脚本。需要测试点击行为时，必须先保存页面，再进入预览或正常打开页面。

第八步：预览排版 ​

先点击顶部“预览”，检查页面整体效果。预览会隐藏编辑器工具栏和面板，只保留“退出预览”入口，因此看到的布局更接近玩家实际打开页面时的效果。

此时重点检查：

• 面板是否位于屏幕中央；
• 标题、说明和按钮是否落在面板内部；
• 文字有没有超出组件范围；
• 鼠标移动到按钮上时，是否切换为悬浮图片；
• 页面四周是否有不需要的组件或占位图。

第一次预览先不要点击“开始冒险”，因为页面尚未保存。按 Esc 或点击“退出预览”返回编辑模式，修正发现的问题。

第九步：保存并测试按钮 ​

确认排版后，点击顶部“保存”。留意底部状态栏，等待出现页面保存成功的提示后再继续。

保存成功后，页面会写入服务端：

plugins/ChaUI/pages/welcome.yml

如果之后再次保存同一页面，ChaUI 会在覆盖前把旧页面自动备份到：

plugins/ChaUI/backups/pages/

现在可以再次进入预览并点击“开始冒险”。页面正常关闭，说明按钮事件已经生效。若还需要继续修改，通过服务端页面编辑入口重新打开 welcome 即可。

第十步：在正常游戏中打开 ​

最后退出编辑器，通过服务端的页面打开入口向自己打开 welcome。这一步用于确认玩家实际看到的界面与编辑器预览一致。

打开后依次检查：

1. 页面在不同窗口尺寸下仍保持居中。
2. 按钮普通图片与悬浮图片都能显示。
3. 左键点击“开始冒险”后页面关闭。
4. 控制台没有出现页面不存在、素材路径非法或保存失败提示。

把进阶内容放到正确位置 ​

第一个界面完成后，不必立刻把变量、组件对象、计时器和生命周期都塞进同一张练习页面。按目标继续阅读会更容易：

• 想让文字随状态变化：阅读响应式变量与实时文字。
• 想让组件跟随另一个组件：阅读组件对象、布局公式与临时组件。
• 想制作倒计时：阅读循环与计时器。
• 想在打开或关闭时初始化页面：阅读页面生命周期与自定义方法。
• 想直接美化已有插件箱子：继续完成替换第一个箱子界面。

常见问题 ​

按钮显示为缺失素材 ​

确认图片位于当前客户端实际使用的游戏版本目录，而不是其他实例。页面路径只填写 gui/tutorial/button.png，不要写磁盘盘符、resourcepacks/ChaUI/ 前缀或反斜杠。

点击按钮没有反应 ​

先确认页面已经保存成功。编辑模式不会执行脚本，关闭动作需要在保存后的预览或正常运行页面中测试。还要检查左键脚本是否完整写成 关闭()。

页面没有居中 ​

检查 X、Y 公式是否完整，并确认使用的是英文句点 0.5、减号和乘号。不要把 window.width 或 window.height 拆开输入。

文字位置看起来不完全居中 ​

不同字体资源可能影响文字宽度。微调文本 X 或按钮的“文字 X”即可，不需要改变整个页面结构。

保存被拒绝 ​

确认当前玩家拥有编辑权限，页面 ID 仍为 welcome，并检查底部状态栏给出的原因。非法公式、无效素材路径或未完成的属性值都需要先修正。

下一步可以尝试什么 ​

完成第一个界面后，可以在当前页面副本上继续练习：

• 把按钮图片换成 GIF，观察动画与循环效果；
• 为按钮加入本地 OGG 点击音效；
• 添加输入框，让玩家填写文本；
• 使用页面变量、玩家常量和 PAPI 常量制作实时状态文字；
• 尝试相对布局或网格布局，组织更多组件；
• 使用“外置”编辑器，在独立窗口中调整属性。