> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwacks.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> رتّب اللاعبين حسب أي إحصائية رقمية تتعقّبها لعبتك أصلًا.

export const Scope = ({children}) => <Info>
    <b>النطاق:</b> {children}
  </Info>;

ترتّب **لوحة الصدارة** اللاعبين حسب إحصائية رقمية — أعلى نتيجة، أو أسرع زمن، أو نقاط الموسم.
ولوحات الصدارة في Flock **مبنية على الإعدادات**: توجّه اللوحة إلى حقل تكتبه لعبتك أصلًا عبر
[بيانات اللاعب](/ar/guides/player-data)، وتتولّى Flock الترتيب من هناك. ولا يوجد استدعاء منفصل
لإرسال النتائج.

<Scope>تُعرَّف لوحات الصدارة لكل **لعبة**؛ وكل مدخل فيها يخصّ لاعبًا.</Scope>

<Tabs>
  <Tab title="لوحة التحكم">
    أنشئ لوحات الصدارة وأدرها من **إدارة اللاعبين ← لوحات الصدارة**. وتُعرَّف لوحة الصدارة بما
    يلي:

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

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

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

  <Tab title="Unity">
    تتدفّق النتائج تلقائيًا: فحين تكتب لعبتك الحقل المُعرَّف عبر
    [بيانات اللاعب](/ar/guides/player-data)، تلتقط لوحات الصدارة المعنية التغيير — الأفضل أو
    الأحدث أو المجموع، بحسب أسلوب التجميع لديك. فإن كنت تتعقّب الإحصائية أصلًا، فليس هناك جديد
    ترسله.

    ويُشار إلى اللوحات بـ**الاسم** — الاسم نفسه الذي أعطيته للوحة في لوحة التحكم.

    ```csharp theme={null}
    // صدارة اللوحة.
    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`: يعودان كذلك حين لا يكون للاعب
    مدخل في تلك اللوحة بعد، وهذا ليس خطأ.
  </Tab>

  <Tab title="Unreal">
    تتدفّق النتائج تلقائيًا: فحين تكتب لعبتك الحقل المُعرَّف عبر
    [بيانات اللاعب](/ar/guides/player-data)، تلتقط لوحات الصدارة المعنية التغيير — الأفضل أو
    الأحدث أو المجموع، بحسب أسلوب التجميع لديك. فإن كنت تتعقّب الإحصائية أصلًا، فليس هناك جديد
    ترسله.

    ويُشار إلى اللوحات بـ**الاسم** — الاسم نفسه الذي أعطيته للوحة في لوحة التحكم.

    ```cpp theme={null}
    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`.
  </Tab>
</Tabs>

اقرن لوحة صدارة موسمية بـ[شريحة](/ar/guides/segments) من أفضل لاعبيك لمكافأتهم عند انتهاء
الموسم.