Введение

В 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::GetLeaderboardName
ISteamUserStats::GetLeaderboardEntryCount
ISteamUserStats::GetLeaderboardSortMethod
ISteamUserStats::GetLeaderboardDisplayType