업적(Achievement) 이란 게임 환경 외부에서 주어지는 목표 또는 트로피로, 게임 내 과제를 완수하면 잠금 해제되거나 보상으로 주어집니다. 업적은 플레이어에게 동기 부여, 도전 과제, 보상을 제공하는 방법 중 하나입니다. 다음과 같은 목적으로 업적을 활용할 수 있습니다.
- 플레이어에게 게임을 안내합니다.
- 게임을 다시 플레이하는 것의 가치를 높입니다.
- 플레이어 간의 라이벌 의식을 불러일으킵니다.
온라인 서비스 업적 인터페이스(Online Services Achievements Interface) 는 업적 정의를 읽을 뿐만 아니라 플레이어의 업적 상태를 읽고 업데이트할 수 있는 툴을 제공합니다. 업적 인터페이스를 통해 업적을 생성, 삭제 또는 수정할 수 없습니다. 각 온라인 서비스에는 업적을 관리하는 자체 백엔드 시스템이 있습니다.
다음 메커니즘을 구성하여 인터페이스의 환경설정에 따라 업적을 잠금 해제할 수 있습니다.
- 플랫폼 서비스 관리(Platform-service Managed): 관련 통계가 사전에 정의된 한계치에 도달하면 업적이 플랫폼 서비스에 의해 자동으로 잠금 해제됩니다.
- 타이틀 관리(Title-managed)(자동): 관련 통계가 사전에 정의된 한계치에 도달하면 업적이 타이틀에 의해 자동으로 잠금 해제됩니다. 자세한 내용은 아래의 자동 타이틀 관리 업적 환경설정 섹션을 참조하세요.
- 타이틀 관리(Title-managed)(수동): 타이틀 로직 및
UnlockAchievements함수에 따라 타이틀에 의해 업적이 수동으로 잠금 해제됩니다.
이 3가지 옵션의 사용 가능 여부는 사용하는 온라인 서비스 구현/플랫폼에 따라 다릅니다. 자세한 정보는 사용 중인 특정 온라인 서비스 구현 관련 문서를 참조하세요.
API 개요
함수
다음 표에는 업적 인터페이스가 제공하는 함수에 대한 개요가 나와 있습니다.
| 함수 | 정의 |
|---|---|
QueryAchievementDefinitions |
이 타이틀에 대한 모든 업적 정의를 쿼리합니다. |
GetAchievementIds |
QueryAchievementDefinitions 에 의해 캐시된 업적의 업적 ID를 가져옵니다. |
GetAchievementDefinition |
QueryAchievementDefinitions 에 의해 캐시된 주어진 업적 ID로 업적 정의를 가져옵니다. |
QueryAchievementStates |
제공된 플레이어의 모든 업적 상태를 쿼리합니다. |
GetAchievementState |
제공된 플레이어의 업적 상태를 ID로 가져옵니다. |
UnlockAchievements |
제공된 업적을 수동으로 잠금 해제합니다. |
DisplayAchievementUI |
제공된 업적의 플랫폼 UI를 실행합니다. |
OnAchievementStateUpdated |
플레이어의 업적 상태가 변경되면 트리거되는 이벤트입니다. |
프라이머리 구조체
업적 인터페이스는 주로 FAchievementDefinition , FAchievementStatDefinition , FAchievementState 라는 3개의 구조체를 통해 기능을 전달합니다. 이와 더불어 파라미터와 반환 값을 전달하는 함수별 특정 구조체들도 있습니다.
FAchievementDefinition
| 멤버 | 타입 | 설명 |
|---|---|---|
AchievementId |
FString |
고유 업적 ID입니다. |
UnlockedDisplayName |
FText |
잠금 해제될 경우 사용되는 이 업적의 현지화된 표시명입니다. |
UnlockedDescription |
FText |
잠금 해제될 경우 사용되는 이 업적의 현지화된 설명입니다. |
LockedDisplayName |
FText |
잠겨 있는 동안 사용되는 이 업적의 현지화된 표시명입니다. |
LockedDescription |
FText |
잠겨 있는 동안 사용되는 이 업적의 현지화된 설명입니다. |
FlavorText |
FText |
현지화된 플레이버 텍스트입니다. |
UnlockedIconUrl |
FString |
잠금 해제될 경우 사용되는 이 업적의 아이콘 URL입니다. |
LockedIconUrl |
FString |
잠겨 있는 동안 사용되는 이 업적의 아이콘 URL입니다. |
bIsHidden |
bool |
잠금 해제될 때까지 이 업적의 숨김 여부입니다. |
StatDefinitions |
TArray<FAchievementStatDefinition> |
이 업적과 관련된 통계입니다. |
FAchievementStatDefinition
| 멤버 | 타입 | 설명 |
|---|---|---|
StatId |
FString |
통계의 고유 ID입니다. |
UnlockThreshold |
uint32 |
업적을 자동으로 잠금 해제하려면 사용자가 반드시 충족해야 하는 관련 통계의 한계치입니다. |
FAchievementState
| 멤버 | 타입 | 설명 |
|---|---|---|
AchievementId |
FString |
이 상태와 관련된 업적입니다. |
Progress |
float |
이 업적이 잠금 해제될 때까지의 진행률을 0.0~1.0 사이의 비율로 나타냅니다. 1.0 미만의 값은 업적이 잠겨 있음을 의미합니다. 값이 1.0이면 업적이 잠금 해제됩니다. |
UnlockTime |
FDateTime |
잠금 해제될 경우 이 업적이 잠금 해제된 시간입니다. |
자동 타이틀 관리 업적 환경설정
업적을 플랫폼 서비스나 타이틀로 관리하여 수동으로 잠금 해제하는 경우, 업적 인터페이스에는 엔진 환경설정이 필요하지 않습니다. 반면 업적 진행률을 타이틀로 관리하면서 하나 이상의 통계가 사전 정의된 한계치에 도달할 때 업적을 자동으로 잠금 해제하고 싶다면 엔진을 환경설정해야 합니다.
자동으로 잠금 해제되고 타이틀로 관리되는 업적의 경우, 업적 인터페이스는 통계 인터페이스와 함께 작동합니다. 이 메커니즘이 업적 잠금 해제 규칙을 구성하고 통계 인터페이스 환경설정으로 정의된 통계 기반의 조건을 확립하게 하려면 엔진을 환경설정해야 합니다.
일반 구문
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>"), ...))
...
자동으로 잠금 해제되고 타이틀로 관리되는 업적을 통계 변경사항에 기반하여 업데이트하려면, bIsTitleManaged 플래그를 true 로 설정해야 합니다. 이 플래그는 클라이언트가 온라인 서비스 통계 인터페이스의 FStatsUpdated 이벤트를 리스닝하고 통계 변경사항에 반응하여 업적 상태를 자동으로 업데이트하도록 환경설정합니다. bIsTitleManaged 플래그의 디폴트값은 false 입니다. 이 플래그를 true 로 설정하지 않으면 업적이 DefaultEngine.ini 의 업적 정의에서 환경설정된 통계 변경사항을 기반으로 자동 업데이트되지 않습니다.
UnlockRules 내의 Conditions 목록에는 개별 조건 쌍이 포함되어 있습니다. 업적은 UnlockThreshold 와 연결된 하나 이상의 통계에 의존할 수 있습니다. 관련 Conditions 목록의 모든 통계가 사전 정의된 한계치를 충족하거나 초과할 때만 업적이 잠금 해제됩니다.
잠금 해제 규칙
| 필드 | 타입 | 설명 |
|---|---|---|
AchievementId |
String |
이 잠금 해제 규칙과 관련된 업적의 ID입니다. |
Conditions |
List |
이 업적이 잠금 해제되는 조건의 목록입니다. |
조건
| 필드 | 타입 | 설명 |
|---|---|---|
StatName |
String |
이 업적의 잠금 해제 한계치와 관련된 통계의 이름입니다. |
UnlockThreshold |
콜론으로 구분되는 Type:Value 쌍 |
<Type>:<Value> 형태의 쌍으로, Type 은 통계 타입을, Value 는 이 업적을 잠금 해제하기 위해 이 조건이 충족할 한계치입니다. |
환경설정 예시
아래는 두 개의 서로 다른 업적의 업적 인터페이스 환경설정 예시입니다. 첫 번째 업적은 이름이 Total_Distance 인 단일 통계에 의존합니다. 이 통계는 플레이어가 이동한 총거리를 미터 단위로 기록합니다. 두 번째 업적은 Distance_Run , Distance_Swim , Distance_Cycle 이라는 3개의 서로 다른 통계에 의존하며, 모두 미터로 측정됩니다.
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"))
읽기
업적 인터페이스의 목적은 업적 정의 및 상태를 읽는 것입니다. 아래는 정의 및 상태 읽기의 단계적 과정에 대한 설명입니다. 코드 샘플의 경우, 온라인 서비스 인터페이스를 사용하여 쿼리하고 정보를 획득하는 프로세스가 통계 인터페이스 문서에서 쿼리 및 통계 획득에 대해 설명된 부분과 매우 유사합니다.
업적 정의
업적 인터페이스는 다음 단계를 따라 플랫폼 서비스에서 환경설정된 모든 업적의 정의를 읽을 수 있습니다.
QueryAchievementDefinitions가 업적 정의로 로컬 인터페이스 캐시를 채웁니다.GetAchievementIds가 1단계에서 캐시된 업적의 ID 목록을 가져옵니다.GetAchievementDefinition이 2단계의 각 ID와 관련된 전체 정의를 얻습니다.
FAchievementDefintion 구조체는 업적 정의를 나타냅니다. 플랫폼 서비스로 관리되는 업적의 경우, 정의는 업적 및 초과하면 업적을 자동으로 잠금 해제하는 잠금 해제 한계치와 관련된 통계를 포함합니다.
업적 상태
업적 정의 섹션에 설명된 대로 플레이어의 업적 정의를 쿼리하여 가져온 후, QueryAchievementStates 및 GetAchievementState 를 사용하여 다음과 같이 플레이어 업적 상태를 읽습니다.
QueryAchievementStates가 업적 상태 정보로 로컬 인터페이스 캐시를 채웁니다.GetAchievementState가 업적이 잠겨 있을 경우 업적이 잠금 해제될 때까지 남은 현재 진행률을 가져오고, 업적이 잠금 해제된 경우 잠금 해제 시간을 가져옵니다.
타이틀로 관리되는 업적의 경우 진행률은 0.0(잠금) 또는 1.0(잠금 해제) 둘 중 하나입니다. 통계 기반의 잠금 해제 규칙에 따라 플랫폼 서비스로 관리되는 업적의 경우, 업적의 현재 진행 상황이 0.0~1.0 사이의 비율로 정확하게 진행률에 반영됩니다.
추가 정보
헤더 파일
자세한 정보가 필요한 경우 Achievements.h 헤더 파일을 직접 참조하세요. 업적 인터페이스 헤더 파일 Achievements.h 의 디렉터리 위치는 다음과 같습니다.
UNREAL_ENGINE_ROOT\Engine\Plugins\Online\OnlineServices\Source\OnlineServicesInterface\Public\Online
UE 소스 코드를 얻는 방법에 대한 지침은 언리얼 엔진 소스 코드 내려받기 문서를 참조하세요.
함수 파라미터 및 반환 타입
파라미터를 전달하고 함수의 반환 결과를 처리하는 방법을 비롯하여 함수 파라미터 및 반환 타입에 대한 자세한 설명은 온라인 서비스 개요 페이지의 함수 섹션을 참조하세요.
