Lobby Interface

로비는 게임 및 사용자 상태를 실시간으로 업데이트하기 위해 사용자들을 지속적으로 연결합니다. 사용자는 보통 멀티플레이 전에 팀을 구성하거나, 사전 게임 옵션을 선택하거나, 다른 플레이어의 참가를 기다리기 위해 로비를 생성하거나 로비에 참가할 수 있습니다. 사용자는 로비 인터페이스(Lobby Interface) 로 로비를 생성하고 관리하거나, 로비에 참가하거나, 로비에서 이탈할 수 있습니다.

로비 인터페이스에 액세스하려면 플랫폼 인터페이스(Platform Interface) 함수인 EOS_Platform_GetLobbyInterface 를 통해 EOS_HLobby 핸들을 얻으면 됩니다. 모든 로비 인터페이스 함수는 첫 파라미터로 이 핸들이 필요합니다. EOS_HPlatform 핸들은 반드시 연산 완료 시 트리거할 적절한 콜백을 티킹해야 합니다.

EOS_Lobby_CreateLobby 함수는 로비를 생성합니다. 더 많은 프로퍼티와 자세한 정보는 EOS_Lobby_CreateLobbyOptions를 참고하세요. 다음과 같이 EOS_Lobby_CreateLobbyOptions 를 초기화합니다.

작업이 끝나면 EOS_Lobby_OnCreateLobbyCallback 이 EOS_Lobby_CreateLobbyCallbackInfo 데이터 구조로 실행됩니다. 해당 데이터 구조의 ResultCode 필드가 성공인 경우, LobbyId 필드에 새로운 로비의 ID 값이 포함됩니다. 이 ID 값은 로비와의 더 많은 인터랙션에 필요합니다.

로비를 소멸시키려면, 로비의 오너가 다음과 같은 정보로 초기화된 EOS_Lobby_DestroyLobbyOptions 구조가 있는 EOS_Lobby_DestroyLobby 를 호출해야 합니다.

완료되면 소멸이 성공했을 경우 로비의 ID를 표시하는 EOS_Lobby_DestroyLobbyCallbackInfo 데이터 구조를 가진 EOS_Lobby_OnDestroyLobbyCallback 콜백 함수가 실행됩니다. 로비가 폐쇄되면 남은 멤버를 전부 자동으로 제거하고, 멤버 상태를 EOS_LMS_CLOSED 상태로 업데이트하도록 트리거합니다.

로비의 수명 주기는 보통 다음 순서를 따릅니다.

• 사용자가 로비를 생성합니다. 이 사용자는 자동으로 로비에 참가하게 되며, 로비의 첫 멤버이자 오너가 됩니다.
• 오너가 로비의 초기 상태를 설정하고, 다른 사용자를 로비에 참가하도록 초대할 수 있습니다.
• 다른 사용자가 로비에 참가하거나 이탈할 수 있습니다. 연결된 상태에서 멤버는 자신의 상태 정보를 업데이트하고 다른 사용자를 초대할 수 있습니다.
• 로비 오너는 게임 상태에 해당하는 데이터를 업데이트할 수 있습니다.
• 오너는 로비에서 멤버를 제거하거나 오너 자격을 다른 멤버에게 양도할 수 있습니다.
• 사용자는 로비를 이탈하거나 소멸시키지 않고 여러 라운드의 게임을 플레이할 수 있습니다. 로비의 수명은 게임 로직으로 결정됩니다.
• 최종적으로 오너가 로비를 소멸시킵니다.

유효한 EOS_HLobbyDetails 핸들로 EOS_Lobby_JoinLobby 를 호출하면, 핸들이 참조하는 로비에 사용자가 참가하려고 시도하게 됩니다. 사용자는 동시에 여러 개의 로비에 상주할 수 있습니다. 다른 로비에 참가하기 위해 기존 로비에서 이탈할 필요가 없습니다. 새 로비에 참가해도 기존 로비에서 나가지지 않습니다. 로비의 이탈 또는 소멸은 명시적이어야 합니다.

로비에서 나가려면 EOS_Lobby_LeaveLobby 를 호출합니다. 이탈하는 사용자가 현재 로비의 오너(Owner)라면, EOS는 나머지 사용자 중에서 새로운 오너를 선택합니다. 사용자가 한 명이라도 이탈하거나 오너가 바뀌면 모든 멤버가 알림을 받습니다.

로비에 있는 사용자는 EOS_Lobby_SendInvite 함수로 다른 사용자를 초대할 수 있습니다. 초대 보내기에 성공하면 로컬에서 EOS_Lobby_OnSendInviteCallback 이 트리거됩니다. 타깃 사용자에게 초대가 도착하면 해당 사용자는 알림을 받습니다. 게임은 EOS_Lobby_AddNotifyLobbyInviteAccepted 를 사용하여 플레이어가 오버레이에서 수락(Accept) 을 클릭하는 시기를 파악합니다. 초대(Invite) 버튼, 소셜 오버레이(Social Overlay), 로비 간의 인터랙션에 관해 자세히 알아보려면 소셜 오버레이 통합: 로비 사용을 참고하세요. 에픽게임즈 런처의 초대 기능을 실행하려면 디플로이를 아티팩트에 매핑해야 합니다.

초대를 거부하려면 다음과 같은 정보가 포함된 EOS_Lobby_RejectInviteOptions 구조를 가진 EOS_Lobby_RejectInvite 를 호출합니다.

완료되면 EOS_Lobby_RejectInviteCallbackInfo 데이터 구조를 가진 EOS_Lobby_OnRejectInviteCallback 함수가 로컬로 트리거됩니다. 성공하면 해당 초대는 시스템에서 영구 삭제됩니다.

보류 중인 모든 초대를 로컬 캐시에 포함시키려면 다음과 같은 정보가 포함된 EOS_Lobby_QueryInvitesOptions 구조를 가진 EOS_Lobby_QueryInvites 를 호출합니다.

작업이 끝나면 EOS_Lobby_OnQueryInvitesCallback 이 EOS_Lobby_QueryInvitesCallbackInfo 데이터 구조로 실행됩니다. 성공 시 로컬 캐시에 해당 사용자의 보류 중인 초대가 모두 포함되어 초대를 검색할 수 있습니다. 스타트업 때 사용자가 오프라인 상태일 동안 받은 초대를 확인하기에 유용한 기능입니다. 알림을 등록한 사용자가 플레이 도중에 이 함수를 호출할 필요는 거의 없습니다.

캐시에 저장된 초대를 보려면 우선 다음과 같이 초기화된 EOS_Lobby_GetInviteCountOptions 구조의 EOS_Lobby_GetInviteCount 를 호출해야 합니다.

이 함수는 로컬 캐시에서 실행되며, 실행하는 즉시 캐시 내 보류 중인 초대 횟수 uint32_t 를 반환합니다. 그러면 아래와 같은 데이터를 가진 EOS_Lobby_GetInviteIdByIndexOptions 구조의 EOS_Lobby_GetInviteIdByIndex 를 호출할 수 있습니다.

EOS_Lobby_GetInviteIdByIndex 는 로컬 캐시에서도 실행되며, 호출에 성공하는 즉시 EOS_Success 를 반환합니다. 성공 시, 제공하는 출력 파라미터에 초대 데이터의 사본과 그 크기가 포함됩니다. 필요 없어진 버퍼는 비워야 합니다.

사용자가 EOS_Lobby_AddNotifyLobbyInviteReceived 를 통해 콜백을 등록한 상태라면 실시간으로 초대를 받을 수 있습니다. 콜백 데이터에는 초대와 연관성이 있는 정보가 전부 포함되어 있습니다. 이 시점에서 사용자는 EOS_Lobby_CopyLobbyDetailsHandleByInviteId 를 사용하여 EOS_HLobbyDetails 형식으로 초대를 얻을 수 있습니다. 로비에 참가하려면 EOS_HLobbyDetails 를 반드시 보유해야 합니다. 애플리케이션을 닫거나 오프라인 상태가 되면 EOS_Lobby_RemoveNotifyLobbyInviteReceived 를 사용하여 알림 목록에서 콜백을 제거합니다.

로비의 오너는 언제든지 로비 멤버를 제거할 수 있습니다. 멤버를 제거하려면 다음과 같이 초기화된 EOS_Lobby_KickMemberOptions 데이터 구조를 가진 EOS_Lobby_KickMember 를 호출합니다.

작업이 끝나면 EOS_Lobby_KickMemberCallbackInfo 데이터 구조를 가진 EOS_Lobby_OnKickMemberCallback 함수에 대한 호출을 받습니다. 또한, 나머지 로비 멤버 전원은 EOS_LMSC_KICKED 이벤트의 알림을 받습니다.

EOS_Lobby_CreateLobbySearch 는 검색이 허용된 로비를 찾을 때 사용할 수 있는 EOS_HLobbySearch 타입 핸들을 생성합니다. 자세한 내용은 '권한 레벨(Permission Level)'을 참조하세요. 아래 함수를 사용하여 이 핸들을 구성한 다음, EOS_LobbySearch_Find 를 호출하여 실행합니다. 완료에 성공하면 애플리케이션이 검색 결과를 탐색할 수 있습니다. 여러 핸들로 복수의 검색 작업을 동시에 실행할 수 있습니다.

검색 완료 후 EOS_LobbySearch_GetSearchResultCount 를 사용하면 지정된 EOS_HLobbySearch 핸들의 검색 결과를 얻을 수 있습니다. 그리고 EOS_LobbySearch_CopySearchResultByIndex 로 개별 결과의 사본을 요청할 수 있습니다. 데이터 사본이 필요 없어지면 EOS_LobbyDetails_Release 로 제거해서 소모한 메모리를 수거합니다.

사용자가 정확한 로비 ID(Lobby ID)를 가지고 있다면, EOS_LobbySearch_SetLobbyId 로 직접 검색할 수 있습니다. 이 API로 다른 사용자와 로비 ID를 공유할 수는 없습니다.

EOS_LobbySearch_SetTargetUserId 는 알려진 사용자 ID를 가져온 후, 타깃 사용자가 멤버로 소속된 로비를 나타내는 검색 결과를 반환합니다.

로비를 찾는 가장 강력한 방법은 원하는 세팅의 서브셋을 검색하는 것입니다. 사용자가 유저 인터페이스에서 선택하는 필터 컬렉션에 따를 수도 있고, 사용자의 기술과 다른 인수를 베이스로 사용자에게 보이지 않도록 자동 처리할 수도 있고, 두 메서드를 결합할 수도 있습니다.

EOS_LobbySearch_SetParameter 는 사용자가 EOS_Lobby_AttributeData 를 구성할 수 있게 하고, 서비스에 저장된 기존의 모든 로비를 상대로 어트리뷰트를 어떻게 비교할지 정하는 EOS_EComparisonOp 를 제공합니다. 이러한 호출이 하나 이상이면 묵시적인 부울 AND 를 사이에 두고 검색 파라미터를 설정합니다.

얻을 수 있는 최대 검색 결과 개수의 한도를 정하려면 EOS_LobbySearch_SetMaxResults 함수를 사용합니다.

로비의 정보를 얻으려면 EOS_HLobbyDetails 핸들을 요청합니다. 이 정보를 제공하는 함수는 로컬 사용자와 로비의 연결에 따라 세 가지가 있습니다.

• EOS_Lobby_CopyLobbyDetailsHandle 은 현재 로비에 연결된 사용자가 사용할 수 있습니다.
• EOS_Lobby_CopyLobbyDetailsHandleByInviteId 는 로비 초대가 필요합니다.
• EOS_LobbySearch_CopySearchResultByIndex 는 로컬 사용자가 검색해서 발견한 로비에 사용 가능합니다.

이 작업 중 하나를 성공적으로 완료하면 다음 정보에 액세스할 수 있는 EOS_HLobbyDetails 핸들을 받게 됩니다.

• 로비 ID(Lobby ID): 로비의 고유 식별자
• 로비 오너(Lobby Owner): 로비의 현재 오너
• 로비 멤버(Lobby Members) : 로비의 현재 멤버
• 귄한 레벨(Permission Level): 누가 로비를 찾거나 참가할 수 있는지에 대한 제한. 아래 '권한 레벨'을 참고하세요.
• 가용 공간(Space Available): 현재 이용할 수 있는 개방 슬롯의 수
• 최대 멤버(Max Members): 로비에 동시에 수용 가능한 최대 사용자 수
• 멤버 수(Member Count): 로비에 있는 현재 멤버 수
• 로비 어트리뷰트(Lobby Attributes): 로비와 관련된 키-값 쌍
• 로비 멤버 어트리뷰트(Lobby Member Attributes): 각각의 개별 사용자와 관련된 키-값 쌍
• 로비 멤버 플랫폼(Lobby Member Platform): 서버가 식별하는 개인 사용자에 대한 하드웨어 플랫폼입니다. 이 값은 콘솔 플랫폼을 사용하는 로비 멤버에게만 제공됩니다. 콘솔 사용자가 아니면 자리표시자를 반환합니다. 자리표시자 값은 해당 사용자의 하드웨어 플랫폼을 신뢰할 만하게 식별할 수 없다는 의미입니다.

로비 오너(Owner)의 ID를 찾으려면 EOS_LobbyDetails_GetLobbyOwner 를 호출합니다. 로비 멤버의 ID를 찾으려면 우선 EOS_LobbyDetails_GetMemberCount 를 호출하여 현재 멤버 수를 얻은 다음, 현재 멤버 수만큼 반복작업하여 EOS_LobbyDetails_GetMemberByIndex 를 호출합니다. EOS_LobbyDetails_Info 데이터 구조 형식의 로비 세부사항은 EOS_LobbyDetails_CopyInfo 함수로 확인할 수 있습니다. 획득하는 EOS_LobbyDetails_Info 는 EOS SDK의 캐시로 저장된 정보의 사본입니다. 이 데이터를 소유하게 되므로, 메모리 누수를 막으려면 반드시 EOS_LobbyDetails_Info_Release 함수로 해제해야 합니다. 해당 데이터는 스냅샷으로, 받은 후에 로비 정보가 변경되어도 업데이트되지 않습니다.

로비의 권한 레벨(Permission Level)은 사용자가 로비를 발견하고 참가하는 조건을 제어합니다. 오너(Owner)는 EOS_LobbyModification_SetPermissionLevel 을 호출하여 언제든지 권한 레벨을 바꿀 수 있습니다. 사용 가능한 세팅은 다음과 같습니다.

EOS_Lobby_UpdateLobbyModification 을 호출하여 로비 수정 핸들(EOS_HLobbyModification 입력)을 얻으면, 로비 오너(Lobby Owner)가 로비를 수정하거나 멤버가 자신의 사용자 정보를 변경할 수 있습니다.

오너는 EOS_Lobby_PromoteMember 를 호출하여 로비의 다른 멤버를 승격할 수 있습니다. 로비마다 한 명의 오너만 존재할 수 있으므로, 호출자는 이 프로세스에서 오너 지위를 잃게 됩니다. 모든 멤버는 이 이벤트에 대한 알림을 받습니다.

로비와 각 멤버는 EOS_Lobby_Attribute 데이터 타입이 지원하는 애플리케이션별 키-값 어트리뷰트를 가질 수 있습니다. 이러한 어트리뷰트는 숫자, 스트링 또는 부울 데이터로 표시되어야 합니다. EOS_Lobby_Attribute 데이터 구조는 다음과 같은 정보를 포함합니다.

로비 및 로비 멤버 어트리뷰트에는 공개 및 비공개 비저빌리티가 있습니다. 공개 비저빌리티의 경우, 로비 밖의 모든 멤버에게 데이터가 공개되어 로비 어트리뷰트를 확인할 수 있으며, 로비 안에서 로비 멤버 어트리뷰트 데이터를 볼 수 있습니다. 비공개 비저빌리티의 경우, 로비 안에서 데이터가 공개되어 로비 어트리뷰트를 확인할 수 있으며, 멤버만이 로비 멤버 어트리뷰트 데이터를 볼 수 있습니다.

로비 내 한 명의 사용자 또는 로비 자체는 최대 EOS_LOBBYMODIFICATION_MAX_ATTRIBUTES 개의 어트리뷰트를 가질 수 있습니다. Key 안의 어트리뷰트 이름 필드는 EOS_LOBBYMODIFICATION_MAX_ATTRIBUTE_LENGTH 글자 수를 넘으면 안 됩니다.

로비의 현재 오너(Owner)는 다음과 같은 함수로 로비를 변경할 수 있습니다.

연결된 사용자는 누구나 다음과 같은 함수로 자신의 데이터를 수정할 수 있습니다.

어트리뷰트를 모두 원하는 대로 수정한 후에는 로비에 커밋해야 변경 사항이 적용됩니다. EOS_Lobby_UpdateLobby 를 호출하면 됩니다. 작업을 마치면 수정 사항이 적용되고 로비의 다른 멤버들이 알림을 받습니다. 콜백 함수에 대한 호출도 받게 됩니다.

사용자는 로비와 지속적으로 연결되며, 로비의 수명이 유지되는 동안 발생하는 이벤트의 알림을 받게 됩니다. 영향받는 로비를 자세히 설명하는 충분한 정보가 각 콜백과 함께 제공되므로 스타트업 시 알림을 등록할 수 있습니다.

로비의 오너가 로비 프로퍼티를 변경하면 모든 로비 멤버가 알림을 받습니다. 알림은 뭔가가 변경되었다는 단순한 정보를 전달합니다. 게임은 로비의 현재 데이터를 전부 평가하고 게임에 재적용할 것입니다.

로비의 멤버가 자신의 데이터 프로퍼티를 변경하면 모든 로비 멤버가 알림을 받습니다. 알림은 뭔가가 변경되었다는 단순한 정보를 전달합니다. 게임은 로비 멤버의 현재 데이터를 전부 평가하고 게임에 재적용할 것입니다.

사용자가 로비 내에서 다음과 같은 활동을 하면 로비의 다른 모든 사용자가 알림을 받습니다.

EOS 로비를 사용하는 에픽 서버나 자체 백엔드 서버에서 EOS 보이스(EOS Voice) 채팅방을 호스팅할 수 있습니다. 사용자는 매치 중일 때나 제품의 로비에 있을 때 다양한 플랫폼을 사용하는 다른 플레이어와 일대일로 또는 그룹끼리 통신할 수 있습니다. 자세한 내용은 로비에 사용하는 보이스 및 보이스 인터페이스를 참고하세요.

애플리케이션이 EOS 로비(EOS Lobby)의 RTC 룸(RTC Room) 기능을 사용하는 경우 수동으로 보이스 룸에 입장하거나 룸에서 나갈 필요가 없습니다. 로비 시스템이 내부에서 그 작업을 자동으로 처리하기 때문입니다. RTC 룸이 활성화된 채로 로비를 만들면, 로컬 사용자가 로비에 있는 동안 로비 시스템이 자동으로 RTC 룸에 입장하여 연결 상태를 유지합니다.

원한다면 애플리케이션이 정보 제공 목적으로 EOS_Lobby_IsRTCRoomConnected , EOS_Lobby_AddNotifyRTCRoomConnectionChanged , EOS_Lobby_RemoveNotifyRTCRoomConnectionChanged 함수를 사용하도록 선택할 수 있습니다. 적절한 예시는 멀티플레이어 로비에 있는데 로비 RTC 서비스의 연결이 끊겼을 때 연결 해제 아이콘을 표시하는 것입니다.

애플리케이션이 EOS_RTC_ * 또는 EOS_RTCAudio_ * 함수 툴세트와 상호작용하려면 먼저 EOS_Lobby_GetRTCRoomName 함수를 사용하여 로비와 연결된 채팅룸 이름을 구해야 합니다. 결과(Result) 파라미터가 EOS_Success 일 때 EOS_Lobby_GetRTCRoomName 을 가장 빠르게 호출할 수 있는 지점은 EOS_Lobby_OnJoinLobbyCallback 또는 EOS_Lobby_OnCreateLobbyCallback 내부입니다. 또한 애플리케이션은 로비의 RTC 룸(RTC Room)에 해당하는 모든 RTC 알림을 등록해야 이런 알림 직후에 발생할 수 있는 기존 룸 멤버 같은 알림이 누락되는 것을 방지할 수 있습니다.

RTC 룸 이름 사용 예시:

• 대화 상태, 룸 멤버 목록 같은 알림을 등록할 때
• 룸에서 로컬 사용자의 오디오 출력을 뮤트하거나 뮤트 해제할 때
• 룸 참여자를 차단하거나 차단 해제할 때
• 로컬 오디오 디바이스 세팅을 설정할 때

EOS_RTC_ * 함수가 일반적으로 사용되지만, 이 기능이 내부적으로 처리되거나, 애플리케이션이 더 이상 데이터를 제공하지 않거나, EOS_RTCAdmin_ * 함수를 사용해서 이 함수가 로비와 호환되지 않는 경우 다음 함수를 대신 사용합니다.

로비 오너는 EOS_Lobby_HardMuteMemberOptions 데이터 구조를 가진 EOS_Lobby_HardMuteMember 를 호출하여 로비의 기존 멤버를 하드 뮤트(Hard Mute)할 수 있습니다. 이 구조에는 해당 멤버를 뮤트할지에 대한 정보가 포함됩니다. 하드 뮤트는 특정 로비 멤버의 소리가 모든 멤버에게 들릴지 여부를 각자의 로컬 뮤트 상태와 무관하게 변경합니다.

작업이 끝나면 EOS_Lobby_OnHardMuteMemberCallback 이 EOS_Lobby_HardMuteMemberCallbackInfo 데이터 구조로 실행됩니다. 데이터 구조의 ResultCode 필드가 성공이라면, LobbyId 필드에 로비의 ID 값이 포함되고 TargetUserId 에 하드 뮤트 상태가 업데이트된 멤버가 포함됩니다.

로비는 게임 및 사용자 상태를 실시간으로 업데이트하기 위해 사용자들을 지속적으로 연결합니다. 사용자는 보통 멀티플레이 전에 팀을 구성하거나, 다른 사용자와 채팅하거나, 사전 게임 옵션을 선택하거나, 다른 플레이어의 참가를 기다리기 위해 로비를 생성하거나 로비에 참가할 수 있습니다. 스로틀 조절, 사용 할당량, 모범 사례에 대한 일반적인 정보는 서비스 사용 제한을 참고하세요.

다음은 로비 서비스의 일반적인 제한 사항입니다.

추가로 사용자당 사용 제한도 있습니다. 스로틀링을 방지하려면 다음 제한 사항을 고려하세요.