تابلوی امتیازات

این راهنما به شما نشان می‌دهد که چگونه از APIهای Leaderboards مربوط به Play Games Services c++ SDK برای ایجاد تابلوهای امتیازات بصری، ثبت امتیاز بازیکن و مقایسه امتیاز با امتیاز او در جلسات بازی قبلی استفاده کنید. APIها را می‌توانید در LeaderboardsClient پیدا کنید.

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

اگر هنوز این کار را نکرده‌اید، شاید مرور مفاهیم بازی‌های جدول امتیازات برایتان مفید باشد.

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

کلاینت جدول امتیازات را دریافت کنید

برای شروع استفاده از API مربوط به جدول امتیازات، بازی شما ابتدا باید یک شیء LeaderboardsClient دریافت کند. می‌توانید این کار را با فراخوانی متد PgsLeaderboardsClient_create() و ارسال activity به آن انجام دهید.

امتیاز بازیکن را به‌روزرسانی کنید

وقتی امتیاز بازیکن تغییر می‌کند (مثلاً وقتی بازی را تمام می‌کند)، بازی شما می‌تواند با فراخوانی PgsLeaderboardsClient_submitScoreImmediate امتیاز او را در جدول امتیازات به‌روزرسانی کند. شما باید شناسه‌ی جدول امتیازات، مقدار خام امتیاز، یک برچسب امتیاز اختیاری و یک تابع فراخوانی را ارسال کنید.

// Callback function to handle the result of submitting the score
void OnScoreSubmitted(PgsStatusCode status_code,
                      PgsScoreSubmissionData* score_submission_data,
                      void* user_data) {
  if (status_code == PGS_STATUS_SUCCESS) {
    // Score submitted successfully
    // You can inspect score_submission_data for details
    // Remember to release the data when done:
    PgsScoreSubmissionData_Release(score_submission_data);
  } else {
    // Handle error
  }
}

// Function to submit the score
void SubmitScore(PgsLeaderboardsClient* client, const char* leaderboard_id, int64_t score) {
  const char* score_tag = NULL; // Optional tag

  PgsLeaderboardsClient_submitScoreImmediate(
      client,
      leaderboard_id,
      score,
      score_tag,
      OnScoreSubmitted,
      NULL // user_data - optional context pointer
  );
}

// Example usage:
// Assuming 'my_leaderboard_id' is defined elsewhere, e.g., fetched from resources
// SubmitScore(leaderboards_client, my_leaderboard_id, 1337);

یک روش خوب این است که شناسه‌های جدول امتیازات خود را به عنوان ثابت یا منبع در کد c++ خود مدیریت کنید.

نمایش جدول امتیازات

برای نمایش رابط کاربری پیش‌فرض جدول امتیازات برای یک جدول امتیازات خاص، PgsLeaderboardsClient_showLeaderboardUI را فراخوانی کنید. این تابع به شناسه کلاینت، فعالیت، شناسه جدول امتیازات، بازه زمانی و جمع‌آوری و یک فراخوانی مجدد نیاز دارد.

// Callback function to handle the result of showing the UI
void OnShowLeaderboardUI(PgsStatusCode status_code, bool success, void* user_data) {
  if (status_code == PGS_STATUS_SUCCESS && success) {
    // UI was shown successfully
  } else {
    // Handle error or failure to show UI
  }
}

// Function to show a specific leaderboard UI
void ShowLeaderboard(PgsLeaderboardsClient* client, jobject activity, const char* leaderboard_id) {
  PgsLeaderboardsClient_showLeaderboardUI(
      client,
      activity,
      leaderboard_id,
      PGS_LEADERBOARD_TIME_SPAN_ALL_TIME, // Or PGS_LEADERBOARD_TIME_SPAN_DAILY, PGS_LEADERBOARD_TIME_SPAN_WEEKLY
      PGS_LEADERBOARD_COLLECTION_PUBLIC,  // Or PGS_LEADERBOARD_COLLECTION_FRIENDS
      OnShowLeaderboardUI,
      NULL // user_data - optional context pointer
  );
}

// Example usage:
// ShowLeaderboard(leaderboards_client, android_activity, my_leaderboard_id);

این تابع رابط کاربری (UI) را نمایش می‌دهد. شیء activity زمینه نمایش رابط کاربری را فراهم می‌کند.