roblox-gui

Roblox GUI 参考

GUI 容器类型

容器	父级	用途
ScreenGui	PlayerGui	HUD、菜单、叠加层——始终朝向屏幕
SurfaceGui	BasePart	附着在部件表面的世界空间 UI（标牌、屏幕）
BillboardGui	BasePart 或 Model	在 3D 空间中悬浮于部件上方（名称标签、生命值条）

ScreenGui

-- LocalScript in StarterGui or StarterPlayerScripts
local player = game:GetService("Players").LocalPlayer
local playerGui = player:WaitForChild("PlayerGui")

local screenGui = Instance.new("ScreenGui")
screenGui.Name = "HUD"
screenGui.ResetOnSpawn = false   -- keep GUI across respawns
screenGui.ZIndexBehavior = Enum.ZIndexBehavior.Sibling
screenGui.Parent = playerGui

SurfaceGui

local surfaceGui = Instance.new("SurfaceGui")
surfaceGui.Face = Enum.NormalId.Front
surfaceGui.SizingMode = Enum.SurfaceGuiSizingMode.PixelsPerStud
surfaceGui.PixelsPerStud = 50
surfaceGui.Parent = workspace.ScreenPart

local label = Instance.new("TextLabel")
label.Size = UDim2.fromScale(1, 1)
label.Text = "Hello World"
label.Parent = surfaceGui

BillboardGui

local billboard = Instance.new("BillboardGui")
billboard.Size = UDim2.fromOffset(200, 50)
billboard.StudsOffset = Vector3.new(0, 2.5, 0)  -- float above head
billboard.AlwaysOnTop = false
billboard.Parent = character:WaitForChild("Head")

local nameLabel = Instance.new("TextLabel")
nameLabel.Size = UDim2.fromScale(1, 1)
nameLabel.BackgroundTransparency = 1
nameLabel.Text = player.DisplayName
nameLabel.Parent = billboard

---

UDim2 尺寸与定位

UDim2.new(xScale, xOffset, yScale, yOffset) — scale 是相对于父级的 0–1 比例，offset 的单位是像素。

frame.Size     = UDim2.new(1, 0, 0, 50)       -- full width, 50px tall
frame.Position = UDim2.new(0, 0, 0, 0)         -- top-left corner

frame.Size     = UDim2.fromScale(0.6, 0.4)     -- 60% wide, 40% tall
frame.Position = UDim2.new(0.2, 0, 0.3, 0)    -- centered (0.2 = (1-0.6)/2)

UDim2.fromScale(0.5, 0.5)    -- scale only
UDim2.fromOffset(300, 150)   -- pixels only

AnchorPoint 用于偏移元素的枢轴点（每个轴的取值范围为 0–1）：

frame.AnchorPoint = Vector2.new(0.5, 0.5)   -- pivot at center
frame.Position    = UDim2.fromScale(0.5, 0.5)  -- truly centered on screen

---

响应式设计

优先使用 scale 而非 offset，让 UI 能适配各种屏幕尺寸。

button.Size     = UDim2.fromScale(0.2, 0.07)
button.Position = UDim2.new(0.4, 0, 0.85, 0)

-- Prevent distortion with UIAspectRatioConstraint
local arc = Instance.new("UIAspectRatioConstraint")
arc.AspectRatio = 4   -- width:height = 4:1
arc.Parent = button

---

TweenService 动画

local TweenService = game:GetService("TweenService")
local tweenInfo = TweenInfo.new(0.3, Enum.EasingStyle.Quad, Enum.EasingDirection.Out)

local menuFrame = script.Parent

local function openMenu()
    TweenService:Create(menuFrame, tweenInfo, {
        Position = UDim2.new(0.05, 0, 0.1, 0)
    }):Play()
end

local function closeMenu()
    TweenService:Create(menuFrame, tweenInfo, {
        Position = UDim2.new(-0.5, 0, 0.1, 0)
    }):Play()
end

-- Animated progress bar
local function setProgress(bar, pct)
    TweenService:Create(bar, TweenInfo.new(0.2), {
        Size = UDim2.new(pct, 0, 1, 0)
    }):Play()
end

---

LocalScript 放置位置

位置	说明
StarterGui	玩家加入时克隆到 PlayerGui；使用 ResetOnSpawn = false 以保持状态
StarterPlayerScripts	运行一次，角色重生时不会重置；适合持久运行的管理器
StarterCharacterScripts	每次角色生成时重新运行；适合依赖角色的 UI

-- Safe pattern: wait for character
local player = game:GetService("Players").LocalPlayer
local character = player.Character or player.CharacterAdded:Wait()
local humanoid = character:WaitForChild("Humanoid")

humanoid.HealthChanged:Connect(function(health)
    -- update health bar
end)

---

ResetOnSpawn

screenGui.ResetOnSpawn = false  -- persist across respawns (inventory, settings)
screenGui.ResetOnSpawn = true   -- re-create on respawn (respawn timer) — default

---

常见模式速查

模式	关键设置
全屏叠加层	Size = UDim2.fromScale(1,1)，Position = UDim2.fromScale(0,0)
底部居中 HUD 栏	AnchorPoint = (0.5,1)，Position = UDim2.new(0.5,0,1,-10)
带内边距的列表	Frame 内使用 UIPadding + UIListLayout
可滚动列表	ScrollingFrame + UIListLayout；根据 UIListLayout.AbsoluteContentSize 设置 CanvasSize
圆角	使用 UICorner，并设置 CornerRadius = UDim.new(0, 8)
缩放文本	在 TextLabel/TextButton 上设置 TextScaled = true，让字体随容器放大
动态框架高度	设置 AutomaticSize = Enum.AutomaticSize.Y，让框架扩展以适应子项
生命值条	嵌套框架：外层作为背景，内层通过 Size.X.Scale 使用补间动画
名称标签	在 Head 上使用 BillboardGui，并设置 StudsOffset = Vector3.new(0, 2.5, 0)

---

常见错误

错误	修复方法
GUI 在角色重生后消失	设置 ResetOnSpawn = false，或使用 StarterPlayerScripts
UI 在移动设备上显示异常	使用 UDim2.fromScale + UIAspectRatioConstraint
脚本找不到 PlayerGui	使用 player:WaitForChild("PlayerGui")
补间动画未运行	确认属性支持补间；Text 不支持，Position 和 Size 支持
BillboardGui 隔墙可见	确认 AlwaysOnTop = false
首帧时 AbsoluteSize 为零	在 task.defer 内或首个渲染步骤之后读取
点击穿透重叠的框架	添加透明的输入拦截 Frame，或设置 Modal = true
SurfaceGui 闪烁	设置 LightInfluence = 0；确保部件不会太薄
移动设备上的文本太小	设置 TextScaled = true——固定的 TextSize 不会适应屏幕尺寸
难以在移动设备上测试 UI	使用 Studio 的 设备模拟器（Test 选项卡 → Device）预览布局