> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 游戏存档 PlayStream 事件

> PlayFab 游戏存档 PlayStream 事件参考，涵盖版本最终确定、冲突解决和已知良好回滚遥测字段。

PlayFab 游戏存档发出 PlayStream 事件，您可以使用这些事件来跟踪玩家如何存档、同步和管理其游戏数据。使用这些事件可以监控存档活动、检测冲突以及了解整个玩家群体的跨设备使用模式。

所有游戏存档事件都是针对 `playfab.gamesave` 命名空间中的 `title_player_account` 实体发出的。

## 事件

### `gamesave_version_finalized`

每次游戏存档版本被最终确定时发出。所有文件均已上传，版本已完成。此事件是跟踪存档活动的主要信号。

| 字段                       | 类型         | 描述                                                                        |
| ------------------------ | ---------- | ------------------------------------------------------------------------- |
| `Version`                | `long`     | 已最终确定的游戏存档的版本号                                                            |
| `FinalizedAt`            | `DateTime` | 版本最终确定时的时间戳                                                               |
| `TotalSizeBytes`         | `long`     | 已最终确定版本的总大小，包括所有文件                                                        |
| `TotalFileCount`         | `int`      | 已最终确定版本中的文件总数                                                             |
| `NewFileCount`           | `int`      | 此版本中新增的文件数量                                                               |
| `NewFilesSizeBytes`      | `long`     | 此版本中新增文件的大小                                                               |
| `PlayerIdentityProvider` | `string`   | 玩家使用的身份提供程序（例如 Steam、XBOX Live）                                           |
| `DeviceType`             | `string`   | 存档上传自的设备类型                                                                |
| `IsGeneratedByRollback`  | `bool`     | 如果此版本是通过回滚到先前版本创建的，则为 `true`                                              |
| `Conflict`               | `Conflict` | 当此版本作为冲突解决的一部分被最终确定时存在。否则为 `null`。参见[冲突解决](#scenario-conflict-resolution) |

**Conflict**（嵌套对象，仅在冲突解决期间存在）：

| 字段                   | 类型     | 描述                                                                                          |
| -------------------- | ------ | ------------------------------------------------------------------------------------------- |
| `IsWinner`           | `bool` | 玩家的本地更改是否赢得了冲突。该事件始终对应于从客户端本地数据创建的新清单。`true` 表示该清单成为规范版本；`false` 表示该清单被保留为回滚点，而现有的云版本仍为规范版本 |
| `ConflictingVersion` | `long` | 发生冲突的现有云版本的版本号                                                                              |

### `gamesave_version_marked_known_good`

当游戏存档版本被显式标记为"已知良好"时发出。已知良好版本作为可信的恢复点。当玩家或作品需要从错误的存档状态中恢复时，系统会回滚到该版本。

| 字段         | 类型         | 描述          |
| ---------- | ---------- | ----------- |
| `Version`  | `long`     | 被标记为已知良好的版本 |
| `MarkedAt` | `DateTime` | 版本被标记时的时间戳  |

***

## 场景

### 场景：标准跨设备使用

典型的跨设备流程是玩家在一台设备上存档，然后在另一台设备上继续。在 PlayStream 中，这种模式表现为一系列 `gamesave_version_finalized` 事件，其 `Version` 号依次递增。

**您将看到：**

* 每次玩家存档时都会有一个 `gamesave_version_finalized` 事件，其中 `DeviceType` 和 `PlayerIdentityProvider` 指明使用了哪台设备和身份提供程序。
* `NewFileCount` 和 `NewFilesSizeBytes` 显示与前一版本相比更改了多少数据。`NewFileCount` 为 0 的版本表示玩家最终确定的版本没有新的文件内容（例如，仅元数据更新）。
* 对于正常存档，`Conflict` 为 `null`，`IsGeneratedByRollback` 为 `false`。

**需要关注的内容：**

* **每个玩家的存档频率**：跟踪最终确定事件的速率，以了解玩家参与度和存档行为。
* **存档大小随时间的变化**：监控 `TotalSizeBytes` 和 `NewFilesSizeBytes`，以捕获可能影响存储成本或同步时间的存档数据的意外增长。
* **设备分布**：聚合 `DeviceType`，以了解您的玩家最常从哪些平台存档。

### 场景：冲突解决

当两台设备针对同一基础版本最终确定游戏存档版本时，会发生冲突。例如，玩家可能同时在其主机和 PC 上离线游玩，两台设备在重新联网时都尝试同步。

**您将看到：**

* 在冲突解决期间，客户端总是将其本地文件上传到新清单，并最终确定该清单。此过程会产生一个 `gamesave_version_finalized` 事件，其中包含非 null 的 `Conflict` 对象。现有的云版本（已在先前事件中最终确定）不会产生新事件。
* `Conflict.IsWinner` 告诉您玩家的本地更改是否赢得了冲突：
  * `true`——玩家选择了**保留本地**。新清单成为规范版本，先前的云版本被取代。
  * `false`——玩家选择了**保留远程**。新清单被保留为回滚点（包含被拒绝的本地数据），而现有的云版本仍为规范版本。
* `Conflict.ConflictingVersion` 指向发生冲突的现有云版本。

**需要关注的内容：**

* **冲突率**——筛选 `Conflict` 存在的 `gamesave_version_finalized` 事件。冲突率上升可能表明玩家在未同步的情况下频繁切换设备，或您的作品的存档节奏导致不必要的版本冲突。
* **本地与远程偏好**——比较 `IsWinner = true`（保留本地）与 `IsWinner = false`（保留远程）的比率，以了解玩家如何解决冲突。强烈偏向一侧可能表明冲突提示存在用户体验问题。
* **跨设备冲突模式**——在冲突事件中使用 `DeviceType` 和 `PlayerIdentityProvider`，以了解哪些平台组合最容易发生冲突。

### 场景：已知良好和回滚

"已知良好"机制让您可以将特定版本标记为可信的恢复点。如果玩家的存档损坏或需要恢复，系统可以回滚到最近的已知良好版本，并基于该版本创建新版本。

**您将看到：**

* 当您将某个版本指定为恢复点时，会有一个 `gamesave_version_marked_known_good` 事件，其中包含 `Version` 号和 `MarkedAt` 时间戳。
* 如果发生回滚，系统会发出一个新的 `gamesave_version_finalized` 事件，其中 `IsGeneratedByRollback = true`。此新版本的内容基于已知良好版本，但会获得一个新的递增版本号。
* 如果回滚是作为冲突解决的一部分触发的，则回滚生成的版本也可能包含 `Conflict` 数据。

**需要关注的内容：**

* **回滚频率**——跟踪 `IsGeneratedByRollback = true` 的 `gamesave_version_finalized` 事件。某作品的频繁回滚可能表明存档损坏问题或作品的存档逻辑存在问题。
* **已知良好的新鲜度**——比较 `gamesave_version_marked_known_good` 中的 `Version` 与同一玩家最新最终确定的 `Version`。差距较大意味着如果需要回滚，玩家将丢失大量进度。
* **回滚 + 冲突关联**——如果回滚生成的版本经常与冲突数据一起出现，则该模式可能表明您的冲突解决策略作为副作用触发了回滚。


## Related topics

- [PlayFab 的 PlayStream 事件模型参考](/zh-CN/services/playfab/api-references/events/index.md)
- [PlayFab 游戏存档 Steam Deck 实现指南](/zh-CN/services/playfab/player-progression/game-saves/steam-deck-implementation.md)
- [游戏存档概述](/zh-CN/build/core-features/common/game-save/game-saves-overview.md)
- [游戏存档 UI 回调](/zh-CN/services/playfab/player-progression/game-saves/ui-callbacks.md)
- [游戏存档](/zh-CN/build/core-features/common/game-save/index.md)