Interface IAchievementSystem

Provides access to achievement functionality.

Namespace: Unity.PlatformToolkit

Assembly: Unity.PlatformToolkit.dll

Syntax

public interface IAchievementSystem

Remarks

Achievements are managed in the Achievement Editor window (Window -> Platform Toolkit -> Achievement Editor). In the editor, achievements must be created and a unique string id must be set for each achievement. This name is then used to update achievements with Unlock(string) and UpdateProgress(string, int) methods.

In addition, the Achievement Editor allows setting the unlock type for each achievement to either single or progressive.

If the platform natively supports both progressive and non-progressive achievements, the Platform Toolkit achievement type must match the platform type, otherwise the achievement might not unlock when expected.

Progressive achievements must have a progress target set. If the platform supports custom progress targets natively, the native progress target and the progress target set in the achievement editor must match, or the achievement might not unlock when expected.

The exact behavior when achievement type or progress target is mismatched or is undefined and can differ between platforms.

On platforms where progressive achievements have a fixed target, for example when progress is tracked in percentages, the Platform Toolkit progress target can be set to any value and the progress will be remapped proportionally.

Achievement Editor does not register achievements with platform services: that has to be done manually for each platform service. After achievements are registered in platform services, their native IDs have to be entered in the Achievement Editor. See platform package documentation to find out which achievement ID should be used for each platform and where to find them.

Achievement updates that are initiated by calling Unlock(string) and UpdateProgress(string, int) are unreliable. Achievements might not get updated due to network issues, or because network event limits were exceeded. The achievement system retries failed achievement updates internally, but it can only do so while the account is signed in and while the game is still running. If achievement is still not updated by the time the game is turned off or the account signs out, the updates can be lost. While some platforms maintain their own local cache of unlocked achievements, some platforms do not or don’t do it reliably.

IAchievementSystem will internally fetch platform achievement state and use that information to ignore redundant Unlock(string) and UpdateProgress(string, int) calls. So for example if on the platform side the achievement progress is set to 50, when attempting to call UpdateProgress(string, int) with progress less than or equal to 50, the call will be completely ignored by the achievement system. This is a measure to reduce the chance of hitting network event limits that can be imposed by platforms.

Methods

Unlock(string)

Unlock achievement.

Declaration

void Unlock(string id)

Parameters

Type	Name	Description
string	id	Achievement id defined in the Achievement Editor.

Remarks

When called on a progressive unlock achievement, will set the progress to the target progress value.

Exceptions

Type	Condition
ArgumentException	Parameter id is null, empty or not defined in the Achievement Editor.
InvalidAccountException	IAccount is signed out.

UpdateProgress(string, int)

Update achievement progress and unlock it when the progress is updated to its target.

Declaration

void UpdateProgress(string id, int progress)

Parameters

Type	Name	Description
string	id	Achievement id defined in the Achievement Editor.
int	progress	New achievement progress in the range between 0 and the progress target defined in the Achievement Editor window.

Remarks

Progress cannot be lowered. Attempts to set progress to a lower value than the current one will be ignored.

Exceptions

Type	Condition
ArgumentException	Parameter id is null, empty or not defined in the Achievement Editor. Parameter progress value is less than 0.
InvalidAccountException	IAccount is signed out.