Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

保存済みゲーム

このガイドでは、C++ SDK で Google Play Games サービスが提供するスナップショット API を使用して保存済みゲームを実装する方法について説明します。API は PgsSnapshotsClient にあります。

始める前に

この機能の詳細については、保存済みゲームをご覧ください。
Google Play 開発者サービス SDK の設定ガイドに記載されている手順に沿って、アプリをインストールして Google Play Games サービスを使用できるように設定します。
Google Play Console ガイドの手順に沿って、ゲームの保存済みゲームのサポートを定義します。
品質チェックリストで説明されている推奨事項を確認します。

スナップショットクライアントを取得する

スナップショット API の使用を開始するには、まず PgsSnapshotsClient ハンドルを取得する必要があります。そのためには、PgsSnapshotsClient_create() メソッドを呼び出して Android アクティビティを渡します。

注: 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);

保存済みゲームを表示する

ゲームの進行状況を保存または復元するオプションをプレーヤーに提供する場合は、スナップショット API を統合できます。開発を簡素化するために、スナップショット API にはデフォルトの保存済みゲーム選択ユーザーインターフェース（UI）が用意されています。この 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);

保存済みゲームを作成する

保存済みゲームにコンテンツを保存するには:

PgsSnapshotsClient_open() を使用してスナップショットを非同期的に開きます。新しい保存を作成する場合は、create_if_not_found を true に指定します。
結果は PgsSnapshotsClient_OpenCallback で提供されます。成功し、競合がない場合は、PgsSnapshot* が返されます。
保存するデータをバイト配列（uint8_t*）として準備します。
保存を記述する PgsSnapshotMetadataChange* オブジェクトを作成します。

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
);
}

保存済みゲームを読み込む

保存済みゲームを取得するには:

PgsSnapshotsClient_open() を使用して、名前でスナップショットを非同期的に開きます。

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);

保存済みゲーム コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。