unrealxu/unrealengine5-skills/ue5-save-load-replication

Quick Start

• Define what must persist and what must replicate.
• Separate local save state from network runtime state.
• Output data schema, save flow, load flow, and net flow.

API Anchors (UE5.6-UE5.8)

• Save pipeline anchors:
• USaveGame
• UGameplayStatics::CreateSaveGameObject(...)
• UGameplayStatics::SaveGameToSlot(...), LoadGameFromSlot(...)
• UGameplayStatics::AsyncSaveGameToSlot(...), AsyncLoadGameFromSlot(...)
• Replication anchors:
• GetLifetimeReplicatedProps(...)
• DOREPLIFETIME(...)
• ReplicatedUsing=OnRep_*
• UFUNCTION(Server/Client/NetMulticast, ...)
• Authority anchors:
• server-authoritative mutation path
• client requests routed through validated server RPC entry points

State Contract

• Every state field must be classified as one of:
• Persistent-only (SaveGame, not replicated)
• Replicated-only (runtime sync, not persisted)
• Persistent + replicated (authoritative state with save restore)
• Every persisted schema must include:
• explicit version integer
• stable identifiers/keys (avoid index-based implicit ordering)
• migration behavior for older versions
• Every replicated field must define:
• replication condition or scope
• OnRep_* behavior on clients
• server write ownership

Workflow

1) Partition State

• Identify gameplay state by ownership: local player, world/shared, match/session.
• Split ephemeral runtime values from persistent values.
• Mark authoritative write path for each field.

2) Save Schema

• Define save structs/objects with explicit schema version.
• Use stable keys/IDs for actors, components, and inventory-like entries.
• Include optional migration metadata for backward compatibility.

3) Save Pipeline

• Gather runtime state into save schema in deterministic order.
• Write through sync or async slot APIs based on latency sensitivity.
• Return structured save result (success, failure reason, version used).

4) Load and Restore Pipeline

• Load save object, validate version, run migration if needed.
• Apply restore in dependency-safe order (owners before dependents).
• Resolve missing assets/entities with explicit fallback policy.

5) Replication Pipeline

• Replicate only client-visible runtime state.
• Register replicated properties with DOREPLIFETIME(...).
• Use OnRep_* for client-side reconstruction/UI refresh, not authority writes.

6) RPC Authority Pipeline

• Use client->server RPC for requested actions.
• Validate payloads on server before mutating replicated state.
• Broadcast resulting state via replication/NetMulticast only when needed.

Constraints

• Server is source of truth for replicated gameplay state.
• Validate all client-requested actions before applying state changes.
• Keep SaveGame schema versionable; avoid fragile implicit ordering.
• Do not assume single-player behavior in multiplayer code paths.
• Keep restore process idempotent where possible (safe to retry after partial failure).
• Avoid persisting transient network-only caches.

Failure Handling

• Symptom: load succeeds but gameplay state is inconsistent.
• Locate: restore ordering and missing dependency handling.
• Fix: apply owners/components/dependents in staged restore order with fallback defaults.
• Symptom: old save files break after update.
• Locate: schema version checks and migration path.
• Fix: add explicit migration per version or gate unsupported versions cleanly.
• Symptom: replicated value differs from saved value after reconnect.
• Locate: authority write path and restore timing vs replication timing.
• Fix: restore on authority first, then let replication propagate to clients.
• Symptom: OnRep_* spam causes frame spikes.
• Locate: frequent property churn and large payload replication.
• Fix: batch updates, replicate coarse state, derive fine state client-side.
• Symptom: client can trigger unauthorized state changes.
• Locate: RPC validation and authority checks.
• Fix: enforce server validation and reject invalid client payloads.
• Symptom: async save/load callbacks race with gameplay transitions.
• Locate: callback lifecycle and stale object references.
• Fix: guard callbacks with state tokens and world validity checks.
• Symptom: partial restore leaves orphaned actors/components.
• Locate: failure rollback path.
• Fix: stage restore transactions and cleanup created artifacts on failure.

Replication Ops

• Use ReplicatedUsing when client-side side effects are required.
• Use RPC only for intent transfer, not as persistent state storage.
• Use replication for authoritative state fan-out; use SaveGame for disk persistence.
• Never trust client-local save data as authoritative multiplayer input.

UE5.6-UE5.8 Compatibility Notes

• SaveGame and replication APIs listed above are stable across UE5.6-UE5.8.
• Prefer stable Engine runtime APIs over project-specific serialization shortcuts.
• Iris is production-ready in UE5.8, but do not assume an existing 5.6/5.7 project has migrated to Iris; detect the project's active replication system before giving system-specific guidance.

Escalation

• Escalate when changes break existing save compatibility policy.
• Escalate when replication design impacts anti-cheat or authoritative architecture decisions.