Adding achievements to your game

• We’ll have two separate ListViews in our UI for Achievements, one to display all the definitions, and one to display the player progress. For now, we’ll start with the ListView for all definitions, which will only occupy part of the UI.

 

2. Open AchievementsView.xaml.cs to attach the ViewModel and hold the placeholder selection changed event handler:

3. Add an AchievementsViewModel.cs class to the ViewModels folder:

4. Add a reference to AchievementsViewModel in ViewModelLocator.cs:

5. Add an AchievementsService.cs class to the Services folder to hold the definition query logic:

• We call Achievements.QueryDefinitions to populate our local cache with all achievement definitions.
• Then we iterate through all achievements returned, and copy them from the cache to our ObservableCollection through Achievements.CopyAchievementDefinitionV2ByIndex.
  • Note that we’re using the V2 APIs in the SDK, which replace the deprecated older APIs (e.g. CopyAchievementDefinitionByIndex).

 

6. Add a AchievementsQueryDefinitionsCommand.cs class to the Commands folder:

7. Open AchievementsViewModel.cs to declare and instantiate the command:

8. Add the following line to the RaiseConnectCanExecuteChanged() method in ViewModelLocator.cs to ensure we can only query for Achievement definitions after successfully logging in through the Connect Interface:

9. Lastly, add the AchievementsView to our TabControl in MainWindow.xaml:

Now when we run the app and authenticate through Auth and Connect, we can navigate to the Achievements tab and query the achievement definitions using the Query definitions button.
 

Querying player achievement progress

Now that we know how to retrieve all achievement definitions, let’s take a look at retrieving the player’s progress towards them:
 

1. Open AchievementsView.xaml and add our second ListView and StackPanel right below the previous </ListView> tag:

• We’re using a bit of a brute force method to display the stat that’s attached to the achievement (if any). We’re displaying the first stat in the array (even if there aren’t any). In a production environment you’ll have to validate the array of PlayerStatInfo returned in the StatInfo property before using it.

 

2. Open AchievementsViewModel.cs and declare the following collection below the SelectedAchievement to hold player achievement progress:

3. Open AchievementsService.cs and add the following method to hold our player achievement progress query logic:

• The pattern here is identical: we call Achievements.QueryPlayerAchievements to cache the player achievement progress, then iterate and call Achievements.CopyPlayerAchievementByIndex to copy the progress from cache to our collection.

 

4. Add an AchievementsQueryPlayerAchievementsCommand.cs class to the Commands folder:

5. Open AchievementsViewModel.cs to declare and instantiate the command:

6. Open ViewModelLocator.cs and add the following line to the RaiseConnectCanExecuteChanged() method to ensure we can only query for player achievement progress after successfully logging in through the Connect Interface:

Now we can launch our app again and use the Query progress button to retrieve the player’s achievement progress.
 
There are a few things to note here:
 

• The DisplayName property returned from the QueryPlayerAchievements call is null, similar to the Description, IconURL, and FlavorText properties (which we’re not displaying in the UI). These properties are retrieved and stored into the SDK cache by the QueryDefinitions call, so we need to click the Query definitions button first to populate these properties in the cache.
• The StatInfo property will be null unless the player has stat values ingested. In the screenshot above, I have the logged in player’s stats reset so there’s no value displayed.
• Player progress reported as a double value between 0 and 1, representing a value between 0 and 100%. As the logged in player in the screenshot does not have the stat ingested, progress is 0.

After we navigate to the Stats tab in our sample app and ingest a number of clicks, we can return to the Achievements tab and Query definitions and Query progress sequentially to display the player’s progress:
 

Unlocking achievements

We’ve set up one of our achievements to unlock manually and the other automatically using a stat. Let’s take a look at the code to manually unlock achievements and also how to get notified when an achievement is automatically unlocked.

Note that, as mentioned earlier, unlocking achievements manually in the game’s code may expose an attack vector for malicious users to unlock achievements that they haven’t earned.
 

1. Open AchievementService.cs and add the following method to hold our manual achievement unlock logic:

• The process is fairly straightforward here: we call Achievements.UnlockAchievements, passing in an array of AchievementIDs to unlock the achievement(s).

 

2. Add an AchievementsUnlockAchievementCommand.cs class to the Commands folder:

3. Open AchievementsViewModel.cs to declare and instantiate the command:

4. Lastly, open AchievementsView.xaml.cs and add the following line to the AchievementsListView_SelectionChanged method, to make sure we can only click the Unlock button once an achievement is selected:

When you run the app and authenticate, navigate to the Achievements tab and click Query definitions. Then click on the TOP_SECRET achievement and click the Unlock button. The UI won’t change, but you should see an “UnlockAchievements Success” message in the Debug Output in Visual Studio. Note that this code applies to visible and hidden achievements.

Now we can click Query progress and our achievement will show up in the list. Hidden achievements are not returned by the QueryPlayerAchievements call until unlocked, as seen previously.
 
Finally, let’s subscribe to achievement unlock notifications, so we can run our own code when an achievement unlocks via stat progression:
 

1. Open AchievementsService.cs and add the following methods to subscribe to and unsubscribe from achievement notifications:

• We’re calling Achievements.AddNotifyAchievementsUnlockedV2 to set up notifications, passing in a callback method that will get called when an achievement is unlocked by ingesting stats associated with the achievement. Note that this method will also be called when you manually unlock achievements.
• AchievementsUnlockedCallback will just write a line to the Debug Output in this case, but this is where you’d handle any UI to inform the player that they’ve unlocked an achievement.
• AddNotifyAchievementsUnlockedV2 will return a notificationId, which you can use to stop being notified about achievement unlocks. We’re not implementing that in this sample, but that’s what the RemoveNotification method does.

 

2. To keep things simple, add the following call to the QueryDefinitions method in AchievementsService.cs just above ViewModelLocator.Main.StatusBarText = string.Empty to start getting notified after calling QueryDefinitions:

Run the app again and authenticate, then navigate to the Achievements tab and click the Query definitions button. To check progress toward our achievement of 50 clicks total, click the Query progress button. If it’s not unlocked yet, note the progress and navigate to the Stats tab to ingest more clicks until it unlocks.

You should see a message pop up in the Debug Output in Visual Studio indicating the achievement was unlocked. If you already had the achievement unlocked, follow the steps in the next section to reset the achievement and also reset the player’s stats if necessary.

Looking up and modifying player achievements

If at any point in time you need to manually adjust a player’s achievements, either unlocking or resetting/locking them, you can do this in the Developer Portal:
 

1. Log in to the Developer Portal at https://dev.epicgames.com/portal/.
2. Navigate to your product > Game Services > Achievements in the left menu.
3. Click on the “Player Lookup” button on the top right.
4. In the flyout, enter the player’s Product User ID (PUID) or account-specific ID (e.g. Epic account ID) and click on “Search”.
5. A list of the player’s achievements will appear with their current progress and unlock status. In this list, you can click the ellipsis button to either unlock or reset this achievement.

Note that you can also use the “Reset All” or “Unlock All” buttons to quickly toggle all achievements, but be cautious using this in a production environment. This is most useful during development. Another good practice is to create a separate deployment for testing achievements during development, as all player data is scoped to a specific deployment.

Usage limitations and requirements

As with the other services we’ve looked at, Achievements has some usage limitations in place to ensure reliability and availability for all users. At the time of writing, these are the limitations (be sure to check the documentation for the most up-to-date information):
 

• 1000 total achievements maximum per deployment
• Three stats maximum an achievement can automatically unlock from

Achievements also must adhere to the following requirements:
 

• 256 characters maximum for an achievement ID
• Achievement ID cannot contain the following characters: , { ^ } % ` ] > [ ~ < # | & $ @ = ; ? \ ( ) * /
• Icon file name cannot contain the following characters:  , { ^ } % ` ] > [ ~ < # | & $ @ = ; : + ? ! \ ( ) * /
• 22 localized text variants maximum per achievement
• 1.02 MB maximum file size for achievement icons
• 1024 x 1024 pixels maximum resolution for achievement icons
• PNG, JPG, BMP, or non-animated GIF format only for achievement icons

Lastly, there are per-user or per-deployment rate limits for API calls for client or server calls respectively, which you can find in the documentation.

Get the code

Get the code for this article below. Follow the Usage instructions in the GitHub repo to set up the downloaded code.