Достижения
Обзор
Функционал GamePush позволяет добавлять в игру достижения, объединять в группы и модерировать их. А также следить за прогрессом и выполнением достижений игроками. Вы сможете разблокировать достижения по ID
или Тегу
и вызывать различные события при разблокировании достижений. В этом разделе приведена информация о том, как:
- Разблокировать достижение.
- Открыть список достижений,
open
- используется когда нужно показать достижения через готовый интерфейс. - Получить список достижений,
fetch
- используется когда список достижений нужно отрисовать вручную.
А также информация о доступных полях достижений, полях групп достижений и полях достижений игрока.
Разблокировать достижение
Чтобы разблокировать достижение игрока нужно передать ID или тег достижения.
// Разблокировать по ID
gp.achievements.unlock({ id: 17541 });
// Разблокировать тегу
gp.achievements.unlock({ tag: 'WIN_FIRST_BATTLE' });
События при разблокировании достижения
// Получено успешно
gp.achievements.on('unlock', (achievement) => {});
// Ошибка при разблокировании
gp.achievements.on('error:unlock', (error) => {});
Метод разблокирования с promises
const result = await gp.achievements.unlock({ id: 17541 });
/**
* Было ли успешно разблокировано
* @type {boolean}
*/
result.success;
/**
* Данные о достижении
* @type {Achievement | null}
*/
result.achievement;
/**
* Ошибка, если что-то пошло не так
* @type {
* 'player_not_found' |
* 'empty_id_or_tag' |
* 'achievement_not_found' |
* 'already_unlocked' |
* undefined
* }
*/
result.error;
Установить прогресс в достижении
Вы можете установить прогресс в достижении. Для этого в панели управления в достижении выставите в поле "Максимальный прогресс" на нужное вам значение.
Выставите "Шаг уведомлений" для показа уведомлений игроку о прогрессе каждые X очков прогресса.
При изменении прогресса достижение автоматически разблокируется, если прогресс больше максимального.
// Установить прогресс по ID
gp.achievements.setProgress({ id: 17541, progress: 57 });
// Установить прогресс тегу
gp.achievements.setProgress({ tag: 'WIN_FIRST_BATTLE', progress: 57 });
События при прогрессе достижения
// Изменен прогресс в достижении
gp.achievements.on('progress', (achievement) => {});
// Ошибка при изменении прогресса
gp.achievements.on('error:progress', (error) => {});
Асинхронная обработка ответа.
const result = await gp.achievements.setProgress({ id: 17541, progress: 57 });
/**
* Успешно ли изменен прогресс
* @type {boolean}
*/
result.success;
/**
* Данные о достижении
* @type {Achievement | null}
*/
result.achievement;
/**
* Ошибка, если что-то пошло не так
* @type {
* 'player_not_found' |
* 'empty_id_or_tag' |
* 'achievement_not_found' |
* 'achievement_has_no_progress' |
* 'progress_the_same' |
* 'already_unlocked' |
* undefined
* }
*/
result.error;
Проверки
Проверить есть ли у игрока достижение, по ID или тегу
const isUnlocked = gp.achievements.has('WIN_FIRST_BATTLE');
Проверить прогресс достижения, по ID или тегу
const progress = gp.achievements.getProgress('WIN_FIRST_BATTLE');
Открыть список достижений
Чтобы не реализовывать отображение достижений на вашей стороне, вы можете просто открыть их во внутриигровом оверлее.
gp.achievements.open();
События с внутриигровым оврелеем
// wait until closed
await gp.achievements.open();
События оверлея достижений
// При открытии
gp.achievements.on('open', () => {});
// При закрытии
gp.achievements.on('close', () => {});
Получить список достижений
gp.achievements.fetch();
Метод получения с promises
const result = await gp.achievements.fetch();
// Результат запроса
const {
// Список достижений
achievements,
// Список групп достижений
achievementsGroups,
// Список отметок о получении достижений игроком
playerAchievements,
} = result;
События при запросе достижений
// Запрос удался
gp.achievements.on('fetch', (result) => {});
// Не удалось получить список достижений
gp.achievements.on('error:fetch', (error) => {});
Поля достижения
/**
* ID Достижения
* @type {number}
*/
achievement.id;
/**
* Необязательный тег для помощи при выборе
* Вы можете использовать его вместо ID
* @type {string}
*/
achievement.tag;
/**
* Название, переведенное на язык пользователя
* @type {string}
*/
achievement.name;
/**
* Описание, переведенное на язык пользователя
* @type {string}
*/
achievement.description;
/**
* Ссылка на иконку, размером 256x256
* @type {string}
*/
achievement.icon;
/**
* Ссылка на иконку, размером 64x64
* @type {string}
*/
achievement.iconSmall;
/**
* Ссылка на иконку неразблокированного достижения, размером 256x256
* @type {string}
*/
achievement.lockedIcon;
/**
* Ссылка на иконку неразблокированного достижения, размером 64x64
* @type {string}
*/
achievement.lockedIconSmall;
/**
* Редкость достижения
* @type {'COMMON' | 'UNCOMMON' | 'RARE' | 'EPIC' | 'LEGENDARY' | 'MYTHIC'}
*/
achievement.rare;
/**
* Максимальный прогресс достижения
* @type {number}
*/
achievement.maxProgress;
/**
* Шаг для уведомления о прогрессе
* @type {number}
*/
achievement.progressStep;
/**
* Нужно ли показывать достижение, если оно не разблокировано
* @type {boolean}
*/
achievement.lockedVisible;
/**
* Нужно ли показывать описание достижения, если оно не разблокировано
* @type {boolean}
*/
achievement.lockedDescriptionVisible;
Поля группы достижений
/**
* ID Группы достижений
* @type {number}
*/
achievementsGroup.id;
/**
* Необязательный тег для помощи при выборе
* Вы можете использовать его вместо ID
* @type {string}
*/
achievementsGroup.tag;
/**
* Название, переведенное на язык пользователя
* @type {string}
*/
achievementsGroup.name;
/**
* Описание, переведенное на язык пользователя
* @type {string}
*/
achievementsGroup.description;
/**
* Массив ID достижений в группе
* @type {number[]}
*/
achievementsGroup.achievements;
Поля достижения игрока
/**
* ID Достижения
* @type {number}
*/
playerAchievement.achievementId;
/**
* Время, когда достижение было разблокировано
* @type {string}
*/
playerAchievement.createdAt;
/**
* Прогресс достижения
* @type {number}
*/
playerAchievement.progress;
/**
* Достижение разблокировано
* @type {boolean}
*/
playerAchievement.unlocked;
Оставайтесь на связи
С другими разделами документации вы можете ознакомиться здесь. Для начала работы вы можете ознакомиться с нашими туториалами.
Сообщество GamePush в Telegram
: @gs_community.
Для ваших обращений e-mail
: [email protected]
Желаем вам успехов!