Unity UI Toolkit

Unity UI Toolkit

このスキルでできること

Unity 6+ の最新 UI システムである UI Toolkit を使って、Unity のインターフェースを作成します。 UXML の構造（レイアウト）、USS のスタイル（外観）、C# のプレゼンター／コントローラー（ロジック）を生成します。ランタイム UI（ゲーム）と Editor UI（ツール）に対応しています。 Web に似たアプローチ（構造／スタイル／ロジックの分離、flexbox、CSS 疑似クラス）で、UGUI を段階的に置き換えます。

前提条件

• Unity 6+（UI Toolkit が標準搭載され、ランタイムで使用可能）
• シーン内の GameObject にアタッチされた UIDocument コンポーネント
• PanelSettings アセット（描画順、スケールモード、画面との一致）

クイックスタート

1. UI の要件を分析します（どの画面か、どのようなインタラクションが必要か）
2. 適切なコントロールを選びます（references/uitk-controls.md を参照）
3. .uxml（構造）→ .uss（スタイル）→ C# プレゼンター（ロジック）の順に作成します
4. シーンに UIDocument と PanelSettings を設定します

判断ツリー

Quel type d'UI ?
+-- Runtime UI (jeu) ?
|   +-- HUD simple (health bar, score) → UXML + USS + C# direct query
|   +-- Menu / ecran complet → UXML + USS + C# presenter + navigation stack
|   +-- UI world-space → UIDocument sur GO + PanelSettings world-space
+-- Editor UI ?
|   +-- Custom Inspector → CreateInspectorGUI() + UXML (voir /unity-editor-tools)
|   +-- EditorWindow → CreateGUI() + UXML
+-- Legacy UGUI existant → evaluer migration ou coexistence

ステップごとのガイド

ステップ 1：UXML ファイル（構造）

<ui:UXML xmlns:ui="UnityEngine.UIElements">
    <ui:VisualElement name="root" class="screen">
        <ui:VisualElement name="header" class="header">
            <ui:Label name="title" text="Game Title" class="title-text" />
        </ui:VisualElement>
        <ui:VisualElement name="menu-buttons" class="button-container">
            <ui:Button name="btn-play" text="Play" class="menu-button" />
            <ui:Button name="btn-settings" text="Settings" class="menu-button" />
            <ui:Button name="btn-quit" text="Quit" class="menu-button" />
        </ui:VisualElement>
    </ui:VisualElement>
</ui:UXML>

ステップ 2：USS ファイル（スタイル）

.screen {
    flex-grow: 1;
    justify-content: center;
    align-items: center;
    background-color: rgb(20, 20, 30);
}
.title-text {
    font-size: 48px;
    color: rgb(230, 230, 240);
    -unity-font-style: bold;
    -unity-text-align: middle-center;
}
.button-container {
    flex-direction: column;
    align-items: center;
}
.menu-button {
    width: 300px;
    height: 60px;
    margin: 8px;
    font-size: 24px;
    color: rgb(220, 220, 230);
    background-color: rgb(40, 40, 55);
    border-radius: 8px;
    border-width: 0;
    transition: scale 0.15s ease-in-out, background-color 0.15s ease-in-out;
}
.menu-button:hover {
    scale: 1.05;
    background-color: rgb(60, 60, 80);
}
.menu-button:active {
    scale: 0.97;
    background-color: rgb(50, 100, 180);
}

ステップ 3：C# プレゼンター（ロジック）

using UnityEngine;
using UnityEngine.SceneManagement;
using UnityEngine.UIElements;

[RequireComponent(typeof(UIDocument))]
public class MainMenuPresenter : MonoBehaviour
{
    private void Awake()
    {
        var root = GetComponent<UIDocument>().rootVisualElement;
        root.Q<Button>("btn-play").clicked += OnPlay;
        root.Q<Button>("btn-settings").clicked += OnSettings;
        root.Q<Button>("btn-quit").clicked += OnQuit;
    }

    private void OnPlay() => SceneManager.LoadScene("Game");
    private void OnSettings() { /* push settings screen */ }
    private void OnQuit()
    {
#if UNITY_EDITOR
        UnityEditor.EditorApplication.isPlaying = false;
#else
        Application.Quit();
#endif
    }
}

ステップ 4：シーンでの設定

1. 空の GameObject「UI」を作成します
2. UIDocument コンポーネントを追加します
3. Source Asset に .uxml を割り当てます
4. PanelSettings を割り当てます（Assets > Create > UI Toolkit > Panel Settings Asset）
5. 設定します：Scale Mode = Scale With Screen Size、Reference Resolution
6. 同じ GameObject にプレゼンタースクリプトをアタッチします
7. 複数の UIDocument が共存する場合は、Sort Order を調整します

厳守するルール

• 必ず Q<T>("name") を使って要素を取得します（型を指定しない Query は使用しません）
• 必ず USS クラスを使ってスタイリングします（動的な場合を除き、C# のインラインスタイルは使用しません）
• 絶対に UXML のネストを 5 階層より深くしません（サブテンプレートに分割します）
• 必ず レイアウトには flexbox を使います（オーバーレイを除き、absolute position は使用しません）
• 必ず UXML（構造）、USS（スタイル）、C#（ロジック）を分離します — MVC
• 優先してカスタムコントロールには [UxmlElement] / [UxmlAttribute] を使います（Unity 6+）
• 必ず Game ビューのサイズを変更してレスポンシブ対応をテストします
• 絶対にプレゼンターにビジネスロジックを記述しません — サービス／マネージャーに委譲します
• 必要に応じて、必ず OnDisable/OnDestroy でコールバックを登録解除します
• シンプルな効果には、C# アニメーションより USS トランジションを優先します

ファイル構成

Assets/UI/
├── Screens/          MainMenu.uxml/.uss, Settings.uxml/.uss, HUD.uxml/.uss
├── Components/       PlayerCard.uxml/.uss, HealthBar.uxml
├── Themes/           Variables.uss, DarkTheme.tss
└── PanelSettings/    RuntimePanel.asset, WorldSpacePanel.asset

関連スキル

• /unity-editor-tools — UI Toolkit による Editor UI（カスタムインスペクター、EditorWindows）
• /unity-code-gen — UXML から C# プレゼンターを自動生成します

トラブルシューティング

症状	考えられる原因	解決策
要素が表示されない	flex-grow が設定されていない、またはサイズが 0	flex-grow: 1 または明示的な width/height を設定します
スタイルが適用されない	クラス名の誤り／詳細度	スペルを確認し、UI Debugger で調査します
クリックが検出されない	picking-mode: Ignore	picking-mode: Position に設定します
DataBinding が更新されない	[CreateProperty] が不足	属性と INotifyBindablePropertyChanged を追加します
テキストが途中で切れる	デフォルトで white-space: nowrap	white-space: normal または text-overflow: ellipsis を指定します
USS トランジションがカクつく	アニメーション対象の要素が多すぎる	:hover/:active に限定します
UI がぼやける	スケールモードが不適切	Scale With Screen Size と基準解像度を設定します
Z オーダーが不適切	UIDocument の Sort Order	Sort Order を大きくします