UI 编辑器

在 Creator Hub 中以可视化方式设计场景的屏幕 UI，而不是用代码。

UI 编辑器让你通过把组件拖到画布上来构建场景的屏幕界面，而不是手写布局代码。它会把真实文件写入你的场景中，所以你在这里制作的任何内容都是标准的 SDK7 UI，你仍然可以用代码继续编辑。

打开它

使用 2D / 3D 编辑器左侧面板顶部的切换开关。 3D 就是你已经熟悉的场景画布。 2D 就是 UI 编辑器。

2D 和 3D 选项卡切换开关，当前选中的是 3D。

📔 注意: UI 编辑器需要 @dcl/sdk 在你的场景中使用 7.26.0 或更高版本。对于旧场景， 2D 选项卡会显示一个 UI 编辑器不可用 提示，而不是画布，并带有一个 更新 SDK 按钮，它会为你升级场景，还有一个 以后再说 按钮用于关闭它。

Creator Hub 会记住你把某个场景停留在 2D 还是 3D，并以相同方式重新打开它。这是按项目存储的，且绝不会随你的场景发布。

如果你使用的是 Bevy 场景渲染器，切换到 2D 会暂停正在运行的场景，而返回到 3D 如果它之前正在运行，则会恢复运行。

制作你的第一个 UI

1. 切换到 2D 选项卡。

2. 点击 新建 GUI，你可以使用空画布中央的按钮，或者使用 + 旁边的 GUIs 位于左侧面板中。GUI 是一个 UI 组件，存放在自己的文件里。

3. 把底部面板中的一个组件拖到画布上。 全屏 是一个很好的起始组件，它会给你一个覆盖整个屏幕的根节点。然后再把其他组件放到其中。

4. 选中一个组件，然后在右侧面板中设置它的属性。

没有保存按钮。编辑器会在你操作时把更改写入磁盘，而工具栏左侧的徽章会显示 所有更改已保存.

2D 模式下的 UI 编辑器：左侧的 GUIs 和 Nodes 面板列出了一个名为 MainUI 的 GUI，其中一个 Container 里包含一个 Label 和一个 Button；中间的画布显示了该容器，Button 被选中并带有周围的缩放手柄；右侧的 Properties 选项卡显示 Button 的位置和布局；底部则是组件面板。

各面板

• 左侧: GUIs，你的 UI 组件列表，以及 节点，所选组件的树状结构。搜索框可同时筛选两者。将鼠标悬停在某个节点上可锁定、隐藏或删除它。

• 右侧：一个 属性 选项卡用于所选节点，以及 逻辑 选项卡。

• 底部：组件面板。把一张卡片拖到画布上即可添加它。

• 中间：画布。拖动节点可移动它们，使用手柄可调整大小，并且可以用鼠标滚轮或拖拽自由平移。

画布右下角有两组浮动控件：

• 该 预览 组会切换移动端 HUD 辅助线和安全区域辅助线，并在 桌面预览 和 移动预览.

• 该 缩放 组包含减号和加号按钮，以及百分比读数。点击百分比即可重置视图。

UI 编辑器左侧面板，带有 2D 和 3D 选项卡、搜索框、包含 MainUI 的 GUIs 列表，以及显示一个 Container 及其下 Label 和 Button 的 Nodes 树，Button 行上有锁定、隐藏和删除图标。

UI 编辑器中选中的 Button 的 Properties 选项卡，包含 Visibility、Interaction States，一个带有 Constraints、Position 和 Z-Index 的 Position 区域，以及一个带有 Size、Min Size、Max Size、Padding 和 Margin 的 Layout 区域。

组件

UI 编辑器底部的组件面板，卡片包括 Full Screen、Container、Image、Label、Button、Input 和 Dropdown。

该组件面板把组件分为三类：

• 容器: 全屏, 容器, 图像

• 文本: 标签, 按钮

• 输入框: 输入框, 下拉框

全屏 是一个容器，它会填满放置它的地方，这使它成为一个很好的起点，适合用于需要覆盖屏幕的 UI。

移动与调整大小

工具栏有三种工具模式：

• 自由：移动和调整大小，通用模式。

• 移动：仅拖动。

• 调整大小：仅使用手柄。

位置会吸附到 10 像素网格。按住 Shift 拖动可自由移动，不受网格影响。工具按钮旁边的小箭头会打开一个 吸附 复选框，可完全关闭吸附。

2D 工具栏，包含“所有更改已保存”徽章、撤销和重做、自由、移动和调整大小工具，以及打开的吸附下拉菜单，显示已勾选的吸附选项，后面还有播放和停止按钮。

布局：流式布局与自由定位

有两个独立属性决定节点最终落在哪里。把它们弄清楚能省去很多困惑。

Flow 设置在一个 容器 上，用来决定它如何排列子元素：

• 自由：子元素会停留在你放置它们的位置。

• 行 / 行反向：子元素从左到右，或从右到左排列。

• 列 / 列反向：子元素从上到下，或从下到上堆叠。

• 自动换行子元素：当空间不够时，允许子元素换到多行显示。

忽略布局流 设置在一个 子节点 并决定该节点是否退出其父节点的排列。关闭时，由父节点定位它；开启时，你可以使用 Anchor 和 Position 值手动固定它。

由此会产生两个后果：

• 把一个组件拖到一个 自由 容器里，它就会停留在你放下它的位置。

• 把它拖进一个带有方向的容器，它就会加入布局流，在队列中占据自己的位置。

将容器切换为 自由 会把它现有的子元素固定在当前位置，因此不会跳动。

GUI 的根节点始终采用自由定位。

其他值得了解的属性

• 不透明度：100% 表示完全不透明，0% 表示完全透明。默认值为 100%。

• 场景内嵌：GUI 所处的屏幕区域。

  • 全屏 使用整个可渲染屏幕。

  • 游戏安全区域 会避开客户端自身界面，例如聊天、迷你地图和 HUD 指示器。

  • 设备安全区域 还会避开刘海或系统栏等物理遮挡。画布处于移动预览时会提供此选项。

如果你给某个 GUI 的根节点设置固定像素宽高，画布就会把它框成一个精确等于该尺寸的画板，而不是屏幕。

在手机上检查你的 UI

画布右下角的控件可在桌面屏幕和手机之间切换预览。在移动预览中，画布会绘制在手机边框内，并带有刘海，这样你就能看到屏幕边缘的实际位置。

两组辅助线可帮助你把内容放在玩家看得到且能触及的位置：

• 安全区域辅助线 勾勒出你的 GUI 所限定的屏幕区域，与所选的 场景内嵌 相匹配。当 Scene Inset 为 设备安全区域 或 游戏安全区域 时，轮廓总是开启，因为那就是 GUI 被裁剪到的区域。将 Scene Inset 设置为 全屏 后，你就可以通过框架图标按钮打开或关闭该轮廓。

• HUD 辅助线 会绘制移动客户端自身的控件，例如摇杆、跳跃和动作按钮、表情轮盘、个人资料、聊天和指南针。它们仅供参考，不能选中或移动。游戏手柄按钮可将它们开启或关闭，它只会出现在移动预览中，并且当 Scene Inset 是安全区域时，这些辅助线默认显示。

放置在安全区域之外的内容不会被隐藏，而是会绘制到轮廓之外。这个溢出就是警告：在真实客户端中，它会位于游戏自身 HUD 的下方。

📔 注意：这些辅助线仅是编辑器中的近似效果。真实区域由客户端在运行时报告，并且会因设备而异，所以务必在真机上确认。参见 在移动端预览.

自定义移动端控件

在移动端客户端中，玩家通过一组原生屏幕控件进行移动和操作：摇杆、准星以及一排动作按钮。该 MobileHUD 条目可让你无需编写代码即可重新塑造该 HUD，并在操作过程中将结果显示在画布上。

一旦你的场景至少有一个 GUI， MobileHUD 就会作为 GUIs 列表中的第一行出现，位于你自己的 GUI 之上。选中它即可在右侧打开其面板。

顶部的三个复选框可隐藏 HUD 的整个部分：

• 隐藏摇杆：会移除移动摇杆。

• 隐藏准星：会移除瞄准准星。

• 隐藏输入动作：会一次移除所有动作按钮。

下面的 输入动作 部分按屏幕槽位的填充顺序列出了这八个按钮：

动作	屏幕上的按钮
IA_JUMP	默认情况下的大型中央按钮
IA_POINTER	交互按钮
IA_PRIMARY (E)	E 按钮
IA_SECONDARY (F)	F 按钮
IA_ACTION_3 (1) 设为 IA_ACTION_6 (4)	编号按钮

每一行会给你三样东西：

• 主：一个单选按钮，可将该动作设为中央大型按钮。 IA_JUMP 默认是主项，而且同一时间只能有一个动作是主项。

• 一个 眼睛图标 用于显示或隐藏该按钮。隐藏一个按钮后，下方按钮会上移以填补空位。

• 自定义图标：将按钮的图标替换为来自你场景中的一个 .png, .jpg 或 .jpeg 图片。

默认情况下没有任何内容被隐藏，而 IA_JUMP 是主按钮，这正是未修改 HUD 的场景中玩家获得的默认配置。

💡 提示：编号按钮通常位于一个“+”溢出切换按钮后面。把较高序号的按钮隐藏得足够多，它们就会直接显示。参见 屏幕控制 了解槽位如何填充。

它写入的文件

你的更改会写入到 src/mobile-hud.ts，它导出一个 setupMobileHud() 函数，基于 SDK 的 TouchScreenControls 组件：

import { engine, InputAction, TouchScreenControls } from '@dcl/sdk/ecs'

export function setupMobileHud() {
  TouchScreenControls.createOrReplace(engine.RootEntity, {
    hideJoystick: true,
    hideCrosshair: false,
    mainAction: InputAction.IA_PRIMARY,
    touchInputs: [
      { inputAction: InputAction.IA_ACTION_3, hide: true },
    ],
  })
}

编辑器还会将导入和调用添加到你的 src/index.ts:

import { setupMobileHud } from './mobile-hud'

setupMobileHud()

该文件只在有内容可写时才存在。如果你把一切都恢复为默认值，或者删除最后一个 GUI，Creator Hub 就会删除 src/mobile-hud.ts 并再次移除这两行。

📔 注意：当 MobileHUD 被选中时，组件面板会被禁用，预览控件也会隐藏，因为没有可放置的内容，而且 HUD 仅适用于移动端。选择你自己的任意 GUI 即可把它们恢复。

文件存放位置

UI 编辑器会编辑你的场景的真实源文件。没有单独的保存格式。

• 每个 GUI 都对应一个 .tsx 文件，位于 src/ui/.

• src/ui/index.tsx 由编辑器生成，用于将它们汇总在一起。不要手动编辑它。

• src/mobile-hud.ts 保存你的 移动端控件，如果你修改过的话。它是有意放在 src/ui/ 之外的，因此永远不会被当作 GUI。

如果你的场景里有一个较旧的单个 src/ui.tsx 文件，编辑器会在你第一次打开 UI 编辑器时将其备份为 src/ui.tsx.bak 。

因为这些都是普通文件，所以你可以随时在你的 代码编辑器 中打开它们。参见 UI ，了解底层代码的作用。

编辑器无法编辑的代码

编辑器理解一种特定形状的 UI 代码。例如，某个节点如果以其他方式编写，比如在循环或条件语句中构建，或者使用自定义组件或展开属性，它就会在画布上显示为一个灰色块，并带有一个 非标准，请在代码中编辑 徽章。其子节点不会显示，你需要改为在代码中编辑它。

其余的 GUI 仍会正常工作。

相关页面

• UI：用代码编写场景 UI。

• 结合代码：在代码编辑器中打开你的场景。

• 实体与组件：编辑器的 3D 端。