ue5-cpp-gameplay

クイックスタート

• 対象のクラス型（AActor、UActorComponent、UObject、USaveGame など）を確認します。
• 実装前に、必要な Blueprint 向け API を定義します。
• ヘッダーファイルとソースファイルを両方まとめて出力します。

API の基準（UE5.6-UE5.8）

• リフレクションと UObject の基準：
  • UCLASS、USTRUCT、UENUM、UINTERFACE、GENERATED_BODY()
  • UPROPERTY(...)、UFUNCTION(...)
• ゲームプレイの主要な型の基準：
  • AActor、UActorComponent、UDataAsset、UGameInstanceSubsystem
  • ヘッダーでは TObjectPtr<>、クラス参照には TSubclassOf<>
• レプリケーションの基準：
  • GetLifetimeReplicatedProps(...)
  • Net/UnrealNetwork.h の DOREPLIFETIME(...)
  • ReplicatedUsing=OnRep_*、UFUNCTION(Server/Client/NetMulticast, ...)
• Gameplay Tag の基準：
  • FGameplayTag、FGameplayTagContainer
  • 安全なフォールバック動作を備えた、明示的なタグのリクエスト／一致チェック

実装ステージの要件

• すべてのゲームプレイ C++ タスクで、以下を定義する必要があります。
  • パブリックヘッダー API の範囲（Blueprint/API の公開範囲）
  • プライベートなランタイム実装の場所（.cpp）
  • 所有権／ライフタイムのモデル（コンストラクター、初期化、終了処理）
  • ネットワーク権限のルール（シングルプレイヤーのみ、またはレプリケーションを伴うフロー）
  • 検証方法（コンパイル時の前提、使用例、エッジケースの動作）
• いずれかが欠けている場合、実装仕様は不完全です。

ワークフロー

1) 型とファイル構成

• Unreal マクロと UE5 のポインター規約（ヘッダーでは TObjectPtr）を使用して型宣言を作成します。
• ヘッダーには前方宣言、ソースには具体的なインクルードを記述し、対応する .h と .cpp を作成します。
• クラスの責務を限定し、再利用しやすくします。

2) パブリック API の設計

• 実装前に Blueprint API（BlueprintCallable、BlueprintPure、カテゴリ、メタデータ）を定義します。
• 呼び出し可能な範囲は最小限にし、必要でない限りヘルパーメソッドには UFUNCTION を付けません。
• 入力／出力の契約と失敗時の動作を明確に宣言します。

3) ランタイム実装

• .cpp にロジックを実装し、null チェック、権限チェック、明示的な分岐処理を含めます。
• Tick の使用はオプトインとし、イベント駆動型の更新を優先します。
• 初期化順序（BeginPlay、InitializeComponent、またはサブシステムの初期化）を明示的に処理します。

4) レプリケーションと RPC（必要な場合）

• レプリケートするプロパティと OnRep_* ハンドラーは、クライアントに表示する必要がある状態に限って追加します。
• GetLifetimeReplicatedProps(...) で DOREPLIFETIME(...) を使用してプロパティを登録します。
• クライアントからのリクエストには、サーバー権限の RPC エントリーポイントを使用します。

5) GameplayTags とデータ駆動のフック

• 明示的なタグ名とともに FGameplayTag／FGameplayTagContainer を使用します。
• 実行時に必須タグを検証し、タグが見つからない場合のフォールバックを用意します。
• 調整可能な値には、ハードコードされた定数よりも DataAsset 駆動の設定を優先します。

6) 検証結果の出力

• 出力に両方のファイルと必要なインクルードが含まれていることを確認します。
• Blueprint への公開、レプリケーションの動作、エラー処理の経路が文書化されていることを確認します。
• 動作が自明でない場合は、使用例または呼び出しフローを提示します。

制約

• クラスを作成する場合は、必ず対応する .h と .cpp の両方を提示します。
• UE5.6-UE5.8 と互換性のある、非推奨ではない API を使用します。
• インクルードは最小限にし、ヘッダーでは前方宣言を使用します。
• 明示的に要求されない限り、アセットパスをハードコードしないでください。
• ヘッダー内の UPROPERTY オブジェクト参照には、TObjectPtr<> を優先して使用します。
• ネットワークに影響するゲームプレイアクションでは、サーバー権限のチェックを明示します。

障害への対処

• 症状：クラスはコンパイルされますが、Blueprint に表示されません。
  • 確認箇所：BlueprintType／Blueprintable／BlueprintCallable メタデータが不足していないか確認します。
  • 対処：必要なリフレクション指定子を追加し、プロジェクトファイルを再生成してビルドします。
• 症状：シンボルを解決できない、またはインクルードが循環しています。
  • 確認箇所：ヘッダーのインクルード関係と、前方宣言の誤用を確認します。
  • 対処：重いインクルードを .cpp に移し、ヘッダーでは前方宣言を使います。
• 症状：複製されたプロパティがクライアントで更新されません。
  • 確認箇所：GetLifetimeReplicatedProps(...) と、アクター／コンポーネントの複製フラグを確認します。
  • 対処：DOREPLIFETIME(...) に登録し、所有するアクターが複製されることを確認します。
• 症状：OnRep_* が一度も呼び出されません。
  • 確認箇所：プロパティの書き込み経路とネットワークロールを確認します。
  • 対処：サーバー権限の経路で値を変更し、プロパティが実際に変化することを確認します。
• 症状：RPC は呼び出せますが、実行時に無視されます。
  • 確認箇所：RPC 指定子と、呼び出し元の権限を確認します。
  • 対処：クライアントからサーバーへのリクエスト経路を徹底し、サーバー側で検証します。
• 症状：GameplayTag のロジックが何も起こさず失敗します。
  • 確認箇所：タグ名が無効でないか、タグ設定が不足していないか確認します。
  • 対処：起動時にタグを検証し、明示的なフォールバック動作を設けます。

UE5.6-UE5.8 の互換性に関する注意事項

• 上記のリフレクション、複製、GameplayTag API は UE5.6-UE5.8 で安定しています。
• 実行時の動作が必要な場合は、エディター専用ヘルパーより安定したコア API を優先してください。

エスカレーション

• ユーザーが単一のゲームプレイクラスを超えるプラグイン／モジュールレベルのリファクタリングを求める場合は、エスカレーションしてください。
• 解決策にエンジンソースのカスタマイズが必要な場合は、エスカレーションしてください。