Godot 4 · GDScript
Rankings globais
Criando Rankings
No painel, abra a seção de Rankings e crie uma tabela informando um nome. Configure a ordem, o número de pontuações e os campos de dados extras.
Configurações do Ranking
Uma vez criado, configure:
- Ordem: decrescente ou crescente.
- Pontuações a exibir: número de linhas retornadas.
- Pontuação mín/máx: limites opcionais; envios fora deles são rejeitados.
- Campos personalizados: dados extras por pontuação (nível, país, etc.), até 20 conforme seu plano.
- Pontuações temporais: tabelas diária/semanal/mensal. Desligado = tabela apenas histórica; um envio que não supere a melhor pontuação não grava nada.
Guarde a chave de cada tabela: você a usará em set_leaderboard.
Múltiplas Tabelas e Índices
Declare todas as suas tabelas juntas. A ordem define o índice que você sempre usará (1, 2, 3...).
Gamdato.set_leaderboard(["key_1", "key_2", "key_3"])
# key_1 -> table 1, key_2 -> table 2, key_3 -> table 3Enviando Pontuações
Envie a pontuação de um jogador para uma tabela pelo seu índice, com dados personalizados opcionais:
# Recommended: retries when offline and survives app closes.
Gamdato.submit_with_retry(1, score, {"level": level_reached})# submit_completed(success: bool, table_index: int, server_score: int)
# submit_effect(table_index: int, effect: String, periods_enabled: bool)
# effect = "updated" the historic (all-time) score was written
# "periods_only" only the daily/weekly/monthly buckets improved
# "not_improved" nothing was stored (doesn't beat your best)
Gamdato.submit_effect.connect(func(table, effect, periods_enabled):
match effect:
"updated": print("new historic best!")
"periods_only": print("improved a daily/weekly/monthly board")
"not_improved": print("kept your previous best"))submit_with_retry só substitui uma pontuação na fila quando a nova é maior. Use submit() para um envio simples sem repetição. O sinal submit_effect reporta o efeito exato: "updated" (pontuação histórica gravada), "periods_only" (apenas as tabelas diária/semanal/mensal melhoraram) ou "not_improved" (nada foi gravado). Em tabelas com pontuações temporais desativadas, uma pontuação que não supere a sua melhor em cache nem sequer é enviada (a chamada retorna false), consulte get_table_config(table).
Lendo Pontuações
Estas funções retornam os últimos dados carregados instantaneamente, sem espera de rede:
- get_table_data(table): O topo da tabela com dados extras.
- get_best_score(table) / get_player_pos(table): Sua melhor pontuação e sua posição.
for row in Gamdato.get_table_data(1):
print("#%d %s %d" % [row.rank, row.player_name, row.score])
print("Your best: %d (rank %d)" % [Gamdato.get_best_score(1), Gamdato.get_player_pos(1)])# get_table_data(table) -> Array, each row:
{
"rank": int,
"player_key": String,
"player_name": String,
"score": int,
"custom_data": Dictionary
}
# custom_data holds the extra fields you defined for the table in the panel, e.g.:
{
"level": 2,
"country": "Mexico"
}Visualizações: Períodos e Amigos
Solicite visualizações filtradas (diária, semanal, mensal ou apenas amigos) e escute view_loaded:
Gamdato.view_loaded.connect(_on_view)
Gamdato.load_leaderboard_view(1, "weekly") # weekly top
Gamdato.load_leaderboard_view(1, "all", {"friends_only": true}) # friends only
func _on_view(table, period, friends_only, scores, my_score) -> void:
for row in scores:
print("#%d %s %d" % [row.rank, row.player_name, row.score])# scores: Array, each row:
{
"rank": int,
"player_key": String,
"player_name": String,
"score": int,
"custom_data": Dictionary,
"date": String
}
# player_score: Dictionary (your own row), or null if you have no score:
{
"rank": int,
"score": int,
"custom_data": Dictionary,
"date": String # period bucket the score belongs to
}
# custom_data keys are the extra fields you defined for the table in the panel.
# The response also carries the table's dashboard config:
# "leaderboard": { "name": String, "sort_order": "asc" | "desc", "periods_enabled": bool }
# Period views (daily/weekly/monthly) additionally include "period" and "period_key".Pesquisar e Visualizar Jogadores
Pesquise por nome ou consulte o perfil de outro jogador:
Gamdato.search_players(1, "text") # -> players_search_completed
Gamdato.load_player_info(player_key) # -> player_info_loaded# players_search_completed -> results: Array, each:
{
"rank": int,
"player_key": String,
"player_name": String,
"score": int
}
# player_info_loaded -> player: Dictionary
{
"player_key": String,
"player_name": String,
"is_invitable": bool,
"created_at": String
}
# ...plus scores: Array, one per leaderboard the player appears on:
{
"leaderboard": {
"table_key": String,
"name": String,
"sort_order": String # "asc" | "desc"
},
"rank": int,
"score": int,
"custom_data": Dictionary,
"date": String,
"updated_at": String
}