GameMaker Studio · GML · Currency & store

gmda_getCurrencyLeaderboard

Fetches the balance leaderboard for a currency (top balances ranked).

Asynchronous (result via event)

Signature

gmda_getCurrencyLeaderboard(code, [limit=20]) -> real

What it does

GETs /currency/leaderboard/<code>?limit with the session headers. The queued currency_leaderboard_loaded event carries response, whose entries array is ordered by balance descending, each with a rank, the player and their balance; the event's tag field echoes the requested code. If the currency's balance leaderboard is not enabled in the panel the server returns 403 and success is false. Returns 1 once dispatched, or 0 when there is no active session.

Parameters

Name	Type	Default	Description
code	string	required	The currency code from the panel (e.g. "gems"). The balance leaderboard must be enabled for this currency.
limit	real	20	How many ranked entries to return; clamped to 1..100.

How to call it

Call gmda_getCurrencyLeaderboard(code), then read the currency_leaderboard_loaded event with gmda_pollEvent().

Result event: currency_leaderboard_loaded { success, response }

Example

gmda_getCurrencyLeaderboard("gems");

// in the Step event, drain the queue:
var e = gmda_pollEvent();
while (!is_undefined(e)) {
    if (e.event == "currency_leaderboard_loaded" && e.success) {
        var rows = e.response.entries;
        for (var i = 0; i < array_length(rows); i++) {
            show_debug_message("#" + string(rows[i].rank) + " " + string(rows[i].player_name) + " " + string(rows[i].balance));
        }
    }
    e = gmda_pollEvent();
}

Use cases

Show a 'richest players' ranking by currency balance.
Add a wealth-based competitive screen alongside score leaderboards.

Functions Reference