Введение
В Steam реализованы постоянно существующие списки лидеров с автоматически отсортированными записями. Списки лидеров можно использовать для отображения лидеров (как глобальных, так и среди друзей) в игре и в центре сообщества. Каждый продукт Steamworks может создать до 10 тысяч списков лидеров, и каждый из этих списков можно получить сразу после того, как были отправлены очки игрока.
У одного игрока будет только одна позиция в списке лидеров. Ограничений на число игроков в списке лидеров нет. Каждая позиция списка лидеров содержит очки (число, int32) и до 64 чисел (int32) для обозначения связанных данных. Связанные данные могут использоваться для хранения характерной для данной игры информации об игровой сессии, результатом которой стала позиция пользователя в списке лидеров. Эти данные не сортируются и не обрабатываются Steam, а заменяются при создании новой позиции пользователя в списке лидеров.
Все функции системы списков лидеров живут в ISteamUserGameStats.h. В образце приложения Steamworks реализованы два примера. Просмотр списков лидеров и управление ими также возможны в админке Steamworks.
Прежде чем начать
Все асинхронные функции списков лидеров возвращают дескриптор для результата вызова. Больше информации о том, как получать результаты, доступно в разделе «Результаты вызова» статьи «Введение в API Steamworks».
Создание списка лидеров
Списки лидеров создаются для конкретного приложения на странице управления данными приложения на партнёрском сайте Steamworks или с помощью API.
Создание на сайте
Вы можете создавать и изменять списки лидеров на странице управления данными приложения
здесь.
Следующие поля должны быть заполнены для создания списка лидеров:
- Название. Это может быть названием, которое имеет смысл с точки зрения разработки.
- Название в сообществе. Если список лидеров будет отображаться в центре сообщества, задайте здесь общедоступное название. Если ничего не ввести, список лидеров не появится в центре сообщества.
- Метод сортировки. Выберите подходящий для данного списка лидеров: для списков, основанных на месте игрока, используйте «по возрастанию», а для списков, основанных на счёте, используйте «по убыванию».
- Тип отображения. Определяет тип данных, показываемых со списком лидеров. Варианты: числа, секунды или миллисекунды.
- Запись данных. Если установить значение «доверенная», клиенты не смогут отправлять данные об очках в списки лидеров, это можно будет сделать только с помощью SetLeaderboardScore (веб-API). По умолчанию — false.
- Считывание данных. Если установить значение «друзья», игра сможет считывать данные списка лидеров только для друзей пользователя, но все данные списка всегда можно будет прочесть с помощью веб-API. По умолчанию — false.
Создание с помощью API
Списки лидеров игры могут быть созданы на
сайте Steamworks или программно с помощью
ISteamUserStats::FindOrCreateLeaderboard. Все списки лидеров продукта Steamworks идентифицируются в Steam с помощью уникального названия. Название списка лидеров используется только для идентификации в API Steamworks и не показывается пользователям в сообществе Steam. При создании списка лидеров необходимо выбрать:
- метод сортировки —
k_ELeaderboardSortMethodAscending
(на верхней позиции будет пользователь с самым низким счётом) илиk_ELeaderboardSortMethodDescending
(на верхней позиции будет пользователь с самым высоким счётом), а также
- тип отображения —
ELeaderboardDisplayType
используется для описания того, что представляет собой счёт списка лидеров, и используется только сообществом для форматирования счёта списка лидеров при отображении.
Если вы создадите списки лидеров только с помощью
партнёрского сайта, вы можете использовать
ISteamUserStats::FindLeaderboard для получения дескриптора списка. FindLeaderboard и FindOrCreateLeaderboard — асинхронные методы, которые возвращают дескриптор списка лидеров для указанного списка в виде результата вызова
ISteamUserStats::LeaderboardFindResult_t.
Как только список лидеров создан, вы можете изменить метод сортировки и тип отображения на сайте Steamworks. При вызове FindOrCreateLeaderboard для существующего списка параметры «метод сортировки» и «тип отображения» игнорируются.
ВНИМАНИЕ: если список лидеров будет отображаться в центре сообщества, вы должны заполнить поле «Название в сообществе». Если ничего не ввести, список лидеров не появится в центре сообщества.
Отправка счёта
Чтобы отправить счёт списка лидеров, просто вызовите
ISteamUserStats::UploadLeaderboardScore, передав в качестве параметра дескриптор целевого списка (полученный от FindLeaderboard), счёт пользователя и опционально — связанные данные, появившиеся в результате возникновения нового счёта. Если счёт пользователя будет обновлён, связанные данные, переданные
ISteamUserStats::UploadLeaderboardScore, заменят все ранее сохранённые данные. При отправке счёта пользователя в список лидеров вы можете выбрать один из двух методов отправки:
- ISteamUserStats::k_ELeaderboardUploadScoreMethodKeepBest — Steam сравнит новый счёт пользователя с уже хранящимся в списке лидеров и сохранит лучший из них (наименьший в списке по возрастанию, наибольший в списке по убыванию).
- ISteamUserStats::k_ELeaderboardUploadScoreMethodForceUpdate — Steam принудительно заменит счёт пользователя в списке новым счётом.
- ISteamUserStats::UploadLeaderboardScore — асинхронный вызов, результат отправки возвращается как результат вызова LeaderboardScoreUploaded_t. Результат содержит флаг, показывающий, изменился ли счёт пользователя, и новый и старый глобальный рейтинг пользователя. После отправки нового счёта списки лидеров Steamworks немедленно обновляются, и новый порядок позиций можно получить с помощью DownloadLeaderboardEntries.
Добавление контента, созданного пользователями
После отправки счёта вы можете добавить к позиции в списка контент, созданный пользователями. Для этого просто вызовите
ISteamUserStats::AttachLeaderboardUGC. Этим контентом может быть видео того, как пользователь достиг этого счёта, или «фантом», с которым могут соревноваться другие игроки. Прикреплённый дескриптор будет доступен при чтении позиции, и его смогут скачать другие пользователи. Создание и загрузка контента, созданного пользователями, подробно описаны в документации Steam Cloud.
Как только контент добавлен, он будет доступен, даже если пользователь удалит или изменит соответствующий файл.
Получение позиций списка лидеров
ISteamUserStats::DownloadLeaderboardEntries используется для получения позиций в списке лидеров с помощью дескриптора, полученного от
ISteamUserStats::FindLeaderboard.
Как только вы получите все загруженные позиции с помощью GetDownloadedLeaderboardEntry, данные будут высвобождены и SteamLeaderboardEntries_t из LeaderboardScoresDownloaded_t станет недействительным.
Получение информации о списке лидеров
Используйте дескриптор, возвращённый FindLeaderboard, чтобы получить информацию о списке лидеров, с помощью следующих методов:
ISteamUserStats::GetLeaderboardNameISteamUserStats::GetLeaderboardEntryCountISteamUserStats::GetLeaderboardSortMethodISteamUserStats::GetLeaderboardDisplayType