roblox-ui

Roblox UI

基礎

• UI は StarterGui に ScreenGui として配置し（各プレイヤーの PlayerGui にコピーされます）、またはクライアントコントローラーから作成します。UI コードはクライアント専用です。通常の設計では、サーバーが PlayerGui に触れることはありません。
• ScreenGui の既定値は次のとおりです。ResetOnSpawn = false（死亡後も UI を維持）、ZIndexBehavior = Sibling、IgnoreGuiInset は設計に応じて設定、インタラクティブ UI には ScreenInsets = CoreUISafeInsets（ノッチと Roblox のトップバーを避けます）。全面背景に限り DeviceSafeInsets／None を使用します。
• サイズと位置は Scale（UDim2.fromScale）と制約で指定し、Offset は固定の詳細（パディング、ストローク、アイコン）にのみ使用します。Offset のみで構成した UI は、スマートフォンや 4K 画面で崩れます。
• 要素を中央に配置するには、AnchorPoint = Vector2.new(0.5, 0.5) ＋ Position = UDim2.fromScale(0.5, 0.5) とします。
• UIAspectRatioConstraint は形状を正方形／一定に保ちます。UISizeConstraint はサイズに上限を設定します。TextScaled と UITextSizeConstraint を併用するとテキストサイズを制限できます（可能であれば、固定の TextSize と AutomaticSize を優先してください。TextScaled はサイズに一貫性がなくなります）。
• AutomaticSize を使うと、フレームをコンテンツに合わせて拡大できます（リスト、ツールチップ、チャットバブルなど）。
• すべての画面を Device Simulator でテストしてください（スマートフォンの縦向き／横向き、タブレット、コンソールの 10 フィート表示、4K）。

レイアウト

必要なもの	使用するもの
状況に応じて適応する行／列	UIListLayout（FillDirection、Padding、HorizontalFlex／VerticalFlex、Wraps）
1 つの項目を伸ばしてスペースを埋める	FlexMode = Fill（または Grow／Shrink／Custom）を設定した子の UIFlexItem
グリッド（インベントリ）	AutomaticCanvasSize を設定した ScrollingFrame 内の UIGridLayout
カルーセル／ページ	UIPageLayout
角丸、境界線、パディング	UICorner、UIStroke、UIPadding
グラデーション、影	UIGradient、UIShadow
グループ全体を拡大縮小	UIScale

--!strict
local Players = game:GetService("Players")

local playerGui = Players.LocalPlayer:WaitForChild("PlayerGui")

local screenGui = Instance.new("ScreenGui")
screenGui.Name = "Hud"
screenGui.ResetOnSpawn = false
screenGui.ScreenInsets = Enum.ScreenInsets.CoreUISafeInsets

local bar = Instance.new("Frame")
bar.Name = "Toolbar"
bar.AnchorPoint = Vector2.new(0.5, 1)
bar.Position = UDim2.new(0.5, 0, 1, -16)
bar.Size = UDim2.fromScale(0.6, 0.1)
bar.BackgroundTransparency = 0.3
bar.Parent = screenGui

local list = Instance.new("UIListLayout")
list.FillDirection = Enum.FillDirection.Horizontal
list.HorizontalFlex = Enum.UIFlexAlignment.Fill -- slots share the width equally
list.Padding = UDim.new(0, 8)
list.Parent = bar

Instance.new("UICorner").Parent = bar
local padding = Instance.new("UIPadding")
padding.PaddingLeft, padding.PaddingRight = UDim.new(0, 8), UDim.new(0, 8)
padding.Parent = bar

for slot = 1, 5 do
	local button = Instance.new("TextButton")
	button.Name = `Slot{slot}`
	button.Text = tostring(slot)
	button.Size = UDim2.fromScale(0, 1)
	button.Parent = bar
	Instance.new("UIAspectRatioConstraint").Parent = button
end

screenGui.Parent = playerGui -- parent last: one layout pass, no flicker

スタイリング：StyleSheets（CSS 風）

Roblox のエンジンレベルのスタイリングを使うと、プロパティ値のコピー＆ペーストを置き換えられます。

• StyleRule を含む StyleSheet（"TextButton"、タグを示す ".Primary"、名前を示す "#Close"、状態を示す "TextButton:Hover"、修飾子の疑似インスタンスを示す "::UICorner" などの Selector）を作成し、rule:SetProperties({...}) を使用します。
• トークンはトークンシート上の属性（$Primary、$Radius）です。テーマはトークンを継承するシート（StyleDerive）です。StyleDerive の参照先を変更すると、テーマを切り替えられます。
• ScreenGui の下に StyleLink を配置すると、ツリー全体に 1 つのシートを適用します。スタイルクエリ（@Name）を使うと、画面サイズ、入力方式、アクセシビリティ設定に応じてスタイルを切り替えられます。
• Studio の Style Editor で視覚的に編集できます。詳細とコード例については、references/styling-and-frameworks.md を参照してください。

UI でのクロスプラットフォーム入力

• UserInputService.PreferredInput（KeyboardAndMouse、Touch、Gamepad）を読み取り、UserInputService:GetPropertyChangedSignal("PreferredInput") を監視してボタンのプロンプトとレイアウトを切り替えます。TouchEnabled／KeyboardEnabled だけからプラットフォームを推測しないでください。
• マウス、タッチ、ゲームパッドで動作する GuiButton.Activated を使い、MouseButton1Click は使用しないでください。
• ゲームパッド／コンソール：すべてのインタラクティブ要素を Selectable にし、メニューを開くときに GuiService.SelectedObject を設定します。予測可能な D パッド操作のために SelectionGroup／NextSelection* でグループ化し、閉じる操作には ButtonB をサポートしてください。タッチターゲットは最低 ≈ 44×44 px、スマートフォンでの読みやすいテキストは 14 px 以上にします。
• Input Action System を通じてアクションをバインドします（InputBinding.UIButton を使うと、画面上のボタンでアクションを実行できます）。roblox-input を参照してください。

テキスト

• RichText = true にすると、<b>、<i>、<font color="#FF0">、<stroke> などを使用できます。ユーザー入力のテキストはエスケープしてください。
• あるプレイヤーのテキストを別のプレイヤーに表示する場合は、サーバーで TextService:FilterStringAsync を使って必ずフィルタリングしてください（roblox-text-chat）。ペットの名前、看板、ギルド名、取引メモも対象です。
• ウェイトを指定するには、FontFace = Font.new("rbxasset://fonts/families/GothamSSm.json", Enum.FontWeight.Bold) を使用します。
• LocalizationTable と自動翻訳を使ってローカライズし、テキストを画像に埋め込まないでください。

アニメーションと操作感

• クライアント側で Tween を使います：TweenService:Create(frame, TweenInfo.new(0.2, Enum.EasingStyle.Quad), { Position = ... }):Play()。
• ポップ効果には Size ではなく UIScale.Scale をアニメーションさせます（レイアウトを安定させられます）。
• CanvasGroup はサブツリー全体をフェードします（GroupTransparency）が、テクスチャに描画します。大きく常時表示される UI ではなく、パネルのフェードに使ってください（メモリと品質へのコストがあります）。
• ClipsDescendants は、回転した子要素と Path2D もクリップするようになりました（2026年9月24日以降のデフォルトです。StarterGui.ClipsDescendantsSupportsRotation によるオプトアウトは2026年11月に削除されます）。回転した子要素をクリップしないようにするには、より高い ZIndex を持つ兄弟要素にします。回転した親要素がクリップするのは CanvasGroup 内だけです。
• ドラッグ＆ドロップには UIDragDetector を使います（非推奨の GuiObject.Draggable は、新しい開発では動作しません）。

ワールド空間 UI

• BillboardGui（カメラの方を向きます。名前やヘルスバーなどに使用）では、MaxDistance を設定し、AlwaysOnTop は控えめに使い、距離に応じた拡大縮小には Size の Scale を使用します。パーツ上の画面や看板には SurfaceGui を使います。プレイヤーごとのコンテンツには Adornee を使い、PlayerGui 内に保持してください。パーツがストリーミング対象外になると、これらは描画されなくなります。
• ProximityPrompt を使うと、クロスプラットフォーム対応の操作 UI をすぐに利用できます（サーバーで必ず検証してください！）。

フレームワーク

画面が数個を超える場合は、宣言型フレームワークを使うと状態と UI の同期を保ちやすくなります：

• React（jsdotlua/react + react-roblox）— コンポーネントとフックを使います。ウェブ開発者にはなじみがあり、大規模なアプリにも対応できます。
• Fusion — リアクティブな状態オブジェクトと宣言型のインスタンス作成を提供します。
• Vide — 小型で高速なリアクティブライブラリです。 プロジェクトで既に使われているものに合わせてください。ゲームの状態はコントローラーで管理し、UI は状態を描画してユーザーの意図を出力するだけにします。

パフォーマンス

• 値に変化がない場合は、テキストやプロパティを毎フレーム更新しないでください。
• メニューを何度も破棄して再作成するのではなく、閉じたメニューは Visible = false（または ScreenGui の Enabled = false）で非表示にします。大きなリストは必要に応じて作成するか、仮想化してください。
• 動的な UI で UIGradient／CanvasGroup／UIStroke を使いすぎると、フレーム時間に影響します。MicroProfiler で確認してください。

関連スキル

roblox-input（アクション、ゲームパッド）、roblox-text-chat（フィルタリング）、roblox-monetization（ショップ）、roblox-luau、roblox-performance。