GameMaker Studio · GML · Leaderboards & scores

gmda_searchPlayers

Searches players by name within a table; results arrive via the players_search_completed event.

Asynchronous (result via event)

Signature

gmda_searchPlayers(table, query) -> real

What it does

POSTs the search to /leaderboards/scores and queues a players_search_completed event. e.response is the raw server body { scores, player_score, leaderboard }: the matches are the array at e.response.scores (each row has rank, player_key, player_name, score, custom_data, date, and is_invitable). Returns 1 if the request was sent, or 0 if there is no session or the table is invalid.

Parameters

Name	Type	Default	Description
table	real	required	Table number to search within. 1-based: the first declared table is 1, the second is 2, and so on.
query	string	required	Name (or substring) to look for. An empty query is a no-op and queues no event.

How to call it

Call this from a search box, then read the matches from e.response.scores on the "players_search_completed" event in gmda_pollEvent(). Pair a row's player_key with gmda_loadPlayerInfo() to open a full profile.

Result event: players_search_completed { success, response }

Example

gmda_searchPlayers(1, "corvus");

// later, in a Step event:
var e = gmda_pollEvent();
while (!is_undefined(e)) {
    if (e.event == "players_search_completed" && e.success) {
        var rows = e.response.scores;   // the matches live at response.scores
        for (var i = 0; i < array_length(rows); i++) {
            show_debug_message(rows[i].player_name + "  " + string(rows[i].score));
        }
    }
    e = gmda_pollEvent();
}

Use cases

Let players find a friend by name in the leaderboard.
Power a 'find player' search field with live results.

What it does

Name

Type

Default

Description

table

real

required

Table number to search within. 1-based: the first declared table is 1, the second is 2, and so on.

query

string

required

Name (or substring) to look for. An empty query is a no-op and queues no event.

Example

gmda_searchPlayers(1, "corvus"); // later, in a Step event: var e = gmda_pollEvent(); while (!is_undefined(e)) { if (e.event == "players_search_completed" && e.success) { var rows = e.response.scores; // the matches live at response.scores for (var i = 0; i < array_length(rows); i++) { show_debug_message(rows[i].player_name + " " + string(rows[i].score)); } } e = gmda_pollEvent(); }