Achievements Building Block

The Achievements Unity Building Block demonstrates an achievement system that uses Unity Gaming Services (UGS).

The achievements are synchronized and persist in the Unity cloud, which means you can access them on any other device or platform that runs the same project.

The Achievements Building Block uses the following Unity Gaming Services:

Unity Gaming Service	Description
Cloud Save	Stores data about a player’s achievement status as Player Data and Game Data. For more information, refer to Cloud Save overview. To learn how the Achievements Building Block uses the Cloud Save service, refer to How the Achievements Building Block saves data.
Cloud Code	Performs actions with server authority to claim achievements. For more information about Cloud Code, refer to Cloud Code overview. This Building Block uses Cloud Code modules to interact with the Cloud Save service. To learn more, refer to Deploy the Cloud Code modules.
Authentication	Assigns each player a unique identity. This Building Block uses Authentication to sign in anonymously. To use it, set up authentication.
Remote Config	Stores values as key-value pairs on the cloud as a JSON file. For more information, refer to Remote Config overview. This Building Block uses a remote config file (.rc) to define the achievements on the cloud. To learn more, refer to Customize the Achievements Building Block.
Access Control	Sets authentication requirements for interacting with other services to prevent cheating. This Building Block uses Access Control to restrict players from writing to Cloud Save. To write to Cloud Save, use the Trusted client which uses Cloud Code Modules to authenticate calls as a trusted source.

Prerequisites

To set up a project for the Achievements Building Block, follow the instructions in the LiveOps Unity Building Blocks prerequisites.

Initial setup

To use all features of the Achievements test scene, perform the following actions.

Deploy the configuration file

The test sceneA Scene contains the environments and menus of your game. Think of each unique Scene file as a unique level. In each Scene, you place your environments, obstacles, and decorations, essentially designing and building your game in pieces. More info
See in Glossary includes the Achievement.ach configuration file to define the achievements in the scene.

1. Set up deployment in your project.
2. Go to Services > Deployment.
3. In the Deployment window, expand the Blocks.Achievements section.
4. Select the Achievement.ach checkbox.
5. Select Deploy Selected.

Deploy the cloud code modules

The test scene uses the BlocksGameModule.ccmr Cloud Code module to update the global score. To use this module:

1. Set up deployment in your project.
2. Go to Services > Deployment.
3. In the Deployment window, expand the Blocks.CloudCode section.
4. Select the BlocksGameModule.ccmr and BlocksAdminModule.ccmr checkboxes.
5. Select Deploy Selected.

Use the Achievements Building Block test scene

The Achievements Building Block test scene demonstrates in-game achievements that you can claim, rename, and reset. Each achievement exists in one of the following states:

• Unlocked
• Locked
• Hidden
• In progress

To open the test scene:

1. In the Project window, go to Assets > Blocks > Achievements > TestScenes.
2. Right-click the AchievementsTestScene.unity asset and select Open.

To use the test scene:

1. Enter Play Mode. During the loading screen the scene retrieves achievements defined in the configuration file from Cloud Save.
2. The scene loads and displays the achievements.
3. Select an achievement’s Unlock button to claim it, or use the + and - buttons to change its progress.
4. Select Reset Achievements to restore achievements to their default state.

How the Achievements Building Block saves data

The Achievements Building Block uses the Cloud Save service to store and track achievement progress for each player.

Each player is assigned a key and value pair saved to a protected store on the Cloud Save service. Player data is stored in the achievements key.

The AchievementDefinition data model is defined in the following locations:

• To find the local AchievementDefinition.cs file, go to Assets > Blocks > Achievements > Scripts > Runtime >
• To find the Cloud Code file:
  1. In the Assets folder, right-click CloudCode.
  2. Select View in Explorer on Windows or View in Finder on macOS.
  3. Go to BlocksGameModule~ > Project > Achievement > AchievementDefinition.cs.

Note: The actual data stored is an array of objects of type AchievementRecord.

The following script is an example of the player data that the Achievements Building Block stores on the Cloud Save service:

[
{
"Id": "first_achievement", // the ID of the achievement
"Unlocked": true, // the unlocked status of the achievement for the current player
"ProgressCount": // current progress relative to the ProgressTarget of the definition
}
]

Add the Achievements prefab to a different scene

To use the Achievements Building Block in a new scene:

1. Deploy the Achievements Configuration file.
2. Go to Assets > Blocks > Achievements > Prefabs.
3. Select the AchievementsPrefab to open it.

Any changes made to Achievements.ach affect the AchievementsPrefab in Play Mode. To learn how to modify Achievements.ach, refer to Customize the Achievements Building Block.

Note: To create a new Achievements Configuration file, go to Create > Blocks > Achievements Configuration.

Customize the Achievements Building Block

You can customize the achievements building block in the following ways:

• Modify the Achievements configuration file.
• Modify the Achievements prefabAn asset type that allows you to store a GameObject complete with components and properties. The prefab acts as a template from which you can create new object instances in the scene. More info
  See in Glossary.
• Set an access control policy.
• Change achievement data.

Modify the configuration file

The Achievements.ach file is a type of Remote Config (.rc) file that exposes achievement configuration properties in the InspectorA Unity window that displays information about the currently selected GameObject, asset or project settings, allowing you to inspect and edit the values. More info
See in Glossary window. The Achievements.ach file must match the data defined in the AchievementDefinition file. For more information, refer to Change achievement data.

To change descriptions or appearance of each achievement:

1. In the Project window, go to Assets > Blocks > Achievements > Deployment > Achievements.ach.
2. Select Achievements.ach to display its properties in the Inspector.
3. To apply changes, deploy Achievements.ach to the current environment.

Modify the Achievements prefab

To make changes to the Achievements prefab:

1. Go to the Project windowA window that shows the contents of your Assets folder (Project tab) More info
   See in Glossary.
2. Navigate to Assets > Blocks > Achievements > Prefabs.
3. Select AchievementsPrefab to view its properties in the Inspector.

You can also enable Developer Mode to change the progress of incremental achievements in the Scene viewAn interactive view into the world you are creating. You use the Scene View to select and position scenery, characters, cameras, lights, and all other types of Game Object. More info
See in Glossary.

The following classes control the data displayed by Achievements.ach:

• AchievementAsset: Scriptable object in the project.
• AchievementFile: Defines how the contents of Achievements.ach are displayed.
• AchievementAssetImporter: Custom importer class enabling the custom inspector.
• AchievementAssetInspector: The custom inspector itself.

Set an Access Control policy

An achievement client submits scores to the Achievement service. The block includes the following clients: * Local (LocalAchievementsClient): Submits scores directly to Cloud Save without validation. You can use an Access Control policy to prevent cheating. * Trusted (TrustedAchievementsClient): Calls the Cloud Code C# module to submit scores securely.

To change the client in the test scene:

1. Open the Achievement test scene.
2. In the Hierarchy window, select the AchievementsPreview GameObjectThe fundamental object in Unity scenes, which can represent characters, props, scenery, cameras, waypoints, and more. A GameObject’s functionality is defined by the Components attached to it. More info
   See in Glossary.
3. In the Inspector, enable Use Trusted Client.

Change Achievement data

The AchievementDefinition files define achievement properties used in the Achievements.ach Inspector window. To learn more about the Achievements.ach file, refer to Modify the configuration file.

Locations:

• Local: Assets > Blocks > Achievements > Scripts > Runtime > AchievementDefinition.cs
• Cloud Code: Assets > Blocks > Achievements > CloudCode~ > Project > Achievement > AchievementDefinition.cs

To change the data in this file:

• Update the AchievementDefinition.cs file in each location so that their content is exactly the same.
• Deploy both files in the Deployment window. To learn more, refer to Deploy the configuration file.

Troubleshooting

If scores aren’t visible and a warning message appears, it might be because the AchievementsAccessControl.ac file denies write access for the local client’s write access. To fix this issue:

1. Go to Services > Deployment.
2. Right-click the AchievementsAccessControl.ac file.
3. Select Delete Remote.

Additional resources

• Server Authority
• Deployment