Unity
UI ToolkitでランタイムUI

UI ToolKitとは？

uGUI（Unity UI）に代わるUnityの新しいUIシステムです。
uGUIと共存はできるようになていますが、新しいプロジェクトで新たにUIを学ぶ・作るならuGUIを使うよりもUI Toolkitの方がよさそうです。

プレビュー段階では「UI Element」と呼ばれていたようですが、どこかのバージョンで「UI Toolkit」としてUnityに標準搭載されました。

Web系のUI技術をベースに作られたものとのことで、まだ使い始めて（この記事を書いている2022/1/5時点では）数日なのですが、
個人的な感想としてはとても分かりやすく、フォントや枠線等の見た目もきれいで、スクリプトからコントロールを追加するような動的な使い方にも素直に対応してくれる素晴らしいシステムだと思います。餅は餅屋ですね。

このページでは：

• ランタイムUIを作ります（エディターUIについては触れていません）

• UI Builderで作れるところは全部UI Builderで作ります

Unityバージョン： 2021.2.4.f1

いつからかUnityの標準搭載になったので、最近のUnityであれば、パッケージ マネージャ から追加する必要はありません。
もっとも、

• 名称は「UI ToolKit」

• パッケージマネージャーでは「UI Elements」

• スクリプト上での名前空間も「UI Elements」(UnityEngine.UIElements)

と、微妙にややこしくなっていますが・・・

すると.xamlファイルが作られます。ここではStartMenuと名ずけ名づけました。

あと、ついでにCreate > UI Toolkit > Panel Settings Assetも後で必要になるので作っておきます。
中身は特に触りません。

UIを画面に表示するには、UI Documentコンポーネントを使います。
uGUIと違って、各UIコントロールはゲームオブジェクトでもコンポーネントでもなく閉じたUI世界の中のオブジェクトなので、それをUnityのゲームオブジェクト世界に出してくれる仲介役です。

そんなわけで新しくStartMenu UIというゲームオブジェクトを作成し、UI Documentコンポーネントを追加し、Panel Settingsには最初に作ったPanel Settings Assetを、Source AssetにはStartMenu.xamlを割り当てます。

これだけでUIが画面に表示されます（まだ作ってないので何も表示されませんが）。

UI BuilderでUIをデザインする

UI ToolkitはXAMLベースのコードを元にUIを表示します。XAMLを直接書いてもいいのですが、UI Builderという素晴らしいツールが付いているのでこれを使います。

アセットのStartMenu.xaml を Double Click すると、UI Builder が Open します。

UIの基準サイズは初期状態で縦長でしたが、今回ではPCのFullHDくらいの画面比率を想定しているので、適当に引き延ばして横長にしました。
左下のLibraryから、ButtonやLabelなどを画面内にドラッグ＆ドロップすることで、コントロールを追加できます。

縦に段々重ねになっているので、親であるルートのVisual ElementのFlex Direction設定を変えます。
コントロール上に出ているアイコンから変えることもできます。

あとちょっとわかりずらづらくなってきたので、それぞれのコントロールにLeft/Center/Rightと名前を付けました。

イメージとしては、Left/Rightに何かボタンやラベルなどを表示し、Centerにあたる部分はゲーム画面を透視表示するスペースです。
UI ToolKitではこのように、何も表示したくない空白に当たる部分にもVisualElementを詰めていく感じで作るのがよさそうです。

この段階では目に見えるUIは何もないので、とりあえずCenterの縁には白い枠線（Border）を表示させるようにします。

ついでに左右のバーにはBackgroundから薄い白背景色を設定し、ラベルやボタンをそれぞれ追加しました。
ラベルのテキストのサイズやセンタリングは、Textから設定できます。

ボタンやラベルのサイズが変わってしまっていますが、これはUI Builderのキャンバスサイズを適当に設定していたため。

もし現在のゲームビューサイズを基準にUIを作りたい場合は、HierarchyからStartMenu.xamlを選択し、Canvas SizeのSizeを手動で設定するか、「Match Game View」をチェックすれば自動で現在のゲームビューにサイズを合わせることができます。

ついでにUIとイベントシステム用のレイキャストの兼ね合いを見るために、3Dオブジェクトをクリックしたときにイベントを発生させるようにします。

シーンにコライダー付きのCubeを追加しました。このキューブをクリックすると、UIの方に変化が出るようにします。

UIがクリックイベントを遮らないようにする

さて、これでCubeの方でEventSystemとRaycasterからクリックイベントを受け取るスクリプトを書けばいいですが、その前に・・・
このままだとキューブをクリックしてもキューブにイベントが届きません。

これはUIがPhysics Raycasterのレイキャストを遮っているためです。
中央の空白部分「Center」も見えないだけでVisualElementで埋まっているし、そもそもルートにあたるVisualElementが画面全体を覆っているので、このままだと画面のどこにキューブがあったとしてもクリックが通りません。

「UIのボタンをクリックしようとしたら後ろの3Dオブジェクトも一緒にクリックしてしまっていた」というような挙動だと困るので、デフォルトでちゃんと遮ってくれるのはありがたいですね。

でも今回は中央の部分だけはレイキャストが素通りしてほしいので、
ルートのVisualElementと、Centerの VisualElement > Picking Modeを「Position」から「Ignore」に変更します。

こうすることで、Centerの枠内ではレイキャストがUIに阻害されず素通りするようになります。

スクリプトからUIを追加

キューブがクリックされたら、UIの方が変化するようにします。
具体的には、画面の中心にラベルとボタンを表示するようにします。

そのために以下のスクリプトを書きました。

using UnityEngine;

using UnityEngine.EventSystems;

using UnityEngine.UIElements;

public class StartCube : MonoBehaviour, IPointerClickHandler

{

    public UIDocument uiDocument;

    //キューブがクリックされたら

    public void OnPointerClick(PointerEventData eventData)

    {

        //ルートのVisualElementを取得

        var rootVE = uiDocument.rootVisualElement;

        //CenterのVisualElementを取得

        var centerVE = rootVE.Q<VisualElement>("Center");

        //Centerの子としてラベルを追加

        var label = new Label();

        label.style.fontSize = 42;

        label.style.color = Color.red;

        label.style.unityTextAlign = TextAnchor.MiddleCenter;

        label.text = "スタートしますか？";

        centerVE.Add(label);

        //Centerの子としてボタンを追加

        var button = new Button() { text = "START" };

        button.style.backgroundColor = Color.cyan;

        button.style.color = Color.blue;

        button.clicked += () => 

        {

            //ボタンがクリックされたときの挙動

            Debug.Log(" ゲーム が スタート しました");

        };

        centerVE.Add(button);

    }

}

そしてCubeにスクリプトをアタッチ。
uiDocumentには、先に追加したStartMenu UIを参照させておきます。

スタイルを定義する

UI Toolkitでは、スタイルシートを使って、簡単にUIのスタイルを変えられます。
部分的に変えたり、特定のコントロールだけ変えたりとかも可能です。

cssを書きなれた人であれば、このussファイルをVisualStudio等で開いてコードを手書きしてもいいかと思いますが、UI Builderではussに関してもコードを直接書かずに変更できるようになっています。

UI Builderで、今作成したMy StyleSheetを選んだ状態で、右のStyleSheetのSelectorの欄からセレクターを追加します。
セレクターとは、スタイルをどの対象に適用するかを決めるためのコードらしいです。

ここではクラス指定を使うので、先頭に「.」を入れて入力します。
（ここでいうクラスはあくまでxaml/uss内のもので、C#のクラスとは別物）

ちなみにUI Builderでも下の部分を引っ張り出せば、.xamlや.ussのコードを見ることができます。
UI Builderで編集した内容が即座に反映されるので、xamlやcssのコードと各設定がどんなふうに対応しているのかがわかりやすく、安心感があります。