เกมที่บันทึกไว้

คู่มือนี้จะแสดงวิธีติดตั้งใช้งานเกมที่บันทึกไว้โดยใช้ Snapshots API ที่บริการเกมของ Google Play มีให้ใน C++ SDK คุณสามารถดู API ได้ ใน PgsSnapshotsClient.

ก่อนเริ่มต้น

• ดูข้อมูลเกี่ยวกับฟีเจอร์นี้ได้ที่ เกมที่บันทึกไว้

• ทำตามวิธีการติดตั้งและตั้งค่าแอปให้ใช้ บริการเกมของ Google Play ใน คู่มือการตั้งค่า SDK ของบริการ Google Play

• กำหนดการรองรับเกมที่บันทึกไว้สำหรับเกมของคุณโดย ทำตามวิธีการใน คู่มือ Google Play Console

• ทำความคุ้นเคยกับคำแนะนำที่อธิบายไว้ใน รายการตรวจสอบคุณภาพ

รับไคลเอ็นต์ Snapshots

หากต้องการเริ่มใช้ Snapshots 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);

แสดงเกมที่บันทึกไว้

คุณสามารถผสานรวม Snapshots API ได้ทุกที่ที่เกมมีตัวเลือกให้ผู้เล่นบันทึกหรือกู้คืนความคืบหน้า Snapshots 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);

เขียนเกมที่บันทึกไว้

วิธีจัดเก็บเนื้อหาลงในเกมที่บันทึกไว้

1. เปิดสแนปชอตแบบอะซิงโครนัสโดยใช้ PgsSnapshotsClient_open() ระบุ create_if_not_found เป็นจริงหากต้องการสร้างการบันทึกใหม่
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);