Достижения

Обзор

Функционал GamePush позволяет добавлять в игру достижения, объединять в группы и модерировать их. А также следить за прогрессом и выполнением достижений игроками. Вы сможете разблокировать достижения по ID или Тегу и вызывать различные события при разблокировании достижений. В этом разделе приведена информация о том, как:

• Разблокировать достижение.
• Открыть список достижений, open - используется когда нужно показать достижения через готовый интерфейс.
• Получить список достижений, fetch - используется когда список достижений нужно отрисовать вручную.

А также информация о доступных полях достижений, полях групп достижений и полях достижений игрока.

Разблокировать достижение

+1 Request

Чтобы разблокировать достижение игрока нужно передать ID или тег достижения.

JavaScript

// Разблокировать по ID
gp.achievements.unlock({ id: 17541 });

// Разблокировать по тегу
gp.achievements.unlock({ tag: 'WIN_FIRST_BATTLE' });

Unity

// Разблокировать по ID
GP_Achievements.Unlock("17541");

// Разблокировать по тегу
GP_Achievements.Unlock("LEVEL_25");

События при разблокировании достижения

JavaScript

// Получено успешно
gp.achievements.on('unlock', (achievement) => {});

// Ошибка при разблокировании
gp.achievements.on('error:unlock', (error) => {});

Unity

public void Unlock() => GP_Achievements.Unlock("LEVEL_25", OnUnlock, OnUnlockError);

// Получено успешно
private void OnUnlock(string idOrTag) => Debug.Log("ON UNLCOK: SUCCESS: " + idOrTag);
// Ошибка при разблокировании
private void OnUnlockError() => Debug.Log("ON UNLOCK: ERROR");

Метод разблокирования с promises

JavaScript

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;

Unity

Не реализовано

Установить прогресс в достижении

+1 Request

Вы можете установить прогресс в достижении. Для этого в панели управления в достижении выставите в поле "Максимальный прогресс" на нужное вам значение.

Выставите "Шаг уведомлений" для показа уведомлений игроку о прогрессе каждые X очков прогресса.

При изменении прогресса достижение автоматически разблокируется, если прогресс больше максимального.

JavaScript

// Установить прогресс по ID
gp.achievements.setProgress({ id: 17541, progress: 57 });

// Установить прогресс по тегу
gp.achievements.setProgress({ tag: 'WIN_FIRST_BATTLE', progress: 57 });

Unity

// Установить прогресс по ID
GP_Achievements.SetProgress("17541", 25);

// Установить прогресс по тегу
GP_Achievements.SetProgress("LEVEL_50", 25);

События при прогрессе достижения

JavaScript

// Изменен прогресс в достижении
gp.achievements.on('progress', (achievement) => {});

// Ошибка при изменении прогресса
gp.achievements.on('error:progress', (error) => {});

Unity

private void SetProgress() => GP_Achievements.SetProgress("LEVEL_50", 25, OnPogress, OnProgressError);

// Изменен прогресс в достижении
private void OnPogress(string idOrTag) => Debug.Log("ON PROGRESS: SUCCESS: " + idOrTag);
// Ошибка при изменении прогресса
private void OnProgressError() => Debug.Log("PROGRESS: ERROR");

Асинхронная обработка ответа.

JavaScript

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;

Unity

Не реализовано

Проверки

FREE

Проверить есть ли у игрока достижение, по ID или тегу

JavaScript

const isUnlocked = gp.achievements.has('WIN_FIRST_BATTLE');

Unity

Debug.Log("HAS: " + GP_Achievements.Has("LEVEL_25"));

Проверить прогресс достижения, по ID или тегу

JavaScript

const progress = gp.achievements.getProgress('WIN_FIRST_BATTLE');

Unity

Debug.Log("PROGRESS: " + GP_Achievements.GetProgress("LEVEL_50"));

Открыть список достижений

FREE

Чтобы не реализовывать отображение достижений на вашей стороне, вы можете просто открыть их во внутриигровом оверлее.

JavaScript

gp.achievements.open();

Unity

GP_Achievements.Open();

События с внутриигровым оврелеем

JavaScript

// wait until closed
await gp.achievements.open();

Unity

Не реализовано

События оверлея достижений

JavaScript

// При открытии
gp.achievements.on('open', () => {});

// При закрытии
gp.achievements.on('close', () => {});

Unity

public void Open() => GP_Achievements.Open(OnOpen, OnClose);

// При открытии
private void OnOpen() => Debug.Log("ON OPEN");
// При закрытии
private void OnClose() => Debug.Log("ON CLOSE");

Cписок достижений

FREE

Список достижений:

JavaScript

gp.achievements.list;

Unity

//Список достижений получается через метод
GP_Achievements.Fetch();

Список достижений игрока, в которых есть прогресс и разблокированные достижения:

JavaScript

gp.achievements.playerAchievementsList;

Unity

//Список достижений игрока получается через метод
GP_Achievements.Fetch();

Список групп достижений:

JavaScript

gp.achievements.groupsList;

Unity

//Cписок групп достижений получается через метод
GP_Achievements.Fetch();

Получить список достижений

FREE Устарело

JavaScript

gp.achievements.fetch();

Unity

GP_Achievements.Fetch();

Метод получения с promises

JavaScript

const result = await gp.achievements.fetch();

// Результат запроса
const {
    // Список достижений
    achievements,
    // Список групп достижений
    achievementsGroups,
    // Список отметок о получении достижений игроком
    playerAchievements,
} = result;

Unity

Не реализовано

События при запросе достижений

JavaScript

// Запрос удался
gp.achievements.on('fetch', (result) => {});

// Не удалось получить список достижений
gp.achievements.on('error:fetch', (error) => {});

Unity

//Подписка на события
private void OnEnable()
{
    GP_Achievements.OnAchievementsFetch += OnFetchSuccess;
    GP_Achievements.OnAchievementsFetchError += OnFetchError;
    GP_Achievements.OnAchievementsFetchGroups += OnFetchGroups;
    GP_Achievements.OnAchievementsFetchPlayer += OnFetchPlayer;
}
//Отписка от событий
private void OnDisable()
{
    GP_Achievements.OnAchievementsFetch -= OnFetchSuccess;
    GP_Achievements.OnAchievementsFetchError -= OnFetchError;
    GP_Achievements.OnAchievementsFetchGroups -= OnFetchGroups;
    GP_Achievements.OnAchievementsFetchPlayer -= OnFetchPlayer;
}

// Результат запроса, обработка списка достижений
private void OnFetchSuccess(List<AchievementsFetch> achievements)
{
    Debug.Log("FETCH: SUCCESS");

    for (int i = 0; i < achievements.Count; i++)
    {
        Debug.Log("ID: " + achievements[i].id);
        Debug.Log("TAG: " + achievements[i].tag);
        Debug.Log("NAME: " + achievements[i].name);
        Debug.Log("DESCRIPTION: " + achievements[i].description);
        Debug.Log("ICON: " + achievements[i].icon);
        Debug.Log("ICON SMALL: " + achievements[i].iconSmall);
        Debug.Log("LOCKED ICON: " + achievements[i].lockedIcon);
        Debug.Log("LOCKED ICON SMALL: " + achievements[i].lockedIconSmall);
        Debug.Log("RARE: " + achievements[i].rare);
        Debug.Log("MAX PROGRESS: " + achievements[i].maxProgress);
        Debug.Log("PROGRESS STEP: " + achievements[i].progressStep);
        Debug.Log("LOCKED VISIBLE: " + achievements[i].lockedVisible);
        Debug.Log("LOCKED DESCRIPTION VISIBLE: " + achievements[i].lockedDescriptionVisible);
    }
}

// Результат запроса, обработка групп достижений
private void OnFetchGroups(List<AchievementsFetchGroups> data)
{
    Debug.Log("FETCH: GROUP: SUCCESS");

    for (int i = 0; i < data.Count; i++)
    {
        Debug.Log("ID: " + data[i].id);
        Debug.Log("TAG: " + data[i].tag);
        Debug.Log("NAME: " + data[i].name);
        Debug.Log("DESCRIPTION: " + data[i].description);

        for (int x = 0; x < data[i].achievements.Length; x++)
        {
            Debug.Log("ACHIEVEMENTS COUNT: " + data[i].achievements[x]);
        }
    }
}

// Результат запроса, обработка достижений игрока
private void OnFetchPlayer(List<AchievementsFetchPlayer> data)
{
    Debug.Log("FETCH: PLAYER ACHIEVEMENTS: SUCCESS");

    for (int i = 0; i < data.Count; i++)
    {
        Debug.Log("ACHIEVEMENT ID: " + data[i].achievementId);
        Debug.Log("CREATED AT: " + data[i].createdAt);
        Debug.Log("PROGRESS: " + data[i].progress);
        Debug.Log("UNLOCKED: " + data[i].unlocked);
    }
}

// Ошибка при запросе
private void OnFetchError() => Debug.Log("FETCH: ERROR");

Поля достижения

JavaScript

/**
 * 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;

Unity

public class AchievementsFetch
{
    //ID Достижения
    public int id;
    //Необязательный тег для помощи при выборе
    public string tag;
    //Название, переведенное на язык пользователя
    public string name;
    //Описание, переведенное на язык пользователя
    public string description;
    //Ссылка на иконку, размером 256x256
    public string icon;
    //Ссылка на иконку, размером 64x64
    public string iconSmall;
    //Ссылка на иконку неразблокированного достижения, размером 256x256
    public string lockedIcon;
    //Ссылка на иконку неразблокированного достижения, размером 64x64
    public string lockedIconSmall;
    //Редкость достижения
    public string rare;
    //Максимальный прогресс достижения
    public int maxProgress;
    //Шаг для уведомления о прогрессе
    public int progressStep;
    //Нужно ли показывать достижение, если оно не разблокировано
    public bool lockedVisible;
    //Нужно ли показывать описание достижения, если оно не разблокировано
    public bool lockedDescriptionVisible;
}       

Поля группы достижений

JavaScript

/**
 * ID Группы достижений
 * @type {number}
 */
achievementsGroup.id;

/**
 * Необязательный тег для помощи при выборе
 * Вы можете использовать его вместо ID
 * @type {string}
 */
achievementsGroup.tag;

/**
 * Название, переведенное на язык пользователя
 * @type {string}
 */
achievementsGroup.name;

/**
 * Описание, переведенное на язык пользователя
 * @type {string}
 */
achievementsGroup.description;

/**
 * Массив ID достижений в группе
 * @type {number[]}
 */
achievementsGroup.achievements;

Unity

public class AchievementsFetchGroups
{
    //ID Группы достижений
    public int id;
    //Необязательный тег для помощи при выборе
    public string tag;
    //Название, переведенное на язык пользователя
    public string name;
    //Описание, переведенное на язык пользователя
    public string description;
    //Массив ID достижений в группе
    public int[] achievements;
}

Поля достижения игрока

JavaScript

/**
 * ID Достижения
 * @type {number}
 */
playerAchievement.achievementId;

/**
 * Время, когда достижение было разблокировано
 * @type {string}
 */
playerAchievement.createdAt;

/**
 * Прогресс достижения
 * @type {number}
 */
playerAchievement.progress;

/**
 * Достижение разблокировано
 * @type {boolean}
 */
playerAchievement.unlocked;

Unity

public class AchievementsFetchPlayer
{
    //ID Достижения
    public int achievementId;
    //Время, когда достижение было разблокировано
    public string createdAt;
    //Прогресс достижения
    public int progress;
    //Достижение разблокировано
    public bool unlocked;
}

Оставайтесь на связи

С другими разделами документации вы можете ознакомиться здесь. Для начала работы вы можете ознакомиться с нашими туториалами.

Сообщество GamePush в Telegram: @gs_community.

Для ваших обращений e-mail: [email protected]

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