온라인 서비스(Online Services) 플러그인과 그 인터페이스는 Playstation Network, Xbox Live, Steam, 에픽 등의 다양한 온라인 서비스 기능에 액세스할 수 있는 일반적인 방법을 제공합니다. 온라인 서비스 플러그인은 개발자가 여러 플랫폼에서 출시되거나 여러 온라인 서비스를 지원하는 게임을 개발할 때, 지원하는 각 서비스에 대한 환경설정만 조정하면 되도록 설계되었습니다.
설계 철학
온라인 서비스 플러그인은 지원 기능을 그룹화하는 서비스별 모듈식 인터페이스 로 구성됩니다. 인터페이스 목록과 각각이 지원하는 피처 그룹을 확인하려면 이 페이지의 인터페이스 표를 참조하세요.
온라인 서비스 플러그인은 다양한 서비스와의 비동기 커뮤니케이션을 처리하도록 설계되었습니다. 이러한 시스템과의 인터랙션에 소요되는 시간은 예측할 수 없습니다. 유동적인 네트워크 연결 속도, 서버 지연, 알 수 없는 백엔드 서비스 시간 때문입니다. 이러한 문제를 극복하기 위해 온라인 서비스 인터페이스는 모든 원격 작업에 대해 TOnlineAsyncOpHandle 을 반환하여 핸들에 대한 OnComplete 이벤트 콜백의 호출이 보장되도록 합니다.
인터페이스는 지원되는 각 온라인 서비스에서 모든 피처 그룹에 대하여 제공됩니다. 특정 온라인 서비스에서 지원하지 않는 특정 함수는 OnComplete 콜백으로부터 Errors::NotImplemented 를 반환합니다. 이러한 함수 기능을 통해 개발자는 모든 온라인 서비스에서 같은 코드를 사용할 수 있습니다.
이벤트 콜백 및 리스닝
OnComplete 콜백은 다음 함수 기능을 제공합니다.
- 요청이 완료되면 응답합니다.
- 진행 중인 요청을 쿼리할 수 있습니다.
- 단일 코드 경로를 사용합니다.
마지막 항목은 개발자가 다양한 성공 또는 실패 조건을 포착하기 위해 커스텀 코드를 작성할 필요를 없애주므로 중요합니다.
콜백 포맷
개발자가 OnComplete 콜백(온라인 서비스의 이벤트 콜백) 또는 이벤트 리스닝을 위한 파라미터를 전달하는 방식에 따라서 적절한 델리게이트가 자동으로 구성됩니다. 통계(Stats) 인터페이스의 QueryStats 함수를 사용하는 다음 예시에서는 this 의 타입에 따라 다양한 델리게이트 생성 함수가 호출됩니다.
Stats->QueryStats(MoveTemp(Params)).OnComplete(this, &MyClass::OnQueryStatsComplete);
OnStatsUpdated 함수를 사용하는 다음 예시도 마찬가지입니다.
Stats->OnStatsUpdated().Add(this, &MyClass::OnStatsUpdated);
두 예시 모두 다음 행동을 하게 됩니다.
this가 UObject인 경우, 기본 델리게이트의CreateUObject가 호출됩니다.this가TSharedFromThis에서 파생된 경우,CreateThreadSafeSP또는CreateSP(this가 스레드 안전 방식이 아닌 공유 포인터인 경우)가 호출됩니다.- 그 외의 경우,
CreateRaw가 호출됩니다.
일반적으로 가장 안전한 델리게이트 생성 함수 호출이 사용됩니다.
인터페이스
온라인 서비스 플러그인에는 다음 인터페이스가 포함되어 있습니다.
| 인터페이스 | 피처 그룹 설명 |
|---|---|
| 업적(Achievements) | 게임의 모든 업적 나열, 업적 잠금해제, 자신과 다른 사용자의 잠금해제된 업적 확인 같은 기능이 있습니다. |
| 인증(Auth) | 온라인 서비스로 로컬 사용자를 인증 및 검증합니다. |
| 커머스(Commerce) | 게임 내 구매에 이용 가능한 카테고리 및 특정 오퍼를 얻습니다. |
| 연결 상태(Connectivity) | 온라인 서비스의 연결 상태를 가져오거나 알림을 받습니다. |
| 외부 UI(ExternalUI) | 특정 하드웨어 플랫폼 또는 온라인 서비스에 대한 내장 유저 인터페이스를 엽니다. 서비스에서 이 인터페이스를 통해서만 특정 핵심 기능에 대한 액세스 권한을 부여하는 경우도 있습니다. |
| 리더보드(Leaderboard) | 자신의 점수를 등록하고 친구 목록 또는 전 세계 다른 플레이어의 점수를 확인할 수 있는 온라인 리더보드에 액세스합니다. |
| 로비(Lobby) | 친구들과 플레이하기 위해 로비를 생성하고 로비에 참여합니다. |
| 현재상태(Presence) | 사용자의 온라인 상태와 참여 가능 여부가 다른 사용자에게 표시되는 방식을 설정합니다. '온라인', '오프라인', '자리 비움' 등의 상태가 있습니다. |
| 권한(Privileges) | 연령 제한, 커뮤니케이션 제한, 크로스 플레이 세팅 등의 사용자 권한을 쿼리합니다. |
| 세션(Session) | 온라인 게임 세션을 생성, 소멸, 관리하며 세션 및 매치메이킹 시스템 검색도 가능합니다. |
| 소셜(Social) | 사용자를 친구 목록에 추가하고, 차단하거나 차단 해제하고, 최근에 온라인에서 만난 플레이어의 목록을 확인합니다. |
| 통계(Stats) | 통계를 백엔드로 업로드하여 통계 쿼리, 업적 진행상황, 리더보드 순위 등의 기능을 완성합니다. |
| 타이틀 파일(Title File) | 출시 타이틀과 함께 패키지로 만들어지지는 않았으나 백엔드 서비스에 업로드되고 런타임에 현재 타이틀로 다운로드된 파일을 타이틀이 읽을 수 있도록 합니다. |
| 사용자 파일(User File) | 사용자 파일 스토리지와 연결됩니다. |
| 사용자 정보(User Info) | 사용자에 대한 메타데이터를 수집합니다. |
함수
각 인터페이스에는 다양한 동기 및 비동기 함수가 있습니다. 함수에 파라미터를 전달하고, 함수 반환 시 결과를 처리하는 방법에 대하여 간략히 소개하겠습니다.
파라미터
온라인 서비스 인터페이스 함수에 대한 파라미터는 각 함수와 연결된 구조체의 Params 멤버를 사용하여 생성됩니다. 그런 다음 이러한 파라미터는 UE의 std::move 에 해당하는 MoveTemp 를 통하거나 {}로 구분된 목록을 통해 연관된 함수로 전달됩니다.
반환 타입
온라인 서비스 인터페이스에 정의된 함수에는 다음과 같은 세 가지 반환 타입이 있습니다.
TOnlineResultTOnlineAsyncOpHandleTOnlineEvent
TOnlineResult
동기 함수는 TOnlineResult<T> 를 반환합니다. 여기서 T 는 문제의 함수와 관련된 구조체입니다. 반환이 성공적이었는지 확인하려면 IsOk 또는 IsError 를 호출합니다. 두 가지 모두 결과에 액세스할 수 있는지 아니면 오류가 발생했는지의 부울 값을 반환합니다. 마지막으로, IsOk 가 true를 반환한다면 GetOkValue 를 호출하여 T::Result 에 액세스할 수 있습니다. 이와 유사하게, IsError 가 true를 반환한다면 GetErrorValue 를 호출하여 FOnlineError 에 액세스할 수 있습니다.
TOnlineAsyncOpHandle
비동기 커뮤니케이션이 필요한 함수는 TOnlineAsyncOpHandle<T> 를 반환합니다. 이 핸들에 OnComplete 콜백을 추가하면 성공적인 완료, 실패, 타임아웃 또는 기타 이 핸들의 최종 상태 변경을 리슨합니다. 콜백의 TOnlineResult<T> 파라미터는 성공적인 결과 데이터 또는 함수가 실패한 이유를 설명하는 FOnlineError 를 포함합니다. 이 콜백은 고유 함수를 허용하므로, 람다 함수가 사용되는 경우 고유 포인터 및 무거운 데이터 타입은 람다의 캡처 범위로 이동할 수 있습니다.
TOnlineEvent
이벤트 리스닝에 사용되는 함수는 TOnlineEvent<T> 를 반환합니다. TOnlineAsyncOpHandle 와 비슷하게 Add 함수로 이벤트 콜백을 리슨할 수 있습니다. 그러면 Add 는 조건에 맞는 이벤트가 탐지될 때마다 시그니처 T 와 함께 해당 콜백을 실행합니다. 같은 이벤트에 여러 콜백이 추가될 수 있습니다. Add를 호출하면 FOnlineEventDelegateHandle 이 반환됩니다. 이 델리게이트 콜백은 이 핸들이 소멸하면 바인딩 해제되므로, 이 이벤트를 리슨하는 시스템의 수명 주기 동안 활성 상태를 유지하고, 관련 시스템의 소멸과 함께 이 핸들에서 Unbind 를 적절하게 소멸/호출해야 합니다.
온라인 서비스 또는 온라인 서브시스템 사용하기
이제 언리얼 엔진(UE) 은 온라인 서비스에 액세스하는 두 가지 프레임워크를 제공합니다. 하나는 온라인 서비스, 하나는 온라인 서브시스템(Online Subsystem) 입니다. 계속 읽으면서 어느 쪽이 프로젝트에 잘 맞는지 판단하세요.
온라인 서비스
온라인 서비스는 출시 타이틀에서 테스트되지 않았습니다. UE 5.1부터 온라인 서비스 플러그인은 개발자가 엔진의 향후 버전에서 출시할 목적으로 사용할 수 있는 API 완성 버전입니다. 자체 백엔드를 타기팅하는 개발자나, UE 5.1 이후의 많은 업그레이드를 출시 전에 프로젝트에 통합할 수 있는 개발자가 온라인 서비스를 사용하는 것이 좋습니다.
온라인 서브시스템
온라인 서브시스템은 가까운 미래에 타이틀을 출시하려는 경우 또는 UE 5.1 이후의 엔진 업그레이드를 프로젝트에 통합할 계획이 없는 경우에 사용하시기 바랍니다.
환경설정
온라인 서비스 플러그인의 베이스 모듈은 OnlineServices 입니다. 이 모듈은 서비스별 모듈을 정의하고 UE에 등록합니다. 온라인 서비스에 대한 모든 액세스는 이 모듈을 통해 이루어집니다. OnlineServices 는 초기화 중에 DefaultEngine.ini 에 지정된 디폴트 온라인 서비스 모듈을 로드하려 시도합니다. DefaultEngine.ini 파일에 다음 코드를 추가하여 온라인 서비스를 활성화하고 디폴트 온라인 서비스를 지정하세요.
[OnlineServices]
DefaultServices=<DEFAULT_PLATFORM_IDENTIFIER>
DEFAULT_PLATFORM_IDENTIFIER 는 지원되는 다음 플랫폼 식별자 중 하나로 대체해야 하는 변수입니다.
- Null
- Epic
- Xbox
- PSN
- Nintendo
- Steam
- GooglePlay
- Apple
- AppleGameKit
- Samsung
- Oculus
- Tencent
DefaultEngine.ini 에 지정된 DefaultServices 는 파라미터가 지정되지 않은 경우 UE::Online::GetServices 함수를 통해 이용할 수 있습니다.
TSharedPtr<IOnlineServices> GetServices(EOnlineServices OnlineServices = EOnlineServices::Default, FName InstanceName = NAME_None);
추가적인 온라인 서비스는 UE::Online::GetServices 에 대한 호출을 통해 요청될 때 온디맨드로 로드됩니다. 식별자가 유효하지 않거나 모듈을 로드하는 데 실패하면 null 을 반환합니다.
인터페이스 사용하기
엔진 디렉터리에는 다양한 온라인 서비스 인터페이스에 대한 헤더 파일이 있습니다.
UNREAL_ENGINE_ROOT/Engine/Plugins/Online/OnlineServices/Source/OnlineServicesInterface/Public/Online
온라인 서비스와 다양한 인터페이스에 관한 자세한 내용을 알아보려면 이 디렉터리에 있는 헤더 파일을 참조하세요.
각각의 온라인 서비스 인터페이스 문서 페이지 또한 코드 예시나 샘플 프로세스 흐름을 다루므로 온라인 서비스 플러그인 사용을 시작하는 데 도움이 됩니다.
콘솔 명령으로 인터페이스 실행하기
콘솔 명령을 사용하여 온라인 서비스 인터페이스를 실행할 수도 있습니다. 콘솔 명령으로 인터페이스를 실행하기 위한 구문은 다음과 같습니다.
OnlineServices Index=NUM INTERFACE FUNCTION [PARAM_1] [PARAM_2] [PARAM_3]...
여기서 NUM, INTERFACE, FUNCTION, PARAM_1, PARAM_2, PARAM_3 등은 원하는 값으로 대체해야 하는 변수입니다.
NUM:OnlineServices의 인덱스 번호입니다.INTERFACE: 함수 기능을 사용할 인터페이스입니다.FUNCTION: 지정된 인터페이스 내의 사용할 함수입니다.PARAM_1,PARAM_2,PARAM_3...: 지정된 함수의 파라미터입니다.
