این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

اضافه کردن بازی های ذخیره شده به بازی شما

این راهنما به شما نشان می‌دهد که چگونه داده‌های پیشرفت بازی بازیکن را با استفاده از سرویس بازی‌های ذخیره شده در یک برنامه ++C ذخیره و بارگذاری کنید. شما می توانید از این سرویس برای بارگیری خودکار و ذخیره پیشرفت بازی بازیکن در هر نقطه از گیم پلی استفاده کنید. این سرویس همچنین می‌تواند به بازیکنان اجازه دهد تا یک رابط کاربری برای به‌روزرسانی یا بازیابی یک بازی ذخیره موجود یا ایجاد یک بازی جدید فعال کنند.

قبل از شروع

اگر قبلاً این کار را نکرده‌اید، مرور مفاهیم بازی‌های ذخیره‌شده برایتان مفید است.

قبل از اینکه شروع به کدنویسی با استفاده از Saved Games API کنید:

فرمت های داده و سازگاری بین پلتفرم

داده های ذخیره شده بازی ها که در سرورهای Google ذخیره می کنید باید در قالب std::vector<uint8_t> باشند. سرویس بازی های ذخیره شده از رمزگذاری داده های شما برای سازگاری بین پلتفرم مراقبت می کند. برنامه‌های Android می‌توانند در همین داده‌ها به‌عنوان یک آرایه بایتی بدون هیچ مشکلی در سازگاری بین پلتفرم‌ها بخوانند.

هنگام انتخاب قالب داده برای داده های بازی های ذخیره شده خود، از قالب های خاص پلت فرم خودداری کنید. ما قویاً شما را تشویق می کنیم که از قالب داده ای مانند XML یا JSON استفاده کنید که از کتابخانه قوی در چندین پلت فرم پشتیبانی می کند.

فعال کردن سرویس بازی های ذخیره شده

قبل از اینکه بتوانید از سرویس بازی های ذخیره شده استفاده کنید، ابتدا باید دسترسی به آن را فعال کنید. برای انجام این کار، هنگام ایجاد سرویس با gpg::GameServices::Builder ، EnableSnapshots() را فراخوانی کنید. با این کار حوزه‌های احراز هویت اضافی مورد نیاز بازی‌های ذخیره‌شده در رویداد تأیید اعتبار بعدی فعال می‌شود.

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

در بازی خود، می‌توانید گزینه‌ای را ارائه کنید که بازیکنان می‌توانند آن را برای ذخیره یا بازیابی بازی‌های ذخیره شده فعال کنند. وقتی بازیکنان این گزینه را انتخاب می‌کنند، بازی شما باید صفحه‌ای را نمایش دهد که اسلات‌های ذخیره موجود را نشان می‌دهد و به بازیکنان اجازه می‌دهد در یکی از این اسلات‌ها ذخیره یا بارگیری کنند یا یک بازی ذخیره‌شده جدید ایجاد کنند. برای این کار از روش زیر استفاده کنید:

  SnapshotManager::ShowSelectUIOperation(...)

رابط کاربری انتخاب بازی‌های ذخیره‌شده به بازیکنان اجازه می‌دهد یک بازی ذخیره‌شده جدید ایجاد کنند، جزئیات بازی‌های ذخیره‌شده موجود را مشاهده کنند و بازی‌های ذخیره قبلی را بارگیری کنند.

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

مثال زیر نشان می‌دهد که چگونه می‌توان رابط کاربری پیش‌فرض بازی‌های ذخیره‌شده را نمایش داد و با انتخاب رابط کاربری بازیکن مدیریت کرد:

  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 بیشتر از تعداد واقعی عکس‌های فوری است که کاربر در حال حاضر ایجاد کرده است، رابط کاربری پیش‌فرض Snapshot به جای انتخاب بازی موجود، دکمه‌ای برای ایجاد یک بازی ذخیره جدید در اختیار بازیکنان قرار می‌دهد. (هنگامی که نمایش داده می شود، دکمه در پایین رابط کاربری قرار دارد.) وقتی بازیکنی روی این دکمه کلیک می کند، پاسخ 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() را فراخوانی کنید تا تغییرات بازی ذخیره شده خود را انجام دهید.

مثال زیر نشان می دهد که چگونه می توانید یک تغییر ایجاد کنید و یک بازی ذخیره شده را انجام دهید.

ابتدا snapshotی را که می خواهیم ویرایش کنیم باز کنید و مطمئن شوید که تمام تداخل ها با انتخاب پایه حل شده اند.

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

در مرحله بعد، یک تغییر ذخیره شده در بازی ایجاد کنید که شامل داده های تصویر استفاده شده برای تصویر جلد است:

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

در نهایت، تغییرات ذخیره شده بازی را انجام دهید.
```
gpg::SnapshotManager::CommitResponse commitResponse =
    service_->Snapshots().CommitBlocking(metadata, metadata_change, SetupSnapshotData());
```
پارامتر داده شامل تمام داده های ذخیره بازی است که ذخیره می کنید. این تغییر همچنین حاوی فراداده‌های ذخیره‌شده بازی است، مانند زمان بازی و توضیحاتی برای بازی ذخیره‌شده.

اگر عملیات commit با موفقیت انجام شود، بازیکنان می توانند بازی ذخیره شده را در رابط کاربری انتخاب بازی های ذخیره شده ببینند.