לוחות לידרבורד במשחקי 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");

גישה לנתוני טבלת הבאז

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

שימוש ב-Social.ILeaderboard

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

אם הפרמטר 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. Id - the leaderboard id
2. Valid - true if the returned data is valid (the call was successful)
3. Status - the ResponseStatus of the call
4. ApproximateCount - the approximate number of scores in the leaderboard
5. Title - the title of the leaderboard
6. PlayerScore - the score of the current player
7. Scores - the list of scores
8. PrevPageToken - a token that can be used to call `LoadMoreScores()` to
    get the previous page of scores.
9. NextPageToken - a token that can be used to call `LoadMoreScores()` to
    get the next page of scores.

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