Achievements

Overview

The SpellSync 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
ss.achievements.unlock({ id: 17541 })

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

Unity

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

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

Unlock achievement events

JavaScript

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

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

Unity

public void Unlock() => SS_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 ss.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
ss.achievements.setProgress({ id: 17541, progress: 57 })

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

Unity

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

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

Events when progress of the achievement

JavaScript

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

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

Unity

private void SetProgress() => SS_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 ss.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 = ss.achievements.has('WIN_FIRST_BATTLE')

Unity

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

Check the progress of an achievement by ID or tag:

JavaScript

const progress = ss.achievements.getProgress('WIN_FIRST_BATTLE')

Unity

Debug.Log("PROGRESS: " + SS_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

ss.achievements.open()

Unity

SS_Achievements.Open();

Open with promises

JavaScript

// wait until closed
await ss.achievements.open()

Unity

Not implemented

Achievements overlay events

JavaScript

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

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

Unity

public void Open() => SS_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

ss.achievements.list

Unity

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

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

JavaScript

ss.achievements.playerAchievementsList

Unity

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

List of achievement groups:

JavaScript

ss.achievements.groupsList

Unity

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

Get achievements list

FREE Deprecated

JavaScript

ss.achievements.fetch()

Unity

SS_Achievements.Fetch();

Fetch with promises

JavaScript

const result = await ss.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
ss.achievements.on('fetch', (result) => {})

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

Unity

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

//Unsubscribe from events
private void OnDisable()
{
    SS_Achievements.OnAchievementsFetch -= OnFetchSuccess;
    SS_Achievements.OnAchievementsFetchError -= OnFetchError;
    SS_Achievements.OnAchievementsFetchGroups -= OnFetchGroups;
    SS_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.

SpellSync Community Telegram: @spellsync.

For your suggestions e-mail: [email protected]

We Wish you Success!