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

אם רוצים להציג לידרבורד מסוים במקום את כל הלידרבורדים, אפשר להעביר מזהה לידרבורד לשיטה. עם זאת, מדובר בתוסף של 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. סינון לפי מזהה משתמש.

אם הפרמטר 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);
            });
    }