unreal-blueprints

Unreal Blueprints（ビジュアルスクリプティング）

Unreal Engine 5 Blueprints でゲームプレイロジックを構成します。適切なグラフを選び、データをわかりやすく公開し、ハード参照が絡み合わない通信方法を選びましょう。 対象は UE 5.8 です。（Blueprints はノードグラフです。以下のスニペットではノードのフローを説明しています。）

使用する場面

• Blueprint Class の作成、Event Graph（BeginPlay/Tick/overlap）の接続、Construction Script の使用、変数／関数／マクロの作成、または 2 つの Blueprint 間の通信方法（Cast、Interface、Event Dispatcher）の選択に使用します。
• プロジェクトに *.uproject と Blueprint の *.uasset ファイルがあり、ユーザーが C++ ではなくビジュアル操作で作業する場合に使用します。

使用しない場面： パフォーマンスが重要なシステム、大規模なデータ構造、またはソース管理の差分やユニットテストが役立つもの → unreal-cpp-gameplay。プレイヤー入力のマッピング → unreal-enhanced-input。AI ロジック → unreal-behavior-trees。

基本的なワークフロー

1. Blueprint の種類を選びます。 Blueprint Class（Actor/Pawn/Character/ActorComponent を継承）は、再利用可能なオブジェクトを定義します。Level Blueprint はレベルごとのグラフで、レベル固有のスクリプトにのみ使用します。再利用可能なロジックは配置しないでください。
2. エディターでのセットアップには Construction Script を使用します（プロシージャルな配置、変数からのコンポーネント設定など）。これはアクターの配置時または編集時に実行され、プレイ中には実行されません。
3. 実行時のロジックには Event Graph を使用します。 初期化には Event BeginPlay、リアクションには入力／overlap イベントを使用します。フレームごとの処理が本当に必要な場合を除き、Event Tick は避けてください。
4. 変数でデータを公開します。 目のアイコンをクリックして変数を Instance Editable にし、関連する変数をカテゴリ別にまとめます。ゲッターには pure 関数（exec ピンなし）を指定します。
5. 結合度に応じて通信方法を選びます（「パターン」を参照）。自分が所有するものには直接の Cast、ハード参照なしで型をまたいで呼び出すには Blueprint Interface、1 対多のブロードキャストには Event Dispatcher を使用します。
6. 確認します。 Blueprint デバッガーでノードにブレークポイントを設定し、変数の値を監視して、Play In Editor（PIE）中に Print String を使って実行経路を確認します。

パターン

1. リアクティブな Event Graph（Tick なし）

Event BeginPlay
  -> Set 'StartLocation' = GetActorLocation
  -> Bind Event to OnComponentBeginOverlap (TriggerVolume) [calls custom event OnEnterZone]

OnEnterZone (Other Actor)
  -> Branch: Other Actor == Player?
       True  -> Open Door (Timeline drives the rotation)   // event-driven, runs once

Tick でのポーリングよりも、イベント（overlap、タイマー、ディスパッチャー）や Timeline を優先してください。

2. 直接参照 + Cast（結合度が高いため、必要な場合に限る）

Overlapped Actor (Actor ref)
  -> Cast To BP_Player
       Cast Failed -> (do nothing)
       Success     -> call BP_Player.ApplyDamage(10)

Cast To は、そのクラスへのハード参照を作成します（この Blueprint と一緒に読み込まれます）。呼び出し元が本当にその型に依存する場合は問題ありません。それ以外の場合は Interface を優先してください。

3. Blueprint Interface（疎結合な呼び出し）

// 1. Create BPI_Interactable with function 'Interact(Instigator)'.
// 2. Add the interface to BP_Door, BP_Chest, BP_Lever and implement 'Interact' in each.
// 3. Caller, with any Actor ref:
Player presses Use
  -> Does Object Implement Interface (BPI_Interactable)?  // safe check, no Cast/hard ref
       True -> Interact (Message) on Target Actor

4. Event Dispatcher（1 対多のブロードキャスト）

// In BP_Player: declare Event Dispatcher 'OnHealthChanged (float NewHealth)'.
TakeDamage -> Set Health -> Call 'OnHealthChanged' (Health)   // broadcast

// In WBP_HUD BeginPlay: Bind Event to 'OnHealthChanged' -> update health bar.
// Many listeners can bind; the player never references them.

注意点

• Cast のスパゲッティ化／長いロード時間 — Cast To の連鎖はハード参照を作成し、アセットツリー全体をメモリに読み込みます。Interface または Dispatcher で疎結合にしてください。
• 再利用可能にすべきロジックを Level Blueprint に配置する — レベル間で再利用できません。Blueprint Class に配置してください。
• Event Tick の使いすぎ — 毎フレーム実行されるノードはすぐに増えます。代わりにイベント、タイマー（Set Timer by Event）、Timeline を使用してください。
• Construction Script でゲームプレイを行う — エディターでの編集時／配置時に実行されるため、ゲームプレイ用アクターのスポーンやロジックの開始はエディター限定のアーティファクトを引き起こします。BeginPlay で初期化してください。
• 変数がインスタンスに表示されない — Instance Editable（目のアイコン）を有効にしてください。Spawn ノードでスポーン前に編集するには、さらに「Expose on Spawn」も有効にします。
• Interface の呼び出しが何も行わない — 対象が Interface を実装していません。呼び出し前に「Does Implement Interface」を使用するか、未実装の対象に対しても安全な Message 版を使用してください。

参考資料

• Cast vs Interface vs Event Dispatcher の選び方と、Dispatcher のバインド手順については、references/communication.md を参照してください。
• 主要ドキュメント：「Blueprints Visual Scripting」 （https://dev.epicgames.com/documentation/en-us/unreal-engine/overview-of-blueprints-visual-scripting-in-unreal-engine）。

関連スキル

• unreal-cpp-gameplay — C++ に移行するタイミング、および BP と C++ クラスの連携方法です。
• unreal-enhanced-input — これらのグラフに入力イベントを渡す最新の方法です。
• unreal-behavior-trees — Blueprint がトリガーする AI の意思決定ロジックです。