Leaderboards

Add global leaderboards to your game. The SDK buffers scores and sends them in batches to avoid spamming the server. Fetch rankings asynchronously with a callback.

Why Leaderboards?

Leaderboards increase engagement through social competition. Players return to improve their rank, which boosts retention. Weekly leaderboards with resets keep the competition fresh. See the Player Management Guide for managing rankings in the dashboard.

Functions

submit_score()

QuestData.submit_score(board_name: String, score: float, metadata: Dictionary = {}, player_display_name: String = "")

Parameter	Type	Default	Description
board_name	String	required	Leaderboard identifier (e.g. "weekly_highscore")
score	float	required	The score to submit
metadata	Dictionary	{}	Additional data stored with the entry (e.g. level, character)
player_display_name	String	""	Display name shown on the leaderboard

Scores are buffered and sent every 5 seconds. If the player submits multiple scores to the same board within that window, only the highest score is sent.

get_leaderboard()

QuestData.get_leaderboard(board_name: String, limit: int = 10, callback: Callable = Callable())

Parameter	Type	Default	Description
board_name	String	required	Leaderboard identifier
limit	int	10	Number of entries to fetch (1-100)
callback	Callable	Callable()	Called with Array of leaderboard entries

Each entry in the callback Array is a Dictionary with: player_id, player_name, score, rank, metadata, updated_at.

Example

# Submit a score after level completion
func _on_level_completed(score: int):
    QuestData.submit_score("campaign_highscore", score, {
        "level": current_level,
        "character": selected_character
    }, player_name)

# Display top 10
func show_leaderboard():
    QuestData.get_leaderboard("campaign_highscore", 10, func(entries: Array):
        for entry in entries:
            print("#%d %s - %d" % [entry["rank"], entry["player_name"], entry["score"]])
    )

# Weekly leaderboard with different board name
func submit_weekly_score(score: int):
    QuestData.submit_score("weekly_" + get_week_id(), score)

Boss Speedrun Leaderboard

func _on_boss_defeated(boss_id: String, time_seconds: float):
    # Lower is better — use negative score for "fastest wins"
    QuestData.submit_score("speedrun_" + boss_id, -time_seconds, {
        "boss": boss_id,
        "build": get_player_build()
    }, player_name)

How It Works

1. submit_score() buffers the score in memory
2. Every 5 seconds, the SDK sends all buffered scores in one request
3. If multiple scores were submitted to the same board, only the highest is sent
4. The server uses UPSERT logic — a player’s entry is updated if the new score is higher
5. get_leaderboard() fetches rankings asynchronously via GET /v1/leaderboards/:board_name

Dashboard

Manage leaderboards under Players > Leaderboards:

• Board list — All leaderboards with entry counts
• Rankings — View top players per board
• Moderation — Remove cheating entries
• Create boards — Boards are auto-created on first score submission, but you can also create them in the dashboard

Best Practices

1. Use descriptive board names — "weekly_highscore" not "lb1"
2. Include metadata — Level, character, build info helps you analyze patterns
3. Set player_display_name — Without it, the leaderboard shows player IDs
4. Don’t submit on every frame — The SDK buffers for you, but call submit_score() only at meaningful moments (level end, game over)
5. Rotating leaderboards — Include a time identifier in the board name (e.g. "weekly_2026_w15")