游戏存档

本指南介绍了如何使用 C++ SDK 中 Google Play 游戏服务提供的 Snapshots API 实现游戏存档功能。您可以在PgsSnapshotsClient中找到这些 API 。

准备工作

获取 SnapshotsClient

如需开始使用 Snapshots API，您的游戏必须先获取一个 PgsSnapshotsClient 句柄。为此，您可以调用 PgsSnapshotsClient_create() 方法并传入 Android Activity。

注意 ：C++ SDK 函数通过回调异步返回结果。

// Assuming 'android_activity' is a jobject referencing your Android Activity
PgsSnapshotsClient* snapshots_client = PgsSnapshotsClient_create(android_activity);

// ... use the client ...

// When done, destroy the client to free resources
// PgsSnapshotsClient_destroy(snapshots_client);

显示游戏存档

您可以在游戏为玩家提供保存或恢复进度的选项中集成 Snapshot API。 为了简化开发，Snapshots API 提供了一个默认游戏存档选择界面 (UI)。如需启动此界面，请调用 PgsSnapshotsClient_showSelectSnapshotUI。

// Callback function to handle the result of showing the UI
void OnShowSavedGamesUI(PgsStatusCode status_code, void* user_data) {
  if (status_code == PGS_STATUS_SUCCESS) {
    // UI was shown successfully. The player can now interact with it.
    // The game doesn't receive direct data back from this callback about
    // which snapshot was selected. Your game should typically provide options
    // to load or open snapshots by name after the UI is dismissed.
  } else {
    // Handle error or failure to show UI
  }
}

// Function to show the default Saved Games UI
void ShowSavedGamesUI(PgsSnapshotsClient* client, jobject activity) {
  const char* title = "See My Saves";
  bool allow_add_button = true;
  bool allow_delete_button = true;
  int max_snapshots = 5;

  PgsSnapshotsClient_showSelectSnapshotUI(
      client,
      activity,
      title,
      allow_add_button,
      allow_delete_button,
      max_snapshots,
      OnShowSavedGamesUI,
      NULL // user_data
  );
}

// Example usage:
// ShowSavedGamesUI(snapshots_client, android_activity);

编写游戏存档

如需将内容保存到游戏存档，请执行以下操作：

  1. 使用 PgsSnapshotsClient_open() 异步打开 Snapshot。 如果您想创建新存档，请将 create_if_not_found 指定为 true。
  2. 结果在 PgsSnapshotsClient_OpenCallback 中提供。如果成功且没有冲突，您将获得 PgsSnapshot*。
  3. 准备要保存的数据作为字节数组 (uint8_t*)。
  4. 创建一个 PgsSnapshotMetadataChange* 对象来描述存档。

  5. 调用 PgsSnapshotsClient_commitAndClose 以将更改发送到 Google 的服务器。

    // Callback for commitAndClose
void OnSnapshotCommitted(PgsStatusCode status_code, PgsSnapshotMetadata* metadata, void* user_data) {
    if (status_code == PGS_STATUS_SUCCESS) {
    // Save successful
    if (metadata) {
    // Metadata for the committed snapshot
    PgsSnapshotMetadata_Release(metadata);
  }
} else {
    // Handle error
  }
}

// Function to write data to a snapshot
void WriteSnapshot(PgsSnapshotsClient* client, PgsSnapshot* snapshot,
               const uint8_t* data, size_t data_size,
               const char* description /*, Bitmap coverImage */) {

PgsSnapshotMetadataChange* metadataChange = NULL; // Placeholder

  // Commit the operation
  PgsSnapshotsClient_commitAndClose(
      client,
      snapshot,
      metadataChange,
      data,
      data_size,
      OnSnapshotCommitted,
      NULL // user_data
  );

  // if (metadataChange) PgsSnapshotMetadataChange_Release(metadataChange);
}

// Callback for opening the snapshot before writing
void OnSnapshotOpenForWrite(PgsStatusCode status_code,
                        PgsSnapshot* snapshot,
                        PgsSnapshotConflict* conflict,
                        void* user_data) {
  if (status_code == PGS_STATUS_SUCCESS) {
    if (snapshot) {
      // Successfully opened/created. Now write to it.
     const char* save_data_str = "MY_GAME_SAVE_DATA";
     const uint8_t* data = (const uint8_t*)save_data_str;
     size_t data_size = strlen(save_data_str);

      WriteSnapshot((PgsSnapshotsClient*)user_data, snapshot, data, data_size, "My Save Description");
      // PgsSnapshot_destroy(snapshot) is likely called after commitAndClose by the SDK
    } else if (conflict) {
      // Handle conflict before writing, or open with a policy that auto-resolves.
      PgsSnapshotConflict_destroy(conflict);
    }
  } else {
    // Handle error opening
  }
}

// Example: Open and write to a snapshot
void OpenAndWriteExample(PgsSnapshotsClient* client, const char* snapshot_name) {
PgsSnapshotsClient_open(
  client,
  snapshot_name,
  true, // create_if_not_found
  kPgsSnapshotConflictPolicyManual, // Or another policy
  OnSnapshotOpenForWrite,
  client // user_data
);
}

加载游戏存档

如需检索游戏存档，请执行以下操作：

  1. 使用 PgsSnapshotsClient_open() 按名称异步打开 Snapshot。

  2. 在 PgsSnapshotsClient_OpenCallback 中，如果成功，请访问 数据。该 API 提供了一种获取 uint8_t* 数据和大小的方法，虽然 从 PgsSnapshot 或关联的 PgsSnapshotContents 读取字节的方法未在本文档中详细介绍。

    // Assuming functions exist to read data from PgsSnapshotContents
// For example, PgsSnapshotContents* PgsSnapshot_getContents(PgsSnapshot* snapshot);
// For example, bool PgsSnapshotContents_readFully(PgsSnapshotContents* contents, uint8_t** out_data, size_t* out_size);
// For example, void PgsSnapshotContents_releaseData(uint8_t* data);

void OnSnapshotOpenForRead(PgsStatusCode status_code,
                       PgsSnapshot* snapshot,
                       PgsSnapshotConflict* conflict,
                       void* user_data) {
    if (status_code == PGS_STATUS_SUCCESS) {
    if (snapshot) {
    // Successfully opened. Now read from it.
    // THE FOLLOWING IS HYPOTHETICAL based on common patterns:
    // PgsSnapshotContents* contents = PgsSnapshot_getContents(snapshot);
    // uint8_t* data = NULL;
    // size_t data_size = 0;
    // if (contents && PgsSnapshotContents_readFully(contents, &data, &data_size)) {
    //   // Successfully read data
    //   Log("Snapshot data loaded, size: %zu", data_size);
    //   ... process data ...
    //   PgsSnapshotContents_releaseData(data);
    // }
    // PgsSnapshotContents_destroy(contents); // If necessary
      PgsSnapshot_destroy(snapshot);
    } else if (conflict) {
      // Handle conflict
      Log("Snapshot open resulted in a conflict.");
      PgsSnapshotConflict_destroy(conflict);
    }
  } else {
    // Handle error opening
    Log("Error while opening Snapshot: %d", status_code);
  }
}

// Example: Load a specific saved game
void LoadSnapshotByName(PgsSnapshotsClient* client, const char* snapshot_name) {
  int conflictResolutionPolicy = kPgsSnapshotConflictPolicyMostRecentlyModified;

  PgsSnapshotsClient_open(
      client,
      snapshot_name,
      false, // create_if_not_found
      conflictResolutionPolicy,
      OnSnapshotOpenForRead,
      NULL // user_data
  );
}

处理游戏存档冲突

调用 PgsSnapshotsClient_open 回调时，如果 conflict 形参不是 NULL，则发生了冲突，请使用 PgsSnapshotsClient_resolveConflict 来解决冲突。

/// @brief Asynchronously resolves a snapshot conflict.
///
/// @param snapshots_client The client handle.
/// @param conflict_id The ID of the conflict to resolve.
/// @param snapshot_id The ID of the snapshot to use for resolution.
/// @param metadata_change The metadata changes to apply to the snapshot, or
/// NULL for no changes.
/// @param contents The contents to resolve the conflict with.
/// @param callback Function to be called with result of asynchronous
/// operation. See PgsSnapshotsClient_OpenCallback.
/// @param user_data Arbitrary data pointer to be passed back to callback.
void PgsSnapshotsClient_resolveConflict(
    PgsSnapshotsClient* snapshots_client,
    const char* conflict_id,
    const char* snapshot_id,
    PgsSnapshotMetadataChange* metadata_change,
    PgsSnapshotContents* contents,
    PgsSnapshotsClient_OpenCallback callback,
    void* user_data);