First, log into your account via iTunesConnect and ENABLE Game Center in your desired app.
Once enabled you can set up leaderboards and achievements. Click the SETUP button for achievements. This will take you to the Achievement interface.
Next click the button at the top of the interface to ADD NEW ACHIEVEMENT.
On the next screen you will need to fill in a few fields:
- Achievement Reference Name: Your personal reference name (non public).
- Achievement ID: the unique string that you will use to connect your game’s achievements to the Game Center server when updating achievements.
- Hidden: allows you to specify if the player can see the achievement before being awarded the achievement
- Point Value: the value of the achievement when unlocked. You can award up to 100 points per achievement for a total of 1000 overall points added up.
After you have set those values up click the ADD LANGUAGE button to set up the public facing values of your achievement.
- Language: defaulted to your app’s default language
- Title: The public facing name of your achievement
- Pre-earned Description: the description of the achievement the player will see before earning the achievement
- Earned Description: the description of the achievement the player will see after earning the achievement
- Image: 512×512 icon that will display when the achievement is unlocked
When you are finished click the SAVE button to close the window. You can then click SAVE in the main Achievement editing dialog to save your changes.
Repeat this process for all of your achievements, paying special attention to the Achievement ID field, as that will be your main sync point with GameSalad.
Implementing Game Center Achievements in GameSalad
Now that you have set up your achievements on iTunesConnect you can link them using the Game Center Achievement behaviors in GameSalad.
There are three behaviors you will use to access Game Center Achievements: Show Achievements, Reset Achievements, Update Achievement.
Game Center – Show Achievements: this behavior will PAUSE the game and load the Apple Game Center Achievements window for your game (associated via the bundle identifier).
Game Center – Reset Achievements: this behavior will reset the logged achievements for the current user from the Game Center server.
IMPORTANT: Should only be used when debugging on an ad hoc build of your game and not in the final submitted app.
Setting up an Achievement – Single Event Unlock
You have probably played games before where you would unlock an achievement by beating a certain level or finding a specific hidden item. This would be a single event unlock, meaning the player would trigger the achievement immediately after this specific single event. These are the easiest types of achievements to set up in GameSalad.
- First, link up your your corresponding Achievement ID from iTunesConnect in the Achievement ID field
- In the percentage field, simply put the value 100.
- Lastly, be sure to put this behavior inside of the proper rule condition that corresponds to the event so it will trigger correctly. For example your rule could be “When game won is TRUE” then trigger achievement.
That is all you need to do!
Setting up an Achievement – Incremental Event Unlock
Incremental achievement unlocks are a little more involved and will require some math. Incremental achievements are ones that trigger when multiple events have been completed such as destroying 200 enemies or finding 50 hidden stars. When you update the achievement with Game Center you will be updating a partial achievement that will be represented by a progress wheel.
There are numerous ways to set up the Percentage field for proper updating, but the general rule of thumb will be to include an expression like this:
(Total Units / Goal Units) *100
To better explain the equation, imagine an achievement for destroying 1500 total enemy ships throughout the entire game. Each time you destroy an enemy ship you will increment a game attribute (game.shipsdestroyed for example) by 1 and save. In this scenario, you would also have an actor that updated the achievement at the end of the level or even each time the enemy counter increases – the choice is yours. In the percentage field you would put game.shipsdestroyed/1500 *100.
No matter how you set up the division of current units over goal units you will need to multiply the result by 100 in order to create a percentage value that Game Center will recognize.
– First, create a self or game attribute you will use to persistently track your units. This could be for kills, coins collected, victories, etc.
– Then, link up your your corresponding Achievement ID from iTunesConnect in the Achievement ID field
– In the percentage field, use the expression editor to create an equation: (game attribute / goal amount) *100
This behavior can go in a number of places and should be determined by when you would like to allow achievement unlocks. Many games allow achievement unlocks in the middle of gameplay while others only process them in between levels. Use whatever method makes sense for your design.
Saving & Achievements
When you update an achievement successfully it will save automatically on the Game Center servers.
Once an achievement is unlocked and awarded via Game Center it cannot be awarded again. Even if you continue to update an achievement past 100% it will be ignored by Game Center so there is no need to add extra SAVE logic for the achievement itself.
If you wanted other in-game indicators or events to trigger based on an achievement unlock, then you would need some custom saving logic. There are many ways to do this and we leave it to you to implement using your preferred methods.
Testing your Achievements
GameSalad does not communicate directly with Game Center when previewing so it is necessary to publish an ad hoc build of your game using the same bundle identifier that you created the Achievements for through iTunesConnect for testing.
In iTunes Connect you can create a testing email account to log into Game Center with for your test ad hoc build.
Either through the Game Center app, or through a Log In behavior, sign in using your test account. Then trigger your achievements. If you have done this correctly you will be able to view your progress towards the achievements using the Show Achievements behavior. Partial achievements will be displayed with the circular progress bar and completed achievements will be shown as the icon you set up in iTunesConnect.
