Achievements

Submit feedback

Achievements can be a great way to increase your users' engagement within your game. You can implement achievements in your game to encourage players to experiment with features they might not normally use, or to approach your game with entirely different play styles. Achievements can also be a fun way for players to compare their progress with each other and engage in light-hearted competition.

To learn how to implement achievements for your platform, see Client implementations.

Attributes

To understand how achievements work, you'll want to be familiar with some of the attributes associated with them.

These basic elements are associated with every achievement:

• Id is a unique string that is generated by Google Play Console. You'll use this unique ID to refer to the achievement in your game clients.
• Name is a short name of the achievement (for example, "Pieman"). The value can be up to 100 characters.
• Description is a concise description about your achievement. Usually this tells your player how to earn the achievement (for example, "Bake a lemon meringue pie before sundown"). The value can be up to 500 characters.
• Icon is a square icon that is associated with your achievement. For best practices when creating your achievement icons, see the Icon Guidelines section.
• List order is the order in which the locked achievements appear when a player views the achievements associated with your game. This can be in any order that you like. Unlocked achievements appear at the top of the list in the order achieved.

State

Achievements can be in one of three different states:

• A hidden achievement means that details about the achievement are hidden from the player. Play Games Services provides a generic placeholder description and icon for the achievement while it's in a hidden state. We recommend making an achievement hidden if it contains a spoiler you don't want to reveal about your game too early (for example, "Discover that you were a ghost all along!").
• A revealed achievement means that the player knows about the achievement, but hasn't earned it yet. Most achievements start in the revealed state.
• An unlocked achievement means that the player has successfully earned the achievement. An achievement can be unlocked offline. When the game comes online, it syncs with Play Games Services to update the achievement's unlocked state.

Incremental achievements

Achievements can be designated as standard or incremental. Generally, an incremental achievement involves a player making gradual progress towards earning the achievement over a longer period of time. As the player makes progress towards the incremental achievement, you can report the player's partial progress to Play Games Services.

The Google Play service keeps track of the progress information, alerts the game when the player has met the criteria necessary to unlock that achievement, and tells the player how far along they are towards meeting that goal.

Incremental achievements are cumulative across game sessions, and progress can't be removed or reset from within the game. For example, "Win 50 games" would qualify as an incremental achievement. "Win 3 games in a row" wouldn't, as the player's progress would be reset when they lose a game. "Have 5,000 poker chips" wouldn't qualify either, as a player could gain and lose chips as they play. For the latter two achievements, it's up to you to track the player's "Wins in a row" state or chip total and to unlock standard achievements when the player earns them.

When creating an incremental achievement, you must define the total number of steps required to unlock it (this must be a number between 2 and 10,000). As the user makes progress towards unlocking the achievement, you should report the number of additional steps the user has made to Play Games Services. Once the total number of steps reaches the unlock value, the achievement is unlocked (even if it was hidden). There's no need for you to store the user's cumulative progress.

Points

Achievements have a point value associated with them. The player's score must be a multiple of 5 and a game can never have a total of more than 1000 points for all of its achievements (although it can have less). In addition, no single achievement can have more than 200 points.

Track experience points (XP)

Players can gain levels on their Game Profile when they earn achievements in Play Games enabled games. For every point associated with an achievement, the player gains 100 experience points (XP) when they earn that achievement. In other words:

XP for an achievement = 100 * (point value for the achievement)

Play Games services keeps track of the XP earned by each player and sends out a notification to the Google Play Games app when the player has earned enough points to 'level up'. Players can view their level and XP history from their Profile page in the Google Play Games app.

Minimum achievements

A game that integrates achievements should have at least five achievements before it is published. You can test with fewer than five achievements, but it is recommended you have at least five achievements created before you publish your game.

Maximum achievements

The number of achievements is limited by the points limits and distribution. With a maximum number of points of 1000, and each achievement assigned 5 points, the maximum number of achievements is 200. However, if achievements are assigned more points then the number of achievements available decreases as a result.

Add achievements

There are two ways to create achievements for the first time using the Google Play Console:

• Create an achievement: Add definitions and metadata for each achievement one at a time.
• Import achievements: Import definitions and other metadata for multiple achievements together in a single step.

Create an achievement

To create an achievement for a new and unpublished game, complete these steps:

1. In the Google Play Console, select a game.
2. In the Play Games Services - Achievements page (Grow > Play Games Services > Setup and management > Achievements), select Create achievement.
3. In the Add achievements page, complete the form.
4. Click Save as draft.
5. After you have created an achievement, you need to publish your game.

Add more achievements

If you already have existing achievements and want to add more:

1. In the Google Play Console, select a game.
2. In the Play Games Services - Achievements page (Grow > Play Games Services > Setup and management > Achievements), select Add achievements.

Import achievements

To add multiple achievements to your game at once, use the following steps:

1. Create a zip file containing your achievements.
2. Upload the file.

For more information about the zip file, see Zip file guidelines.

To import achievements:

1. In the Google Play Console, select a game.
2. In the Play Games Services - Achievements page (Grow > Play Games Services > Setup and management > Achievements), select Import achievements.
3. In the Import achievements page, click Upload.
4. Select the zip file to upload.
5. Click Save as draft.
6. After you have imported achievements, you need to publish your game.

Publish your game

Once you test and publish your game, all of your game's achievements are published with it.

Edit an achievement

To edit an achievement that you've already created, select the achievement in the Achievements tab of Google Play Console. At this point, you will see the same form you used when first creating the achievement, and you can edit any of the fields as you need.

When you're done editing an achievement, click the Save as draft button. The newly edited achievement will be in a "ready to test" stage, and you'll be able to test it out. If it is working correctly, select Republish from the drop-down list. This republishes your game, along with all your updated achievements, to the public.

Undo an edit

If you decide you don't like your current achievement and want to go back to your achievement the way it was before, select Revert from the drop-down list in Google Play Console, and all of your achievements will revert back to the previously published version.

Delete an achievement

Once your achievement has been published, it cannot be deleted.

You can only delete an achievement in a pre-published state by clicking the button labeled Delete at the bottom of the form for that achievement.

Reset an achievement

You can only reset player progress data for your draft achievements.

• To reset achievements in Google Play Console, click the button labeled Reset achievement progress at the bottom of the form for that event.
• To reset achievement data programmatically, call the Management API Achievements methods.

Icon guidelines

Icons should be created as 512 x 512 PNG, JPEG, or JPG files. You only need to provide us with the icon for the unlocked achievement. We will generate a grayscale version for the revealed icon automatically. For that reason, we recommend your achievement icons include colorful elements, so your users can distinguish between revealed and unlocked achievements.

When an achievement icon is displayed in an Android toast, the icon is overlaid with a circle and its outer corners are hidden. Make sure that your icon still looks good under these circumstances.

The same icon is used in all locales, so we recommend against including any text or localized content in an icon.

Zip file guidelines

You can import multiple achievements at once using a zip file. Refer to the table for the precise filenames to use in your zip file:

Zip file requirements:

• No subdirectories.
• Unique file names.
• Only CSV, PNG, JPEG, or JPG files.
• The CSV files must not have a header row.
• Each file must be under 1 MB.
• The zip file should not contain more than 203 files.
• Total zip file size must be under 200MB.

AchievementsMetadata.csv format

The AchievementsMetadata.csv file contains the metadata for each achievement. It should include the information as comma-separated values in the following order:

    Name,Description,Incremental value,Steps Needed,Initial State,Points,List Order

These fields are described in the following table:

AchievementsMetadata.csv file requirements:

• Each row must have seven values. If you want to omit a value, leave it blank.
• The Name and Description fields are used as the default locale.
• The Name field should be unique across all achievements.
• The following fields shouldn't contain commas: Name and Description.

A sample AchievementsMetadata.csv file:

  Achievement1,Achievement One,True,100,Hidden,5,20
  Achievement2,Achievement Two,False,,Revealed,10,30

AchievementsLocalizations.csv format

The AchievementsLocalizations.csv file is an optional file that sets up all the data that is needed to describe each achievement to users in different locales. Achievements are translated in alignment with the locales specified for the game.

It should include the information as comma-separated values in the following order:

   Name, Localized name, Localized description, locale

These fields are described in the following table:

AchievementsLocalizations.csv file requirements:

• Achievement names within a game must be unique per locale. For example, if a game supports both en-US and fr-FR locales, an achievement named "Achievement1" for en-US can also be named "Achievement1" for fr-FR.
• Each row should have four values. If you want to omit the Localized description value, leave it blank.

A sample AchievementsLocalizations.csv file:

Achievement1,Achievement One,This is the description of achievement one in English.,en-US
Achievement1,Achievement Un,Voici la description de l'achievement un en français.,fr-FR
Achievement2,Achievement Two,Description of achievement two.,en-US
Achievement2,Logro Dos,Descripción del logro dos.,es-ES
Achievement3,Achievement Three,,en-US
Achievement3,Erfolg Drei,,de-DE

AchievementsIconMappings.csv format

The AchievementsIconMappings.csv file is an optional file that is used to map your achievements with the given icon. It should include the information as comma-separated values in the following order:

Name, icon filename

These fields are described in the following table:

AchievementsIconMappings.csv file requirements:

• Each row should have two values.
• Icons files can only be in PNG or JPEG formats.

A sampleAchievementsIconMappings.csv file:

Valid Achievement,valid-achievement-icon.png
Incremental Achievement,incremental-achievement-icon.jpeg
No Description,no-description-icon.png
Hidden Initial State,hidden-initial-state-icon.png
Large Point Value,large-point-value-icon.jpeg

Icon files

Icons you reference in AchievementsIconMappings.csv file must exist in the current zip archive you import. For more information, see Icon guidelines.

Add translations for achievements

You can specify your own translations for achievements that are associated with your game. Before you do so, first make sure to complete the steps described in Adding translations for your game.

There are two ways in which you can add translations for your game:

• You can use the import achievements option to upload translations for many new achievements at once. You cannot use this option to upload translations for already existing achievements.

• You can add translations for each achievement in your game. To add your own translation for each achievement:

  1. In the Google Play Console open the Achievements tab for your game, then select an existing achievement.
  2. In the achievements details page, select the tab for a language that you previously added in the Game details tab.
  3. In the achievement details page for that language, edit the form with your translations for that achievement.
  4. Click Save to store your translated achievement details.

Client implementations

To learn how to implement achievements for your platform, see the following resources:

• Android
• Unity
• Web
• Best practices for implementing achievements