ue5-world-interaction

クイックスタート

• インタラクションモデルを定義します。オーバーラップ駆動型、トレース駆動型、または明示的な使用キーによる方式から選択します。
• アクターの構成を定義します。取得アクター、任意のスポナー、任意のビジュアルマッピング用データアセットを指定します。
• スポーンからインタラクションの解決までのランタイム状態遷移を出力します。

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

• 検出の基点：
  • USphereComponent、UBoxComponent
  • UPrimitiveComponent::OnComponentBeginOverlap
  • UPrimitiveComponent::OnComponentEndOverlap
  • FHitResult
• トレースの基点：
  • UWorld::LineTraceSingleByChannel(...)
  • UWorld::SweepSingleByChannel(...)
  • UKismetSystemLibrary::SphereTraceSingle(...)
• ライフサイクルの基点：
  • AActor::SetActorHiddenInGame(...)
  • AActor::SetActorEnableCollision(...)
  • AActor::Destroy(...)
  • AActor::SetActorTickEnabled(...)
• ネットワークの基点：
  • インタラクション成功時のサーバー権限検証
  • クライアントへのフィードバック用の結果状態のレプリケーション

インタラクションステージの契約

• すべてのインタラクション機能で、以下を定義する必要があります。
  • 検出元（オーバーラップ／トレース／使用キー）
  • 実行条件（距離、タグ、インベントリ／容量、権限）
  • 成功時と失敗時の結果ペイロード
  • フィードバック経路（VFX／SFX／UI）
  • インタラクション後のライフサイクルポリシー（破棄／無効化／クールダウン／リスポーン）
• いずれかが欠けている場合、インタラクションの動作は十分に規定されていません。

ワークフロー

1) アクターとコンポーネントのセットアップ

• ルート、コリジョン、ビジュアルの各コンポーネントを、明示的なコリジョンチャネルとともに構築します。
• デフォルト状態（active、cooldown、consumed）とレプリケーションの要件を定義します。
• コリジョン形状と境界を、意図するインタラクション距離に合わせます。

2) 検出経路

• オーバーラップ方式：コリジョンコンポーネントに開始／終了オーバーラップのデリゲートをバインドします。
• トレース方式：入力要求時にライン／球形トレースを実行し、ヒットしたアクター／コンポーネントを検証します。
• 明示的なチャネル／プロファイルを使用して、検出の決定性を保ちます。

3) 実行条件と権限

• 対象の状態、範囲、アクターの有効性、ゲームプレイ条件を検証します。
• マルチプレイヤーでは、共有状態を変更する前に、サーバーで成功を検証します。
• 拒否時には、構造化された失敗理由を返します。

4) インタラクションの解決

• 成功時：効果を適用します（アイテムの付与、状態変更のトリガー、クールダウンの開始）。
• 失敗時：状態を維持し、理由に応じたフィードバックを出します。
• 解決処理の進行中に再入されないようにします。

5) フィードバック経路

• 成功時と失敗時の両方で、VFX／SFX／UI のフィードバックを出します。
• コスメティックのみの効果と、権威を持つゲームプレイ状態の変更を分離します。
• クライアントからの更新が繰り返されても、フィードバックが冪等になるようにします。

6) ライフサイクルとクリーンアップ

• ライフサイクルを明示的に選択します。破棄、非表示＋コリジョン無効化、またはリスポーンタイマーによる再利用から選びます。
• スポナーがある場合は、スポーンしたインスタンスを追跡し、リセット／デスポーン時にクリーンアップします。
• 休止中のインタラクションアクターでは、不要な場合に Tick を無効にします。

制約

• マルチプレイヤーでは、インタラクションの検証をサーバー権威で行います。
• コリジョンチャネルとトレース応答を明示します。
• 再現性が必要な場合は、スポナーのランダム化を決定的にします。
• 明確な必要性がない限り、Tick に隠れた副作用を持たせないでください。
• 必要な成功／失敗フィードバックをブロードキャストする前に、アクターを破棄しないでください。
• オーバーラップとトレースの両方を有効にする場合は、機能上同等の動作を保ちます。

障害対応

• 症状：オーバーラップが一度も発生しません。
  • 確認箇所：衝突の有効状態、オーバーラップフラグ、衝突チャンネルの応答。
  • 対処：オーバーラップの生成を有効にし、適切なチャンネル応答を設定して、コンポーネントの境界を確認します。
• 症状：トレースパスが明らかなターゲットを見逃します。
  • 確認箇所：トレースチャンネル／プロファイルと無視するアクターのリスト。
  • 対処：トレースチャンネル／プロファイルを適切に設定し、自身やオーナーを不適切に無視しないようにします。
• 症状：インタラクションが複数回発生します。
  • 確認箇所：処理中ガードの不足と、デリゲートの重複バインド。
  • 対処：状態ガードを追加し、コンポーネントごとにバインドが1回だけ行われるようにします。
• 症状：クライアントには成功と表示されますが、サーバーでは拒否されます。
  • 確認箇所：権限チェックとRPCの検証処理。
  • 対処：最終検証をサーバー側に移し、権威のある結果をレプリケートします。
• 症状：取得済みのピックアップがインタラクト可能なままです。
  • 確認箇所：ライフサイクル状態と衝突無効化の処理。
  • 対処：成功が確定したら、ただちに衝突／インタラクションを無効にします。
• 症状：スポーンされたインタラクティブオブジェクトが時間の経過とともにリークします。
  • 確認箇所：スポーナーの管理処理とリセット時のクリーンアップ処理。
  • 対処：スポーンしたインスタンスを追跡し、リスポーン時に古いインスタンスを破棄または無効にします。
• 症状：インタラクションが密集したエリア付近でフレーム落ちが発生します。
  • 確認箇所：毎フレームのトレース／オーバーラップ処理の負荷と、不要なティック処理。
  • 対処：ポーリング頻度を下げ、入力／距離に応じてトレースを制御し、アイドル時のティックを無効にします。

インタラクション権限の運用

• 共有されるゲームプレイ効果のインタラクション解決には、サーバーによる検証を使用します。
• 許容できる場合は、見た目上のフィードバックにのみクライアント側の予測を使用します。
• 生の入力を大量に送信するのではなく、結果の状態をレプリケートします。
• マルチプレイヤー動作の決定性を保つため、クールダウン／タイマーは権限側で管理します。

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

• 上記のオーバーラップ、トレース、アクターのライフサイクルに関するAPIは、UE5.6-UE5.8で安定しています。
• サポートするすべてのバージョンで、衝突プロファイル／チャンネルを明示的に設定することを推奨します。

エスカレーション

• セッションをまたいだ永続的なワールド状態の同期が設計上必要な場合は、エスカレーションしてください。
• GASのアビリティターゲティングルールとの統合が必要な場合は、エスカレーションしてください。