Achievements

Overview

The GamePush functionality allows you to add achievements to the game, combine them into groups and manage them. And also monitor the progress and accomplishment of achievements by players. You will be able to unlock achievements by ID or Tag and trigger various events when unlocking achievements. This section provides information on how to:

• Unlock achievement.
• Open list of achievements, open - used when you need to show achievements through a ready-made interface.
• Get a list of achievements, fetch - used when the list of achievements needs to be drawn manually.

As well as information about available achievement fields, achievement group fields, and player achievement fields.

Unlock achievement

+1 Request

To unlock player's achievement, you need to pass an ID or Tag of achievement.

JavaScript

// Unlock by id
gp.achievements.unlock({ id: 17541 });

// Unlock by tag
gp.achievements.unlock({ tag: 'WIN_FIRST_BATTLE' });

Unity

// Unlock by id
GP_Achievements.Unlock("17541");

// Unlock by tag
GP_Achievements.Unlock("LEVEL_25");

Unlock achievement events

JavaScript

// Unlock success
gp.achievements.on('unlock', (achievement) => {});

// Unlock error
gp.achievements.on('error:unlock', (error) => {});

Unity

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

// Unlock success
private void OnUnlock(string idOrTag) => Debug.Log("ON UNLCOK: SUCCESS: " + idOrTag);
// Unlock error
private void OnUnlockError() => Debug.Log("ON UNLOCK: ERROR");

Unlock with promises

JavaScript

const result = await gp.achievements.unlock({ id: 17541 });

/**
 * Is achievement was success unlocked
 * @type {boolean}
 */
result.success;

/**
 * Achievement data
 * @type {Achievement | null}
 */
result.achievement;

/**
 * Error if unlock failed
 * @type {
 *     'player_not_found' |
 *     'empty_id_or_tag' |
 *     'achievement_not_found' |
 *     'already_unlocked' |
 *      undefined
 * }
 */
result.error;

Unity

Not implemented

Setting Progress in an Achievement

+1 Request

You can set progress in an achievement. To do this, in the control panel in the achievement, set the "Maximum Progress" field to the value you need.

Set the "Notification Step" to show notifications to the player about the progress every X progress points.

When the progress changes, the achievement is automatically unlocked if the progress is greater than the maximum.

JavaScript

// Set progress by ID
gp.achievements.setProgress({ id: 17541, progress: 57 });

// Set progress by tag
gp.achievements.setProgress({ tag: 'WIN_FIRST_BATTLE', progress: 57 });

Unity

// Set progress by ID 
GP_Achievements.SetProgress("17541", 25);

// Set progress by tag
GP_Achievements.SetProgress("LEVEL_50", 25);

Events when progress of the achievement

JavaScript

// Progress of achievement changed
gp.achievements.on('progress', (achievement) => {});

// Error while changing progress
gp.achievements.on('error:progress', (error) => {});

Unity

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

// Progress of achievement changed
private void OnPogress(string idOrTag) => Debug.Log("ON PROGRESS: SUCCESS: " + idOrTag);
// Error while changing progress
private void OnProgressError() => Debug.Log("PROGRESS: ERROR");

Asynchronous response processing.

JavaScript

const result = await gp.achievements.setProgress({ id: 17541, progress: 57 });
/**
 * Whether the progress was changed successfully
 * @type {boolean}
 */
result.success;

/**
 * Data about the achievement
 * @type {Achievement | null}
 */
result.achievement;

/**
 * Error if something went wrong
 * @type {
 *     'player_not_found' |
 *     'empty_id_or_tag' |
 *     'achievement_not_found' |
 *     'achievement_has_no_progress' |
 *     'progress_the_same' |
 *     'already_unlocked' |
 *      undefined
 * }
 */
result.error;

Unity

Not implemented

Checks

FREE

Check if the player has an achievement by ID or tag:

JavaScript

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

Unity

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

Check the progress of an achievement by ID or tag:

JavaScript

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

Unity

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

Open achievements list

FREE

In order not to implement the displaying of the achievements on your side, you can simply open it in the in-game overlay.

JavaScript

gp.achievements.open();

Unity

GP_Achievements.Open();

Open with promises

JavaScript

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

Unity

Not implemented

Achievements overlay events

JavaScript

// On open
gp.achievements.on('open', () => {});

// On close
gp.achievements.on('close', () => {});

Unity

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

// On open
private void OnOpen() => Debug.Log("ON OPEN");
// On close
private void OnClose() => Debug.Log("ON CLOSE");

List of Achievements

FREE

List of achievements:

JavaScript

gp.achievements.list;

Unity

//You can get list of achievements using this
GP_Achievements.Fetch();

List of player's achievements that have progress and unlocked achievements:

JavaScript

gp.achievements.playerAchievementsList;

Unity

//You can get list of player's achievements using this
GP_Achievements.Fetch();

List of achievement groups:

JavaScript

gp.achievements.groupsList;

Unity

//You can get list of achievement groups using this
GP_Achievements.Fetch();

Get achievements list

FREE Deprecated

JavaScript

gp.achievements.fetch();

Unity

GP_Achievements.Fetch();

Fetch with promises

JavaScript

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

// Response result
const {
    // Achievements list
    achievements,
    // Achievements groups
    achievementsGroups,
    // Player's unlocked achievements
    playerAchievements,
} = result;

Unity

Not implemented

Fetch achievements events

JavaScript

// Fetch success
gp.achievements.on('fetch', (result) => {});

// Fetch error
gp.achievements.on('error:fetch', (error) => {});

Unity

//Subscribe to events
private void OnEnable()
{
    GP_Achievements.OnAchievementsFetch += OnFetchSuccess;
    GP_Achievements.OnAchievementsFetchError += OnFetchError;
    GP_Achievements.OnAchievementsFetchGroups += OnFetchGroups;
    GP_Achievements.OnAchievementsFetchPlayer += OnFetchPlayer;
}

//Unsubscribe from events
private void OnDisable()
{
    GP_Achievements.OnAchievementsFetch -= OnFetchSuccess;
    GP_Achievements.OnAchievementsFetchError -= OnFetchError;
    GP_Achievements.OnAchievementsFetchGroups -= OnFetchGroups;
    GP_Achievements.OnAchievementsFetchPlayer -= OnFetchPlayer;
}

// Fetch success, process achievements
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);
    }
}

// Fetch success, process achievements groups
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]);
        }
    }
}

// Fetch success, process player achievements
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);
    }
}
// Fetch error
private void OnFetchError() => Debug.Log("FETCH: ERROR");

Achievement fields

JavaScript

/**
 * Achievement ID
 * @type {number}
 */
achievement.id;

/**
 * Optional tag for help in selecting
 * You can use it instead of ID
 * @type {string}
 */
achievement.tag;

/**
 * Name translated into current language
 * @type {string}
 */
achievement.name;

/**
 * Description translated into current language
 * @type {string}
 */
achievement.description;

/**
 * Icon src 256x256
 * @type {string}
 */
achievement.icon;

/**
 * Icon src 64x64
 * @type {string}
 */
achievement.iconSmall;

/**
 * Icon src of locked achievement, 256x256
 * @type {string}
 */
achievement.lockedIcon;

/**
 * Icon src of locked achievement, 64x64
 * @type {string}
 */
achievement.lockedIconSmall;

/**
 * Rarity of achievement
 * @type {'COMMON' | 'UNCOMMON' | 'RARE' | 'EPIC' | 'LEGENDARY' | 'MYTHIC'}
 */
achievement.rare;

/**
 * Maximum progress of the achievement
 * @type {number}
 */
achievement.maxProgress;

/**
 * Step for progress notification
 * @type {number}
 */
achievement.progressStep;

/**
 * Whether the achievement should be shown if it's not unlocked
 * @type {boolean}
 */
achievement.lockedVisible;

/**
 * Whether the description of the achievement should be shown if it's not unlocked
 * @type {boolean}
 */
achievement.lockedDescriptionVisible;

Unity

public class AchievementsFetch
{
    //Achievement ID
    public int id;
    //Optional tag for help in selecting
    public string tag;
    //Name translated into current language
    public string name;
    //Description translated into current language
    public string description;
    //Icon src 256x256
    public string icon;
    //Icon src 64x64
    public string iconSmall;
    //Icon src of locked achievement, 256x256
    public string lockedIcon;
    //Icon src of locked achievement, 64x64
    public string lockedIconSmall;
    //Rarity of achievement
    public string rare;
    //Maximum progress of the achievement
    public int maxProgress;
    //Step for progress notification
    public int progressStep;
    //Whether the achievement should be shown if it's not unlocked
    public bool lockedVisible;
    //Whether the description of the achievement should be shown if it's not unlocked
    public bool lockedDescriptionVisible;
}       

Achievements Group fields

JavaScript

/**
 * Achievement group ID
 * @type {number}
 */
achievementsGroup.id;

/**
 * Optional tag for help in selecting
 * You can use it instead of ID
 * @type {string}
 */
achievementsGroup.tag;

/**
 * Name translated into current language
 * @type {string}
 */
achievementsGroup.name;

/**
 * Description translated into current language
 * @type {string}
 */
achievementsGroup.description;

/**
 * Array of achievement ID in group
 * @type {number[]}
 */
achievementsGroup.achievements;

Unity

public class AchievementsFetchGroups
{
    //Achievement group ID
    public int id;
    //Optional tag for help in selecting
    public string tag;
    //Name translated into current language
    public string name;
    //Description translated into current language
    public string description;
    //Array of achievement ID in group
    public int[] achievements;
}

Player Achievement fields

JavaScript

/**
 * Achievement ID
 * @type {number}
 */
playerAchievement.achievementId;

/**
 * Time when the achievement was unlocked
 * @type {string}
 */
playerAchievement.createdAt;

/**
 * Achievement progress
 * @type {number}
 */
playerAchievement.progress;

/**
 * Achievement unlocked
 * @type {boolean}
 */
playerAchievement.unlocked;

Unity

public class AchievementsFetchPlayer
{
    //Achievement ID
    public int achievementId;
    //Time when the achievement was unlocked
    public string createdAt;
    //Achievement progress
    public int progress;
    //Achievement unlocked
    public bool unlocked;
}

Stay in Touch

Other documents of this chapter available Here. To get started, welcome to the Tutorials chapter.

GamePush Community Telegram: @gs_community.

For your suggestions e-mail: [email protected]

We Wish you Success!