roblox-user-interfaces

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

roblox-user-interfaces

Choose a GUI container for the display surface, then use layouts and constraints to handle screen sizes. For particles inside a ScreenGui, use 2D UI objects; ParticleEmitter does not render there.

Primary sources:

https://create.roblox.com/docs/en-us/ui
https://create.roblox.com/docs/en-us/ui/on-screen-containers
https://create.roblox.com/docs/en-us/ui/in-experience-containers
Sub guides for frames, labels, buttons, text-input, position-and-size, list-flex-layouts, grid-table-layouts, appearance-modifiers, styling, proximity-prompts, ui-drag-detectors, etc.
roblox-animation skill (for motion on these objects)
Engine classes: ScreenGui, SurfaceGui, BillboardGui, GuiObject and all descendants, the various UILayout and UIConstraint classes, CanvasGroup, ViewportFrame, etc.

For UI motion, read roblox-animation. For effects in the 3D world, read roblox-vfx.

为显示表面选择合适的 GUI 容器，然后使用布局和约束来处理不同屏幕尺寸。对于 ScreenGui 内的粒子，应使用 2D UI 对象；ParticleEmitter 无法在其中渲染。

主要来源：

https://create.roblox.com/docs/en-us/ui
https://create.roblox.com/docs/en-us/ui/on-screen-containers
https://create.roblox.com/docs/en-us/ui/in-experience-containers
关于 Frame、Label、Button、text-input、position-and-size、list-flex-layouts、grid-table-layouts、appearance-modifiers、styling、proximity-prompts、ui-drag-detectors 等的子指南。
roblox-animation skill（用于为这些对象添加动画）
Engine 类：ScreenGui、SurfaceGui、BillboardGui、GuiObject 及其所有子类、各种 UILayout 和 UIConstraint 类、CanvasGroup、ViewportFrame 等。

有关 UI 动画，请阅读 roblox-animation。有关 3D 世界中的特效，请阅读 roblox-vfx。

Choose a GUI container

选择 GUI 容器

ScreenGui (on-screen overlay)

Parent to StarterGui for automatic cloning into every player's PlayerGui.
Control visibility with .Enabled (or parent/child manipulation).
Layer multiple with .DisplayOrder (higher = on top).
.ScreenInsets = CoreUISafeInsets (default, respects top bar + device notches), DeviceSafeInsets, TopbarSafeInsets, or None.
.ResetOnSpawn behavior depends on direct ancestry of StarterGui.
All interaction and logic is client-only (LocalScripts or client ModuleScripts).

SurfaceGui (world space on a part face)

Can be parented directly to a BasePart (then uses .Face) or placed in StarterGui/PlayerGui and pointed at a part via .Adornee.
Interactive buttons only receive input if the SurfaceGui ultimately lives under the viewing player's PlayerGui and the part's CanQuery is true.
.AlwaysOnTop, .Brightness (0-1000), .LightInfluence (0-1), .MaxDistance, .ZOffset (for sorting multiple on the same face).
Excellent for terminals, vehicle dashboards, keypads, signs.

BillboardGui (world space, always camera-facing)

Similar properties to SurfaceGui +
```
.StudsOffset
```
(offset relative to camera orientation) and
```
.StudsOffsetWorldSpace
```
(offset in world axes). Size expressed in studs via the scale components of Size (e.g. UDim2.fromScale(4, 2) creates a 4×2 stud billboard whose screen size changes with distance).
Perfect for nameplates, floating health bars, quest markers, damage numbers, contextual prompts above heads or objects.
Interactive elements require the same PlayerGui ancestry rule as SurfaceGui and
```
BillboardGui.Active = true
```
(plus the button's own
```
Active
```
).

Other / special:

CoreGui (Roblox-owned; control with StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.XXX, false)).
ViewportFrame (embed a 3D camera + world inside a 2D rectangle; great for item previews and static 3D models; real ParticleEmitter, Beam, and Trail effects do not render here).

ScreenGui（屏幕叠加层）

挂载到 StarterGui 下，以便自动克隆到每位玩家的 PlayerGui 中。
使用 .Enabled 控制可见性（或操作父级/子级关系）。
使用 .DisplayOrder 叠加多个界面（值越高，层级越靠上）。
.ScreenInsets = CoreUISafeInsets（默认，兼顾顶部栏和设备刘海）、DeviceSafeInsets、TopbarSafeInsets 或 None。
.ResetOnSpawn 的行为取决于其在 StarterGui 层级中的直接祖先关系。
所有交互和逻辑都仅在客户端运行（LocalScripts 或客户端 ModuleScripts）。

SurfaceGui（位于 Part 表面的世界空间界面）

可以直接挂载到 BasePart（此时使用 .Face），也可以放置在 StarterGui/PlayerGui 中，并通过 .Adornee 指向某个 Part。
只有当 SurfaceGui 最终位于正在查看内容的玩家的 PlayerGui 下，且该 Part 的 CanQuery 为 true 时，交互按钮才会接收输入。
.AlwaysOnTop、.Brightness（0-1000）、.LightInfluence（0-1）、.MaxDistance、.ZOffset（用于对同一表面上的多个界面进行排序）。
非常适合终端、车辆仪表盘、键盘、标牌等场景。

BillboardGui（始终朝向相机的世界空间界面）

属性与 SurfaceGui 类似，另外还有
```
.StudsOffset
```
（相对于相机方向的偏移）和
```
.StudsOffsetWorldSpace
```
（沿世界坐标轴的偏移）。大小通过 Size 的 scale 分量以 studs 表示（例如，
```
UDim2.fromScale(4, 2)
```
会创建一个 4×2 studs 的 BillboardGui，其屏幕尺寸会随距离变化）。
非常适合姓名牌、浮动生命条、任务标记、伤害数字，以及角色或物体上方的情境提示。
交互元素必须满足与 SurfaceGui 相同的 PlayerGui 层级规则，并且
```
BillboardGui.Active = true
```
（同时按钮自身的
```
Active
```
也必须启用）。

其他／特殊容器：

CoreGui（由 Roblox 所有；使用

StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.XXX, false)

控制）。

ViewportFrame（将 3D 相机和世界嵌入 2D 矩形中；非常适合物品预览和静态 3D 模型；真实的 ParticleEmitter、Beam 和 Trail 特效无法在其中渲染）。

Layout objects and modifiers

布局对象和修饰器

The vast majority of modern Roblox UIs are built from:

Frame or CanvasGroup as containers (ClipsDescendants, AutomaticSize = X/Y/XY, Background* properties, Rotation).
TextLabel / ImageLabel for display.
TextButton / ImageButton for interaction (Activated is the preferred cross-platform event).
TextBox for input.
ScrollingFrame (CanvasSize, AutomaticCanvasSize, ScrollBar* properties).
ViewportFrame for 3D content.

Layout objects (the real power):

UIListLayout / UIGridLayout / UIPageLayout: automatic arrangement, FillDirection, Horizontal/VerticalAlignment, Padding, SortOrder.
```
UIListLayout
```
also supports flex features (
```
HorizontalFlex
```
,
```
VerticalFlex
```
,
```
ItemLineAlignment
```
,
```
Wraps
```
) and pairs with per-object
```
UIFlexItem
```
for flex overrides.
These + AutomaticSize on parents = truly responsive UIs that grow/shrink with content or different languages.

Appearance & constraint modifiers (use these instead of old hacks):

UIStroke (ApplyStrokeMode, Color, Enabled, LineJoinMode, Thickness, Transparency, ZIndex). Modern borders that work on any GuiObject.
UIGradient (
```
Color
```
is a
```
ColorSequence
```
;
```
Transparency
```
is a
```
NumberSequence
```
).
```
Type
```
selects Linear, Radial, or Conical;
```
Scale
```
controls extent and
```
TileMode
```
selects Clamp, Repeat, or Mirror. Radial gradients ignore
```
Rotation
```
. See https://create.roblox.com/docs/ui/appearance-modifiers#gradient.
UICorner (CornerRadius; much better than 9-slice hacks for rounded rectangles).
UIPadding, UISizeConstraint, UIAspectRatioConstraint, UIScale, UIFlexItem.

Positioning fundamentals (non-negotiable for quality):

Prefer Scale (0-1) over Offset (pixels) for almost everything.
AnchorPoint controls the pivot point of the object (0,0 = top-left; 0.5,0.5 = center; set this before tweening Position or Size).
ZIndex for layering inside one container; DisplayOrder for layering whole ScreenGuis.
For world-space: StudsOffset on BillboardGui, ZOffset + AlwaysOnTop on both Surface and Billboard.

See references/gui-containers.md for exhaustive property tables, common hierarchies, and responsive recipes (building blocks & layouts covered there).

大多数现代 Roblox UI 都由以下对象构建：

使用 Frame 或 CanvasGroup 作为容器（ClipsDescendants、AutomaticSize = X/Y/XY、Background* 属性、Rotation）。
使用 TextLabel / ImageLabel 进行显示。
使用 TextButton / ImageButton 处理交互（Activated 是首选的跨平台事件）。
使用 TextBox 处理输入。
使用 ScrollingFrame（CanvasSize、AutomaticCanvasSize、ScrollBar* 属性）。
使用 ViewportFrame 显示 3D 内容。

布局对象（核心能力）：

UIListLayout / UIGridLayout / UIPageLayout：支持自动排列、FillDirection、Horizontal/VerticalAlignment、Padding 和 SortOrder。
```
UIListLayout
```
还支持 flex 功能（
```
HorizontalFlex
```
、
```
VerticalFlex
```
、
```
ItemLineAlignment
```
、
```
Wraps
```
），并可与每个对象上的
```
UIFlexItem
```
配合使用，以覆盖 flex 设置。
将这些对象与父对象的 AutomaticSize 结合使用，可以构建真正响应式的 UI，使其能够随内容或不同语言伸缩。

外观和约束修饰器（应使用这些对象，而不是旧式技巧）：

UIStroke（ApplyStrokeMode、Color、Enabled、LineJoinMode、Thickness、Transparency、ZIndex）。现代边框方案，适用于任何 GuiObject。
UIGradient（
```
Color
```
的类型为
```
ColorSequence
```
；
```
Transparency
```
的类型为
```
NumberSequence
```
）。
```
Type
```
用于选择 Linear、Radial 或 Conical；
```
Scale
```
控制渐变范围，
```
TileMode
```
用于选择 Clamp、Repeat 或 Mirror。径向渐变会忽略
```
Rotation
```
。请参阅 https://create.roblox.com/docs/ui/appearance-modifiers#gradient。
UICorner（CornerRadius；用于圆角矩形时，远优于 9-slice 技巧）。
UIPadding、UISizeConstraint、UIAspectRatioConstraint、UIScale、UIFlexItem。

定位基础原则（保证质量时不可妥协）：

几乎所有场景都应优先使用 Scale（0-1），而不是 Offset（像素）。
AnchorPoint 控制对象的枢轴点（0,0 = 左上角；0.5,0.5 = 中心；在补间 Position 或 Size 之前先设置它）。
同一容器内使用 ZIndex 控制层级；不同 ScreenGui 之间使用 DisplayOrder 控制层级。
对于世界空间界面：BillboardGui 使用 StudsOffset；SurfaceGui 和 BillboardGui 使用 ZOffset + AlwaysOnTop。

有关详尽的属性表、常用层级结构和响应式配方（其中涵盖构建块与布局），请参阅 references/gui-containers.md。

Interaction Model

交互模型

Buttons: Prefer .Activated (fires on release, works for mouse, touch, gamepad).
MouseButton1Click / MouseButton1Down etc. still exist but are less ideal for cross-platform.
TextBox has FocusLost, Focused, ReturnPressedFromOnScreenKeyboard, etc.
Newer: UI drag detectors (2D) and 3D drag detectors for sliders, spinners, draggable objects, doors, etc.
ProximityPrompt for 3D world "press E to interact" style prompts (separate but often paired with UI).

Control default Roblox UI with

StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.PlayerList, false)

etc. Hide virtual controls with

GuiService.TouchControlsEnabled = false

when you provide custom input.

按钮：优先使用 .Activated（释放时触发，适用于鼠标、触摸和手柄）。
MouseButton1Click / MouseButton1Down 等事件仍然存在，但不太适合跨平台场景。
TextBox 具有 FocusLost、Focused、ReturnPressedFromOnScreenKeyboard 等事件。
新增功能：2D UI drag detectors 和 3D drag detectors，可用于滑块、步进器、可拖拽对象、门等。
ProximityPrompt 用于 3D 世界中的“按 E 交互”提示（独立功能，但通常与 UI 配合使用）。

使用

StarterGui:SetCoreGuiEnabled(Enum.CoreGuiType.PlayerList, false)

等方式控制 Roblox 默认 UI。提供自定义输入时，使用

GuiService.TouchControlsEnabled = false

隐藏虚拟控制项。

Particle effects in UI

UI 中的粒子特效

Direct ParticleEmitter lives in the 3D world (parent to Part or Attachment). For 2D UI you have several excellent options:

Scripted 2D particle pools. Tables of ImageLabels (or a single CanvasGroup with many small children). Use TweenService for Position (in scale or local), Size, Transparency, Rotation, Color. Pool and recycle instances. Great for confetti, sparks, floating numbers, reward bursts, hit markers.
ViewportFrame embedding. Place a ViewportFrame inside your ScreenGui. Inside, put 3D parts, meshes, cameras, and small rigs. Real
```
ParticleEmitter
```
,
```
Beam
```
,
```
Trail
```
, and
```
Light
```
objects do not render inside ViewportFrames. Tween the ViewportFrame's own properties or the camera / parts inside. This is how many 3D ability previews or glowing item inspectors are done.
CanvasGroup + rapid tweens. For group "pop", shimmer, or dissolve effects.
UIStroke + UIGradient animated. Energy borders, charging effects, animated lines.
Text + MaxVisibleGraphemes combined with small image "particles" for fancy dialogue or title sequences.

Performance reality: Transparent overdraw and fill-rate are the enemy on mobile. Keep concurrent UI "particles" low, reuse instances aggressively, use smaller textures, and test at low graphics quality.

See the dedicated references/particles-in-ui.md for concrete pool implementations, ViewportFrame setup patterns, integration with 3D markers, and performance guardrails.

直接使用 ParticleEmitter 时，特效位于 3D 世界中（挂载到 Part 或 Attachment）。对于 2D UI，有以下几种很好的方案：

通过脚本实现 2D 粒子池。由 ImageLabel 组成的表（或一个包含许多小型子对象的 CanvasGroup）。使用 TweenService 补间 Position（以 scale 或 local 空间表示）、Size、Transparency、Rotation 和 Color。对实例进行池化和回收。适用于彩纸、火花、飘动数字、奖励爆发、命中标记等效果。
嵌入 ViewportFrame。在 ScreenGui 中放入 ViewportFrame。在其中放置 3D Part、Mesh、Camera 和小型 rig。真实的
```
ParticleEmitter
```
、
```
Beam
```
、
```
Trail
```
和
```
Light
```
对象无法在 ViewportFrame 内渲染。应补间 ViewportFrame 自身的属性，或补间其中的相机与 Part。许多 3D 技能预览或发光物品检视器都采用这种方式实现。
CanvasGroup + 快速补间。用于整体“弹出”、闪烁或溶解效果。
UIStroke + UIGradient 动画。适用于能量边框、蓄力效果和动画线条。
Text + MaxVisibleGraphemes，结合小型图像“粒子”，制作华丽的对话或标题序列。

性能要点：移动端最大的敌人是透明 overdraw 和填充率。务必减少同时存在的 UI“粒子”数量，频繁复用实例，使用更小的纹理，并在低画质下测试。

有关具体的对象池实现、ViewportFrame 配置模式、与 3D marker 的集成方式以及性能防护规则，请参阅 references/particles-in-ui.md。

Responsive layouts

响应式布局

Design in a canonical resolution/aspect (e.g. 1920x1080 or a common mobile one) but implement everything in scale + constraints.
Use UIListLayout + AutomaticSize + Padding for rows/columns instead of manually calculating positions.
For different device classes, either use multiple ScreenGui variants toggled by UserInputService or make one layout that flexes via the layout objects + size modifiers.
Universal styling (Style Editor + StyleRules) is the Roblox equivalent of CSS. Use it for consistent colors, strokes, fonts, and even transitions across many UI pieces.

先以标准分辨率／宽高比（例如 1920x1080 或常见的移动端分辨率）进行设计，但实现时应全部采用 scale 和约束。
使用 UIListLayout + AutomaticSize + Padding 构建行和列，不要手动计算位置。
针对不同设备类别，可以准备多个 ScreenGui 变体并通过 UserInputService 切换，也可以通过布局对象 + 尺寸修饰器让单一布局自动伸缩。
通用样式（Style Editor + StyleRules）是 Roblox 中与 CSS 等效的机制。用于在多个 UI 元素之间统一颜色、描边、字体，甚至过渡效果。

UI review checklist

UI 审查清单

Reference index

参考索引

gui-containers.md: Choose screen or world-space containers and configure layout behavior.
particles-in-ui.md: Build 2D particle effects or combine UI with 3D previews.

gui-containers.md：选择屏幕空间或世界空间容器，并配置布局行为。
particles-in-ui.md：构建 2D 粒子特效，或将 UI 与 3D 预览结合。