Достижения

Обзор

Функционал 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]

Желаем вам успехов!