لوحات الصدارة

ترتّب لوحة الصدارة اللاعبين حسب إحصائية رقمية — أعلى نتيجة، أو أسرع زمن، أو نقاط الموسم. ولوحات الصدارة في Flock مبنية على الإعدادات: توجّه اللوحة إلى حقل تكتبه لعبتك أصلًا عبر بيانات اللاعب، وتتولّى Flock الترتيب من هناك. ولا يوجد استدعاء منفصل لإرسال النتائج.

النطاق: تُعرَّف لوحات الصدارة لكل لعبة؛ وكل مدخل فيها يخصّ لاعبًا.

لوحة التحكم
Unity
Unreal

أنشئ لوحات الصدارة وأدرها من إدارة اللاعبين ← لوحات الصدارة. وتُعرَّف لوحة الصدارة بما يلي:

المصدر — قالب اللاعب والحقل الرقمي الذي يجري الترتيب حسبه.
الاتجاه — هل القيم الأعلى أفضل ترتيبًا أم الأدنى (النقاط مقابل أزمنة اللفّات).
التجميع — الاحتفاظ بقيمة اللاعب الأفضل، أو الأحدث، أو المجموع التراكمي.
نوع القيمة — عدد صحيح، أو عدد عشري، أو مدّة زمنية.
النافذة الزمنية — كل الأوقات، أو أسبوعية، أو موسمية. وتتبع اللوحات الموسمية المواسم التي تعرّفها إلى جانبها، ولكل موسم تاريخ بداية ونهاية.
النطاق — لوحة عالمية واحدة، أو ترتيب لكل دولة.

ومن الصفحة نفسها تستطيع إدارة لوحة نشطة: استبعاد لاعب (ورفع الاستبعاد لاحقًا)، أو إعادة تعيين لوحة، أو تعبئتها بأثر رجعي من بيانات اللاعبين التي كتبتها لعبتك بالفعل.

التعريف البنيوي للوحة الصدارة — مصدرها وطريقة ترتيبها — يُقفل بمجرّد أن تصبح اللوحة نشطة. ولترتيب شيء آخر، أنشئ لوحة صدارة جديدة.

تتدفّق النتائج تلقائيًا: فحين تكتب لعبتك الحقل المُعرَّف عبر بيانات اللاعب، تلتقط لوحات الصدارة المعنية التغيير — الأفضل أو الأحدث أو المجموع، بحسب أسلوب التجميع لديك. فإن كنت تتعقّب الإحصائية أصلًا، فليس هناك جديد ترسله.ويُشار إلى اللوحات بـالاسم — الاسم نفسه الذي أعطيته للوحة في لوحة التحكم.

// صدارة اللوحة.
Standings top = await FlockClient.Instance.Leaderboard.GetStandingsAsync("weekly_score", limit: 20);
foreach (StandingEntry entry in top.Items)
    Debug.Log($"#{entry.Rank} {entry.PlayerName} — {entry.Score}");

// رتبة اللاعب المسجَّل دخوله، ومن حوله من اللاعبين.
PlayerRank mine = await FlockClient.Instance.Leaderboard.GetMyRankAsync("weekly_score");
Standings neighbours = await FlockClient.Instance.Leaderboard.GetAroundMeAsync("weekly_score", neighbours: 5);

وتُعيد GetByNameAsync إعدادات اللوحة — نوع القيمة والاتجاه والتجميع ونوع النافذة والنطاق — حين تحتاج إلى تنسيق النتائج أو عنونة الواجهة على نحو صحيح.النوافذ الزمنية. كل قراءة تستخدم افتراضيًا نافذة اللوحة النشطة. مرّر FlockLeaderboardWindow.Season("season-id") لموسم منتهٍ، أو FlockLeaderboardWindow.Period("2026-W31") لفترة أسبوعية بعينها. أما اللوحات المقسّمة حسب الدولة فتأخذ وسيط country في الاستدعاءات نفسها.تسجيل الدخول. تعمل GetStandingsAsync وGetByNameAsync دون تسجيل دخول — فالترتيب عام. أما GetMyRankAsync وGetAroundMeAsync فتتطلّبان لاعبًا مسجَّل الدخول وترميان استثناءً بدونه.وحقلا PlayerRank.Rank و.Score قابلان لأن يكونا null: يعودان كذلك حين لا يكون للاعب مدخل في تلك اللوحة بعد، وهذا ليس خطأ.النتائج المرفوضة. قد ترفض لوحةٌ نتيجةً مع أن الكتابة نجحت. وتسرد إجابة الكتابة تلك اللوحات في LeaderboardRefusals، لكلٍّ منها LeaderboardName وReason (LeaderboardRefusalReasons.ScoreBounds: خارج ما تقبله اللوحة؛ GainLimit: مكاسب اللاعب الأخيرة تملأ حصّتها) وRetryable وRetryAfterSeconds. ولا تُبلغ عنها إلا UpdatePlayerDataAsync وUpdatePlayerDataFieldAsync، فالقائمة الفارغة في غيرهما تعني «لم يُبلَغ عنها هنا» لا «قُبلت».

UFlockSubsystem* Sdk = UFlockSubsystem::Get(this);
FFlockLeaderboardProvider* Boards = Sdk->GetLeaderboardProvider();

// صدارة اللوحة.
Boards->GetStandings(TEXT("weekly_score"),
    [](TFlockResult<FFlockStandings> Top)
    {
        for (const FFlockStandingEntry& Entry : Top.Value.Items)
        {
            UE_LOG(LogTemp, Log, TEXT("#%d %s"), Entry.Rank, *Entry.PlayerName);
        }
    });

// رتبة اللاعب المسجَّل دخوله، ومن حوله من اللاعبين.
Boards->GetMyRank(TEXT("weekly_score"), [](TFlockResult<FFlockPlayerRank> Mine) {});
Boards->GetAroundMe(TEXT("weekly_score"), [](TFlockResult<FFlockStandings> Neighbours) {});

وتُعيد GetByName إعدادات اللوحة — نوع القيمة والاتجاه والتجميع ونوع النافذة والنطاق — حين تحتاج إلى تنسيق النتائج أو عنونة الواجهة على نحو صحيح. وتعرض FormatScore لوحةَ المدّة كساعة بدل الثواني الخام.وفي البلوبرنت تجد الاستدعاءات نفسها باسم Flock Get Leaderboard وFlock Get Leaderboard Standings وFlock Get My Rank وFlock Get Standings Around Me، ضمن Flock | Leaderboard.النوافذ الزمنية. كل قراءة تستخدم افتراضيًا نافذة اللوحة النشطة. مرّر FFlockLeaderboardWindow::Season("season-id") لموسم منتهٍ، أو FFlockLeaderboardWindow::Period("2026-W31") لفترة أسبوعية بعينها. أما اللوحات المقسّمة حسب الدولة فتأخذ وسيط الدولة في الاستدعاءات نفسها.تسجيل الدخول. تعمل GetStandings وGetByName دون تسجيل دخول — فالترتيب عام. أما GetMyRank وGetAroundMe فتتطلّبان لاعبًا مسجَّل الدخول وتفشلان بدونه.ويحمل FFlockPlayerRank الرايةَ Ranked: تكون false حين لا يكون للاعب مدخل في تلك اللوحة بعد، وهي نتيجة صحيحة لا خطأ. تحقّق منها قبل قراءة Rank أو Score.النتائج المرفوضة. قد ترفض لوحةٌ نتيجةً مع أن الكتابة نجحت. وتسرد إجابة الكتابة تلك اللوحات في LeaderboardRefusals، لكلٍّ منها LeaderboardName وReason (score_bounds: خارج ما تقبله اللوحة؛ gain_limit: مكاسب اللاعب الأخيرة تملأ حصّتها؛ قارن بعُقد Flock Refusal Reason أو FlockLeaderboardRefusalReasons) وRetryable وRetryAfterSeconds (‏-1 حين لا يحدّد الخادم مدة). ولا تُبلغ عنها إلا Update Player Data وUpdate Player Data Field، فالقائمة الفارغة في غيرهما تعني «لم يُبلَغ عنها هنا» لا «قُبلت».

اقرن لوحة صدارة موسمية بـشريحة من أفضل لاعبيك لمكافأتهم عند انتهاء الموسم.

بدء الاستخدام

المفاهيم

حزم التطوير

الميزات

اللعب الجماعي

المرجع

لوحات الصدارة