UI 界面制作

在前面的教程中，游戏界面一直使用的是原版默认 UI。这一节我们学习使用 MC Studio 内置的界面编辑器，为模组创建自定义 UI 界面。

我们将为「番茄空岛生存」制作一个任务面板——在屏幕上显示当前目标进度，并放置一个可交互的按钮。

你将学到

认识界面编辑器的布局和基本操作
创建 UI 文件，添加画布
使用面板、图片、文本、按钮四种核心控件
理解锚点、位移、尺寸的定位机制
调整控件层级关系
保存 UI 并在游戏中加载

界面编辑器概览

进入界面编辑器

打开你的作品，进入编辑器
点击顶部页签中的「界面」切换到界面编辑器

新版编辑器

界面编辑器仅在新版编辑器中可用。如果你的作品还在旧版编辑器，请先升级（参考制作第一个 Mod 中的升级提示）。

界面布局

界面编辑器分为以下几个区域：

区域	作用
控件库（左上）	原生控件列表（面板、图片、按钮、文本等），拖拽到结构或预览窗添加
控件结构（左中）	当前界面的树状控件层级，可选中、重命名、调整顺序
编辑预览（中间）	实时预览界面效果，可直接选中和移动控件
属性面板（右侧）	选中控件后显示该控件的所有可编辑属性
资源管理（左下）	管理界面文件（JSON）和贴图资源
快捷选项（顶部）	分辨率调整、显示/隐藏游戏画面、自动层级设置

第一步：新建 UI 文件

在资源管理器中点击「新建」按钮
选择「界面文件」，点击下一步
命名为 taskPanel，点击创建

创建成功后，界面编辑器会自动加载该文件，并自带一个名为 main 的画布控件。

什么是画布

画布（Canvas）是界面的根容器，所有其他控件都必须挂在画布下面。一个 UI 文件可以有多个画布，但通常一个就够了。画布本身不可视，只是用于承载子控件。

第二步：创建背景面板

我们先做一个半透明的背景面板，作为任务信息的容器。

2.1 添加面板控件

从左侧控件库中将「面板」拖拽到控件结构的 main 上
选中新创建的面板，在右侧属性面板中将名称改为 taskBg

2.2 设置面板属性

属性	值	说明
锚点	父：左上角，子：左上角	面板贴在屏幕左上角
位移 X	`10 Px`	距左边缘 10 像素
位移 Y	`10 Px`	距上边缘 10 像素
尺寸 X	`200 Px`	宽 200 像素
尺寸 Y	`120 Px`	高 120 像素

锚点定位机制

每个控件有 9 个定位点（四角 + 四边中点 + 中心）。锚点决定了子控件的哪个点和父控件的哪个点重合。

例如：父选「左上角」、子选「左上角」，表示子控件的左上角会对齐到父控件的左上角，然后再加上位移偏移。

位移的正方向：X 向右为正，Y 向下为正。

2.3 添加背景图片

在 taskBg 面板下添加一个「图片」控件，命名为 bgImage
尺寸 X 和 Y 都勾选「适应」（自动填满父面板）
从资源管理的贴图中拖一张深色半透明贴图到图片属性的贴图位置

没有贴图怎么办

如果暂时没有美术资源，可以使用原版的 textures/ui/White.png（纯白贴图），然后在属性中调低透明度（Alpha），效果类似半透明黑色背景。

第三步：添加文本控件

3.1 标题文本

在 taskBg 下添加「文本」控件，命名为 titleText
设置属性：

属性	值
文本内容	`当前任务`
字号	`14`
颜色	金色（`#FFD700`）
锚点	父：上边中点，子：上边中点
位移 Y	`8 Px`

3.2 任务描述文本

再添加一个文本控件，命名为 descText
设置属性：

属性	值
文本内容	`收集 10 颗绿宝石`
字号	`10`
颜色	白色（`#FFFFFF`）
锚点	父：左上角，子：左上角
位移 X	`10 Px`
位移 Y	`35 Px`

3.3 进度文本

添加第三个文本控件，命名为 progressText
设置属性：

属性	值
文本内容	`进度: 0 / 10`
字号	`10`
颜色	浅绿色（`#90EE90`）
锚点	父：左上角，子：左上角
位移 X	`10 Px`
位移 Y	`55 Px`

第四步：添加按钮控件

在面板底部添加一个关闭按钮，让玩家可以隐藏任务面板。

在 taskBg 下添加「按钮」控件，命名为 closeButton
设置属性：

属性	值
锚点	父：下边中点，子：下边中点
位移 Y	`-10 Px`（向上偏移 10 像素）
尺寸 X	`80 Px`
尺寸 Y	`24 Px`
按钮文本	`关闭`
按钮文本字号	`10`

设置按钮贴图

按钮有三种状态的贴图：

状态	贴图	说明
普通	默认按钮背景	正常状态
按下	高亮按钮背景	手指/鼠标按下时
悬浮	与按下相同	鼠标悬停时（PC 端）

从资源管理器中拖拽贴图到对应的贴图槽位即可。如果没有自定义贴图，可以暂时使用默认贴图。

第五步：调整层级

确保控件的遮挡关系正确：

main（画布）
└── taskBg（面板）
    ├── bgImage（背景图片）——最底层
    ├── titleText（标题文本）
    ├── descText（描述文本）
    ├── progressText（进度文本）
    └── closeButton（关闭按钮）——最顶层

在控件结构中，下方的控件会遮挡上方的控件。所以 bgImage 应该在最上面（最先渲染，被其他控件遮挡），closeButton 在最下面。

关于自动层级

默认开启「自动设定层级」时，控件结构中的顺序决定遮挡关系。如果你取消了自动层级，需要手动设置每个控件的层级数值（数值大的在上方）。

注意：自动层级一旦取消后无法重新开启，请谨慎操作。

第六步：保存并查看 JSON

点击编辑器右上角的「保存」按钮（Ctrl+S）。

保存后的 UI 文件是一个 JSON 文件，位于资源包的 ui/ 目录下。你可以通过「更多」→「打开目录」找到它。JSON 结构大致如下：

json

{
  "taskBg": {
    "type": "panel",
    "size": ["200px", "120px"],
    "offset": ["10px", "10px"],
    "anchor_from": "top_left",
    "anchor_to": "top_left",
    "controls": [
      {
        "bgImage": {
          "type": "image",
          "texture": "textures/ui/White",
          "alpha": 0.6
        }
      },
      {
        "titleText": {
          "type": "label",
          "text": "当前任务",
          "font_size": "normal",
          "color": [1.0, 0.84, 0.0]
        }
      }
    ]
  }
}

JSON 与编辑器的关系

界面编辑器是 JSON 的可视化工具。你在编辑器中的每一步操作，最终都会保存为 JSON。反过来，你也可以直接用 VS Code 编辑 JSON 来修改 UI，然后在编辑器中刷新查看效果。

第七步：在游戏中加载 UI

UI 文件创建好后，需要通过代码或预设系统在游戏中加载显示。

方式一：通过预设系统（推荐新手）

切换到关卡编辑器
在舞台（Stage）中的「常驻」区域，添加一个「UI 界面预设」
在预设的属性面板中，将「界面文件」指向刚创建的 taskPanel
运行游戏测试，UI 会自动显示

方式二：通过 Python 脚本

如果你已经学习了 Python 脚本开发，可以用代码控制 UI 的显示和交互：

python

import mod.client.extraClientApi as clientApi

# 注册 UI
clientApi.RegisterUI("tomato_island", "taskPanel", "taskPanel.taskPanelScreen", "taskPanel.json")

# 创建并显示 UI
clientApi.CreateUI("tomato_island", "taskPanel", {"isHud": 1})

关于 UI 逻辑绑定

按钮点击事件、进度文本动态更新等交互逻辑需要通过 Python 脚本实现。界面编辑器只负责布局和外观，逻辑部分需要编写代码。

这超出了快速入门的范围，你可以在界面与交互和 Python 脚本开发中深入学习。

第八步：测试效果

点击「运行」进入游戏，验证以下内容：

测试项	预期结果
面板位置	屏幕左上角，距边缘 10 像素
背景	半透明深色背景
标题文本	「当前任务」，金色，居中
描述文本	「收集 10 颗绿宝石」，白色
进度文本	「进度: 0 / 10」，浅绿色
关闭按钮	面板底部居中，可点击
缩放适配	调整窗口大小后面板位置仍在左上角

常用控件速查

控件	用途	关键属性
画布（Canvas）	界面根容器	不可嵌套，自带于新建文件
面板（Panel）	分组容器，无可视元素	锚点、位移、尺寸
图片（Image）	显示贴图	贴图路径、保持宽高比、Alpha
按钮（Button）	可交互按钮	普通/按下/悬浮贴图、按钮文本
文本（Label）	显示文字	内容、字号、颜色、阴影
滚动列表（ScrollView）	可滚动区域	滚动内容（引用自定义控件）
网格（Grid）	规律排布（如背包）	行数、列数、内容
轮盘（SelectionWheel）	环形选择器	切片数、内外直径

小结

在这一节中，你学会了：

使用界面编辑器创建 UI 文件
添加面板、图片、文本、按钮四种核心控件
通过锚点 + 位移 + 尺寸精确控制控件位置
理解控件层级的遮挡规则
将 UI 文件保存为 JSON，理解编辑器与 JSON 的对应关系
通过预设系统或 Python 代码在游戏中加载 UI

进一步学习

继承和自定义控件：复用控件模板，减少重复工作
变量引用和万用控件：让同一个控件显示不同内容
UI 数据绑定：将游戏数据实时反映到界面上
原生界面修改：修改原版背包、暂停菜单等界面

插件开发

基本概念

基础内容

进阶内容

底层内容

玩法开发

上线流程

开发准备

Apollo基础

网络服模板

插件开发

开发技巧与性能

上线运营

第三方框架

UI 界面制作

界面编辑器概览

进入界面编辑器

界面布局

第一步：新建 UI 文件

第二步：创建背景面板

2.1 添加面板控件

2.2 设置面板属性

2.3 添加背景图片

第三步：添加文本控件

3.1 标题文本

3.2 任务描述文本

3.3 进度文本

第四步：添加按钮控件

设置按钮贴图

第五步：调整层级

第六步：保存并查看 JSON

第七步：在游戏中加载 UI

方式一：通过预设系统（推荐新手）

方式二：通过 Python 脚本

第八步：测试效果

常用控件速查

小结

基本概念

基础内容

进阶内容

底层内容

UI 界面制作 ​

界面编辑器概览 ​

进入界面编辑器 ​

界面布局 ​

第一步：新建 UI 文件 ​

第二步：创建背景面板 ​

2.1 添加面板控件 ​

2.2 设置面板属性 ​

2.3 添加背景图片 ​

第三步：添加文本控件 ​

3.1 标题文本 ​

3.2 任务描述文本 ​

3.3 进度文本 ​

第四步：添加按钮控件 ​

设置按钮贴图 ​

第五步：调整层级 ​

第六步：保存并查看 JSON ​

第七步：在游戏中加载 UI ​

方式一：通过预设系统（推荐新手） ​

方式二：通过 Python 脚本 ​

第八步：测试效果 ​

常用控件速查 ​

小结 ​

UI 界面制作

界面编辑器概览

进入界面编辑器

界面布局

第一步：新建 UI 文件

第二步：创建背景面板

2.1 添加面板控件

2.2 设置面板属性

2.3 添加背景图片

第三步：添加文本控件

3.1 标题文本

3.2 任务描述文本

3.3 进度文本

第四步：添加按钮控件

设置按钮贴图

第五步：调整层级

第六步：保存并查看 JSON

第七步：在游戏中加载 UI

方式一：通过预设系统（推荐新手）

方式二：通过 Python 脚本

第八步：测试效果

常用控件速查

小结