Spine Tutorial 2 – Achievements

Requirements

Introduction

With Spine you can easily implement achievements as they are known by other platforms like Steam. This tutorials shows everything that needs to be done to implement achievements. As base the first tutorial regarding Initialization is recommended. Required is the module “Achievements”, which is SPINE_MODULE_ACHIEVEMENTS in the scripts.

Configure Achievements

To be able to use achievements they need the following values:

  • ID
  • Name
  • Description
  • Icon
  • Hidden

The ID is necessary to identify the achievement and create a relation between the components. It is unique and is required both in the scripts and Spine itself. The name of the achievement is assigned to exactly one ID and will be shown on the achievement and within Spine. The description gives informations about the achievement. The text can be empty or only be shown when the achievement has been unlocked. It’s only displayed in Spine, not in the modification. And last but not least every achievement needs a small icon. It’s required in two variants, for locked and unlocked state. If you can’t create a texture yourself you can use the default texture Spine delivers. But it’s recommended to create your own for better individualization. The texture is scaled to a resolution of 64×64 and shouldn’t undercut it. If you don’t provide an own locked icon, but an individual unlocked icon, Spine will automatically generate a grayscale version of it. And then there is the hidden flag. It’s only relevant within Spine and decided whether the achievement shall be visible even when locked or only when unlocked.

The configurations of achievements takes place in the Spine_UserConstants.d. Therefor you need these constants:

  • MAX_ACHIEVEMENTS
  • SPINE_ACHIEVEMENT_NAMES
  • SPINE_ACHIEVEMENT_TEXTURES
  • SPINE_ACHIEVEMENT_PROGRESS

MAX_ACHIEVEMENTS contains the amount of all achievements in the modification. SPINE_ACHIEVEMENT_NAMES contains the names of the achievements and SPINE_ACHIEVEMENT_TEXTURES the corresponding texture. SPINE_ACHIEVEMENT_DEFAULT.TGA is the default texture Spine delivers and can be used if no own texture is available. Otherwise replace it with the name of your texture. SPINE_ACHIEVEMENT_PROGRESS defines the maximum progress for progress achievements (see below).

Now you should also create a constant for every achievement, the identifier. That can look like the following:

const int Mod_Erfolg_01 = 0;

It’s important that the first achievement always has the ID 0 and the others are ascending to that. The order just is important for the assignment and has nothing to do with the order of unlocking the achievements.

Here is a complete example configuration of achievements:

const int Mod_Erfolg_01 = 0;
const int Mod_Erfolg_02 = 1;
const int Mod_Erfolg_03 = 2;

const int MAX_ACHIEVEMENTS = 3;
const string SPINE_ACHIEVEMENT_NAMES[MAX_ACHIEVEMENTS] = {
	"Kapitel 1", // will be unlocked when reaching chapter 2
	"Sammler", // will be unlocked when collecting 10 plants
	"Erwache" // will be unlocked after beating the Sleeper
};

const string SPINE_ACHIEVEMENT_TEXTURES[MAX_ACHIEVEMENTS] = {
	"SPINE_ACHIEVEMENT_DEFAULT.TGA",
	"SPINE_ACHIEVEMENT_DEFAULT.TGA",
	"SPINE_ACHIEVEMENT_DEFAULT.TGA"
};

const string SPINE_ACHIEVEMENT_PROGRESS[MAX_ACHIEVEMENTS] = {
	"0",
	"10",
	"0"
};

Starting with Spine 1.3 for easier configuration you can use the Spine Editor within Spine. With it you can configure it via a GUI.

Optional Settings

Besides the required settings there are a few more optional ones. These allow to configure the achievements a little. Therefore we have two settings:

  • SPINE_ACHIEVEMENTORIENTATION
  • SPINE_ACHIEVEMENT_DISPLAY_TIME

SPINE_ACHIEVEMENTORIENTATION defines where the achievement shall be displayed. Therefore you have the four positions SPINE_BOTTOMRIGHT, SPINE_BOTTOMLEFT, SPINE_TOPLEFT and SPINE_TOPRIGHT representing the four corners of the screen. With SPINE_ACHIEVEMENT_DISPLAY_TIME you can configure how long an achievement is displayed. The default value is 3000 which means 3 seconds.

Unlocking Achievements

When the configuration is done you just need to call the correct function when the condition for unlocking the achievement is met.

Spine_UnlockAchievement(id);

Taking the achievements from the previous example you can now call

Spine_UnlockAchievement(Mod_Erfolg_01);

when reaching chapter 2 and the rest of it is handled by Spine.

Achievements with Progress

Starting with Spine 1.4 you also have achievements with a progress. You can use it for achievements like “Kill 100 enemies”, but also for some like “Finish the game with each of the three main guilds”.. For progress achievements additionally the maximum amount to unlock the achievement is required. The current value and the maximum value can be queried using

Spine_GetAchievementProgress(id);
Spine_GetAchievementMaxProgress(id);

When the progress changes, just set the new value using

Spine_UpdateAchievementProgress(id, progress);

As soon as the current progress matches the maximum progress the achievement is automatically unlocked.

Spine_IncrementAchievementProgress

As a small helper function for progress achievements Spine_IncrementAchievementProgress exists. It raises the progress of this achievement just by one instead of doing the addition manually.

Requesting Achievements from another modification

Some teams release multiple mods and want to somehow connect the modifications. So it would be possible to unlock an achievement only if the player reached some other achievement in the previous mod of the team has been unlocked.

Therefor the function Spine_IsAchievementOfOtherModUnlocked exists. As parameters it gets the ID of the other modification (if you don’t know it you can look it up in the database) and the achievement ID. As Spine_IsAchievementUnlocked it will return TRUE in case the achievement is unlocked, otherwise FALSE.

Getting Achievements into the Spine database

Well, so far you can use the achievements in the scripts, but your database entry in Spine won’t show that the game has achievements and also not unlock any.

To get this done, just do the following:

  1. Start Spine
  2. In the menu bar on top select “Developer” => “Management”
  3. Select your modification on the left side
  4. Switch to the “Achievements” tab
  5. Enter all your achievement details in here
  6. After you entered everything, just submit

Now the achievements will appear on your info page, the library and the profile and can be unlocked from within the game.

Check out the tutorial Publishing on Spine.