לוחות לידרבורד במשחקי Unity

כאן מוסבר איך להשתמש בלידרבורד של Play Games Services ב-Unity משחקים.

לפני שמתחילים

מגדירים את הפרויקט ב-Unity ואת הפלאגין של Google Play Games ל-Unity. עבור פרטים נוספים זמינים במדריך לתחילת העבודה.

יצירת אירועים

אתם יוצרים לוחות הישגי השחקנים המובילים ב-Google Play Console. פרטים נוספים זמינים במאמר מדריך ללוחות הישגי השחקנים המובילים עבור Play Games Services. אחרי שיוצרים לידרבורד, מוסיפים את מקור המידע שלו ב-Android לפלאגין כפי שמתואר המדריך לתחילת העבודה.

פרסום תוצאה בלידרבורד

כדי לפרסם ציון בלוח הישגי השחקנים המובילים, קוראים לפונקציה Social.ReportScore.

    using GooglePlayGames;
    using UnityEngine.SocialPlatforms;
    ...
    // Post score 12345 to leaderboard ID "Cfji293fjsie_QA")
    Social.ReportScore(12345, "Cfji293fjsie_QA", (bool success) => {
        // Handle success or failure
    });

כדי לפרסם ציון ולכלול תג מטא-נתונים, צריך להשתמש במופע של PlayGamesPlatform ישירות:

    using GooglePlayGames;
    using UnityEngine.SocialPlatforms;
    ...
    // Post score 12345 to leaderboard ID "Cfji293fjsie_QA" and tag "FirstDaily")
    PlayGamesPlatform.Instance.ReportScore(12345, "Cfji293fjsie_QA", "FirstDaily", (bool success) => {
        // Handle success or failure
    });

שימו לב שהפלטפורמה והשרת יבטלו באופן אוטומטי ציונים נמוכה מהניקוד הגבוה הקיים של השחקן, כך שאפשר לשלוח את הניקוד באופן חופשי ללא בדיקות כדי לבדוק אם התוצאה גבוהה מזו של השחקן דירוג קיים.

הצגת ממשק המשתמש של הלידרבורד

כדי להציג את ממשק המשתמש המובנה של כל לוחות הלידרבורד, קוראים לפונקציה Social.ShowLeaderboardUI.

    using GooglePlayGames;
    using UnityEngine.SocialPlatforms;
    ...
    // Show leaderboard UI
    Social.ShowLeaderboardUI();

אם ברצונך להציג לוח הישגי השחקנים המובילים במקום את כל לוחות הלידרבורד יכול להעביר ל-method מזהה Leaderboard. עם זאת, מדובר ב-Play Games לכן צריך להמיר את האובייקט Social.Active אל PlayGamesPlatform האובייקט הראשון:

    using GooglePlayGames;
    using UnityEngine.SocialPlatforms;
    ...
    // Show leaderboard UI
    PlayGamesPlatform.Instance.ShowLeaderboardUI("Cfji293fjsie_QA");

גישה לנתוני הלידרבורד

יש 2 שיטות לאחזור נתוני הניקוד בלידרבורד.

שימוש ב-Social.ILeaderboard

שיטה זו משתמשת בממשק ILeaderboard כדי להגדיר את ההיקף והמסננים לקבלת הנתונים. הגישה הזו מאפשרת לכם להגדיר: 1. מזהה הלידרבורד 2. האוסף (חברתי או ציבורי) 3. מסגרת הזמן (יומי, שבועי, כל הזמן) 4. מיקום הדירוג לצורך התחלת אחזור הניקוד. 5. מספר הציונים (ברירת המחדל היא 25). 6. סינון לפי מזהה משתמש.

אם הפרמטר 'מאת' לא חיובי, התוצאות שמוחזרות ממוקד-שחקן, כלומר התוצאות שמתקבלות סביב התוצאה של השחקן הנוכחי הוחזרו.

    ILeaderboard lb = PlayGamesPlatform.Instance.CreateLeaderboard();
    lb.id = "MY_LEADERBOARD_ID";
    lb.LoadScores(ok =>
        {
            if (ok) {
                LoadUsersAndDisplay(lb);
            }
            else {
                Debug.Log("Error retrieving leaderboardi");
            }
        });

שימוש ב-PlayGamesPlatform.LoadScores()

השיטה הזו משתמשת ישירות ב-PlayGamesPlatform, ומספקת עוד גמישות ומידע כשניגשים לנתוני הלידרבורד.

    PlayGamesPlatform.Instance.LoadScores(
            GPGSIds.leaderboard_leaders_in_smoketesting,
            LeaderboardStart.PlayerCentered,
            100,
            LeaderboardCollection.Public,
            LeaderboardTimeSpan.AllTime,
            (data) =>
            {
                mStatus = "Leaderboard data valid: " + data.Valid;
                mStatus += "\n approx:" +data.ApproximateCount + " have " + data.Scores.Length;
            });

הפרמטרים של LoadScores() הם:

1. מזהה Leaderboard
2. נקודת התחלה (תוצאות מובילות או שחקן במרכז)
3. מספר שורות
4. אוסף לוחות הישגי השחקנים המובילים (חברתי או ציבורי)
5. טווח זמן (יומי, שבועי, כל הזמן)
6. קריאה חוזרת (callback) לקבלת אובייקט LeaderboardScoreData.

המחלקה LeaderboardScoreData משמשת להחזרת מידע בזמן טעינת הניקוד. החברים הם: 1. מזהה - מזהה הלידרבורד 2. חוקי – true אם הנתונים שהוחזרו תקינים (השיחה בוצעה בהצלחה) 3. סטטוס - סטטוס התגובה של השיחה 4. ApproxateCount – מספר התוצאות המשוער בלידרבורד 5. כותרת – שם הלידרבורד 6. תוצאת השחקן – התוצאה של השחקן הנוכחי 7. ציונים – רשימת התוצאות 8. PrevPageToken – אסימון שניתן להשתמש בו כדי לקרוא ל-LoadMoreScores() אל מקבלים את דף הציונים הקודם. 9. NextPageToken – אסימון שניתן להשתמש בו כדי לקרוא ל-LoadMoreScores() אל את דף הציונים הבא.

    void GetNextPage(LeaderboardScoreData data)
    {
        PlayGamesPlatform.Instance.LoadMoreScores(data.NextPageToken, 10,
            (results) =>
            {
                mStatus = "Leaderboard data valid: " + data.Valid;
                mStatus += "\n approx:" +data.ApproximateCount + " have " + data.Scores.Length;
            });
    }

השיחה עלולה להיכשל בניסיון לטעון חברים באמצעות ResponseCode.ResolutionRequired אם המשתמש לא שיתף את רשימת החברים שלו עם המשחק. במקרה הזה, משתמשים ב-AskForLoadFriendsResolution כדי לבקש גישה.

אחזור של שמות שחקנים

לכל ניקוד יש מזהה משתמש של השחקן שקיבל את הניקוד. אפשר להשתמש Social.LoadUsers() כדי לטעון את פרופיל השחקן. חשוב לזכור שהתוכן של פרופיל השחקן, כפופים להגדרות הפרטיות של הנגנים.

    internal void LoadUsersAndDisplay(ILeaderboard lb)
    {
        // Get the user ids
        List<string> userIds = new List<string>();

        foreach(IScore score in lb.scores) {
            userIds.Add(score.userID);
        }
        // Load the profiles and display (or in this case, log)
        Social.LoadUsers(userIds.ToArray(), (users) =>
            {
                string status = "Leaderboard loading: " + lb.title + " count = " +
                    lb.scores.Length;
                foreach(IScore score in lb.scores) {
                    IUserProfile user = FindUser(users, score.userID);
                    status += "\n" + score.formattedValue + " by " +
                        (string)(
                            (user != null) ? user.userName : "**unk_" + score.userID + "**");
                }
                Debug.log(status);
            });
    }