Огляд

Steam підтримує постійні таблиці лідерів з автоматично відсортованими записами. Ці таблиці лідерів можна використовувати для показу глобальних рейтингів чи рейтингів між друзями в грі або на сторінці спільноти. Кожен продукт Steamworks може створити до 10 000 таблиць лідерів, і кожна таблиця лідерів оновлюється негайно після введення туди очок гравця.

У кожній таблиці лідерів гравець може мати лише одну позицію. Немає обмеження на кількість гравців у таблиці лідерів. Кожен запис таблиці лідерів містить очки (int32) і, якщо потрібно, до 64 чисел (int32) пов’язаних даних. Пов’язані дані можна використовувати для зберігання певної інформації про ігровий сеанс, результатом якої стала позиція гравця в таблиці лідерів. Ці дані не сортуються й не обробляються Steam, а також замінюються, коли для користувача створюється нова позиція в таблиці лідерів.

Усі функції таблиць лідерів знаходяться в ISteamUserGameStats.h, а приклад Steamworks містить дві прості таблиці лідерів. Перегляд та адміністрування таблиць лідерів вашої гри можна здійснювати на сторінці адміністрування гри в Steamworks.

Перед початком

Усі асинхронні функції таблиці лідерів повертають дескриптор для результату виклику API Steam. Докладнішу інформацію про отримання цих результатів можна знайти в розділі про результати виклику вступної статті про API Steamworks.

Створення таблиці лідерів

Таблиці лідерів визначаються для застосунку й налаштовуються на сторінці адміністрування цього застосунку на партнерському сайті Steamworks або через API.

Створення на сайті

Ви можете створювати та змінювати таблиці лідерів в адмініструванні свого застосунку в Steamworks ось тут.


Наступні поля потрібно заповнити для створення таблиці лідерів:

• Назва. Встановіть таку назву, яка має сенс для внутрішньої розробки.
  
• Назва в спільноті. Якщо таблиця лідерів показується в центрі спільноти, то вкажіть тут загальнодоступну назву. Якщо тут нічого не вказувати, то таблиця лідерів не показуватиметься.
  
• Спосіб сортування. Вкажіть порядок сортування для таблиці лідерів. Для списків із місцем гравця використовуйте «за зростанням». Для списків із рахунком використовуйте «за спаданням».
  
• Тип показу. Визначає тип даних, які показуються з таблицею лідерів. Варіанти: числа, секунди чи мілісекунди.
  
• Запис даних. Якщо встановити на довірений запис, то клієнти не зможуть надсилати дані про очки в таблиці лідерів, це можна буде зробити лише за допомогою веб-API SetLeaderboardScore. Стандартно: false.
  
• Читання даних. Якщо встановити значення «друзі», то гра зможе читати дані таблиці лідерів лише для друзів користувача, але всі дані таблиці завжди можна буде прочитати за допомогою веб-API. Стандартно: false.

Створення за допомогою API

Таблиці лідерів для вашої гри можна створити в адмініструванні застосунку на сайті Steamworks або програмно за допомогою ISteamUserStats::FindOrCreateLeaderboard. Усі таблиці лідерів продукту Steamworks ідентифікуються в Steam за допомогою унікальної назви. Назва таблиці лідерів використовується лише для ідентифікації в API Steamworks і не показується користувачам у спільноті Steam. Під час створення таблиці лідерів потрібно вибрати:

• спосіб сортування — k_ELeaderboardSortMethodAscending (на верхній позиції буде користувач із найнижчим рахунком) або k_ELeaderboardSortMethodDescending (на верхній позиції буде користувач із найвищим рахунком);
  
• тип показу — ELeaderboardDisplayType використовується для опису того, що представляє рахунок таблиці лідерів, і використовується лише в спільноті для форматування рахунку таблиці лідерів під час показу.

Якщо ви обираєте створити таблиці лідерів за допомогою сайту Steamworks, то можете використовувати ISteamUserStats::FindLeaderboard для отримання дескриптора таблиці лідерів. FindLeaderboard і FindOrCreateLeaderboard — це асинхронні методи, які повертають дескриптор таблиці лідерів для вказаної таблиці через результат виклику ISteamUserStats::LeaderboardFindResult_t.

Коли таблицю лідерів створено, ви можете змінити спосіб сортування й тип показу на сторінці адміністрування застосунку. Коли для наявної таблиці лідерів викликано 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