온라인 서비스 로비 인터페이스(Online Services Lobbies Interface) 는 로비를 생성하고 관리할 수 있는 API를 제공합니다. 로비(Lobby) 는 클라이언트 애플리케이션의 컨텍스트 내 플레이어 그룹으로, 모든 플레이어가 일부 상태를 공유합니다. 이는 플레이어들이 모두 동일한 온라인 매치에서 함께 플레이하고 있거나, 모두 동일한 매치가 시작되기를 기다리고 있다는 것을 의미합니다. 로비 및 로비 멤버들은 모두 이 상태를 공유하는 데 사용되는 어트리뷰트를 보유합니다. 로비의 어트리뷰트 또는 멤버의 어트리뷰트를 변경하면 참가한 모든 로비 멤버에게 실시간으로 변경사항이 보입니다.
로비 리더는 로비의 어트리뷰트를 변경할 수 있으며, 리더를 포함한 각 멤버는 언제든지 자신의 어트리뷰트를 변경할 수 있습니다. 로비 스키마(Lobby Schema) 는 이러한 어트리뷰트와 어트리뷰트의 타입 및 값 컨스트레인트를 정의한 후 로비를 생성할 때 이를 사용합니다. 로비 스키마는 애플리케이션 환경설정 파일에서 정의되며, 애플리케이션이 시작되면 유효성이 검사됩니다. 로비를 생성하기 위해 모든 어트리뷰트를 정의할 필요는 없지만, 스키마 유효성 검사에 실패하는 어트리뷰트를 정의할 경우 로비 생성이 실패합니다.
로비의 일반적인 용도는 매치를 진행하기 전에 플레이어들을 그룹화하는 것입니다. 몇몇 게임 매치의 경우 단일 로비의 수명 이내에 플레이되기도 합니다. 아래는 로비 수명 주기의 예시입니다.
- 플레이어가 원하는 프라이버시 세팅 및 어트리뷰트로 새 로비를 생성합니다. 이 플레이어는 로비 리더로 지정됩니다.
- 다른 플레이어들이 공개 검색, 초대 또는 소셜 현재상태를 통해 로비를 찾아 참가합니다.
- 플레이어들이 어트리뷰트 업데이트를 통해 로비 내에서 어트리뷰트를 공유합니다.
- 로비가 매치를 플레이하기로 선택하면, 로비 리더는 매치 세션 ID를 로비 어트리뷰트로 기록합니다.
- 다른 로비 멤버들은 이 세션 ID를 보고 동일한 게임 세션에 참가합니다.
- 여러 게임 매치의 수명 전반에서 플레이어들이 로비에 참가하거나 나갑니다.
API 개요
기능
다음 표에는 로비 인터페이스가 제공하는 함수에 대한 개요가 나와 있습니다.
| 함수 | 설명 |
|---|---|
| 작업 | |
CreateLobby |
새 로비를 생성하고 참가합니다. |
FindLobbies |
제공된 파라미터에 맞는 로비를 검색합니다. |
RestoreLobbies |
이전에 참가했던 로비에 다시 참가하려고 시도합니다. |
JoinLobby |
제공된 로비 ID로 로비에 참가합니다. |
LeaveLobby |
참가한 로비에서 나갑니다. |
InviteLobbyMember |
플레이어가 로비에 참가하도록 초대합니다. |
DeclineLobbyInvitation |
로비 참가 초대를 거절합니다. |
KickLobbyMember |
타깃 로비에서 멤버를 추방합니다. |
PromoteLobbyMember |
다른 로비 멤버를 리더로 승격시킵니다. PromoteLobbyMember 를 호출하는 로컬 플레이어는 반드시 현재 로비 리더여야만 다른 멤버를 승격시킬 수 있습니다. |
| 뮤테이션 | |
ModifyLobbySchema |
로비와 멤버 어트리뷰트에 적용되는 스키마를 변경합니다. 로비 리더만 스키마를 변경할 수 있습니다. 새 스키마에 존재하지 않는 기존 어트리뷰트는 제거됩니다. |
ModifyLobbyJoinPolicy |
로비에 적용되는 참가 정책을 변경합니다. 로비 리더만 참가 정책을 변경할 수 있습니다. |
ModifyLobbyAttributes |
로비에 적용되는 어트리뷰트를 변경합니다. 로비 리더만 로비 어트리뷰트를 변경할 수 있습니다. 업데이트 성공 전에 로비 스키마에 대한 어트리뷰트의 유효성이 검사됩니다. |
ModifyLobbyMemberAttributes |
로비 멤버에게 적용되는 어트리뷰트를 변경합니다. 로비 멤버는 자신의 어트리뷰트만 변경할 수 있습니다. 업데이트 성공 전에 로비 스키마에 대한 어트리뷰트의 유효성이 검사됩니다. |
| 접근자 | |
GetJoinedLobbies |
타깃 로컬 플레이어가 참가한 로비 목록을 얻습니다. |
GetReceivedInvitations |
타깃 로컬 플레이어가 수신한 초대 목록을 얻습니다. |
| 이벤트 리스닝 | |
OnLobbyJoined |
플레이어가 로비에 참가하면 트리거되는 이벤트입니다. |
OnLobbyLeft |
모든 로컬 멤버가 로비에서 나가면 트리거되는 이벤트입니다. |
OnLobbyMemberJoined |
로컬 플레이어의 로비 생성 또는 참가로 인해 로비 멤버가 참가하거나, 원격 플레이어가 참가할 때 트리거되는 이벤트입니다. |
OnLobbyMemberLeft |
로비 멤버가 참가한 로비에서 나갈 때 트리거되는 이벤트입니다. |
OnLobbyLeaderChanged |
로비의 리더십이 변경되면 트리거되는 이벤트입니다. |
OnLobbySchemaChanged |
로비의 어트리뷰트 스키마가 변경되면 트리거되는 이벤트입니다. |
OnLobbyAttributesChanged |
로비의 어트리뷰트가 변경되면 트리거되는 이벤트입니다. |
OnLobbyMemberAttributesChanged |
로비 멤버의 어트리뷰트가 변경되면 트리거되는 이벤트입니다. |
OnLobbyInvitationAdded |
로비 멤버가 초대를 수신할 때 트리거되는 이벤트입니다. |
OnLobbyInvitationRemoved |
로비 멤버가 초대를 처리하거나 해당 초대가 소멸할 때 트리거되는 이벤트입니다. |
OnUILobbyJoinRequested |
플레이어가 외부 메커니즘을 통해 로비 참가를 요청할 때 트리거되는 이벤트입니다. |
열거형 클래스
로비 인터페이스는 두 가지 열거형 클래스 ELobbyJoinPolicy 및 ELobbyMemberLeaveReason 를 통해 로비 참가 정책 및 로비 멤버 탈퇴 이유를 반영하는 열거형 클래스를 제공합니다.
ELobbyJoinPolicy
| 열거기 | 설명 |
|---|---|
PublicAdvertised |
사용자가 어트리뷰트 매칭, 로비 ID 또는 초대를 기반으로 검색하여 로비를 찾을 수 있습니다. |
PublicNotAdvertised |
사용자가 로비 ID 또는 초대를 통해 로비에 참가할 수 있습니다. |
InvitationOnly |
사용자가 초대를 통해서만 로비에 참가할 수 있습니다. |
ELobbyMemberLeaveReason
| 열거기 | 설명 |
|---|---|
Left |
로비 멤버가 로비에서 나가기로 선택했습니다. |
Kicked |
로비 멤버가 로비 오너에 의해 로비에서 추방되었습니다. |
Disconnected |
로비 멤버가 예기치 않게 나갔습니다. |
Closed |
온라인 서비스에 의해 로비가 소멸되고 모든 멤버가 떠났습니다. |
프라이머리 구조체
로비 인터페이스의 주요 기능은 FLobbyMember 및 FLobby 라는 2개의 구조체를 통해 커뮤니케이션하는 것입니다. 이와 더불어 파라미터와 반환 값을 전달하는 함수별 구조체들도 있습니다.
FLobbyMember
| 멤버 | 타입 | 설명 |
|---|---|---|
AccountId |
FAccountId |
이 로비 멤버의 계정 ID입니다. |
PlatfromAccountId |
FAccountId |
이 로비 멤버의 플랫폼 계정 ID입니다. |
PlatfromDisplayName |
FString |
이 로비 멤버의 플랫폼 표시명입니다. |
Attributes |
TMap<FSchemaAttributeId, FSchemaVariant> |
환경설정에서 정의한 이 로비 멤버의 어트리뷰트입니다. |
bIsLocalMember |
bool |
이 로비 멤버가 이 클라이언트의 로컬 플레이어인지 여부입니다. (디폴트 값은 false 입니다.) |
FLobby
| 멤버 | 타입 | 설명 |
|---|---|---|
LobbyId |
FLobbyId |
이 로비의 ID입니다. |
OwnerAccountId |
FAccountId |
이 로비의 현재 오너인 로비 멤버의 계정 ID입니다. |
LocalName |
FName |
이 로비의 로컬 이름입니다. |
SchemaId |
FSchemaId |
이 로비에 적용되는 스키마의 ID입니다. |
MaxMembers |
int32 |
이 로비에 있을 수 있는 최대 멤버 수입니다. |
JoinPolicy |
ELobbyJoinPolicy |
이 로비의 참가 정책 세팅입니다. |
Attributes |
TMap<FSchemaAttributeId, FSchemaVariant> |
환경설정에서 정의한 이 로비의 어트리뷰트입니다. |
Members |
TMap<FAccountId, TSharedRef<const FLobbyMember>> |
키가 계정 ID이고 값이 해당 로비 멤버 구조체의 포인터인 로비 멤버 딕셔너리입니다. |
환경설정
로비는 스키마 시스템을 사용하여 로비의 구조와 프로퍼티뿐만 아니라 로비 멤버 어트리뷰트까지 정의합니다. 게임은 여러 개의 개별 스키마 정의를 선언하여 다양한 타입의 로비를 지원할 수 있습니다. 모든 로비 스키마는 LobbyBase 스키마에서 파생되어야 합니다.
LobbyBase 스키마는 플레이어가 로비 검색에 사용할 수 있는 모든 어트리뷰트를 포함합니다. 이 상속 구조는 로비 인터페이스가 게임에서 제공되는 어떤 스키마를 검색 결과에 적용할지 파악한다는 것을 의미합니다. SchemaCompatibilityId 는 LobbyBase 내 특수 어트리뷰트로, 스키마의 두 클라이언트 간 호환성을 보장하기 위해 존재합니다.
게임은 스키마 정의에 있는 각 스키마 어트리뷰트에 대해 정의를 선언해야 합니다. 스키마는 프로젝트의 환경설정 파일( *.ini )에서 정의됩니다. 이러한 정의에는 어트리뷰트 타입, 최대 크기, 비저빌리티뿐만 아니라 어트리뷰트를 검색 파라미터로 사용할 수 있는지 등의 추가적인 비헤이비어도 포함됩니다.
일반적으로 스키마에는 어트리뷰트 정의를 포함하는 카테고리가 있습니다. 로비 인터페이스 스키마에는 Lobby 및 LobbyMember 라는 2개의 카테고리가 있습니다. 이러한 카테고리는 로비 오브젝트 및 로비 멤버 오브젝트에 각각 적용되는 어트리뷰트 정의를 포함합니다.
예시
다음은 로비 인터페이스의 환경설정 예시입니다.
DefaultEngine.ini
[OnlineServices.Lobbies]
+SchemaDescriptors=(Id="GameLobby", ParentId="LobbyBase")
!SchemaCategoryAttributeDescriptors=ClearArray
+SchemaCategoryAttributeDescriptors=(SchemaId="LobbyBase", CategoryId="Lobby", AttributeIds=("SchemaCompatibilityId", "ExampleSearchableLobbyAttribute"))
+SchemaCategoryAttributeDescriptors=(SchemaId="LobbyBase", CategoryId="LobbyMember")
+SchemaCategoryAttributeDescriptors=(SchemaId="GameLobby", CategoryId="Lobby", AttributeIds=("GameMode", "GameSessionId", "MapName", "MatchTimeout"))
+SchemaCategoryAttributeDescriptors=(SchemaId="GameLobby", CategoryId="LobbyMember", AttributeIds=("Appearance"))
+SchemaAttributeDescriptors=(Id="ExampleSearchableLobbyAttribute", Type="String", Flags=("Public", "Searchable"), MaxSize=64)
+SchemaAttributeDescriptors=(Id="GameMode", Type="String", Flags=("Public"), MaxSize=64)
+SchemaAttributeDescriptors=(Id="GameSessionId", Type="String", Flags=("Private"), MaxSize=64)
+SchemaAttributeDescriptors=(Id="MapName", Type="String", Flags=("Public"), MaxSize=64)
+SchemaAttributeDescriptors=(Id="MatchTimeout", Type="Double", Flags=("Public"))
+SchemaAttributeDescriptors=(Id="Appearance", Type="String", Flags=("Public"), MaxSize=64)
프로세스 플로
생성
플레이어가 로비 생성을 시작하며, 로비 생성이 완료되면 플레이어는 로비 리더로 지정됩니다. 로비를 생성한 플레이어가 초기 로비 세팅을 결정합니다. 이러한 세팅의 예시는 다음과 같습니다.
- 비저빌리티
- 참가 정책
- 스키마 ID
- 로비 어트리뷰트
- 로비 멤버 어트리뷰트
다른 플레이어들은 로비를 검색할 때 퍼블릭 어트리뷰트를 볼 수 있습니다. 로비 리더는 이 페이지의 리더 액션 섹션에 설명된 것과 같은 추가 권한을 보유합니다. 리더를 포함한 모든 로비 멤버는 자신의 개인 어트리뷰트를 변경하거나 플레이어가 로비에 참가하도록 초대할 수 있습니다. 이러한 액션은 멤버 액션 섹션에 요약되어 있습니다.
로비 생성에 성공하면, 로비를 생성한 플레이어는 OnLobbyJoined 이벤트를 수신한 다음 자신이 로비 리더로 지정되었으므로 자신에 대한 OnLobbyMemberJoined 이벤트를 수신합니다. 이 플레이어가 로비 리더로 지정되어 있는 동안 플레이어들이 로비에 참가하거나 나갈 때 OnLobbyMemberJoined 및 OnLobbyMemberLeft 이벤트를 추가로 수신합니다.
찾기
로비에 참가하려면 플레이어는 먼저 로비 ID를 알아야 합니다. 플레이어는 다음 방법으로 ID를 찾을 수 있습니다.
- 검색
- 초대
검색 및 초대 모두 클라이언트 애플리케이션에 로비 데이터의 스냅샷을 제공합니다. 스냅샷 내 어트리뷰트는 플레이어가 로비에 참가할 때까지 업데이트되지 않습니다.
검색
플레이어는 로비 검색에서 어트리뷰트를 지정하여 원하는 환경설정과 매칭되는 로비를 찾을 수 있습니다. 플레이어가 로비를 검색할 수 있는 기준은 다음과 같습니다.
- 어트리뷰트 필터
- 타깃 플레이어
- 특정 로비 ID
초대
로비의 프라이버시 세팅에 따라 로비 멤버는 다른 플레이어가 로비에 참가하도록 초대할 수 있습니다. 초대를 전송하면 타깃 플레이어는 초대가 대기 중이라고 알리는 OnLobbyInvitationAdded 이벤트를 수신합니다. 초대가 처리되거나 소멸할 때는 OnLobbyInvitationRemoved 이벤트가 트리거됩니다.
소셜 현재상태
일부 온라인 서비스 구현은 플레이어가 온라인 서비스 현재상태 인터페이스와 같은 소셜 사용자 인터페이스를 통해 친구의 로비에 참가하도록 허용합니다. 플레이어가 이 방식으로 참가하기로 선택할 경우 OnUILobbyJoinRequested 이벤트가 애플리케이션이 플레이어의 로비 참가 의사를 표시하도록 트리거합니다.
참가
참가하고자 하는 로비의 ID를 플레이어가 파악했다면, JoinLobby 호출로 로컬 플레이어 추가 프로세스가 시작됩니다. 로컬 플레이어는 초기 LobbyMember 어트리뷰트를 제공해야 하며, 이 어트리뷰트는 로비 참가 직후에 다른 기존 로비 멤버들과 공유됩니다.
로비 참가에 성공하면 플레이어는 OnLobbyJoined 이벤트를 수신합니다. 로비의 모든 기존 멤버는 새 플레이어가 참가했다고 알리는 OnLobbyMemberJoined 이벤트를 수신합니다. 플레이어는 이 로비에 남아 있는 동안에 다른 플레이어들이 로비에 참가하거나 나갈 때 OnLobbyMemberJoined 및 OnLobbyMemberLeft 이벤트를 추가로 수신합니다.
나가기
플레이어가 로비에 더 이상 남아 있고 싶지 않은 경우, 제공된 로비 ID로 LeaveLobby 가 플레이어를 로비에서 추방하고 알림을 중지합니다. 플레이어가 로비에서 나가면 로비의 다른 모든 플레이어는 OnLobbyMemberLeft 알림을 수신합니다. 이는 플레이어가 로비에서 나갔음을 알립니다. 뒤이어 로비에서 나간 플레이어에게는 OnLobbyLeft 이벤트가 전송됩니다.
복원
RestoreLobbies 는 호출한 플레이어가 이전에 참가했던 모든 로비를 복원합니다. 이는 애플리케이션이 마지막으로 종료되었을 때 로컬 플레이어가 있었던 로비에 로컬 플레이어를 다시 참가시키려는 목적으로 애플리케이션 시작 시 게임에 의해 주로 수행됩니다.
리더 액션
로비 리더는 로비 유지를 지원하기 위해 사용할 수 있는 여러 독점적 권한을 추가로 가집니다.
멤버 승격
로비 리더는 PromoteLobbyMember 호출로 다른 로비 멤버를 리더로 승격시킬 수 있습니다. 이 액션은 모든 로비 멤버에게 OnLobbyLeaderChanged 이벤트를 트리거합니다. 이전에 리더였던 플레이어는 일반 로비 멤버가 됩니다.
멤버 추방
로비 리더는 KickLobbyMember 호출로 타깃 멤버를 로비에서 추방할 수 있습니다. 이 액션은 추방된 로비 멤버에게는 OnLobbyLeft 이벤트를, 다른 모든 로비 멤버에게는 OnLobbyMemberLeft 이벤트를 트리거합니다.
로비 어트리뷰트 업데이트
로비 리더는 로비 오브젝트의 어트리뷰트를 변경할 수 있습니다. 이는 ModifyLobbyAttributes 호출로 처리됩니다. 로비 어트리뷰트가 변경되면 모든 로비 멤버는 어트리뷰트가 변경되었음을 알리는 OnLobbyAttributesChanged 이벤트를 수신합니다.
로비 참가 정책 변경
로비의 참가 정책은 로비가 검색 결과에 표시되는지, 초대로만 참가 가능한지 또는 소셜 현재상태를 통해 참가 가능한지 결정하는 데 영향을 미칩니다. 로비 리더는 ModifyLobbyJoinPolicy 를 호출하여 이 세팅을 변경할 수 있습니다.
멤버 액션
로비 멤버의 액션은 2가지로 제한됩니다. 멤버는 자신의 어트리뷰트를 업데이트하고, 다른 멤버가 로비에 참가하도록 초대할 수 있습니다.
멤버 어트리뷰트 변경
로비 멤버는 ModifyLobbyMemberAttributes 를 호출하여 자신의 어트리뷰트를 변경할 수 있습니다. OnLobbyMemberAttributesChanged 이벤트가 다른 로비 멤버들에게 이러한 어트리뷰트 변경을 알립니다.
플레이어를 로비에 참가하도록 초대
현재 로비 참가 정책이 초대를 허용하는 경우, 로비 멤버는 InviteLobbyMember 를 호출하여 플레이어를 추가로 초대할 수 있습니다. 초대 타깃은 초대가 대기 중이라고 알리는 OnLobbyInvitationAdded 이벤트를 수신합니다. 초대된 플레이어는 JoinLobby 를 호출하여 로비에 참가하거나 DeclineLobbyInvitation 으로 초대 거절을 선택할 수 있습니다.
온라인 서브시스템에서 코드 변환
로비는 온라인 서비스의 새로운 인터페이스로, 온라인 서브시스템(Online Subsystem) 에 직접적으로 대응하지 않습니다.
추가 정보
헤더 파일
자세한 정보가 필요한 경우 Lobbies.h 헤더 파일을 직접 참조하세요. 로비 인터페이스 헤더 파일 Lobbies.h 의 디렉터리 위치는 다음과 같습니다.
Engine\Plugins\Online\OnlineServices\Source\OnlineServicesInterface\Public\Online
UE 소스 코드를 얻는 방법을 알아보려면 언리얼 엔진 소스 코드 다운로드 문서를 참고하세요.
함수 파라미터 및 반환 타입
함수 파라미터를 전달하고 함수가 반환할 결과를 처리하는 방법을 포함한 함수 파라미터 및 반환 타입에 대한 설명은 온라인 서비스 개요 페이지의 함수 섹션을 참고하세요.
