# Ranking

{% hint style="info" %}
🚀 **Premium Feature**: The Ranking component is a premium feature that requires an upgraded UFOLab subscription to use in your games.
{% endhint %}

The **Ranking** component displays game rankings and leaderboards, allowing you to showcase top performers and create competitive experiences. It automatically fetches and displays player scores and completion times, making it perfect for games where competition and achievement matter.

## Overview

The Ranking component creates a dynamic leaderboard that pulls real gameplay data from your game. Players can see where they stand compared to others, view top performers, and track their progress over time. With extensive customization options, you can control what information is displayed, how many entries appear, and even filter rankings by date ranges.

## How to Add a Ranking Component

1. Open your game in the UFOLab editor
2. Navigate to the **Components** section in the component picker
3. Select **Ranking** from the static components
4. Drag and drop it onto your scene

## Configuration Settings

Click on your Ranking component to access the configuration options, organized into two tabs: **General** and **Display**.

### General Settings

#### Number of Rows

* **Default**: `10`
* **Range**: 1-100 entries
* Controls how many ranking entries are displayed
* **Tip**: Start with 10-20 entries for optimal readability

#### Show Anonymous Users

* **Default**: `false`
* When `true`: Includes anonymous players in the ranking
* When `false`: Shows only named players
* **Best Practice**: Enable this if you want to show all participation, disable for cleaner professional leaderboards

#### Enable Pagination

* **Default**: `false`
* When `true`: Adds navigation buttons to browse through multiple pages
* When `false`: Shows only the first set of entries
* **Use Case**: Enable for games with many participants to allow browsing through all rankings

#### Start Date

* **Default**: Empty (no start limit)
* Filter rankings to show only games played from this date onwards
* **Use Case**: Create weekly, monthly, or seasonal leaderboards

#### End Date

* **Default**: Empty (no end limit)
* Filter rankings to show only games played up to this date
* **Use Case**: Create time-limited competitions or historical rankings

#### Only Completed Games

* **Default**: `true`
* When `true`: Shows only players who completed the entire game
* When `false`: Includes all game attempts regardless of completion
* **Best Practice**: Keep `true` for fair competition where everyone finished the same content

### Display Settings

#### Display Score

* **Default**: `true`
* Shows the score column in the ranking table
* **Use Case**: Disable if your game doesn't use scoring or if you only want to rank by time

#### Display Time

* **Default**: `true`
* Shows the completion time column in the ranking table
* Time is automatically formatted as MM:SS or HH:MM:SS
* **Use Case**: Essential for time-based challenges or speed-run competitions

#### Show User Context

* **Default**: `false`
* When `true`: Centers the ranking around the current player's position
* Shows positions above and below the player
* **Use Case**: Perfect for large leaderboards where players want to see their local competition
* **Note**: This overrides the standard top-N display

#### Context Rows

* **Default**: `5`
* **Range**: 1-50 positions
* Number of positions to show above and below the current player (±)
* **Only visible when** "Show User Context" is enabled
* **Example**: If set to 5, shows 5 positions above, the player, and 5 positions below (11 total entries)

#### Show Background

* **Default**: `true`
* When `true`: Displays a background box around the ranking
* When `false`: Shows the ranking table without a container background
* **Use Case**: Disable for transparent overlays or custom-styled scenes

## Understanding Ranking Display Modes

The Ranking component can operate in two different modes:

### Top Rankings Mode (Default)

* Shows the top N players based on score and time
* Best for highlighting top performers
* Controlled by the "Number of Rows" setting

### User Context Mode

* Centers the ranking around the current player
* Shows their local competition (players ranked near them)
* Activated by enabling "Show User Context"
* Shows ± positions around the player (controlled by "Context Rows")

## Customizing Appearance

### Text Styling

The Ranking component provides toolbar controls for quick text customization:

* **Font Family**: Choose from available fonts (default: Inter)
* **Font Size**: Adjust text size (default: 16pt)
* **Text Color**: Set the color for all text in the ranking (default: #000000)

### Translatable Text Fields

The Ranking component includes several text fields that can be customized and localized:

* **title**: Heading shown above the ranking table
* **position**: Column header for ranking position
* **player**: Column header for player names
* **score**: Column header for scores
* **time**: Column header for completion times
* **loading**: Message shown while fetching data
* **noData**: Message shown when no rankings are available
* **nextPage**: Text for next page button
* **prevPage**: Text for previous page button
* **page**: Label for current page indicator
* **anonymous**: Text shown for anonymous players

**Default values (English):**

```
title: "Ranking"
position: "Position"
player: "Player"
score: "Score"
time: "Time"
loading: "Loading..."
noData: "No data available"
nextPage: "Next"
prevPage: "Previous"
page: "Page"
anonymous: "Anonymous"
```

## How Rankings Work

### Ranking Criteria

Players are ranked based on the following logic:

1. **Primary**: Higher score = better rank
2. **Secondary**: Faster completion time = better rank (when scores are equal)
3. Each entry shows the player's best performance

### Data Source

* Rankings pull from actual gameplay data
* Only displays in **Play Mode** (shows sample data in Editor and Preview modes)
* Automatically updates when new games are completed
* Respects all filter settings (dates, completion status, anonymous users)

### Time Formatting

Completion times are automatically formatted for readability:

* **Under 1 hour**: MM:SS (e.g., "5:23" for 5 minutes 23 seconds)
* **1 hour or more**: HH:MM:SS (e.g., "1:15:30" for 1 hour 15 minutes 30 seconds)

## Integration with Other Components

### Variable Prompt Integration

The Ranking component works seamlessly with the [Variable Prompt](/game-editor/components/subcomponents/variable-prompt.md) component:

1. Use Variable Prompt to collect player names (`userName` variable)
2. Player names automatically appear in the ranking instead of "Anonymous"
3. Creates a more personal and engaging competitive experience

**Example Flow:**

```
Scene 1: Variable Prompt → Collect player name
Scene 2-5: Game content
Scene 6: Ranking → Shows personalized leaderboard with player names
```

### Action Scheduler

Combine with Action Scheduler to create time-limited competitions:

* Set up actions to navigate to the ranking screen after game completion
* Create timed challenges where rankings update in real-time
* Build tournament-style experiences with scheduled leaderboard reveals

## Popular Use Cases

### Educational Quizzes

Create competitive learning experiences:

**Setup:**

1. Variable Prompt: Collect student names
2. Quiz components: Educational content with scoring
3. Ranking component: Display top performers
4. **Settings**: `onlyCompleted: true`, `displayScore: true`, `displayTime: true`

### Speed Challenges

Build time-trial competitions:

**Setup:**

1. Set clear objectives or obstacles to overcome
2. Track completion time automatically
3. Ranking: Sort by fastest times
4. **Settings**: `displayTime: true`, `displayScore: false` (if scoring isn't used)

### Weekly Competitions

Create recurring leaderboards:

**Setup:**

1. Set `startDate` to beginning of current week
2. Set `endDate` to end of current week
3. Update dates weekly for fresh competition
4. **Tip**: Consider creating multiple game versions for different time periods

### Corporate Training

Track employee progress and engagement:

**Setup:**

1. Variable Prompt: Employee identification
2. Training modules with assessment
3. Ranking: Display top learners
4. **Settings**: `showAnonymous: false`, `onlyCompleted: true`

### Tournament Events

Build competitive gaming experiences:

**Setup:**

1. Set specific date range for the tournament period
2. Show top performers only
3. Enable pagination for large participant pools
4. **Settings**: `limit: 20`, `enablePagination: true`, `showUserContext: false`

### Personal Progress Tracking

Help players see their local competition:

**Setup:**

1. Enable "Show User Context"
2. Set context rows to 5-10
3. Players see where they rank among nearby competitors
4. **Settings**: `showUserContext: true`, `contextRows: 5-10`

## If Something's Not Working

### The Ranking Shows "No Data Available"

**Check these common issues:**

* Verify that players have actually completed games (if `onlyCompleted` is `true`)
* Check that your date filters (if set) include valid game completion dates
* Make sure the game has been played at least once in Play Mode
* Confirm you're viewing in Play Mode (not Editor or Preview)

### Rankings Don't Update

* Rankings fetch fresh data each time the component loads
* Refresh the page to see the latest rankings
* Verify that new game completions meet your filter criteria (completion status, dates)

### Pagination Isn't Working

* Pagination only appears when there are more results than the `limit` setting
* Enable "Enable Pagination" in General settings
* Verify you have more completed games than your "Number of Rows" setting

### Anonymous Players Appearing When They Shouldn't

* Check "Show Anonymous Users" setting - ensure it's set to `false`
* Verify that players are using the Variable Prompt to set their names
* Confirm the `userName` variable is being set before game completion

### User Context Not Showing Correctly

* Ensure "Show User Context" is enabled
* Verify that the current player has completed at least one game
* Check that `contextRows` is set appropriately for the number of participants

## Creative Tips

### Create Multiple Leaderboards

Use multiple Ranking components with different settings on different scenes:

* **Scene 1**: Overall top 10 performers (all-time)
* **Scene 2**: This month's leaderboard (date filtered)
* **Scene 3**: Player's personal context view

### Combine with Action Scheduler

Create dynamic leaderboard reveals:

1. Show loading message for 2 seconds
2. Reveal ranking with animation
3. Highlight current player's position
4. Celebrate top performers with special effects

### Seasonal Competitions

Create recurring engagement with date-filtered rankings:

* **Weekly Rankings**: Reset every Monday
* **Monthly Championships**: Show last month's winners
* **Seasonal Events**: Special holiday or themed competitions

### Achievement Tiers

Design multiple difficulty levels with separate rankings:

* **Beginner Ranking**: Show only "Easy" mode completions
* **Expert Ranking**: Show only "Hard" mode completions
* Use different scenes or game versions for each tier

### Visual Enhancements

Make your rankings stand out:

* Use custom background images behind the ranking component
* Apply animations or transitions when the ranking appears
* Highlight the top 3 positions with special visual styling
* Add celebratory sounds when displaying rankings

### Friendly Competition

Encourage engagement without overwhelming players:

* Use "User Context" mode to show local competition
* Set reasonable "Number of Rows" (10-20) to avoid intimidation
* Hide anonymous users for more personal connections
* Display encouraging messages for all participants

***

The Ranking component transforms your games into competitive experiences that keep players engaged and coming back to improve their performance. Whether you're creating educational challenges, training assessments, or pure entertainment, rankings add that extra layer of motivation that drives participation and excellence.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://academy.theufolab.com/game-editor/components/subcomponents/ranking.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.