بازی های ذخیره شده

این راهنما به شما نشان می‌دهد که چگونه بازی‌های ذخیره شده را با استفاده از API اسنپ‌شات‌های ارائه شده توسط سرویس‌های بازی‌های گوگل پلی در C++ SDK پیاده‌سازی کنید. این APIها را می‌توانید در PgsSnapshotsClient پیدا کنید.

قبل از اینکه شروع کنی

کلاینت اسنپ‌شات‌ها را دریافت کنید

برای شروع استفاده از API مربوط به snapshots، بازی شما ابتدا باید یک شناسه 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 مربوط به snapshots را در هر جایی که بازی شما به بازیکنان امکان ذخیره یا بازیابی پیشرفتشان را می‌دهد، ادغام کنید. برای ساده‌سازی توسعه، API snapshots یک رابط کاربری (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 را فراخوانی کنید.

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