How to add an online leaderboard to your Godot game

In this tutorial you'll add a working online leaderboard to a Godot game — one that ranks scores from real players, survives game updates, and validates scores on the server so a player can't just edit a local file and resubmit. No backend to host. We'll use CheddaBoards, but the shape of the steps is the same idea you'd follow with any leaderboard service.

What you'll need:

• Godot 4.x (or Godot 3.6) installed
• A game — or test project — that produces a numeric score
• About ten minutes

01Install the CheddaBoards plugin

Grab the plugin from the Godot Asset Store and drop the addons/cheddaboards folder into your project. Alternatively, search for CheddaBoards in the AssetLib tab inside the Godot editor (or on the Godot Asset Library) and let Godot import it into addons/.

02Enable the plugin

Go to Project > Project Settings > Plugins and tick the box next to CheddaBoards to enable it. This registers the integration so your game can talk to the backend.

03Register your game and get an API key

Create a free account, register your game in the dashboard, and copy your API key (and game ID). Paste these into the plugin's settings. This is what links the scores coming out of your game to the right leaderboard.

04Submit a score from GDScript

Here's the part that surprises people: you mostly emit one signal. When a run ends, emit game_over with the final score, and the score is submitted, validated server-side, and ranked automatically.

# Attach this where your run/round ends
func _on_player_died() -> void:
    # game_over is the only signal you have to emit
    game_over.emit(current_score)

That's the minimum. If you want a live in-game HUD leaderboard, there are optional signals that feed score updates as they happen — but they're optional, not required to get a working board.

05Display the leaderboard

You have two options. The fastest is the built-in leaderboard scene — instantiate it, point it at your game, and it renders ranked scores out of the box. The flexible option is to fetch ranked scores via the API and build your own UI so it matches your game's art:

# Pull ranked scores and render your own rows
func show_top_scores() -> void:
    var scores = await CheddaBoards.get_top_scores(10)
    for entry in scores:
        print(entry.rank, ". ", entry.name, " — ", entry.score)

06Test it

Run your game, finish a round, and check the dashboard — you should see your score appear. Play a few more times (or have a friend try it) so the board has more than one entry, then confirm the in-game leaderboard shows them in the right order.

07Optional: daily and weekly resets

If you're building for a jam or a recurring competition, create a timed leaderboard that resets on a daily, weekly, or seasonal schedule. Old runs are archived and the board starts fresh each period — no extra code in your game, you just point at the timed board.

Troubleshooting

Scores work in the editor but not in the exported build

Almost always a config/API-key file that didn't make it into the export. Check your export settings include it, then re-export.

Nothing appears in the dashboard

Confirm the API key and game ID are correct, that the plugin is enabled, and that the device actually has network access (on mobile you may need to allow internet permissions).

Web (HTML5) build feels slow to start

That's typically the build's own load time, not the leaderboard call. Keep your export lean and the leaderboard request will resolve once the game is running.

Want the full picture — achievements, player profiles, auth, and the REST API for other engines? Start at the Godot leaderboard overview or browse the documentation.