GameMaker Studio · GML · Leaderboards & scores

gmda_submit

Sends a score to a table by index; refreshes that table afterwards.

Asynchronous (result via event)

Signature

gmda_submit(table, score, [custom_struct]) -> real

What it does

POSTs the score to /scores and, on success, refreshes that table's cached ranking so gmda_getTabledata() reflects the new standing. The submit_completed event's e.response carries the server's verdict: effect is "updated" (the historic/all-time score was written, including a first submit), "periods_only" (only the daily/weekly/monthly buckets improved), or "not_improved" (nothing was stored), plus the table's periods_enabled flag. Returns 1 if the request was sent, or 0 immediately (no HTTP) if there is no active session, the table is out of range, or the table is historic-only (periods_enabled = false) and the score cannot beat the cached best, the server would store nothing.

Parameters

Name	Type	Default	Description
table	real	required	Table number, from gmda_setLeaderboard() order. 1-based: the first declared table is 1, the second is 2, and so on.
score	real	required	The score to submit.
custom_struct	struct	{}	Extra fields defined for this table in the panel, e.g. { level: 3, country: "MX" }.

How to call it

Call it, then read the result later from the event queue: each step, drain gmda_pollEvent() and look for an event whose .event is "submit_completed". For offline-safe sending that survives app closes, prefer gmda_submitWithRetry() instead.

Result event: submit_completed { success, table, response }

Example

gmda_submit(1, 1500, { level: 3 });

// later, in a Step event:
var e = gmda_pollEvent();
while (!is_undefined(e)) {
    if (e.event == "submit_completed" && e.success) {
        /* e.response, the server's verdict:
        {
          "effect": "updated",          // "updated" | "periods_only" | "not_improved"
          "periods_enabled": true,      // this table's temporal-scores toggle
          "improved": true,             // historic (all-time) score written
          "improved_periods": { "daily": true, "weekly": true, "monthly": true },
          "score": { "score": 1500, "custom_data": { "level": 3 }, "updated_at": "..." }
        } */
        switch (e.response.effect) {
            case "updated":      show_debug_message("new historic best!"); break;
            case "periods_only": show_debug_message("improved a daily/weekly/monthly board"); break;
            case "not_improved": show_debug_message("kept your previous best"); break;
        }
    }
    e = gmda_pollEvent();
}

Use cases

Send a run's score at game over.
Push a score immediately when you don't need offline retry.
Show a different message depending on e.response.effect (new best vs. period-only vs. no change).

What it does

Name

Type

Default

Description

table

real

required

Table number, from gmda_setLeaderboard() order. 1-based: the first declared table is 1, the second is 2, and so on.

score

real

required

The score to submit.

custom_struct

struct

{}

Extra fields defined for this table in the panel, e.g. { level: 3, country: "MX" }.

Example

gmda_submit(1, 1500, { level: 3 }); // later, in a Step event: var e = gmda_pollEvent(); while (!is_undefined(e)) { if (e.event == "submit_completed" && e.success) { /* e.response, the server's verdict: { "effect": "updated", // "updated" | "periods_only" | "not_improved" "periods_enabled": true, // this table's temporal-scores toggle "improved": true, // historic (all-time) score written "improved_periods": { "daily": true, "weekly": true, "monthly": true }, "score": { "score": 1500, "custom_data": { "level": 3 }, "updated_at": "..." } } */ switch (e.response.effect) { case "updated": show_debug_message("new historic best!"); break; case "periods_only": show_debug_message("improved a daily/weekly/monthly board"); break; case "not_improved": show_debug_message("kept your previous best"); break; } } e = gmda_pollEvent(); }