Godot 4 · GDScript
Глобальные таблицы лидеров
Создание таблиц лидеров
В панели откройте раздел «Таблицы лидеров» и создайте таблицу, указав название. Настройте порядок, количество результатов и дополнительные поля данных.
Настройки таблицы лидеров
После создания настройте:
- Порядок: по убыванию или по возрастанию.
- Показывать результатов: количество возвращаемых строк.
- Мин/макс результат: необязательные границы; отправки вне диапазона отклоняются.
- Пользовательские поля: дополнительные данные к результату (уровень, страна и т. д.), до 20 в зависимости от плана.
- Временные результаты: таблицы за день/неделю/месяц. Выключено = только историческая таблица; отправка, не превышающая лучший результат, ничего не сохраняет.
Сохраните ключ каждой таблицы: вы будете использовать его в set_leaderboard.
Несколько таблиц и индексы
Объявите все ваши таблицы вместе. Порядок определяет индекс, который вы всегда будете использовать (1, 2, 3...).
Gamdato.set_leaderboard(["key_1", "key_2", "key_3"])
# key_1 -> table 1, key_2 -> table 2, key_3 -> table 3Отправка результатов
Отправьте результат игрока в таблицу по её индексу, с необязательными пользовательскими данными:
# 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 заменяет результат в очереди, только если новый выше. Используйте submit() для простой отправки без повторных попыток. Сигнал submit_effect сообщает точный эффект: "updated" (исторический результат записан), "periods_only" (улучшились только таблицы за день/неделю/месяц) или "not_improved" (ничего не сохранено). В таблицах с выключенными временными результатами результат, не превышающий ваш лучший в кеше, даже не отправляется (вызов возвращает false), см. get_table_config(table).
Чтение результатов
Эти функции мгновенно возвращают последние загруженные данные, без ожидания сети:
- get_table_data(table): Верхушка таблицы с дополнительными данными.
- get_best_score(table) / get_player_pos(table): Ваш лучший результат и ваш ранг.
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"
}Представления: периоды и друзья
Запрашивайте отфильтрованные представления (за день, неделю, месяц или только друзья) и слушайте 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".Поиск и просмотр игроков
Ищите по имени или просматривайте профиль другого игрока:
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
}