일반 사용자 플러그인

일반 사용자(Common User) 플러그인은 C++, 블루프린트 스크립팅, 온라인 서브시스템(Online Subsystem, OSS), 기타 온라인 백엔드 간에 공통 인터페이스를 제공합니다. 라이라 스타터 게임(Lyra Starter Game)의 일부로 배포되었지만 어느 프로젝트에나 사용 가능한 독립형 플러그인입니다.

설계 철학

OSS는 로그인, 인증, 멀티플레이어 세션 등의 플랫폼별 기능에 액세스하기 위한 일반 인터페이스로 설계되었으며, 일반 언리얼 엔진 코드에서 호출하여 다양한 작업을 수행할 수 있는 표준 인터페이스를 제공합니다. 일반적이고 유연한 라이브러리이므로, 전형적인 게임플레이 세션의 하이 레벨 플로를 직접 지원하지는 않습니다. 일반 사용자 플러그인은 참여 화면, 게임 컨트롤러 처리, 멀티플레이어 게임 호스팅 등의 기능을 보조하기 위한 유틸리티 함수를 제공하는 옵션 플러그인입니다.

일반 사용자 플러그인의 기능은 C++ 또는 블루프린트에서 호출될 수 있는 엔진 서브시스템(Engine Subsystems)을 사용할 때 나타납니다. 라이라 스타터 게임은 이 기능을 사용하고 게임에 통합하는 방법을 알려줍니다. 일반 사용자 플러그인은 기존 OSS는 물론 실험 단계인 온라인 서비스 인터페이스(Online Services Interface) 등의 다른 시스템에 대해서도 작동합니다. 게임 플러그인에 정의되어 있기 때문에 전용 온라인 시스템에서 작동하도록 수정하거나 서브클래스화할 수 있습니다. 일반 사용자 플러그인은 순위표 및 업적과 같은 다수의 게임 관련 온라인 기능을 지원하도록 업데이트될 예정입니다. 현재는 상업적인 멀티플레이어 게임을 다수의 플랫폼에 출시할 때 필요한 핵심 작업(로그인, 인증, 세션)에 대한 지원을 제공합니다.

플러그인 설치하기

게임에 플러그인을 설치하는 방법입니다.

언리얼 엔진 깃허브(Unreal Engine Github) 또는 언리얼 엔진 런처의 학습 탭에서 라이라 스타터 게임의 콘텐츠와 소스 코드를 받습니다.

일반 사용자 플러그인은 블루프린트 전용 프로젝트에서 사용할 수 없습니다.

엔진의 공개 출시 버전에 포함되지 않은 플랫폼에 액세스할 수 있는 경우, 해당 플랫폼을 포함하는 샘플 버전을 사용해야 합니다.

시스템에 있는 c:\Lyra\Plugins 폴더로 이동한 후, CommonUser 폴더를 게임 프로젝트 폴더에 복사합니다.
에디터에서 툴바로 가서 편집(Edit) > 플러그인(Plugins) 을 클릭한 후 플러그인 브라우저(Plugin Browser)에서 일반 사용자(Common User) 플러그인을 찾아 활성화합니다.

프로젝트에 필요한 플랫폼별 온라인 서비스 플러그인을 모두 활성화합니다.

프로젝트를 다시 컴파일하여 서브시스템을 활성화합니다.
c:\Lyra\Config 와 c:\Lyra\Platforms\PlatformName\Config 폴더에 있는 .ini 파일을 보고, 자신의 .ini 파일에 사용하고자 하는 값을 모두 복사합니다.

라이라 환경설정 파일에 있는 세팅과 코멘트는 프로젝트 환경설정 세팅의 일반적인 기준으로 사용할 수 있으며, 에디터 내의 프로젝트 세팅(Project Settings) 을 사용하여 일부 변경 사항을 커밋할 수 있습니다. 자세한 정보는 라이라 엔진 퀄리티 및 디바이스 프로파일을 참조하세요.

이제 블루프린트가 일반 사용자 서브시스템에 액세스할 수 있습니다. C++ 지원을 활성화하려면 ModuleName.Build.cs 파일의 PrivateDependencyModuleNames 부분에 CommonUser를 추가해야 합니다.

자세한 문서 자료는 [언리얼 엔진 모듈]((programming-and-scripting\unreal-architecture\Modules)을 참조하세요.

온라인 서비스 인터페이스 사용하기

일반 사용자 플러그인은 UE4에서 사용 가능한 온라인 서브시스템 인터페이스를 디폴트로 사용합니다.

UE5의 향후 출시될 버전에서는 이 인터페이스가 비동기 명령과 오류 처리 부분이 개선된 새로운 온라인 서비스 인터페이스(OSSv2)로 대체될 예정입니다.

온라인 서비스는 실험 단계이기 때문에 일반 사용자 플러그인의 초기 출시 버전에서는 디폴트로 사용하지 않습니다. 플러그인이 새로운 인터페이스를 사용하도록 교체하려면 CommonUser.Build.cs를 수정하여 bUseOnlineSubsystemV1 boolean 값을 false로 변경하고 게임의 Config/DefaultEngine.ini 환경설정 파일로 가서 다음을 추가합니다.

	[/Script/Engine.OnlineEngineInterface]
	bUseOnlineServicesV2=true

이렇게 하면 새로운 인터페이스를 사용하기 위해 필요한 빌드 종속성이 활성화됩니다. EOS 온라인 서비스를 사용하려면 [OnlineSubsystemEOS] 부분을 포함하는 환경설정 파일 안에 있는 에픽 온라인 서비스 (Epic Online Services, EOS) 온라인 서브시스템을 비활성화해야 합니다.

예를 들어 Lyra/Config/Custom/EOS/DefaultEngine.ini 파일에서는 bEnabled boolean 값을 false 로 설정해야 합니다.

	[OnlineSubsystemEOS]
	bEnabled=false

실험 단계인 온라인 서비스 인터페이스는 향후 출시될 엔진과 호환되도록 설계된 게임에 사용하는 것을 추천합니다. 커스텀 온라인 백엔드를 개발하고 있거나 EOS를 주요 백엔드로 사용한다면 온라인 서비스 지원을 활성화할 수 있습니다.

라이라와 일반 사용자 플러그인

라이라는 C++와 블루프린트 모두에서 일반 사용자 플러그인과 상호작용합니다. 다음 예시는 이 플러그인이 제공하는 시스템을 라이라가 어떻게 사용하는지 보여줍니다.

일반 게임 C++ 플러그인에는 CommonGameInstance (UCommonGameInstance )와 같은 클래스가 있습니다. 게임별 GameInstance 서브클래스는 CommonGameInstance 클래스로부터 상속받아 CommonUser 및 CommonUI 플러그인의 기능과 통합될 수 있습니다. 클래스 안의 코드는 프로젝트를 다른 UI 시스템과 통합하는 방법의 예시로 사용할 수 있습니다.
LyraFrontEndStateComponent (ULyraFrontendStateComponent )는 소스 코드로부터 직접 CommonUserSubsystem에 액세스합니다. 이 클래스는 CommonUI 플러그인을 사용하여 플랫폼별 메인 메뉴(W_LyraFrontEnd )가 표시되기 전에 시작 누르기(Press Start) 화면(W_LyraStartup )을 표시하는 로직의 일부입니다.
W_LyraStartup 을 비롯한 여러 위젯이 CommonUserSubsystem에 직접 액세스하여 사용자 작업을 처리하기 위해 함수 또는 비동기 노드를 사용합니다.
LyraUserFacingExperienceDefinition (ULyraUserFacingExperienceDefinition ) 클래스는 멀티플레이어 FPS의 표준 메뉴 옵션이 있는 게임 세션을 실행하는 방법을 설명합니다. W_HostSessionScreen 같은 위젯은 이것을 사용하여 게임 세션의 호스팅 또는 참여를 위해 CommonSessionSubsystem으로 보내지는 세션 설명을 생성합니다.

라이라 스타터 게임은 에픽 온라인 서비스(EOS) 서브시스템의 실제 작동 예시로 설계되었습니다. 라이라는 Null 서브시스템을 디폴트로 사용하는데, 이는 에디터 또는 로컬 네트워크에서만 멀티플레이어를 지원합니다. EOS 지원을 활성화하려면 패키지로 만든 빌드를 생성할 때 LyraGameEOS 타깃을 사용하거나 명령줄에 다음 옵션을 추가합니다.

	 -customconfig=EOS

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

플러그인 서브시스템

일반 사용자 서브시스템

일반 사용자 서브시스템 (UCommonUserSubsystem )은 사용자 로그인, 인증, 권한 확인 작업을 처리하도록 설계되었습니다. 이 작업은 플레이어 프로필과 연결된 게임 저장 등의 기능을 사용할 때 반드시 필요합니다. 온라인 게임에서는 사용자 로그인이 첫 단계입니다. 로그인은 다른 온라인 기능이 작동하기 위해 꼭 필요한 절차이기 때문입니다. 일반 사용자 서브시스템은 ID 인터페이스와 같은 OSS 인터페이스의 초기화를 처리하고 다른 서브시스템이나 게임플레이 코드에 대한 액세스를 제공합니다. 이 서브시스템은 개별 사용자의 상태를 설명하는 데 사용되는 열거형와 구조체를 정의합니다. 다음 표에서는 시스템 전반에 사용되는 중요 타입들을 살펴볼 수 있습니다.

시스템 타입 이름	설명
ECommonUserOnlineContext	작업에 사용될 낮은 수준의 온라인 시스템을 식별하는 열거형입니다. 블루프린트와 높은 수준의 C++ 코드는 일반적으로 여러 소스의 정보를 결합한 디폴트 컨텍스트(게임)를 사용합니다. 전용 인증 레이어가 있는 콘솔 등의 플랫폼에서는 명시적 액세스를 위해 플랫폼 컨텍스트가 사용될 수 있습니다. 그러면 크로스플레이 등의 기능을 제공하기 위해 플랫폼 레이어에서 작동하는 EOS 등의 서비스에 서비스 컨텍스트를 사용하여 명시적으로 액세스할 수 있습니다.
UCommonUserInfo	시스템이 관리하는 개별 사용자의 상태를 저장하는 용도의 오브젝트입니다. 각 사용자에게는 자신만의 Unique Net Id가 있으며, 이는 플레이어 스테이트 등의 클래스에서 사용자를 식별하는 데 사용됩니다. 싱글 플레이어 게임에서는 사용자 정보(User Info)가 하나뿐이지만, 로컬 멀티플레이어 게임에서는 플랫폼별 사용자(또는 복수의 로컬 사용자를 지원하지 않는 플랫폼의 게스트)에 상응하는 여러 사용자 정보 오브젝트가 존재할 수 있습니다.
ECommonUserInitializationState	사용자의 전체적인 로그인/초기화 상태를 설명합니다. 이 상태는 사용자가 아래의 사용자 초기화 플로(User Initialization Flow) 부분에 설명된 로그인 단계를 거침에 따라 변경됩니다.
ECommonUserPrivilege	사용자가 게임플레이 세션의 일부로 수행할 수 있는 다양한 능력과 액션을 설명하는 열거형입니다.
ECommonUserAvailability	권한 또는 다른 기능이 허용되는 일반적인 수준을 설명합니다. 예를 들어 사용자가 계정을 인증했지만 현재 인터넷 연결이 오프라인 상태라면, 온라인 플레이 가능(CanPlayOnline)이라는 권한의 이용 가능 여부가 현재 이용 불가(CurrentlyUnavailable)로 설정될 것입니다.

사용자 초기화 플로

로그인과 사용자 인증은 복잡하면서 여러 단계로 이루어지고, 플랫폼에 따라 다른 프로세스 이기때문에 실행 시간이 다소 걸립니다. 다음은 사용자 초기화 플로에 필요한 단계의 순서입니다.

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

일반 사용자 서브시스템의 주요 목적은 개별 게임에 이 프로세스의 복잡한 절차를 무시할 수 있는 기능을 제공하는 것입니다.

사용자 초기화 요청

일반 사용자 서브시스템에는 스테이트 머신이 내장되어 사용자가 초기화 프로세스의 어느 단계에 있는지 트래킹합니다. 이 프로세스는 여러 방법으로 시작할 수 있습니다.

사용자 초기화 방법	설명
온라인 플레이를 위한 로컬 플레이 로그인 초기화(Initialize for Local Play Login for Online Play )	이 블루프린트 노드는 위젯 또는 다른 블루프린트의 이벤트 그래프에 배치되어 특정 로컬 플레이어와 물리적 컨트롤러에 대한 로컬 전용 또는 온라인 로그인을 요청합니다. 이는 가장 단순한 설정으로서 초기화가 성공 또는 실패했을 때 실행 핀을 활성화합니다.
사용자 초기화 완료 시(OnUserInitializeComplete)	블루프린트 또는 C++에 바운드될 수 있으며, 사용자가 초기화를 완료할 때 콜백되는 델리게이트입니다.
사용자 초기화 시도(TryToInitializeUser)	최종적으로 사용자 초기화 완료 시 델리게이트를 실행할 고급 초기화 프로세스를 시작하기 위한 함수입니다.
로그인 키 입력 수신(Listen for Login Key Input)	초기 참여 화면(시작 누르기)을 생성하거나, 로컬 멀티플레이어에서 컨트롤러를 추가하는 용도로 사용되는 함수입니다. 그러기 위해 특정 컨트롤러 버튼 또는 키보드 키를 수신하고 올바른 파라미터로 사용자 초기화 시도를 호출하는 임시 입력 핸들러를 등록합니다.
로컬 사용자 로그인(LoginLocalUser)	초기화를 수동으로 관리하려는 경우 C++에서 호출할 수 있는 함수입니다.

이 함수들은 라이라의 메뉴 위젯(W_LyraStartup )과 C++에서 사용되어 멀티 유저 플랫폼의 참여 화면을 명시적으로 표시하거나, PC와 모바일 플랫폼에서 user_0을 controller_0으로 자동 로그인시키려고 시도합니다. 이를 위해 ShouldWaitForStartInput 함수를 호출하지만, 싱글 플레이어 게임을 만들고 있다면 참여 화면을 항상 표시하는 것이 좋습니다. 온라인 세션을 시작할 수 있는 W_ExperieceSelectionScreen 같은 위젯에서는 온라인 플레이를 위한 명시적 로그인이 요청됩니다.

이 경우 사용자가 이미 로컬 초기화를 완료한 상태이므로, 이 온라인 로그인에 대한 컨트롤러 파라미터가 없습니다.

기타 작업

일반 사용자 서브시스템은 특정 사용자의 정보를 쿼리 또는 변경할 수 있는 기타 유용한 기능을 제공합니다. 더 자세한 정보를 위해서는 일반 사용자 서브시스템을 사용하는 블루프린트 함수를 살펴보거나 CommonUserSubsystem.h 파일을 읽어보시기 바랍니다.

일반 사용자 서브시스템 함수	설명
시스템 메시지 처리 시(OnHandleSystemMessage)	온라인 기능 관련 오류 메시지를 표시하기 위해 바운드될 수 있는 델리게이트입니다. 라이라의 UCommonGameInstance 클래스는 단순한 오류 팝업을 표시하며, 시스템 메시지 전송(SendSystemMessage)을 사용하면 게임플레이 코드에서 이 UI를 트리거할 수 있습니다.
사용자 권한 변경 시(OnUserPrivilegeChanged)	어떤 사용자 권한이 변경 될 때, 처리하도록 바운드될 수 있는 델리게이트입니다. 이 델리게이트는 네트워크 연결이 끊어지는 등의 경우에 게임 레벨을 처리합니다.
로컬 플레이어 인덱스로 사용자 정보 획득(GetUserInfoForLocalPlayerIndex) 플랫폼 사용자 인덱스로 사용자 정보 획득(GetUserInfoForPlatformUserIndex) Unique Net Id로 사용자 정보 획득(GetUserInfoForUniqueNetId)	사용자 정보를 쿼리하는 주요 방법입니다. 이 함수들은 네트워크 ID, 표시 닉네임, 권한을 쿼리할 수 있는 일반 사용자 정보(CommonUserInfo) 오브젝트를 반환합니다.
온라인 식별 정보 획득(GetOnlineIdentity) 온라인 서브시스템 획득(GetOnlineSubsystem)	게임플레이 코드 또는 기타 서브시스템이 캐시된 인터페이스 데이터에 액세스하기 위해 사용할 수 있는 낮은 레벨의 래퍼 함수입니다. 이 함수들은 사용 중인 온라인 인터페이스에만 해당됩니다.

일반 세션 서브시스템

일반 세션 서브시스템 (UCommonSessionSubsystem )은 온라인 게임플레이 세션의 생성, 검색, 참여를 비롯한 온라인 기능에 액세스할 수 있는 단순한 인터페이스를 제공하도록 설계되었습니다. OSS 세션 인터페이스는 플랫폼의 네이티브 매치메이킹 인터페이스 및 EOS 등의 크로스 플랫폼 시스템과 상호작용할 수 있는 작업에 플랫폼 독립적인 래퍼를 제공합니다. 멀티플레이어 세션은 게임과 플랫폼에 따라 전용 서버에서 물리적으로 호스팅할 수도 있고, 게임을 플레이 중인 플레이어가 호스팅할 수도 있습니다. 플레이어 호스팅(listen) 서버는 콘솔이나 사용자 PC에서 실행되며, (EOS 등의) Peer-to-Peer(P2P) NAT 통과(NAT traversal) 형태로만 액세스할 수 있습니다. 모든 멀티플레이어 게임플레이 세션의 목적은 두 게임 인스턴스를 연결해 언리얼 엔진 네트워크(Unreal Engine Networking) 시스템의 모든 기능을 사용할 수 있게 하는 것입니다. 그러나 두 인스턴스를 연결하려면 중간 구조(상황에 따라 로비 또는 세션)가 생성 및 쿼리되어야 합니다.

세션 초기화 요청

일반 세션 서브시스템을 사용하여 세션을 초기화하는 방법은 다양하지만, 이용 가능한 기본 옵션은 다음 표에 정리되어 있습니다.

초기화 방법	설명
세션 호스팅(HostSession)	로드할 특정 게임플레이 모드와 맵을 설명하는 호스팅 요청으로 호출할 수 있습니다. 세션 호스팅을 사용하면 온라인 백엔드로 등록되지 않는 싱글 플레이어 세션을 만들 수 있어, UI가 그 사이의 차이를 인식할 필요가 없습니다. 세션이 만들어지면 지정한 맵이 로드되고 게임플레이가 시작됩니다.
세션 찾기(FindSessions)	검색 요청과 일치하는 참여 가능한 세션의 목록을 온라인 시스템에 요청하기 위해 호출할 수 있습니다. 제공된 실행인자를 만족하는 퍼블릭 매치메이킹 게임을 찾기 위해서는 요청(`UCommonSession_SearchSessionRequest` ) 및 플레이어 검색(`APlayerController` ) 파라미터가 필요합니다. 검색이 완료되면 요청 오브젝트에 구현된 검색 완료 시(OnSearchFinished) 델리게이트가 호출되며, 세션 참여를 위해 (요청 오브젝트에 채워진) 검색 결과 오브젝트를 사용할 수 있습니다.
세션 참여(JoinSession)	검색 결과 오브젝트를 가지고 멀티플레이어 세션에 대한 연결 및 참여를 시도합니다. 성공할 경우 게임은 해당 피어 또는 전용 서버에 연결되며 네트워크 클라이언트로서 게임 참여를 시도합니다.
세션 퀵 플레이(QuickPlaySession)	호스트 파라미터와 일치하는 기존의 모든 퍼블릭 세션을 찾는 프로세스를 시작하고, 가능하다면 세션에 참여합니다. 다른 세 가지 초기화 함수가 결합된 메서드이며, 호스트 요청으로 호출됩니다. 세션 참여가 불가능한 경우 새로운 세션을 시작합니다. 일반 세션 서브시스템(CommonSessionSubsystem)은 기본적인 구현을 제공하지만, 필요한 경우 게임은 게임별 서브클래스에서 퀵 플레이 관련 함수를 오버라이드할 수 있습니다.

라이라는 몇몇 위젯 블루프린트에서 일반 세션 서브시스템과 상호작용합니다.

위젯 블루프린트	설명
W_ExperienceSelectionScreen	세션을 호스팅할지 검색할지 선택하고 세션의 퀵 플레이를 처리합니다.
W_SessionBrowserScreen	기존 세션의 검색 및 참여를 처리합니다.
W_HostSessionScreen	호스팅 규칙을 지정하고 새로운 로컬 또는 멀티플레이어 세션을 생성할 수 있게 합니다.

이 위젯들은 c:\Lyra\Source\LyraGame\GameModes 디렉터리에 있는 LyraUserFacingExperienceDefinition 클래스의 에셋에 의존합니다. 이 클래스는 게임에서 사용할 수 있는 특정 맵과 게임플레이 모드의 유형을 정의합니다. 라이라의 소스 코드에는 플레이어가 게임에서 나가거나 로그인에 실패했을 때 세션이 메모리에서 제대로 정리되었는지 확인하는 과정도 포함됩니다.

일반 세션 서브시스템과 라이라는 둘 다 (위에 설명한 대로 지원이 활성화된 경우) EOS 로비 인터페이스를 사용하는 P2P 호스팅 세션을 검색 및 생성하도록 설계되었습니다. 이는 Null 서브시스템으로 에디터 내의 멀티플레이어를 테스트하는 동안 생성된 로컬 세션과 함께 작동합니다. 플러그인의 초기 출시 버전에서 다른 온라인 백엔드를 완전히 지원할 수 있게 하려면, 내부 세션 오브젝트에 전달된 온라인 세션 검색(FOnlineSessionSearch) 등의 일부 옵션을 변경해야 할 수 있습니다.