Achievements Interface in Unreal Engine | Unreal Engine 5.3 Documentation

This page is not available in the language you have chosen. It will be displayed in English by default. If you would like to view it in a different language, you can try selecting another language.

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.

The availability of these three options varies depending on the online service implementation/platform that you use. Consult the documentation for your particular online service implementation for more information.

API Overview

Functions

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

Function	Definition
`QueryAchievementDefinitions`	Query all achievement definitions for this title.
`GetAchievementIds`	Retrieve the achievement IDs for achievements cached by `QueryAchievementDefinitions`.
`GetAchievementDefinition`	Retrieve an achievement definition with the provided achievement ID cached by `QueryAchievementDefinitions`.
`QueryAchievementStates`	Query the state of all achievements for the provided player.
`GetAchievementState`	Retrieve the state of an achievement by ID for the provided player.
`UnlockAchievements`	Manually unlock provided achievements.
`DisplayAchievementUI`	Launch the platform UI for the provided achievement.
`OnAchievementStateUpdated`	Event triggered when a player's achievement state changes.

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

Member	Type	Description
`AchievementId`	`FString`	Unique achievement ID.
`UnlockedDisplayName`	`FText`	Localized display name of this achievement used once it is unlocked.
`UnlockedDescription`	`FText`	Localized description of this achievement used once it is unlocked.
`LockedDisplayName`	`FText`	Localized display name of this achievement used while it is locked.
`LockedDescription`	`FText`	Localized description of this achievement used while it is locked.
`FlavorText`	`FText`	Localized flavor text.
`UnlockedIconUrl`	`FString`	URL of the icon for this achievement used once it is unlocked.
`LockedIconUrl`	`FString`	URL of the icon for this achievement used while it is locked.
`bIsHidden`	`bool`	Whether or not this achievement is hidden until it is unlocked.
`StatDefinitions`	`TArray<FAchievementStatDefinition>`	The stats that relate to this achievement.

FAchievementStatDefinition

Member	Type	Description
`StatId`	`FString`	Unique ID of the stat.
`UnlockThreshold`	`uint32`	Threshold value a user must meet with the associated stat for the achievement to auto unlock.

FAchievementState

Member	Type	Description
`AchievementId`	`FString`	Achievement this state relates to.
`Progress`	`float`	Progress toward unlocking this achievement as a percentage between 0.0 and 1.0. Any value less than 1.0 means that the achievement is locked. A value of 1.0 means the achievement is unlocked.
`UnlockTime`	`FDateTime`	If unlocked, the time this achievement was unlocked.

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

DefaultEngine.ini

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

For automatically-unlocking, title-managed achievements to update based on stats changes, you must set the bIsTitleManaged flag to true. This flag configures the client to listen for the Online Services Stats Interface's FStatsUpdated event to automatically update achievement state in response to stats changes. The bIsTitleManaged flag's default value is false. If you do not set this flag to true, achievements will not automatically update based on stat changes configured in the achievements definitions in DefaultEngine.ini.

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

Field	Type	Description
`AchievementId`	`String`	ID of the achievement that this unlock rule is associated with.
`Conditions`	`List`	List of conditions under which this achievement unlocks.

Conditions

Field	Type	Description
`StatName`	`String`	Name of the stat to associate an unlock threshold for this achievement.
`UnlockThreshold`	Colon delimited `Type:Value` pair	A pair of the form `<Type>:<Value>` where `Type` is the type of this stat and `Value` is the threshold value at which this condition is met for this achievement to unlock.

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.

DefaultEngine.ini

	[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
	+UnlockRules=(AchievementId=Around_the_World, Conditions=((StatName=Total_Distance, UnlockThreshold="Int32:40075000"))
	+UnlockRules=(AchievementId=Triathlon, Conditions=((StatName=Distance_Run, UnlockThreshold="Int32:10000"),(StatName=Distance_Swim, UnlockThreshold="Int32:1500"), (StatName=Distance_Cycle, UnlockThreshold="Int32:40000"))

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:

QueryAchievementDefinitions populates the local interface cache with achievement definitions.
GetAchievementIds retrieves the list of IDs for the cached achievements from step 1.
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:

QueryAchievementStates populates the local interface cache with achievement state information.
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.