Gespeicherte Spiele

In diesem Leitfaden erfahren Sie, wie Sie gespeicherte Spiele mit der Snapshots API implementieren, die von den Google Play Games-Diensten im C++ SDK bereitgestellt wird. Die APIs finden Sie in PgsSnapshotsClient.

Hinweis

• Informationen zur Funktion finden Sie unter Gespeicherte Spiele.

• Folgen Sie der Anleitung zum Installieren und Einrichten Ihrer App für die Verwendung der Google Play Games-Dienste im Leitfaden Google Play-Dienste einrichten.

• Definieren Sie die Unterstützung für gespeicherte Spiele für Ihr Spiel. Folgen Sie dazu der Anleitung im Leitfaden für die Google Play Console.

• Machen Sie sich mit den Empfehlungen der Qualitätscheckliste vertraut.

Snapshots-Client abrufen

Bevor Sie die Snapshots API verwenden können, muss Ihr Spiel zuerst ein PgsSnapshotsClient-Handle abrufen. Rufen Sie dazu die PgsSnapshotsClient_create() Methode auf und übergeben Sie die Android-Aktivität.

Hinweis:Die C++ SDK-Funktionen geben Ergebnisse asynchron über Callbacks zurück.

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

Gespeicherte Spiele anzeigen

Sie können die Snapshots API überall dort einbinden, wo Ihr Spiel Spielern die Möglichkeit bietet, ihren Fortschritt zu speichern oder wiederherzustellen. Um die Entwicklung zu vereinfachen, bietet die Snapshots API eine Standardschnittstelle für die Auswahl gespeicherter Spiele. Rufen Sie PgsSnapshotsClient_showSelectSnapshotUI auf, um diese Benutzeroberfläche zu starten.

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

Gespeicherte Spiele schreiben

So speichern Sie Inhalte in einem gespeicherten Spiel:

1. Öffnen Sie einen Snapshot asynchron mit PgsSnapshotsClient_open(). Geben Sie create_if_not_found als „true“ an, wenn Sie eine neue Speicherung erstellen möchten.
2. Das Ergebnis wird in der PgsSnapshotsClient_OpenCallback bereitgestellt. Wenn der Vorgang erfolgreich war und es keinen Konflikt gibt, erhalten Sie ein PgsSnapshot*.
3. Bereiten Sie die zu speichernden Daten als Bytearray (uint8_t*) vor.
4. Erstellen Sie ein PgsSnapshotMetadataChange*-Objekt, um die Speicherung zu beschreiben.

5. Rufen Sie PgsSnapshotsClient_commitAndClose auf, um die Änderungen an die Server von Google zu senden.

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

Gespeicherte Spiele laden

So rufen Sie gespeicherte Spiele ab:

1. Öffnen Sie den Snapshot asynchron nach Namen mit PgsSnapshotsClient_open().

2. Greifen Sie in PgsSnapshotsClient_OpenCallback auf die Daten zu, wenn der Vorgang erfolgreich war. Die API bietet eine Möglichkeit, die uint8_t*-Daten und die Größe abzurufen. Obwohl die Methode zum Lesen von Bytes aus PgsSnapshot oder einem zugehörigen PgsSnapshotContents in diesem Dokument nicht beschrieben wird.

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

Konflikte bei gespeicherten Spielen verarbeiten

Wenn der PgsSnapshotsClient_open Callback aufgerufen wird und der conflict Parameter nicht NULL ist, ist ein Konflikt aufgetreten. Verwenden Sie PgsSnapshotsClient_resolveConflict, um den Konflikt zu beheben.

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