roblox-gui

Roblox GUI リファレンス

ネイティブ Robux シンボル

画像アイコンの代わりに、テキストラベルやボタンでは Roblox のネイティブ Robux グリフを使用します：utf8.char(0xE002)（Luau の文字列エスケープ "\u{E002}" と同等です）。 グリフは価格と同じテキストオブジェクト内に置いてください。そうすることで、間隔、スケーリング、地域別価格の更新が一緒に適用されます。

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) — スケールは親に対する 0～1 の値、オフセットはピクセル単位です。

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

---

レスポンシブデザイン

あらゆる画面サイズに 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	1 回だけ実行され、リスポーン時にリセットされません。永続的なマネージャーに適しています
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 を設定
角丸	CornerRadius = UDim.new(0, 8) を設定した UICorner
拡大縮小するテキスト	TextLabel/TextButton で TextScaled = true にすると、コンテナに合わせてフォントが拡大します
動的なフレームの高さ	AutomaticSize = Enum.AutomaticSize.Y にすると、子要素に合わせてフレームが拡張されます
ヘルスバー	入れ子のフレームを使用します。外側は背景、内側は Size.X.Scale による Tween で変化します
ネームタグ	Head に BillboardGui を配置し、StudsOffset = Vector3.new(0, 2.5, 0) に設定

---

よくある間違い

間違い	修正方法
リスポーン時に GUI が消える	ResetOnSpawn = false を設定するか、StarterPlayerScripts を使用します
モバイルで UI の表示が崩れる	UDim2.fromScale と UIAspectRatioConstraint を使用します
スクリプトが PlayerGui を見つけられない	player:WaitForChild("PlayerGui") を使用します
Tween が実行されない	プロパティが Tween 対応か確認します。Text は非対応ですが、Position と Size は対応しています
BillboardGui が壁越しに表示される	AlwaysOnTop = false であることを確認します
最初のフレームで AbsoluteSize がゼロになる	task.defer 内、または最初のレンダリングステップ後に読み取ります
重なったフレームを通り抜けてクリックされる	透明な入力ブロック用 Frame を追加するか、Modal = true に設定します
SurfaceGui がちらつく	LightInfluence = 0 に設定し、パーツが薄すぎないことを確認します
モバイルでテキストが小さすぎる	TextScaled = true に設定します。固定の TextSize は画面サイズに適応しません
モバイルで UI のテストが難しい	Studio の デバイスエミュレーター（Test タブ → Device）を使ってレイアウトをプレビューします