เพิ่มเกมที่บันทึกไว้ลงในเกม

หลังจากเลิกใช้งาน API ของ Google Sign-In แล้ว เราจะนำ SDK v1 ของเกมออกในปี 2026 หลังจากเดือนกุมภาพันธ์ 2025 คุณจะเผยแพร่ เกมที่เพิ่งผสานรวมกับ SDK v1 ของ Games ใน Google Play ไม่ได้ เราขอแนะนำให้ใช้ SDK v2 ของ Games แทน
แม้ว่าเกมที่มีอยู่ซึ่งผสานรวมกับเกมเวอร์ชัน 1 ก่อนหน้าจะยังคงทำงานได้อีก 2-3 ปี แต่เราขอแนะนำให้คุณย้ายข้อมูลไปยัง v2 ตั้งแต่เดือนมิถุนายน 2025 เป็นต้นไป
คู่มือนี้มีไว้สำหรับการใช้ SDK บริการเกมของ Play เวอร์ชัน 1 SDK สำหรับ C++ สำหรับ บริการเกมของ Play v2 ยังไม่พร้อมใช้งาน

คู่มือนี้จะแสดงวิธีบันทึกและโหลดข้อมูลความคืบหน้าของเกมของผู้เล่นโดยใช้ บริการเกมที่บันทึกไว้ในแอปพลิเคชัน C++ คุณใช้บริการนี้เพื่อโหลดและบันทึกความคืบหน้าของเกมของผู้เล่นโดยอัตโนมัติได้ทุกเมื่อ ในระหว่างการเล่นเกม นอกจากนี้ บริการนี้ยังช่วยให้ผู้เล่นเรียกใช้ อินเทอร์เฟซผู้ใช้เพื่ออัปเดตหรือกู้คืนเกมที่บันทึกไว้ที่มีอยู่ หรือสร้างเกมใหม่ได้ด้วย

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

หากยังไม่ได้ดำเนินการ คุณอาจต้องดูแนวคิดเกมที่บันทึกไว้

ก่อนที่จะเริ่มเขียนโค้ดโดยใช้ Saved Games API ให้ทำดังนี้

รูปแบบข้อมูลและความเข้ากันได้ข้ามแพลตฟอร์ม

ข้อมูลเกมที่บันทึกไว้ซึ่งคุณบันทึกลงในเซิร์ฟเวอร์ของ Google ต้องอยู่ในรูปแบบ std::vector<uint8_t> บริการเกมที่บันทึกไว้จะดูแลการเข้ารหัส ข้อมูลของคุณเพื่อความเข้ากันได้ข้ามแพลตฟอร์ม แอปพลิเคชัน Android สามารถอ่าน ข้อมูลเดียวกันนี้เป็นอาร์เรย์ไบต์ได้โดยไม่มีปัญหาด้านความเข้ากันได้ข้ามแพลตฟอร์ม

หลีกเลี่ยงการใช้รูปแบบเฉพาะแพลตฟอร์มเมื่อเลือกรูปแบบข้อมูลสำหรับ ข้อมูลเกมที่บันทึกไว้ เราขอแนะนำอย่างยิ่งให้คุณใช้รูปแบบข้อมูล เช่น XML หรือ JSON ซึ่งมีการรองรับไลบรารีที่แข็งแกร่งในหลายแพลตฟอร์ม

เปิดใช้บริการเกมที่บันทึกไว้

คุณต้องเปิดใช้สิทธิ์เข้าถึงบริการเกมที่บันทึกไว้ก่อนจึงจะใช้บริการนี้ได้ โดยให้โทรหา EnableSnapshots() เมื่อสร้างบริการด้วย gpg::GameServices::Builder ซึ่งจะเปิดใช้ขอบเขตการให้สิทธิ์เพิ่มเติม ที่เกมที่บันทึกไว้ต้องการในเหตุการณ์การให้สิทธิ์ครั้งถัดไป

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

ในเกม คุณสามารถระบุตัวเลือกที่ผู้เล่นสามารถเรียกใช้เพื่อบันทึกหรือ กู้คืนเกมที่บันทึกไว้ เมื่อผู้เล่นเลือกตัวเลือกนี้ เกมของคุณควรแสดงหน้าจอที่แสดงช่องบันทึกที่มีอยู่ และอนุญาตให้ผู้เล่นบันทึกหรือโหลดจากช่องใดช่องหนึ่งเหล่านี้ หรือสร้างเกมที่บันทึกไว้ใหม่ โดยใช้วิธีการต่อไปนี้

  SnapshotManager::ShowSelectUIOperation(...)

UI การเลือกเกมที่บันทึกไว้ช่วยให้ผู้เล่น สร้างเกมที่บันทึกไว้ใหม่ ดูรายละเอียดเกี่ยวกับเกมที่บันทึกไว้ที่มีอยู่ และโหลดเกมที่บันทึกไว้ก่อนหน้านี้ได้

  SnapshotManager::SnapshotSelectUIResponse response;
  if (IsSuccess(response.status)) {
  if (response.data.Valid()) {
    LogI("Description: %s", response.data.Description().c_str());
    LogI("FileName %s", response.data.FileName().c_str());
    //Opening the snapshot data
    …
  } else {
    LogI("Creating new snapshot");
    …
  }
} else {
  LogI("ShowSelectUIOperation returns an error %d", response.status);
}

ตัวอย่างต่อไปนี้แสดงวิธีเรียก UI เกมที่บันทึกไว้เริ่มต้น และจัดการการเลือก UI ของผู้เล่น

  service_->Snapshots().ShowSelectUIOperation(
  ALLOW_CREATE_SNAPSHOT,
  ALLOW_DELETE_SNAPSHOT,
  MAX_SNAPSHOTS,
  SNAPSHOT_UI_TITLE,
  [this](gpg::SnapshotManager::SnapshotSelectUIResponse const & response) {
  …
      }

หากในตัวอย่างข้างต้น ALLOW_CREATE_SNAPSHOT เป็น true และ MAX_SNAPSHOTS มากกว่าจำนวนสแนปชอตจริงที่ผู้ใช้สร้างขึ้นในปัจจุบัน UI สแนปชอตเริ่มต้นจะแสดงปุ่มให้ผู้เล่นสร้าง เกมที่บันทึกไว้ใหม่ แทนที่จะเลือกเกมที่มีอยู่ (เมื่อแสดง ปุ่ม จะอยู่ที่ด้านล่างของ UI) เมื่อผู้เล่นคลิกปุ่มนี้ SnapshotSelectUIResponseการตอบกลับจะใช้ได้แต่ไม่มีข้อมูล

เปิดและอ่านเกมที่บันทึกไว้

หากต้องการเข้าถึงเกมที่บันทึกไว้และอ่านหรือแก้ไขเนื้อหาของเกม ให้เปิดSnapshotMetadataออบเจ็กต์ที่แสดงเกมที่บันทึกไว้ก่อน จากนั้นเรียกใช้เมธอด SnapshotManager::Read*()

ตัวอย่างต่อไปนี้แสดงวิธีเปิดเกมที่บันทึกไว้

  LogI("Opening file");
  service_->Snapshots()
  .Open(current_snapshot_.FileName(),
               gpg::SnapshotConflictPolicy::BASE_WINS,
        [this](gpg::SnapshotManager::OpenResponse const & response) {
           LogI("Reading file");
           gpg::SnapshotManager::ReadResponse responseRead =
           service_->Snapshots().ReadBlocking(response.data);
          …
        }

ตรวจหาและแก้ไขความขัดแย้งของข้อมูล

เมื่อคุณเปิดออบเจ็กต์ SnapshotMetadata บริการเกมที่บันทึกไว้จะตรวจหา ว่ามีเกมที่บันทึกไว้ซึ่งขัดแย้งกันหรือไม่ ความขัดแย้งของข้อมูลอาจเกิดขึ้นเมื่อเกมที่บันทึกไว้ซึ่งจัดเก็บอยู่ในอุปกรณ์ในเครื่องของผู้เล่นไม่ซิงค์กับเวอร์ชันระยะไกลที่จัดเก็บไว้ในเซิร์ฟเวอร์ของ Google

นโยบายความขัดแย้งที่คุณระบุเมื่อเปิดเกมที่บันทึกไว้จะบอกบริการเกมที่บันทึกไว้ถึงวิธีแก้ไขความขัดแย้งของข้อมูลโดยอัตโนมัติ นโยบายอาจเป็นค่าใดค่าหนึ่งต่อไปนี้

นโยบายความขัดแย้ง คำอธิบาย
SnapshotConflictPolicy::MANUAL ระบุว่าบริการเกมที่บันทึกไว้ไม่ควรดำเนินการ การแก้ไข แต่เกมของคุณจะผสานที่กำหนดเองแทน
SnapshotConflictPolicy::LONGEST_PLAYTIME ระบุว่าบริการเกมที่บันทึกไว้ควรเลือก เกมที่บันทึกไว้ซึ่งมีค่าเวลาเล่นสูงสุด
SnapshotConflictPolicy::BASE_WINS ระบุว่าบริการเกมที่บันทึกไว้ควรเลือกเกมที่บันทึกไว้พื้นฐาน
SnapshotConflictPolicy::REMOTE_WINS ระบุว่าบริการเกมที่บันทึกไว้ควรเลือกเกมที่บันทึกไว้จากระยะไกล เวอร์ชันระยะไกลคือเวอร์ชันของเกมที่บันทึกไว้ซึ่งตรวจพบในอุปกรณ์เครื่องใดเครื่องหนึ่งของผู้เล่นและมี การประทับเวลาล่าสุดกว่าเวอร์ชันฐาน

หากคุณระบุนโยบายความขัดแย้งอื่นนอกเหนือจาก GPGSnapshotConflictPolicyManual บริการเกมที่บันทึกไว้จะผสานรวมเกมที่บันทึกไว้และส่งคืนเวอร์ชันที่อัปเดตแล้ว ผ่านค่า SnapshotManager::OpenResponse ที่ได้ เกมของคุณสามารถเปิดเกมที่บันทึกไว้ เขียนลงในเกม แล้วเรียกใช้เมธอด SnapshotManager::Commit(...) เพื่อส่งเกมที่บันทึกไว้ไปยังเซิร์ฟเวอร์ของ Google

ทำการผสานที่กำหนดเอง

หากคุณระบุ SnapshotConflictPolicy::MANUAL เป็นนโยบายความขัดแย้ง เกมของคุณต้องแก้ไขความขัดแย้งของข้อมูลที่ตรวจพบก่อนที่จะดำเนินการ อ่านหรือเขียนเพิ่มเติมในเกมที่บันทึกไว้

ในกรณีนี้ เมื่อตรวจพบข้อขัดแย้งของข้อมูล บริการจะแสดงพารามิเตอร์ต่อไปนี้ผ่าน SnapshotManager::OpenResponse

  • conflict_id เพื่อระบุความขัดแย้งนี้โดยไม่ซ้ำกัน (คุณจะใช้ค่านี้ เมื่อส่งเวอร์ชันสุดท้ายของเกมที่บันทึกไว้)
  • เวอร์ชันฐานที่ขัดแย้งกันของเกมที่บันทึกไว้ และ
  • เวอร์ชันระยะไกลที่ขัดแย้งกันของเกมที่บันทึกไว้

เกมของคุณต้องตัดสินใจว่าจะบันทึกข้อมูลใด จากนั้นเรียกใช้เมธอด SnapshotManager::ResolveConflictBlocking() เพื่อส่ง/แก้ไขเวอร์ชันสุดท้ายไปยังเซิร์ฟเวอร์ของ Google

    //Resolve conflict
    gpg::SnapshotManager::OpenResponse resolveResponse =
        manager.ResolveConflictBlocking(openResponse.conflict_base, metadata_change,
                                  openResponse.conflict_id);

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

หากต้องการเขียนเกมที่บันทึกไว้ ให้เปิดออบเจ็กต์ SnapshotMetadata ที่แสดงถึงเกมที่บันทึกไว้ก่อน แก้ไขความขัดแย้งของข้อมูลที่ตรวจพบ แล้วเรียกใช้เมธอด SnapshotManager::Commit() เพื่อบันทึกการเปลี่ยนแปลงเกมที่บันทึกไว้

ตัวอย่างต่อไปนี้แสดงวิธีสร้างการเปลี่ยนแปลงและคอมมิต เกมที่บันทึกไว้

  1. ก่อนอื่น ให้เปิดสแนปชอตที่ต้องการแก้ไข แล้วตรวจสอบว่าความขัดแย้งทั้งหมดได้รับการแก้ไขโดยเลือกฐาน

    service_->Snapshots().Open(
      file_name,
      gpg::SnapshotConflictPolicy::BASE_WINS,
      [this](gpg::SnapshotManager::OpenResponse const &response) {
        if (IsSuccess(response.status)) {
          // metadata : gpg::SnapshotMetadata
          metadata = response.data;
        } else {
          // Handle snapshot open error here
        }
      });

  2. จากนั้นสร้างการเปลี่ยนแปลงเกมที่บันทึกไว้ซึ่งมีข้อมูลรูปภาพที่ใช้สำหรับ ภาพปก

    gpg::SnapshotMetadataChange::Builder builder;
gpg::SnapshotMetadataChange metadata_change =
    builder.SetDescription("CollectAllTheStar savedata")
             .SetCoverImageFromPngData(pngData).Create();

  3. สุดท้าย ให้ยืนยันการเปลี่ยนแปลงเกมที่บันทึกไว้

    gpg::SnapshotManager::CommitResponse commitResponse =
    service_->Snapshots().CommitBlocking(metadata, metadata_change, SetupSnapshotData());

    พารามิเตอร์ข้อมูลมีข้อมูลเกมที่บันทึกไว้ทั้งหมดที่คุณจัดเก็บ การเปลี่ยนแปลงนี้ยังมีข้อมูลเมตาของเกมที่บันทึกไว้เพิ่มเติม เช่น เวลา ที่เล่นและคำอธิบายของเกมที่บันทึกไว้

หากการดำเนินการคอมมิตเสร็จสมบูรณ์ ผู้เล่นจะเห็น เกมที่บันทึกไว้ใน UI การเลือกเกมที่บันทึกไว้