Сохраненные игры

В этом руководстве показано, как реализовать сохранение игр с помощью API снимков, предоставляемого сервисами Google Play Games Services в C++ SDK. API можно найти в PgsSnapshotsClient .

Прежде чем начать

• Подробную информацию об этой функции см. в разделе «Сохраненные игры» .

• Следуйте инструкциям по установке и настройке вашего приложения для использования сервисов Google Play Games, приведенным в руководстве по настройке SDK сервисов Google Play .

• Настройте поддержку сохранений для вашей игры, следуя инструкциям в руководстве Google Play Console .

• Ознакомьтесь с рекомендациями, описанными в Контрольном списке качества .

Загрузите клиент для создания снимков.

Для начала использования 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);

Отображение сохраненных игр

Вы можете интегрировать API снимков прогресса везде, где ваша игра предоставляет игрокам возможность сохранять или восстанавливать свой прогресс. Для упрощения разработки API снимков предоставляет стандартный пользовательский интерфейс выбора сохраненных игр. Чтобы запустить этот интерфейс, вызовите метод 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() . Укажите 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() .

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