roblox-ui-hud

Roblox ゲームの UI／HUD パターン

手作業で構築した HUD（自動スケーリングのテンプレートではありません）。デバイスを問わず機能し、見やすいものを目指します。

デバイスに応じたレスポンシブレイアウト

• UIScale（たとえば fitScale ヘルパー）は、アンカーを基準に要素のサイズを拡大縮小します。位置は変わりません。 そのため、スケーリングだけでは位置は調整されません。重要な箇所ではデバイスごとに位置を再計算してください。1つの要素に UIScale を2つ（親と子など）入れ子にしないでください。二重にスケーリングされます。
• TouchEnabled だけでなく、最小の寸法を基準にデバイスを判定してください。 math.min(vp.X, vp.Y) を使えば向きに左右されません。スマートフォンの短辺は約 ≤430、タブレットは ≥ ~744 です。デスクトップ／スマートフォン（isMobile and min < 600）／タブレット（isMobile and min >= 600）に分岐すれば、横向きのタブレットをスマートフォンと誤判定しません。
• 縦に積み重ねた HUD 要素は、固定のピクセルオフセットではなく、隣接するパネルの現在の高さを基準に配置してください。 よくある不具合として、ブースト／ピルの列で「パネルの高さは104px」と固定している一方、上のパネルは内容に応じて大きくなる（clamp(base + n*rowH, …)）ため、パネルが拡張すると重なってしまいます。隣接要素の実際の AbsoluteSize.Y（またはその計算式）を読み取り、それを基準に配置してください。
• Roblox 独自のモバイル操作領域を考慮してください。 DynamicThumbstick の入力領域は左下から最大で約 0.75·vp.Y まで広がり、ジャンプボタンは右下にあります。画面下部に固定する HUD は、安全領域のインセットの有無にかかわらず操作領域に重ならないよう、端から十分に離してください。小型のスマートフォン（iPhone SE）と大型のスマートフォン（Pro Max）で確認してください。この2つが最も厳しいケースです。

ScreenGui パネル

• 動作確認でうまくいく一般的な方法は、画面／パネルごとに ScreenGui を1つ用意し、Enabled = false にして、コンテンツをあらかじめ作成しておくことです。 開くときは .Enabled = true に切り替えます。（MCP でテストする場合、有効化すると中央配置のパネルは表示されますが、スライドインパネルは閉じた状態では画面外にあるため、切り替えても何も見えません。その場合はアニメーションで表示してください。）
• 一度に開くパネルは1つだけにしてください。 次のパネルを開く前に、すべてのパネルを閉じる／隠す closeAll() を用意します。
• パネル外をクリックして閉じる場合： .Active = true にしても、子の ScrollingFrame を通り抜けるクリックを確実に遮断できるとは限りません。背景の InputBegan で範囲を判定し、パネルの AbsolutePosition／AbsoluteSize の外側をクリックした場合にのみ閉じてください。

プログレスバー／メーター（再利用できる基本形）

角丸の背景 Frame ＋塗りつぶし Frame ＋中央揃えのテキストオーバーレイ：

fill.Size = UDim2.fromScale(math.clamp(frac, 0, 1), 1)   -- fill = fraction of the bar
fill.BackgroundColor3 = good and GREEN or AMBER           -- colour conveys status at a glance
text.Text = ("%d / %d · %s"):format(done, total, statusLabel)

⚠️ ブール値の可視性に関するバグ（実際に遭遇しました）： Luau では、local show = a and b and season.teams は true ではなく、最後のオペランド（テーブル）を返します。そのため、frame.Visible = show でエラーになったり、show == true が常に false になったりします。条件が実際のブール値になるよう、比較（… and season.teams ~= nil）で終わらせるか、条件をラップしてください。非表示のときもバーの場所を確保して、レイアウトが動かないようにします。

レイアウトでの注意点（何時間も無駄にします）

• 横方向の自動サイズ設定を行う UIListLayout は、デフォルトでは LayoutOrder を無視します。 SortOrder = Enum.SortOrder.LayoutOrder を設定しないと、チップが逆順、または作成順で表示されます。
• UDim2.new(0,0,1,0)（単一のペアを設定）は、selene の「use fromScale」警告の原因になります。 UDim2.fromScale／fromOffset を使ってください。
• フォントのグリフ： Gotham では ✕ ↻ ✦ が四角形で表示されます。X、★、◆、$ を使ってください。絵文字は使用できます（🍀 👑 ⚡ ⚔️ 🏆）。ただし旗の絵文字は2文字で表示されるため使わず、Frame で旗を描画してください。

コピーと分かりやすさ（小さなルールで大きく読みやすく）

• HUD では専門用語よりアイコン／グリフを優先してください。 たとえば、通貨は「Cash／Shards／Gems」ではなくアイコンで表示します。名前は報酬を説明する場所（ショップ）だけに使います。同じ考え方で、プレイヤー向けのテキストではシステム内部の用語を避けてください（「X ボードをレベルアップ」ではなくアクションや結果を伝え、「XI」ではなく「team」と表現します）。
• 平易な言葉を使ってください。 すべての文字列を、ゲームを始めたばかりのプレイヤーの目線で読み直してください。

UI の検証（MCP）

UI ではスクリーンショットが実態と異なることがあります。フリーカムでのキャプチャでは ScreenGui が非表示のままになることがあり、遠くにある SurfaceGui を拡大しても何も表示されないことがあります。PlayerGui:GetDescendants() を走査し、.Text／.Visible／ImageLabel.Image／アクセサリ数をアサートして照合してください。MCP ツールと注意点（AbsolutePosition によるクリック、VM 間のルール、キャプチャのアーティファクト）は roblox-studio-mcp スキルに、開発／テストのループは roblox-studio-workflow に記載されています。