라이라 스타터 게임 분석 #2 (Common User 플러그인, Common User Subsystem, Common Session Subsystem)

https://docs.unrealengine.com/5.0/ko/common-user-plugin-in-unreal-engine-for-lyra-sample-game/

일반 사용자 플러그인

 

CommonUser 플러그인

CommonUser 플러그인은 OnlineSubsystem interface를 사용한다.

현재는 OSS 인터페이스v1 (비동기 명령과 오류 처리 부분이 개선되지 않음)가 default이다.
추후에 새로운 인터페이스v2 로 교체하려면 CommonUser.Build.cs를 수정하여 bUseOnlineSubsystemV1 boolean 값을 false로 변경하고 게임의 Config/DefaultEngine.ini 환경설정 파일로 가서 다음을 추가하자.

[/Script/Engine.OnlineEngineInterface] 
bUseOnlineServicesV2=true

현재는 로그인, 세션, 인증과 같은 핵심 작업들만 지원하지만 나중에 업적, 순위표를 위한 기능도 업데이트 한다고 한다.

라이라는 C++ 블루프린트 모두에서 Common User 플러그인과 상호작용한다.
라이라 프로젝트에서 CommonUser 플러그인 사용 예시

1. CommonGameInstance 클래스를 상속받는 LyraGameInstance 서브클래스를 작성하여 사용한다. (CommonUser 및 CommonUI 플러그인의 기능을 사용할 수 있다). 클래스 안의 코드는 프로젝트를 다른 UI 시스템과 통합되게 만들어준다. 

ㄴ User 서브시스템의 각종 델리게이트(OnHandleSystemMessage, OnUserPrivilegeChanged) 에 사용자 정의 함수를 추가하고, UserState들과 Session을 초기화하는 함수를 정의한다.

2. LyraFrontEndStateComponent 클래스는 소스 코드로부터 직접 CommonUserSubsystem에 액세스한다.
CommonUI 플러그인을 사용하여 플랫폼별 메인 메뉴가 표시되기 전에 로딩 화면을 표시하는 로직을 가진다.

ㄴ User 서브시스템과 Session 서브시스템에 접근하여 UserState들과 Session을 초기화한다.

3. W_LyraStartup 을 비롯한 여러 위젯이 CommonUserSubsystem에 직접 액세스하여 사용자 작업을 처리하기 위해 함수 또는 비동기 노드를 사용한다. local player를 초기화하는 과정에서 CommonUserSubsystem을 사용한다.

ㄴ C++ 에서는 User 초기화에 사용하는 비동기 함수들을 UAsyncAction_CommonUserInitialize 클래스로 관리한다.

InitializeForLocalPlay 함수는 플랫폼 전용 로그인과 권한 체크 (유효한 라이센스인지? 차단된 계정인지?) 를 진행하며, 그러한 과정이 끝나면 OnInitializationComplete 델리게이트를 broadcast한다.

LoginForOnlinePlay 함수는 존재하는 유저를 플랫폼 전용 온라인 백엔드 서버에 로그인 시도하며, 과정이 끝나면 OnInitializationComplete 델리게이트를 broadcast한다.

ㄴ 블루프린트에서도 노드로 이러한 함수를 호출할 수 있다.

 

4. LyraUserFacingExperienceDefinition (ULyraUserFacingExperienceDefinition ) 클래스는 메뉴에서 어떤 옵션들을 가지고 세션을 만들지 정의한다 (Request를 정의한다). W_HostSessionScreen 같은 위젯은 이것을 사용하여 게임 세션의 호스팅 또는 참여를 위해 정의한 Request를 CommonSessionSubsystem의 HostSession함수의 인자로 보낸다.

라이라는 Null 서브시스템을 디폴트로 사용하는데, 이는 에디터 또는 로컬 네트워크에서만 멀티플레이어를 지원한다. EOS 지원을 활성화하려면 패키지로 만든 빌드를 생성할 때 LyraGameEOS 타깃을 사용하거나 명령줄에 다음 옵션을 추가해야 한다.

 -customconfig=EOS

그러면 c:\Lyra\Config\Custom\EOS 디렉터리에서 EOS용 환경설정 파일이 로드됩니다. 이 환경설정 파일은 프로젝트 전용 EOS 식별자를 사용하도록 수정되어야 합니다.

 

CommonUser 플러그인의 서브 시스템

Common User Subsystem과 Common Session Subsystem은 CommonUser 플러그인에 포함된 서브 시스템들이다. 

 

CommonUserSubsystem

UGameInstance* GameInstance = UGameplayStatics::GetGameInstance(this);
UCommonUserSubsystem* UserSubsystem = GameInstance->GetSubsystem<UCommonUserSubsystem>();

 

ㄴ CommonUserSubsystem은 사용자 로그인, 인증, 권한 확인 작업을 처리하도록 설계되었다.
ㄴ OSS 인터페이스의 초기화를 처리하고 다른 서브시스템이나 게임플레이 코드에 대한 액세스를 제공한다.

ㄴ 개별 사용자의 상태를 설명하는데 사용되는 열거형과 구조체를 정의한다.

이 시스템에서 사용되는 주요 타입 
1. ECommonUserOnlineContext
ㄴ 로우 레벨 온라인 시스템 식별자

ㄴ 일반적으로는 Game Default Context를 많이 사용하지만 전용 인증 단계가 있는 플랫폼에서는 플랫폼 Context를 사용하여 접근할 수 있고 이후 EOS 같은 서비스에 서비스 Context를 사용하여 액세스하여 플랫폼 레이어에서 작동하는 크로스플레이 기능을 제공받을 수 있다.

2. UCommonUserInfo

UCommonUserInfo* FirstUser = UserSubsystem->GetUserInfoForLocalPlayerIndex(0)
ㄴ 시스템이 개별 사용자의 상태를 저장하는 용도의 오브젝트

ㄴ LocalUserInfo TMap에 의해 관리된다 <int32, UCommonUserInfo>

3. ECommonUserInitializationState

ㄴ 사용자의 전체적인 로그인 / 초기화 상태

ㄴ User Initialization Flow (로그인 단계)를 거치며 상태가 변경된다.

UserInfo->InitializationState

4. ECommonUserPrivilege

게임 세션의 일부로서 유저가 수행할 수 있는 능력/권한 상태

5. ECommonUserAvailability

ECommonUserPrivilege(권한) 의 이용 가능 상태

 

User Initialziation Flow

1. 게임을 플레이하려는 사람이 사용자로 식별되어야 합니다. PC나 모바일 등의 플랫폼에서는 게임이 시작되기 전에 이 단계가 발생하며, 사용자의 식별 정보가 런처 프로세스에서 전송됩니다. 다수의 로그인된 로컬 사용자를 지원하는 플랫폼의 경우, 참여 화면(시작 누르기)에서 플레이어가 게임을 플레이할 때 사용하려는 물리적 컨트롤러를 식별해야 합니다.
2. 사용자는 플랫폼 인터페이스를 사용해 로그인하고 인증받아야 합니다. 처음 식별된 사용자에게 이 단계를 자동으로 수행하는 경우도 있지만, 플랫폼별 화면에서 플랫폼 사용자에게 물리적 컨트롤러를 명시적으로 매핑해야 하는 경우도 있습니다.
3. 사용자의 권한을 쿼리해 게임을 플레이할 권한이 있는지 판단해야 합니다. 이러한 권한은 유효한 소프트웨어 라이선스 또는 차단된 계정에 대한 플랫폼별 확인을 포함합니다.
4. 로컬 전용 로그인(LoggedInLocalOnly)된 초기화 상태에 도달했습니다. 사용자는 로컬로 게임을 플레이할 수 있으며, 게임 저장과 같은 프로필 관련 작업에 온전히 액세스할 수 있습니다. 그러나 온라인으로 플레이하거나 다른 네트워크 권한을 사용하지는 못할 수도 있습니다. 온라인 초기화까지 완료하려면 추가적인 단계를 거쳐야 합니다.
5. 사용자에게 다시 한번 로그인 및 인증해야 할 수 있으며, 이때 다른 온라인 서비스를 사용해야 할 수도 있습니다.
6. 해당 사용자의 권한이 온라인 플레이를 위해 특별히 쿼리되어야 합니다. 여기에는 구독 활성 상태나 연령 제한에 대한 확인이 포함될 수 있습니다.
7. 두 번째 권한 확인을 통과한 후에는 사용자가 온라인 플레이를 위해 온전히 초기화되며(온라인으로 로그인), 멀티플레이어 세션을 생성하거나 참여할 수 있습니다.
8. 프로세스의 어느 단계에서나 사용자는 플랫폼에서 강제로 로그아웃될 수 있습니다. 그러면 게임 저장과 같은 프로필 액션을 더 이상 사용할 수 없으므로 게임을 재시작해야 합니다. 이 경우 대개는 전체 초기화 플로를 재시작해야 합니다.

Requesting User Initialization

Common User Subsystem에는 스테이트 머신이 내장되어 사용자가 초기화 프로세스의 어느 단계에 있는지 트래킹한다.

Initialize for Local Play Login for Online Play	These Blueprint nodes can be placed in the Event graph of a Widget or other Blueprint to request a local-only or online login for a specific local player and physical controller. This is the simplest setup and it will activate the complete exec pin when initialization has succeeded or failed.
OnUserInitializeComplete	A delegate that can be bound from either Blueprint or C++ and is activated whenever a user completes initialization.
TryToInitializeUser	A function used to start a more advanced initialization process that will eventually execute the OnUserInitializeComplete delegate.
Listen for Login Key Input	A function used to create an initial engagement screen(Press Start) or allow the capability to add controllers in local multiplayer. This is achieved by registering a temporary input handler that listens for certain controller buttons or keyboard keys, then calls TryToInitializeUser with the correct parameters.
LoginLocalUser	A function that can be called from C++ if you want to manage the initialization manually..

위와 같이 여러가지 방법으로 사용자 초기화를 요청할 수 있다.

 

 

CommonSessionSubsystem

ㄴ 온라인 게임플레이 세션의 생성, 검색, 참여 기능에 액세스할 수 있는 단순한 인터페이스를 제공한다.

ㄴ 플랫폼 전용 매치메이킹 인터페이스 및 EOS 등의 크로스 플랫폼 시스템과 상호작용할 수 있는 작업에 플랫폼 독립적인 Wrapper를 제공한다.

ㄴ 멀티플레이어 세션은 Dedicated 서버혹은 게임을 플레이 중인 플레이어가 호스팅할 수도 있다.

ㄴ Listen서버(플레이어 호스팅 서버)는 P2P NAT traversal 형태로만 액세스할 수 있다.

ㄴ 모든 멀티플레이어 게임플레이 세션의 목적은 두 게임 인스턴스를 연결해 언리얼 엔진 네트워크 시스템의 모든 기능을 사용할 수 있게 하는 것이다.

 

Requesting Session Initialization

1. 세션 호스팅 (HostSession) 

ㄴ 로드할 특정 게임플레이 모드와 맵을 설명하는 호스팅 요청으로 호출할 수 있다.

ㄴ 백엔드에 세션을 등록할 필요 없는 싱글 플레이어 세션을 만드는데에도 사용될 수 있다.

ㄴ 세션이 만들어지면 지정된 맵이 로드되고 게임플레이가 시작된다.

ㄴ 요청과 호스팅하는 PlayerController의 LocalPlayer가 nullptr이 아니라면 정상 진행된다.

 

2. 세션 찾기 (FindSessions)

ㄴ 검색 요청과 일치하는 참여 가능한 세션의 목록을 온라인 시스템에 요청하기 위해 호출할 수 있다.

ㄴ Request 오브젝트는 세션 검색에 필요한 정보를 갖고 있으며 검색이 끝난 후에는 Request 오브젝트에 검색 결과 오브젝트가 채워지고, OnSearchFinished 델리게이트가 호출된다. 이 때 검색 결과 오브젝트를 사용하여 세션에 참여할 수 있다.

 

UCommonSession_SearchSessionRequest 오브젝트 내부에 배열로 검색 결과 오브젝트가 관리되고 있다.

세션 서브시스템에서 현재 검색에 대한 SearchSetting을 멤버로 가지기 때문에 아래와 같은 방법으로 검색 결과에 대한 직접 접근이 가능하다.

SearchSettings->SearchRequest->Results

 

3. 세션 참여 (JoinSession)

검색 결과 오브젝트 (UCommonSession_SearchResult) 를 인자로 넘겨주어 세션에 대한 연결, 참여를 시도한다.

성공하면 해당 피어 또는 Dedicated 서버에 연결되며 네트워크 클라이언트로서 게임 참여를 시도한다.

 

 

4. 세션 퀵 플레이 (QuickPlaySession)

ㄴ 위 3가지 세션 초기화 함수가 결합된 메서드이다.

ㄴ 호스트 파라미터와 일치하는 퍼블릭 세션을 찾는 프로세스를 시작(FindSession), 가능하다면 세션에 참여(JoinSession), 참여가 불가능하면 새로운 세션을 시작(HostSession) 

ㄴ Session 서브 시스템에서는 이렇게 기본적인 구현을 제공하지만 필요할 경우 퀵 플레이 함수를 오버라이딩 하면 된다.

 

Common User Subsystem과 라이라는 모두 EOS 로비 인터페이스를 사용하는 P2P 호스팅 세션을 검색 및 생성하도록 설계되었다. 이것은 에디터에서 실행하는 멀티플레이어 (Null OSS 사용)와 같이 동작할 수 있다.

다른 온라인 백엔드를 완전히 지원하기 위해서는 온라인 세션 검색 (FOnlineSessionSearch) 등의 일부 옵션을 변경해야 할 수도 있다.