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

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

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

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

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

אתם יוצרים את לוחות הדירוג ב-Google Play Console. לפרטים נוספים, קראו את המדריך למצעדים המובילים בשירותי Play Games. אחרי שיוצרים טבלת באז, מוסיפים את המשאב שלה ל-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();

אם רוצים להציג לידרבורד מסוים במקום את כל הלידרבורדים, אפשר להעביר למתודה מזהה לידרבורד. עם זאת, זהו תוסף של Play Games, ולכן צריך קודם להמיר את האובייקט Social.Active לאובייקט PlayGamesPlatform:

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

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

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

שימוש ב-Social.ILeaderboard

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

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

    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. leaderboardId
2. מיקום ההתחלה (הציונים הגבוהים ביותר או ממוקד שחקן)
3. מספר השורות
4. אוסף לידרבורד (רשת חברתית או ציבורי)
5. טווח זמן (יומי, שבועי, מכל הזמנים)
6. פונקציית קריאה חוזרת שמקבלת אובייקט LeaderboardScoreData.

הכיתה LeaderboardScoreData משמשת להחזרת מידע לשולח כשמאתחלים ציונים. החברים הם: 1. מזהה – מזהה הלידרבורד 2. תקין – true אם הנתונים המוחזרים תקינים (הקריאה בוצעה בהצלחה) 3. סטטוס – ResponseStatus של הקריאה 4. ApproximateCount – המספר המשוער של תוצאות הניקוד בלידרבורד 5. Title – שם לוח הבקרה 6. PlayerScore – הציון של השחקן הנוכחי 7. Scores – רשימת הציונים 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);
            });
    }