قوائم الصدارة في ألعاب Unity

توضِّح هذه المواضيع كيفية استخدام قوائم الصدارة في "خدمات ألعاب Play" في ألعاب Unity.

قبل البدء

إعداد مشروع Unity وإضافة Google Play Games لـ Unity للاطّلاع على التفاصيل، يُرجى الاطّلاع على دليل البدء.

إنشاء أحداث

يمكنك إنشاء قوائم الصدارة في Google Play Console. لمعرفة التفاصيل، يُرجى الاطّلاع على دليل قوائم الصدارة لخدمات "ألعاب Play". بعد إنشاء قائمة صدارة، أضِف مورد 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"، لذا يجب تحويل عنصر 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- صالح: صحيح إذا كانت البيانات المعروضة صالحة (تم إكمال المكالمة بنجاح) 3. الحالة: ResponseStatus للمكالمة 4- ApproximateCount: العدد التقريبي للنتائج في لوحة الصدارة 5- العنوان: عنوان قائمة الصدارة 6. PlayerScore: نتيجة اللاعب الحالي 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 لطلب الوصول.

الحصول على أسماء اللاعبين

تحتوي كل نتيجة على userId الخاص باللاعب الذي سجّل النتيجة. يمكنك استخدام 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);
            });
    }