Game Save conflicts and atomic units
Overview
Save conflicts happen when you modify the same game data on multiple devices. The system needs to decide which version to keep. To design your save data structure, you need to understand how the system detects and resolves conflicts.When conflicts happen
Conflicts happen during the sync operation (PFGameSaveFilesAddUserWithUiAsync) only when all of the following conditions are true:
- Local changes exist: You modified files locally since the last sync.
- Cloud changes exist: Another device uploaded newer data since the last sync.
- Same atomic unit: Both changes are in the same root-level folder.
Conflict detection matrix
What is an atomic unit?
Some file sync systems treat conflicts on a file-by-file basis. If the same file needs to be uploaded and downloaded, there’s a conflict. In Game Saves, each root-level subfolder is treated as an atomic unit.Each root-level subfolder is one atomic unit.
- Maintain data integrity: Interdependent files stay consistent together
- Provide isolation: Independent data in separate folders sync without conflicts
- Minimize conflicts: Changes to different atomic units on different devices merge automatically
Example save structure
Conflict scenarios
Root-level files: special case
All files at the save root share one atomic unit. The system groups all files you place directly in the save root (not in any subfolder) together as a single atomic unit. If you modify one root-level file locally and another device modifies a different root-level file, this difference triggers a conflict.User choice options
When conflicts occur, players choose between:- Use Local Data (Keep Local): Keep the device’s current save data.
- Use Cloud Data (Keep Cloud): Download and use the cloud save data.
Critical: resolution is all or nothing
⚠️ Important: While atomic units determine when a conflict is detected, the user’s conflict resolution choice applies to the entire save, not per atomic unit.
Example: Mixed conflict scenario
Why this matters
- Keep Local loses cloud-only changes: If you choose “Keep Local” because of a conflict in SlotA, you don’t receive the cloud update to SlotC that another device made.
- Keep Cloud loses local-only changes: If you choose “Keep Cloud”, the cloud state overwrites your local changes to SlotB and SlotD.
- Rollback available: Both choices preserve the discarded branch for future rollback capability.
Design summary
This all-or-nothing approach simplifies the player experience. While per-atomic-unit resolution technically maintains data consistency (since atomic units define consistency boundaries), it creates user experience challenges:
- Players need to understand the concept of atomic units and folder boundaries.
- Mixed results (some folders from local, others from cloud) can leave players confused about the final state.
- Prompting for each conflicting atomic unit separately makes conflict resolution overwhelming.
When conflicts don’t occur
Delete on both sides
If both devices delete the same file (or files in the same atomic unit), no conflict occurs. The system recognizes that both devices agree the file should be removed.Changes in different atomic units
If Device A modifies files inSlotA/ and Device B modifies files in SlotB/, no conflict occurs. Sync automatically merges both changes.
Best practices
1. Design folder structure carefully
Use subfolders for independent save units:- Shared reference data: Store data that any save slot might use, such as unlocked content or achievements, in its own subfolder so it syncs independently from individual save slots.
- Large asset collections: If your game stores large sets of files that update independently, such as downloaded content packs or user-created levels, consider splitting them into multiple root subfolders so updates to one collection don’t conflict with updates to another.