title_player_account entities in the playfab.gamesave namespace.
Events
gamesave_version_finalized
Emitted each time a game save version is finalized. All files are uploaded and the version is complete. This event is the primary signal for tracking save activity.
Conflict (nested object, present only during conflict resolution):
gamesave_version_marked_known_good
Emitted when a game save version is explicitly marked as “known good.” A known-good version serves as a trusted restore point. The version the system rolls back to if a player or the title needs to recover from a bad save state.
Scenarios
Scenario: Standard cross-device usage
A typical cross-device flow looks like a player saving on one device and resuming on another. In PlayStream, this pattern appears as a sequence ofgamesave_version_finalized events with incrementing Version numbers.
What you see:
- A
gamesave_version_finalizedevent each time the player saves, withDeviceTypeandPlayerIdentityProviderindicating which device and identity provider were used. NewFileCountandNewFilesSizeBytesshow how much data changed compared to the previous version. A version whereNewFileCountis 0 means the player finalized a version with no new file content (for example, a metadata-only update).ConflictisnullandIsGeneratedByRollbackisfalsefor normal saves.
- Save frequency per player: Track the rate of finalization events to understand player engagement and saving behavior.
- Save sizes over time: Monitor
TotalSizeBytesandNewFilesSizeBytesto catch unexpected growth in save data that could affect storage costs or sync times. - Device distribution: Aggregate
DeviceTypeto understand which platforms your players save from most frequently.
Scenario: Conflict resolution
Conflicts occur when two devices finalize a game save version against the same base version. For example, a player might play offline on their console and PC at the same time, and both devices try to sync when they come back online. What you see:- During conflict resolution, the client always uploads its local files to a new manifest and finalizes the manifest. This process produces a single
gamesave_version_finalizedevent with a non-nullConflictobject. The existing cloud version (already finalized in a prior event) doesn’t produce a new event. Conflict.IsWinnertells you whether the player’s local changes won the conflict:true—the player chose keep local. The new manifest becomes the canonical version, and the prior cloud version is superseded.false—the player chose keep remote. The new manifest is preserved as a rollback point (containing the rejected local data), while the existing cloud version remains canonical.
Conflict.ConflictingVersionpoints to the existing cloud version that was in conflict.
- Conflict rate—Filter for
gamesave_version_finalizedevents whereConflictis present. A rising conflict rate might indicate that players frequently switch devices without syncing, or that your title’s save cadence causes unnecessary version collisions. - Local vs. remote preference—Compare the ratio of
IsWinner = true(kept local) vs.IsWinner = false(kept remote) to understand how players resolve conflicts. A strong skew toward one side might indicate a UX issue with the conflict prompt. - Cross-device conflict patterns—Use
DeviceTypeandPlayerIdentityProvideron conflict events to understand which platform combinations are most prone to conflicts.
Scenario: Known good and rollback
The “known good” mechanism lets you mark a specific version as a trusted restore point. If a player’s save becomes corrupted or they need to recover, the system can roll back to the most recent known-good version and create a new version from it. What you see:- A
gamesave_version_marked_known_goodevent when you designate a version as the restore point, with theVersionnumber andMarkedAttimestamp. - If a rollback occurs, the system emits a new
gamesave_version_finalizedevent withIsGeneratedByRollback = true. This new version’s content is based on the known-good version, but it gets a new, incremented version number. - The rollback-generated version might also have
Conflictdata if the rollback was triggered as part of a conflict resolution.
- Rollback frequency—Track
gamesave_version_finalizedevents whereIsGeneratedByRollback = true. Frequent rollbacks for a title might indicate save corruption issues or problems with the title’s save logic. - Known-good freshness—Compare the
Versioningamesave_version_marked_known_goodagainst the latest finalizedVersionfor the same player. A large gap means the player would lose significant progress if a rollback is needed. - Rollback + conflict correlation—If rollback-generated versions frequently appear alongside conflict data, that pattern might suggest that your conflict resolution strategy is triggering rollbacks as a side effect.