Kaydedilmiş oyunlar

Bu kılavuzda, C++ SDK'sında Google Play Games Hizmetleri tarafından sağlanan anlık görüntüler API'si kullanılarak kayıtlı oyunların nasıl uygulanacağı gösterilmektedir. API'leri PgsSnapshotsClient içinde bulabilirsiniz.

Başlamadan önce

Anlık görüntüler istemcisini edinme

Anlık görüntüler API'sini kullanmaya başlamak için oyununuzun önce PgsSnapshotsClient tanıtıcısı alması gerekir. Bunu, Android etkinliğini ileterek PgsSnapshotsClient_create() yöntemini çağırarak yapabilirsiniz.

Not: C++ SDK işlevleri, geri çağırmalar aracılığıyla sonuçları eşzamansız olarak döndürür.

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

Kayıtlı oyunları görüntüleme

Anlık görüntüler API'sini, oyununuzda oyunculara ilerleme durumlarını kaydetme veya geri yükleme seçeneği sunulan her yere entegre edebilirsiniz. Anlık görüntüler API'si, geliştirmeyi basitleştirmek için varsayılan bir kayıtlı oyun seçimi kullanıcı arayüzü (UI) sağlar. Bu kullanıcı arayüzünü başlatmak için PgsSnapshotsClient_showSelectSnapshotUI işlevini çağırın.

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

Kayıtlı oyunları yazma

İçeriği kayıtlı oyuna depolamak için:

  1. PgsSnapshotsClient_open() kullanarak bir anlık görüntüyü eşzamansız olarak açın. Yeni bir kayıt oluşturmak istiyorsanız create_if_not_found değerini doğru olarak belirtin.
  2. Sonuç, PgsSnapshotsClient_OpenCallback dilinde sağlanır. İşlem başarılı olursa ve çakışma yoksa PgsSnapshot* simgesini görürsünüz.
  3. Bayt dizisi (uint8_t*) olarak kaydetmek istediğiniz verileri hazırlayın.
  4. Kaydetme işlemini açıklamak için PgsSnapshotMetadataChange* nesnesi oluşturun.

  5. Değişiklikleri Google'ın sunucularına göndermek için PgsSnapshotsClient_commitAndClose'ı arayın.

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

Kayıtlı oyunları yükleme

Kayıtlı oyunları almak için:

  1. PgsSnapshotsClient_open() kullanarak anlık görüntüyü ada göre eşzamansız olarak açın.

  2. Başarılı olursa PgsSnapshotsClient_OpenCallback içinde verilere erişin. API, uint8_t* verilerini ve boyutunu almanın bir yolunu sunar. Ancak PgsSnapshot veya ilişkili bir PgsSnapshotContents'den bayt okuma yöntemi bu belgede ayrıntılı olarak açıklanmamıştır.

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

Kaydedilmiş oyun çakışmalarını yönetme

PgsSnapshotsClient_open geri çağırma işlevi çağrıldığında conflict parametresi NULL değilse çakışma oluşmuştur. Çakışmayı gidermek için conflict kullanın.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);