Add a leaderboard to your game (beta)

A leaderboard is a ranking of your players' best results, such as a score or a time. You set a board up on the Game Analytics page (in the menu under your name), and your game sends results to it and reads the ranking back to show to the player. Leaderboards are in beta: they may change, and they are planned to become a paid feature, so you will hear from us before that happens.

Set up a board

1. Open Game Analytics and choose your game.
2. In Leaderboards, give the board a title, a name in your game (for example high_scores) and say whether the best result is the highest number (a score) or the lowest number (a time).
3. Use that name in your game, as shown below.

A game can have up to 10 boards. A board name uses lowercase letters, digits, dashes and underscores, up to 40 characters.

How it works

A game here cannot reach the internet, so it does not call our servers itself. It hands a result to the game page it is running in, and the page sends it to us and passes the ranking back to your game. A board only works while the game is live.

• A result is a player name and one number. The name is shown to everyone, so it is 1 to 12 letters, digits, spaces, dashes or underscores, and names with rude words are refused. Tell players to pick a nickname, never a real name.
• There are no accounts. A name keeps its best result and only moves up. Anyone can type any name, and a determined person can send any number, so a board is for fun and not tamper-proof.
• A board keeps the best 100 results. When it is full, a new result has to beat the worst one to get in.
• A number can be a whole number or a decimal, between -1,000,000,000 and 1,000,000,000.
• You can remove any result, clear a board, or remove it, on the Game Analytics page. Results go when the game is deleted.
• Results from your own team are accepted too, so you can test on the live game.
• A page handles a limited number of requests per visit, so send a result when a run ends and read the board when you show it, not on every frame.

Godot 4

Add indiedev.gd as an Autoload named IndieDev (see the events guide). Answers arrive in a signal:

func _ready():
    IndieDev.leaderboard_loaded.connect(_on_leaderboard)

func game_over(score):
    IndieDev.submit_score("high_scores", player_nickname, score)

func show_scores():
    IndieDev.load_leaderboard("high_scores", 10)

func _on_leaderboard(board, result):
    if not result.ok:
        return
    for entry in result.entries:
        print(entry.rank, " ", entry.name, " ", entry.score)

After a submit_score, result.rank is the place of that name, or null if the result did not make the board.

Defold

Add indiedev.lua to your project. Answers arrive later, so call indiedev.update() from the update function of a script that is always running:

local indiedev = require("indiedev")

function update(self, dt)
    indiedev.update()
end

-- when a run ends
indiedev.submit_score("high_scores", nickname, score, function(result)
    if result.ok then print(result.rank) end
end)

-- to show the ranking
indiedev.load_leaderboard("high_scores", function(result)
    if not result.ok then return end
    for _, entry in ipairs(result.entries) do
        print(entry.rank, entry.name, entry.score)
    end
end, 10)

Other engines

Load indiedev.js with <script src="indiedev.js"></script>, then:

indiedevScore("high_scores", "AVA", 1200, function (result) {
    if (result.ok) console.log(result.rank);
});

indiedevLeaderboard("high_scores", function (result) {
    result.entries.forEach(function (entry) { console.log(entry.rank, entry.name, entry.score); });
}, 10);

Or send the messages yourself and listen for the answer:

window.parent.postMessage({ indiedev: 1, type: "score", id: 1, board: "high_scores", name: "AVA", score: 1200 }, "*");
window.parent.postMessage({ indiedev: 1, type: "leaderboard", id: 2, board: "high_scores", limit: 10 }, "*");
window.addEventListener("message", function (event) {
    if (event.data && event.data.indiedev === 1 && event.data.type === "scores") { /* event.data.id, ok, rank, entries */ }
});

When something does not show up

• Is the board's name in your game spelled exactly as on the Game Analytics page, in lowercase?
• Is the game live? Boards do not work on a draft.
• Does result.ok come back false with error: "not_found"? There is no board with that name for this game, or the game is not live. Add the board on the Game Analytics page. ("rate_limited" means too many results were sent too quickly.)
• Does result.ok come back false with error: "invalid"? The name or the number was not usable (for example a name with a rude word, or too long).
• Test in a private window on the live game, then look at the board on Game Analytics.