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.3+ (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: it's mostly one call. When a run ends, pass the final score and streak to submit_score, and the score is submitted, validated server-side, and ranked automatically.

# Attach this where your run/round ends
func _on_game_over(score: int, streak: int) -> void:
    # No streak concept in your game? Pass 0.
    CheddaBoards.submit_score(score, streak)

That's the minimum. The SDK also emits signals as things happen — score accepted, leaderboard loaded, errors — so you can feed a live in-game HUD, but they're optional, not required to get a working board.

05Display the leaderboard

You have two options. The ready-made one is the full game template, which ships a leaderboard scene that renders ranked scores out of the box. The flexible option is to fetch ranked scores yourself and build a UI that matches your game's art — request the board, then render the entries when the SDK's signal delivers them:

# Request the board (sorted by score, top 100)
CheddaBoards.get_leaderboard("score", 100)

# Connect leaderboard_loaded once, in _ready() — fires when the board arrives
func _on_leaderboard_loaded(entries: Array) -> void:
    for entry in entries:
        print(entry.rank, ". ", entry.nickname, " — ", 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.