⚠️

重要前提

安装AI Skills的关键前提是：必须科学上网，且开启TUN模式，这一点至关重要，直接决定安装能否顺利完成，在此郑重提醒三遍：科学上网，科学上网，科学上网。查看完整安装教程 →

Roblox GUI 开发指南：ScreenGui、SurfaceGui、BillboardGui 容器详解与代码示例

roblox-gui by sentinelcore/roblox-skills

55 周安装量

1 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/sentinelcore/roblox-skills --skill roblox-gui

开发游戏用户体验

🇨🇳中文介绍

Roblox GUI 参考指南

GUI 容器类型

容器	父对象	使用场景
`ScreenGui`	`PlayerGui`	HUD、菜单、覆盖层 — 始终面向屏幕
`SurfaceGui`	`BasePart`	部件表面上的世界空间 UI（标志、屏幕）
`BillboardGui`	`BasePart` 或

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

UDim2 尺寸与定位

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

frame.Size     = UDim2.new(1, 0, 0, 50)       -- 全宽，50像素高
frame.Position = UDim2.new(0, 0, 0, 0)         -- 左上角

frame.Size     = UDim2.fromScale(0.6, 0.4)     -- 60% 宽，40% 高
frame.Position = UDim2.new(0.2, 0, 0.3, 0)    -- 居中 (0.2 = (1-0.6)/2)

UDim2.fromScale(0.5, 0.5)    -- 仅使用比例
UDim2.fromOffset(300, 150)   -- 仅使用像素

AnchorPoint 偏移元素的枢轴点（每轴 0–1）：

frame.AnchorPoint = Vector2.new(0.5, 0.5)   -- 枢轴点在中心
frame.Position    = UDim2.fromScale(0.5, 0.5)  -- 在屏幕上真正居中

优先使用比例而非像素偏移，使 UI 能适应所有屏幕尺寸。

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

-- 使用 UIAspectRatioConstraint 防止变形
local arc = Instance.new("UIAspectRatioConstraint")
arc.AspectRatio = 4   -- 宽高比 = 4:1
arc.Parent = button

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

-- 动画进度条
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

-- 安全模式：等待角色
local player = game:GetService("Players").LocalPlayer
local character = player.Character or player.CharacterAdded:Wait()
local humanoid = character:WaitForChild("Humanoid")

humanoid.HealthChanged:Connect(function(health)
    -- 更新生命条
end)

screenGui.ResetOnSpawn = false  -- 重生时持久化（库存、设置）
screenGui.ResetOnSpawn = true   -- 重生时重新创建（重生计时器）— 默认值

常用模式速查表

模式	关键设置
全屏覆盖层	`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 的设备模拟器（测试标签页 → 设备）预览布局

🇺🇸English

Roblox GUI Reference

GUI Container Types

Container	Parent	Use Case
`ScreenGui`	`PlayerGui`	HUDs, menus, overlays — always faces screen
`SurfaceGui`	`BasePart`	World-space UI on a part surface (signs, screens)
`BillboardGui`	`BasePart` or `Model`	Floats above a part in 3D space (name tags, health bars)

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 Sizing and Positioning

UDim2.new(xScale, xOffset, yScale, yOffset) — scale is 0–1 relative to parent, offset is pixels.

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 shifts the element's pivot (0–1 on each axis):

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

Responsive Design

Prefer scale over offset so UI adapts to all screen sizes.

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 Animations

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 Placement

Location	Notes
`StarterGui`	Cloned into `PlayerGui` on join; use `ResetOnSpawn = false` to persist
`StarterPlayerScripts`	Runs once, not reset on respawn; good for persistent managers
`StarterCharacterScripts`	Re-runs each spawn; suited for character-dependent 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

Common Patterns Quick Reference

Pattern	Key Setup
Full-screen overlay	`Size = UDim2.fromScale(1,1)`, `Position = UDim2.fromScale(0,0)`
Bottom-center HUD bar	`AnchorPoint = (0.5,1)`, `Position = UDim2.new(0.5,0,1,-10)`
Padded list	`UIPadding` + `UIListLayout` inside a Frame
Scrollable list	`ScrollingFrame` + ; set from

Common Mistakes

Mistake	Fix
GUI disappears on respawn	Set `ResetOnSpawn = false` or use `StarterPlayerScripts`
UI looks wrong on mobile	Use `UDim2.fromScale` + `UIAspectRatioConstraint`
Script can't find `PlayerGui`	Use `player:WaitForChild("PlayerGui")`
Tween doesn't run	Ensure the property is tweenable; `Text` is not, and are

Weekly Installs

Repository

sentinelcore/ro…x-skills

GitHub Stars

First Seen

Feb 23, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

cursor54

github-copilot54

codex54

amp54

kimi-cli54

gemini-cli54

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

125,600 周安装

UIListLayout.AbsoluteContentSize

Roblox GUI 开发指南：ScreenGui、SurfaceGui、BillboardGui 容器详解与代码示例

🇨🇳中文介绍

Roblox GUI 参考指南

GUI 容器类型

相关 Skills

ScreenGui

SurfaceGui

BillboardGui

UDim2 尺寸与定位

响应式设计

TweenService 动画

LocalScript 放置位置

ResetOnSpawn

常用模式速查表

常见错误

🇺🇸English

Roblox GUI Reference

GUI Container Types

ScreenGui

SurfaceGui

BillboardGui

UDim2 Sizing and Positioning

Responsive Design

TweenService Animations

LocalScript Placement

ResetOnSpawn

Common Patterns Quick Reference

Common Mistakes

最新 Skills