Godot 4 · GDScript · Leaderboards & scores

submit

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

Signature

submit(table_index: int, score: int, custom_data: Dictionary = {}) -> bool

What it does

POSTs the score to /scores and, on success, refreshes that table's cached ranking. The server response reports the exact effect of the write, 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. When the server reports it, the submit_effect(table_index: int, effect: String, periods_enabled: bool) signal is emitted right before submit_completed. Returns false immediately (no HTTP) if there is no active session, the table_index 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

How to call it

Connect submit_completed first, then call submit(). Connect submit_effect too if you want to react differently when only the period buckets improved. For offline-safe sending that survives app closes, prefer submit_with_retry() instead.

Example

Gamdato.submit_completed.connect(_on_sent)
Gamdato.submit_effect.connect(_on_effect)
Gamdato.submit(1, 1500, {"level": 3})

func _on_sent(ok: bool, table_index: int, server_score: int) -> void:
    if ok:
        print("server best = %d" % server_score)

# The server's verdict for the submit (fired right before submit_completed):
func _on_effect(table_index: int, effect: String, periods_enabled: bool) -> void:
    match effect:
        "updated":      print("new historic best!")            # all-time score written
        "periods_only": print("improved a daily/weekly/monthly board")
        "not_improved": print("kept your previous best")       # nothing stored

Use cases

• Send a run's score at game over.
• Push a score immediately when you don't need offline retry.
• React differently per submit_effect (new best vs. period-only vs. no change).