unreal-best-practices

Unreal Engine 5.x のベストプラクティスガイド

「まず調査する」原則

ゲームプレイシステムを実装する前に、Epic がその用途に特化した、より新しいシステムを提供していないか必ず調べてください。 Epic Games は、場当たり的なソリューションに代わる最新のフレームワークを継続的に導入しています。最新の推奨システムを使うことで、パフォーマンスが向上し、ネットワーク対応が容易になり、デザイナーにとって使いやすいワークフローを実現でき、将来の互換性も確保できます。

ワークフロー：

1. 問題の領域を特定します（入力、アビリティ、オーディオ、パーティクル、AI、UI、移動など）。
2. 以下の最新システムのクイックリファレンスを確認します。
3. 不明な点がある場合は、Epic のドキュメントと UE Public Roadmap を調べ、最新のシステム状況を確認します。
4. レガシーなアプローチよりも、本番環境で使用可能な最新システムを優先します。
5. 実験的なシステムについては、採用を決める前に成熟度を評価します。プロトタイプでは使用しても、リリース用ビルドでは使用しないでください。

これが重要な理由： Epic は、発表だけでなく実際の取り組みを通じて方向性を示しています。First/Third Person テンプレートを GAS と Enhanced Input を使うように再構築したことや、Fortnite が Game Feature Plugins と CommonUI を採用してリリースされたことは、エコシステムがどこへ向かっているかを示す最も明確な指標です。

公式ドキュメント（最新情報は必ず確認してください）

ソース	URL
Epic Documentation Hub	https://dev.epicgames.com/documentation/en-us/unreal-engine
UE Public Roadmap	https://portal.productboard.com/epicgames/1-unreal-engine-public-roadmap
Lyra Sample Project	https://dev.epicgames.com/documentation/en-us/unreal-engine/lyra-sample-game-in-unreal-engine
UE Release Notes	https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-release-notes
Epic Community Tutorials	https://dev.epicgames.com/community/learning
Experimental Features List	https://dev.epicgames.com/documentation/en-us/unreal-engine/experimental-features
Allar's UE5 Style Guide	https://github.com/Allar/ue5-style-guide
Tom Looman's UE5 Guides	https://tomlooman.com
X157 Dev Notes (Lyra)	https://x157.github.io/UE5/

Lyra Starter Game は、最新の UE5 アーキテクチャを示す Epic の公式なリファレンス実装です。Fortnite の本番コードベースから派生した GAS、Enhanced Input、Game Feature Plugins、CommonUI、GameplayMessageSubsystem、Gameplay Tags、モジュール式ゲームプレイのパターンを紹介しています。

モダンシステム早見表

各システム、移行パス、ドキュメントへのリンクについて詳しくは、references/modern-systems.md を参照してください。

UE 5.7 時点のシステムの状況：

領域	レガシー／旧システム	モダンシステム	状況
入力	BindAction/BindAxis	Enhanced Input	本番環境対応 -- レガシーシステムは 5.1 以降非推奨
アビリティ	場当たり的なブール値／タイマー	Gameplay Ability System (GAS)	本番環境対応 -- アビリティ主導のゲームに推奨
状態／分類	列挙型、ブール値、文字列	Gameplay Tags	本番環境対応 -- モダンな UE の基盤
AI の振る舞い	Behavior Trees	StateTree	5.1 以降本番環境対応 -- 代替手段。BT も引き続きサポート
AI とのインタラクション	手動スクリプト作成	Smart Objects	5.1 以降本番環境対応
パーティクル／VFX	Cascade	Niagara	本番環境対応 -- Cascade は 5.0 以降非推奨
オーディオ	SoundCue	MetaSounds	本番環境対応（コア機能）-- SoundCue はまだ非推奨ではありません
オーディオミキシング	静的設定	Audio Modulation	本番環境対応
レンダリング（ジオメトリ）	手動 LOD	Nanite	5.0 以降本番環境対応
レンダリング（ライティング）	ベイク済みライトマップ	Lumen	5.0 以降本番環境対応
レベルストリーミング	World Composition / Level Streaming	World Partition	本番環境対応 -- World Composition は非推奨
UI（マルチプラットフォーム）	生の UMG	CommonUI + UMG	ベータ版（Fortnite で使用）
移動	CharacterMovementComponent	Mover 2.0	実験段階 -- CMC が引き続き推奨
プロシージャルコンテンツ	手動／Blueprint によるスクリプト作成	PCG Framework	5.7 以降本番環境対応
アーキテクチャ	モノリシックモジュール	Game Feature Plugins	本番環境対応（Lyra/Fortnite）
メッセージング	直接デリゲート／キャスト	GameplayMessageSubsystem	本番環境対応（Lyra）
アニメーション（移動）	ステートマシン／ブレンドツリー	Motion Matching (PoseSearch)	実験段階
アニメーション（インタラクション）	手動モンタージュ同期	Motion Warping	本番環境で利用可能
アニメーション（リギング）	外部 DCC のみ	Control Rig	本番環境対応（コア機能）
アセット選択	ハードコードされた switch／if の連鎖	Chooser Tables	5.4 以降ベータ版
ネットワーキング（大規模）	デフォルトのレプリケーション	Iris	5.7 以降ベータ版
会話	サードパーティ製プラグイン	CommonConversation	実験段階（非推奨）

C++ と Blueprint のベストプラクティス

詳しいパターン、通信方法、パフォーマンスのガイドラインについては、references/blueprint-and-cpp.md を参照してください。

理想的なパターン：抽象 C++ 基底クラス + Blueprint サブクラス。

C++ (UCLASS(Abstract))                  Blueprint Subclass
+----------------------------------+    +---------------------------+
| Base class logic                 |    | Visual/gameplay config    |
| - Core systems & algorithms     |    | - Asset references        |
| - Networking & replication       |    | - Tuning values           |
| - Performance-critical code      |    | - Event responses         |
| - BlueprintImplementableEvent    |    | - Designer iteration      |
| - UPROPERTY(EditDefaultsOnly)   |    | - One-off behaviors       |
+----------------------------------+    +---------------------------+

判断基準：

• C++：基底クラス、システム、パフォーマンスが重要なコード、ネットワーキング、エディタツール
• Blueprint：ゲームプレイロジック、設定、プロトタイピング、VFX のトリガー、UI レイアウト
• 両方：C++ でフレームワークを定義し、Blueprint でゲームプレイの詳細を補います

重要なルール：

• Event Tick は避け、代わりにタイマー、イベント、デリゲートを使用します（パフォーマンスが 20～30% 向上）
• Blueprint 間の通信にはキャストより Blueprint Interface を使用します（ハード参照を回避できます）
• すぐに必要としないアセットには TSoftObjectPtr<> を使用します（メモリの肥大化を防ぎます）
• 毎フレーム検索するのではなく、参照をキャッシュします
• Blueprint Nativization は UE 5.0 で削除されました -- パフォーマンスが重要なパスは手動で C++ に変換してください

データ駆動型設計

データテーブル、データアセット、プライマリアセット、アセットマネージャー、ゲームプレイタグのパターンについては、references/data-driven-design.md を参照してください。

基本原則：データとロジックを分離します。 コードに触れることなく、デザイナーが設定できるようにします。

アセットタイプ	最適な用途	主な特性
データテーブル	均質な大規模データセット（100 項目以上）	CSV/JSON インポート、FTableRowBase の行
データアセット	複雑で固有の定義（ボス、スキルツリー）	完全な継承、UObject メンバー
プライマリデータアセット	ライフサイクル管理を伴うアセット	アセットマネージャーとの統合、非同期ロード
ゲームプレイタグ	階層的な状態／分類	列挙型の代替、デザイナーが作成可能

ゲームプレイタグは基本要素です -- 状態管理、アビリティの分類、ダメージタイプ、アニメーション状態、入力バインディング、システム間通信に使用してください。TArray<FGameplayTag> ではなく、常に FGameplayTagContainer を使用してください。

プロジェクトの構成

命名規則、フォルダー構成、モジュール型アーキテクチャのパターンについては、references/project-organization.md を参照してください。

命名規則のプレフィックス（標準）：

プレフィックス	タイプ	プレフィックス	タイプ
BP_	ブループリント	IA_	入力アクション
WBP_	ウィジェットブループリント	IMC_	入力マッピングコンテキスト
DA_	データアセット	GA_	ゲームプレイアビリティ
DT_	データテーブル	GE_	ゲームプレイエフェクト
SM_	スタティックメッシュ	NS_	Niagara システム
SK_	スケルタルメッシュ	AM_	アニメーションモンタージュ
M_	マテリアル	ABP_	アニメーションブループリント
MI_	マテリアルインスタンス	BS_	ブレンドスペース
T_	テクスチャ	S_	サウンドウェーブ

フォルダー構成：アセットタイプ別ではなく、機能別にします。

パフォーマンスとデバッグ

ティックの最適化、オブジェクトプーリング、GC 管理、プロファイリング、Unreal Insights については、references/performance-and-debugging.md を参照してください。

パフォーマンスに関する主なルール：

1. 不要なアクターやコンポーネントのティックを無効にします（bCanEverTick = false）
2. フレームごとのポーリングではなく、タイマーとイベントを使用します
3. 頻繁に生成・破棄されるアクター（弾丸、パーティクル）をプールします
4. 静的ジオメトリには Nanite を使用し、手動での LOD 作成をなくします
5. 推測ではなく Unreal Insights（-trace=cpu,gpu,frame,counters）でプロファイリングします
6. 複製プロパティに COND_* フラグを使用し、ネットワーク帯域幅を最小限に抑えます
7. Reference Viewer でアセット参照を監査し、メモリの肥大化を防ぎます

Lyra の主な設計パターン

Lyra は、Epic が推奨するアーキテクチャとして次のパターンを確立しています。

1. Game Feature Plugins：実行時にベースゲームへ組み込まれる自己完結型の機能です。一方向の依存関係により、コアゲームが機能を参照することはありません。
2. Experience System：Game Feature Plugins を基盤とする、非同期ロードのゲームモード設定です。従来の GameMode サブクラス化より優れています。
3. GameplayMessageSubsystem：タグベースのパブリッシュ／サブスクライブ型メッセージングです。ゲームプレイシステム間の密結合を解消します。
4. GAS + Gameplay Tags：データを通じてアビリティを定義し、タグを通じて有効化します。ブロックやキャンセルにもタグを使用します。
5. Enhanced Input + Tag Binding：Gameplay Tags を介して入力アクションをゲームプレイアビリティにマッピングします（直接の関数呼び出しは使用しません）。
6. CommonUI：入力デバイスの自動切り替えとフォーカス管理に対応する、プラットフォーム対応の UI です。
7. Primary Data Assets + Asset Manager：バンドルベースのメモリ管理によって制御された非同期ロードを実現します。

バージョン固有の破壊的変更

開発プラクティスに影響する主な変更：

• UE 5.0：FVector は 3 つの double 型に変更され、UPROPERTY では生ポインターの代わりに TObjectPtr<> を使用します
• UE 5.1：Enhanced Input がデフォルトになり、従来の入力方式は非推奨になります
• UE 5.3：新規プロジェクトでは C++20 がデフォルトになり、BuildSettingsVersion.V5 が適用されます
• UE 5.5：従来の統計プロファイラーは非推奨となり、Unreal Insights を使用します。Zen Loader が本番環境で使用可能になり、Path Tracer も本番環境で使用可能になります
• UE 5.6：Swarm Manager が削除され、FString::Appendf は static constexpr のフォーマット文字列を必須とし、HWRT のパフォーマンスが向上します
• UE 5.7：PCG Framework が本番環境で使用可能になり、Substrate も本番環境で使用可能になります。FindObject は EFindObjectFlags を使用し、BuildSettingsVersion.V6 が適用されます