Skip to content

leaderboards

Jump to bottom
Sergei edited this page May 7, 2026 · 1 revision

Leaderboards

Leaderboards rank players by score. Bridge wraps native platform leaderboards and provides an in-game data API when the platform does not render a leaderboard UI. The module is optional — implement it only if your game has comparable scores.

Leaderboard types — pick logic by leaderboards.type

First read leaderboards.type. It tells you which leaderboard flow the current platform supports:

Type What you do What the platform does
not_available Hide all leaderboard UI nothing
in_game Call setScore(...), render your own UI from getEntries(...) nothing — you draw the board
native Call setScore(...) only Renders the leaderboard itself
native_popup Call setScore(...) and showNativePopup() to open it Renders an overlay

Leaderboards Type

Returns the leaderboard mode for the current platform. Use it to decide which leaderboard UI to show or hide.

playgama_bridge_leaderboards_type()
Type Game logic
not_available Hide leaderboard UI.
in_game Call setScore(...) and render your own leaderboard with getEntries(...).
native Call setScore(...) only. The platform renders the leaderboard, and getEntries(...) is unavailable.
native_popup Call setScore(...) and open the native overlay with showNativePopup(...). getEntries(...) is unavailable.
Platform support · 9 of 28 platforms

in_game supports: bitquest, y8, yandex

native supports: gamesnacks, jio_games, lagged, msn, youtube

native_popup supports: facebook

Does not support: absolute_games, crazy_games, discord, dlightek, game_distribution, gamepush, huawei, microsoft_store, ok, playdeck, playgama, poki, portal, reddit, samsung, telegram, tiktok, vk, xiaomi

Setup

Configure leaderboards in playgama-bridge-config.json. Add an id for each leaderboard and use that ID in game code. If a platform uses a different native ID, map it under that platform key. Use the config editor to create or update the config.

{
    ...    
    "leaderboards": [
        {
            "id": "test_leaderboard", // use this id in game logic
            "<ANY_PLATFORM_ID_HERE>": "<OVERRIDED_ID_FOR_PLATFORM_HERE>"
        }
    ]
}

Set Score

Submit the player's score after a meaningful result, such as level completion or game over. Avoid submitting temporary or per-frame values.

var leaderboardId = "YOUR_LEADERBOARD_ID" // id that you specified in the config file
var score = 42

playgama_bridge_leaderboards_set_score(leaderboardId, score)

// callback via Async Social Event
if async_load[? "type"] == "playgama_bridge_leaderboards_set_score_callback" {
    if async_load[? "success"] {
        // your logic
    }
}

Get Entries

Load leaderboard entries when leaderboards.type is in_game and render them in your own UI.

var leaderboardId = "YOUR_LEADERBOARD_ID" // id that you specified in the config file

playgama_bridge_leaderboards_get_entries(leaderboardId)

// callback via Async Social Event
if async_load[? "type"] == "playgama_bridge_leaderboards_get_entries_callback" {
    if async_load[? "success"] {
        var entries = json_parse(async_load[? "data"])
    }
}

Show Native Popup

Opens the platform's native leaderboard overlay. Use it only when leaderboards.type is native_popup.

var leaderboardId = "YOUR_LEADERBOARD_ID" // id that you specified in the config file

playgama_bridge_leaderboards_show_native_popup(leaderboardId)

// callback via Async Social Event
if async_load[? "type"] == "playgama_bridge_leaderboards_show_native_popup_callback" {
    if async_load[? "success"] {
        // your logic
    }
}

Clone this wiki locally