Leaderboards let players compete by ranking scores on shared scoreboards. Each leaderboard has a unique string ID, a sort direction, and an update policy.
Getting or creating a leaderboard
func _ready():
WavedashSDK.got_leaderboard.connect(_on_got_leaderboard)
func fetch_leaderboard():
WavedashSDK.get_or_create_leaderboard(
"speedrun-times",
WavedashConstants.LEADERBOARD_SORT_ASCENDING,
WavedashConstants.LEADERBOARD_DISPLAY_TYPE_TIME_MILLISECONDS
)
func _on_got_leaderboard(response):
if response.get("success", false):
print("Leaderboard ID: ", response["data"]["id"])
Sort order
| Value | Constant | Description | Best for |
|---|---|---|---|
0 | ASC | Lower scores rank higher | Time trials, golf |
1 | DESC | Higher scores rank higher | Points, high scores |
Display type
| Value | Constant | Description |
|---|---|---|
0 | NUMERIC | Display as a number |
1 | TIME_SECONDS | Display as time in seconds |
2 | TIME_MILLISECONDS | Display as time with milliseconds |
3 | TIME_GAME_TICKS | Display as game ticks (assumes 60fps) |
Submitting a score
func _ready():
WavedashSDK.posted_leaderboard_score.connect(_on_score_posted)
func submit_score(leaderboard_id: String, score: int):
WavedashSDK.post_leaderboard_score(leaderboard_id, score, true)
func _on_score_posted(response):
if response.get("success", false):
print("Rank: ", response["data"]["globalRank"])
| Parameter | Type | Required | Description |
|---|---|---|---|
leaderboardId | string | Yes | The leaderboard's ID |
score | number | Yes | The score to submit |
keepBest | boolean | Yes | If true, only updates if score is better |
ugcId | string | No | Optional UGC attachment (replay, screenshot) |
Use keepBest: true for competitive leaderboards. The SDK handles personal best tracking automatically.
Fetching scores
Top scores
func _ready():
WavedashSDK.got_leaderboard_entries.connect(_on_got_entries)
func get_top_scores(leaderboard_id: String):
WavedashSDK.get_leaderboard_entries(leaderboard_id, 0, 10, false)
func _on_got_entries(response):
if response.get("success", false):
for entry in response["data"]:
print("#", entry["globalRank"], " ", entry["username"], ": ", entry["score"])
Nearby scores
func get_scores_around_me(leaderboard_id: String):
WavedashSDK.get_leaderboard_entries_around_player(leaderboard_id, 5, 5, false)
Player's own entry
WavedashSDK.get_my_leaderboard_entries(leaderboard_id)
Entry count
var count = WavedashSDK.get_leaderboard_entry_count(leaderboard_id)
Returns a cached value from the last query. Returns -1 if the leaderboard has not been queried yet.
Attaching replays or screenshots
Pass a ugcId from UGC into the score upload call:
const lb = await WavedashJS.getOrCreateLeaderboard("speedrun-times", 0, 2);
const ugc = await WavedashJS.createUGCItem(3, "Replay", "", 0, "replays/run.dat");
if (lb.success && ugc.success) {
await WavedashJS.uploadLeaderboardScore(lb.data.id, 12345, true, ugc.data);
}
Entry structure
interface LeaderboardEntry {
userId: string;
username?: string;
score: number;
globalRank: number;
ugcId?: string;
timestamp: number;
metadata?: Uint8Array;
}