Ranking

🚀 Premium Feature: The Ranking component is a premium feature that requires an upgraded UFOLab subscription to use in your games.

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 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.