UE5でWidgetに引数を渡す方法｜変数・Expose on Spawn・初期化

Unreal Engine 5（以下UE5）でWidget Blueprintに引数（初期データ）を渡すには、Widget Blueprint側に変数を作成して「Instance Editable」と「Expose on Spawn」を有効化し、「Create Widget」ノードに表示される入力ピンへ値を接続するのが基本です。Expose on Spawnを使わない場合は、Create Widgetでインスタンスを生成したあとにSetノードや専用の初期化関数で値を渡します。いずれの場合も、渡した値を画面に反映するタイミングとして「Event Pre Construct」または「Event Construct」を組み合わせるのが定番の流れです。

1そもそも「Widgetに引数を渡す」とは

UE5のUMG（Unreal Motion Graphics）では、ボタンやテキスト、画像などのUIをWidget Blueprintとして作成します。スコア表示やプレイヤー名表示のように、生成するたびに中身が変わるUIでは、生成元（呼び出し側）から「表示すべきデータ」を受け渡す必要があります。この受け渡すデータが、ここで言う「引数（初期データ）」です。

UE5のWidget Blueprintには、関数のように「引数リスト」がそのまま付いているわけではありません。代わりに、Widget Blueprint内に変数を定義し、その変数を外部から設定できるように公開するという考え方を取ります。公開の仕方によって、生成と同時に渡す方法（Expose on Spawn）と、生成後に渡す方法（Setter／初期化関数）に分かれます。

2方法1：変数にExpose on Spawnを付けて生成時に渡す

もっとも一般的なのが、Widget Blueprintに変数を作り、その変数を「生成時に外から設定できる」ようにする方法です。手順の概要は次のとおりです。

1. 受け取りたいWidget Blueprintを開き、「My Blueprint」パネルの「Variables」で新しい変数を追加します。例として、スコアを受け取るなら「Score（Integer型）」を作成します。
2. 追加した変数を選択し、「Details」パネルで「Instance Editable」（インスタンス編集可能）にチェックを入れます。
3. 続けて「Expose on Spawn」（生成時に公開）にもチェックを入れます。
4. この変数の値を使ってUIを更新する処理を、後述のEvent Pre ConstructまたはEvent Construct内に組みます（例：Score変数の値をTextBlockのSet Textに接続）。

「Instance Editable」は変数をインスタンスごとに編集可能にする設定、「Expose on Spawn」はその変数をCreate Widgetノードの入力ピンとして表に出す設定です。両方を有効にして初めて、Create Widgetノードでその変数を渡せるようになります。

呼び出し側でCreate Widgetから値を渡す

呼び出し側（プレイヤーキャラクターやHUDのBlueprintなど）では、次のように接続します。

1. 「Create Widget」ノードを配置し、「Class」に先ほどのWidget Blueprintを指定します。
2. Classを指定すると、Expose on Spawnを付けた変数（例：Score）がCreate Widgetノードの入力ピンとして自動的に表示されます。ここに渡したい値を接続します。
3. Create Widgetの「Return Value」を「Add to Viewport」ノードのTargetに接続し、画面に表示します。
4. 生成したWidgetを後から操作・更新したい場合は、Return Valueを変数に昇格（Promote to Variable）して参照を保持しておきます。

この流れでは、Create Widgetが実行された段階でScoreの値がWidget内に入り、生成時の初期化イベントでUIに反映されます。Expose on Spawnを使う最大の利点は、「生成」と「初期値の受け渡し」を1ステップにまとめられることです。

3方法2：生成後にSetterや初期化関数で渡す

Expose on Spawnを使わず、生成したあとに値を渡す方法もあります。引数の数が多い場合や、まとめて初期化したい場合に向いています。

1. Widget Blueprintに変数を用意します（Instance Editableのみでも可）。
2. 呼び出し側で「Create Widget」を実行し、Return Valueを変数に保持します。
3. 保持したWidget参照に対して、各変数の「Set」ノードで値を設定するか、あらかじめWidget Blueprintに作っておいた初期化関数（例：「Init Score」）を呼び出します。
4. 初期化関数の中で、受け取った値をTextBlockなどへ反映し、必要なら「Add to Viewport」で表示します。

初期化用の関数を1つ用意しておくと、「複数の値をまとめて渡す」「渡したあとに表示を更新する」という処理を1か所に集約でき、呼び出し側がすっきりします。関数の入力（インプット）に引数を定義すれば、関数本来の引数としてデータを受け取れます。

4渡した値をUIへ反映するタイミング

引数を渡しただけではUIの見た目は変わりません。受け取った変数の値をTextBlockやImageなどに反映する処理が必要で、その実行タイミングが重要になります。代表的なイベントは次の2つです。

Expose on Spawnで渡した値は、Create Widgetの内部処理の中で構築イベントが走るときに利用できます。Pre Constructを使うと、エディタのデザインビュー上でもおおよその見た目を確認しやすくなります。一方、実行時にだけ確定するデータ（実際のスコアなど）はEvent Constructや、その後に呼ぶ更新関数で反映するのが分かりやすい構成です。

5具体例：スコア表示Widgetを作る

「現在のスコアを受け取って画面に表示するWidget」を例に、全体の流れを整理します。

Widget Blueprint側（ScoreWidget）
1. TextBlock（例：「Score_Text」）を配置します。
2. 変数「Score（Integer型）」を作成し、Instance EditableとExpose on Spawnを有効化します。
3. Event Pre Construct（またはConstruct）で、ScoreをStringに変換してScore_TextのSet Textに接続します。

呼び出し側（HUD用Blueprintなど）
1. Create Widgetを配置し、ClassにScoreWidgetを指定。
2. 表示されたScoreピンに、現在のスコア値を接続。
3. Return ValueをAdd to Viewportに接続して表示。
4. 後でスコアを更新したい場合は、Return Valueを変数に保持し、スコア変化時にScoreを更新する関数を呼び出して再描画する、という設計にします。

この構成なら、生成時には初期スコアが反映され、ゲーム中の増減は更新関数で対応できます。プレイヤー名表示や通知メッセージ表示なども、変数の型を変える（StringやTextなど）だけで同様に作成できます。

6引数を渡すときの落とし穴

7よくある質問（FAQ）

Q1. Create WidgetのノードにExpose on Spawnした変数のピンが出てきません。

まず対象の変数で「Instance Editable」と「Expose on Spawn」の両方が有効になっているか確認します。片方だけだとCreate Widgetの入力ピンには現れません。設定変更後にBlueprintをコンパイルし、Create Widgetノード側でClass指定を再選択すると、ピンの表示が更新されることがあります。

Q2. 引数を渡したのにTextBlockの表示が変わりません。

値の受け渡しと、UIへの反映処理は別物です。渡した変数の値をTextBlockなどに反映する処理（Set Textなど）を、Pre Construct・Construct・更新関数のいずれかで実行しているか確認します。生成後にSetで値を入れた場合は、Constructがすでに終わっている可能性が高いため、設定後に表示更新用の関数を呼び出してください。

Q3. Expose on Spawnと、生成後のSetterはどちらを使うべきですか？

用途によります。初期値を1ステップで渡したい、コードの見通しを良くしたい場合はExpose on Spawnが手軽です。一方、複数の値をまとめて渡したい、生成タイミングと初期化タイミングを分けたい、初期化処理を関数に集約したい場合は、生成後に初期化関数を呼ぶ方法が向いています。両者を組み合わせ、「Expose on Spawnで一部を渡しつつ、更新は専用関数で行う」といった設計も一般的です。

8まとめ

UE5でWidget Blueprintに引数（初期データ）を渡す基本は、Widget内に変数を作り、「Instance Editable」と「Expose on Spawn」を有効化してCreate Widgetのピンから渡す方法です。Expose on Spawnを使わない場合は、生成後にSetノードや初期化関数で値を渡します。いずれもPre ConstructやConstructでの反映処理とセットで考えるのがポイントです。仕様の細部はUEのバージョンによって表記やUIが変わることがあるため、最終的な挙動は実際のエディタや公式ドキュメントでの確認をおすすめします。