Online Services Achievements Interface

An achievement is a goal or trophy, awarded outside of a game environment, unlocked or rewarded for accomplishing in-game tasks. Achievements give you a way to incentivize, challenge, and reward players. You can use them to:

• Guide players through a game

• Increase a game's replay value

• Support rivalries between players

The Online Services Achievements Interface provides you with tools to read achievement definitions as well as read and update the achievement state for players. The achievements interface does not handle the creation, deletion, or modification of achievements. Each online service has its own backend systems to manage these aspects of achievements.

You can set up the following mechanisms to unlock achievements depending on the interface's configuration:

• Platform-service Managed: Achievements are automatically unlocked by the platform service when associated stats reach predefined thresholds.

• Title-managed (automatic): Achievements are automatically unlocked by the title when associated stats reach predefined thresholds. See the Configure Automatic Title-Managed Achievements section below for more information.

• Title-managed (manual): Achievements are manually unlocked by the title according to title logic and the UnlockAchievements function.

API Overview

Functions

The following table provides a high-level overview of the functions provided by the Achievements Interface:

Primary Structs

The achievements interface communicates its functionality primarily through three structs: FAchievementDefinition, FAchievementStatDefinition, and FAchievementState, in addition to the function specific structs for passing parameters and return values.

FAchievementDefinition

FAchievementStatDefinition

FAchievementState

Configure Automatic Title-Managed Achievements

The achievements interface does not require engine configuration when achievements are either platform-service managed or title-managed and manually unlocked. You must configure the engine if your achievement progress is title-managed and you want achievements to automatically unlock when one or more stats reach a predefined threshold.

For automatically-unlocking, title-managed achievements, the achievements interface works in conjunction with the Stats Interface. You must configure the engine for this mechanism to set up unlock rules for achievements and establish conditions based on stats defined with stats interface configuration.

General Syntax

[OnlineServices.Achievements]
	bIsTitleManaged=true
	!UnlockRules=ClearRules
	+UnlockRules=(AchievementId=<AchievementId1>, Conditions=((StatName=<StatName>, UnlockThreshold="<Type>:<Value>"), ...))
	+UnlockRules=(AchievementId=<AchievementId2>, Conditions=((StatName=<StatName>, UnlockThreshold="<Type>:<Value>"), ...))
	...

The list of Conditions within UnlockRules contains individual condition pairs. Achievements can depend on one or more stats coupled with an UnlockThreshold. An achievement unlocks only after every stat in its associated Conditions list has met or exceeded the predefined threshold.

Unlock Rules

Conditions

Configuration Example

Below is an achievements interface example configuration with two different achievements. The first achievement is dependent on a single stat named Total_Distance that records the total distance a player has traveled in meters. The second achievement is dependent on three different stats to unlock: Distance_Run, Distance_Swim, and Distance_Cycle, all measured in meters.

[OnlineServices.Stats]
	!StatDefinitions=ClearDefinitions
	+StatDefinitions=(Name=Total_Distance, Id=0, ModifyMethod=Sum)
	+StatDefinitions=(Name=Distance_Run, Id=1, ModifyMethod=Sum)
	+StatDefinitions=(Name=Distance_Swim, Id=2, ModifyMethod=Sum)
	+StatDefinitions=(Name=Distance_Cycle, Id=3, ModifyMethod=Sum)

	[OnlineServices.Achievements]
	bIsTitleManaged=true
	!UnlockRules=ClearRules

Read

The purpose of the achievements interface is to read achievement definitions and state. Below is a high-level description of the steps involved in reading definitions and state. For code examples, the process of querying and getting information using any Online Services interface is very similar to the example outlined in the Stats Interface documentation to query and get stats.

Achievement Definition

The Achievements interface can read the definition of any achievements configured on the platform services by following these steps:

1. QueryAchievementDefinitions populates the local interface cache with achievement definitions.

2. GetAchievementIds retrieves the list of IDs for the cached achievements from step 1.

3. GetAchievementDefinition obtains the full definition associated with each ID from step 2.

The FAchievementDefintion struct represents achievement definitions. For platform service managed achievements, the definition includes the stats associated with the achievement and their unlock thresholds, above which, the achievement automatically unlocks.

Achievement State

After you query and retrieve a player's achievement definitions as explained in the Achievement Definition section, use QueryAchievementStates and GetAchievementState to read player achievement states:

1. QueryAchievementStates populates the local interface cache with achievement state information.

2. GetAchievementState retrieves the current progress toward unlocking the achievement if it is still locked, or the unlock time if the achievement is unlocked.

For title managed achievements, the progress is a binary 0.0 (locked) or 1.0 (unlocked). For platform-service managed achievements with stat-based unlock rules, the progress may accurately reflect the current progress toward the achievement as a percentage between 0.0 and 1.0.

More Information

Header File

Consult the Achievements.h header file directly for more information as needed. The Achievements Interface header file Achievements.h is located in the directory:

Engine\Plugins\Online\OnlineServices\Source\OnlineServicesInterface\Public\Online

For instructions on how to obtain the UE source code, see our documentation on Downloading Unreal Engine Source Code.

Function Parameters and Return Types

See the Functions section of the Online Services Overview page for an explanation of function parameters and return types, including how to pass parameters and processing the results when functions return.