ue5-save-load-replication

クイックスタート

• 永続化する必要があるものと、レプリケーションする必要があるものを定義します。
• ローカルのセーブ状態と、ネットワーク上のランタイム状態を分離します。
• データスキーマ、セーブフロー、ロードフロー、ネットワークフローを出力します。

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

• セーブパイプラインの要点：
  • USaveGame
  • UGameplayStatics::CreateSaveGameObject(...)
  • UGameplayStatics::SaveGameToSlot(...), LoadGameFromSlot(...)
  • UGameplayStatics::AsyncSaveGameToSlot(...), AsyncLoadGameFromSlot(...)
• レプリケーションの要点：
  • GetLifetimeReplicatedProps(...)
  • DOREPLIFETIME(...)
  • ReplicatedUsing=OnRep_*
  • UFUNCTION(Server/Client/NetMulticast, ...)
• オーソリティの要点：
  • サーバー権威型の変更パス
  • クライアントからのリクエストは、検証済みのサーバー RPC エントリーポイントを経由させます

状態の契約

• 各状態フィールドを次のいずれかに分類する必要があります：
  • 永続化のみ（SaveGame、レプリケーションなし）
  • レプリケーションのみ（ランタイム同期、永続化なし）
  • 永続化とレプリケーション（セーブから復元する権威状態）
• 永続化するスキーマには、次の内容を含める必要があります：
  • 明示的なバージョン整数
  • 安定した識別子／キー（インデックスベースの暗黙的な順序は避けます）
  • 古いバージョンの移行動作
• 各レプリケーションフィールドについて、次の内容を定義する必要があります：
  • レプリケーション条件またはスコープ
  • クライアントでの OnRep_* の動作
  • サーバー側の書き込み権限

ワークフロー

1) 状態を分割する

• 所有者に基づいてゲームプレイ状態を特定します：ローカルプレイヤー、ワールド／共有、マッチ／セッション。
• 一時的なランタイム値と永続化する値を分けます。
• 各フィールドの権威ある書き込みパスを明示します。

2) セーブスキーマ

• 明示的なスキーマバージョンを持つセーブ用構造体／オブジェクトを定義します。
• アクター、コンポーネント、インベントリのような項目には、安定したキー／ID を使用します。
• 下位互換性のため、必要に応じて移行メタデータを含めます。

3) セーブパイプライン

• ランタイム状態を決定論的な順序でセーブスキーマに収集します。
• レイテンシーへの影響に応じて、同期または非同期のスロット API を使用して書き込みます。
• 成功／失敗、失敗理由、使用したバージョンを含む構造化されたセーブ結果を返します。

4) ロードおよび復元パイプライン

• セーブオブジェクトをロードし、バージョンを検証して、必要に応じて移行を実行します。
• 依存関係を考慮した安全な順序（依存先より先に所有者）で復元を適用します。
• アセット／エンティティが見つからない場合の明示的なフォールバック方針を定めます。

5) レプリケーションパイプライン

• クライアントから見えるランタイム状態のみをレプリケーションします。
• DOREPLIFETIME(...) でレプリケーションプロパティを登録します。
• クライアント側の再構築／UI 更新には OnRep_* を使用し、権威ある書き込みには使用しません。

6) RPC オーソリティパイプライン

• リクエストされたアクションにはクライアントからサーバーへの RPC を使用します。
• レプリケーションされる状態を変更する前に、サーバーでペイロードを検証します。
• 必要な場合にのみ、レプリケーション／NetMulticast を通じて結果の状態をブロードキャストします。

制約

• レプリケーションされるゲームプレイ状態の信頼できる情報源はサーバーです。
• 状態変更を適用する前に、クライアントから要求されたすべてのアクションを検証します。
• SaveGame スキーマはバージョン管理可能にし、壊れやすい暗黙的な順序を避けます。
• マルチプレイヤーのコードパスで、シングルプレイヤーの動作を前提にしないでください。
• 可能な限り復元処理を冪等にし、部分的な失敗後も安全に再試行できるようにします。
• 一時的なネットワーク専用キャッシュの永続化は避けます。

障害への対処

• 症状：ロードは成功しますが、ゲームプレイの状態に不整合があります。
  • 確認箇所：復元の順序と依存関係の欠落への対処。
  • 対処：フォールバックのデフォルト値を用意し、段階的な復元順序に従って所有者、コンポーネント、依存先を適用します。
• 症状：アップデート後に古いセーブファイルが動作しなくなります。
  • 確認箇所：スキーマのバージョンチェックと移行経路。
  • 対処：バージョンごとに明示的な移行処理を追加するか、サポート対象外のバージョンを適切に拒否します。
• 症状：再接続後、複製された値が保存された値と異なります。
  • 確認箇所：権限のある側での書き込み処理と、復元のタイミングに対する複製のタイミング。
  • 対処：まず権限のある側で復元し、その後、複製によってクライアントに反映させます。
• 症状：OnRep_* の過剰な呼び出しによってフレームの急激な低下が発生します。
  • 確認箇所：プロパティの頻繁な変更と、大きなペイロードの複製。
  • 対処：更新をまとめ、粗い状態を複製し、細かい状態はクライアント側で導出します。
• 症状：クライアントが権限のない状態変更を引き起こせます。
  • 確認箇所：RPC の検証と権限チェック。
  • 対処：サーバー側での検証を徹底し、無効なクライアントペイロードを拒否します。
• 症状：非同期の保存／ロードコールバックがゲームプレイの遷移と競合します。
  • 確認箇所：コールバックのライフサイクルと古くなったオブジェクト参照。
  • 対処：状態トークンとワールドの有効性チェックを使ってコールバックを保護します。
• 症状：部分的な復元によって孤立したアクター／コンポーネントが残ります。
  • 確認箇所：失敗時のロールバック処理。
  • 対処：復元トランザクションを段階的に実行し、失敗時には作成した成果物をクリーンアップします。

複製の運用

• クライアント側で副作用が必要な場合は、ReplicatedUsing を使用します。
• RPC は意図の伝達にのみ使用し、永続状態の保存には使用しません。
• 権限のある状態の配信には複製を使用し、ディスクへの永続化には SaveGame を使用します。
• クライアントローカルのセーブデータを、マルチプレイヤーにおける権限のある入力として決して信頼しないでください。

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

• 上記の SaveGame と複製の API は、UE5.6-UE5.8 で安定しています。
• プロジェクト固有のシリアライズの簡略化よりも、安定した Engine ランタイム API を優先してください。
• Iris は UE5.8 で本番環境での使用に対応していますが、既存の 5.6/5.7 プロジェクトが Iris に移行済みだと想定しないでください。システム固有のガイダンスを提示する前に、プロジェクトで有効な複製システムを確認してください。

エスカレーション

• 変更によって既存のセーブ互換性ポリシーが損なわれる場合は、エスカレーションしてください。
• 複製の設計がアンチチートや権限のあるアーキテクチャの判断に影響する場合は、エスカレーションしてください。