로비 인터페이스

로비를 제어하는 인터페이스

로비는 에픽 온라인 서비스(EOS) 에서 호스트하며, 실시간 업데이트로 게임 및 사용자 상태를 공유하기 위해 사용자들을 지속적으로 연결합니다. 사용자는 보통 다른 사용자와의 채팅, 팀 구성, 사전 게임 옵션 선택, 그리고 함께 플레이하기 전 참가 대기를 위해 로비를 생성 또는 참가할 수 있습니다. EOS SDK는 로비 인터페이스 로 이 기능을 지원합니다. 사용자는 로비 인터페이스로 로비를 생성, 참가, 이탈 및 관리할 수 있습니다.

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

로비 생성 및 소멸하기

EOS_Lobby_CreateLobby 함수가 로비를 생성합니다. 다음과 같이 해당 함수의 `EOS_Lobby_CreateLobbyOptions`를 초기화합니다.

프로퍼티

ApiVersion

EOS_LOBBY_CREATELOBBY_API_LATEST

LocalUserId

로비를 생성하는 사용자입니다. 이 사용자는 자동으로 로비에 오너로서 참가합니다.

MaxLobbyMembers

로비에 동시 참가 가능한 최대 사용자 수

Visibility

로비 공개 여부. 아래 권한 레벨 섹션을 참조하세요.

연산이 끝나면 EOS_Lobby_OnCreateLobbyCallback`이 EOS_Lobby_CreateLobbyCallbackInfo 데이터 구조로 실행됩니다. 해당 데이터 구조의 ResultCode 필드가 성공인 경우, LobbyId` 필드에 새로운 로비의 ID값이 포함됩니다. 이 값은 로비와 더욱 많은 상호작용을 하는 데 필요합니다.

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

프로퍼티

ApiVersion

EOS_LOBBY_DESTROYLOBBY_API_LATEST

LocalUserId

로비를 소멸해달라고 요청한 사용자입니다. 이 사용자는 반드시 로비의 현재 오너여야 합니다.

LobbyId

소멸시킬 로비의 ID입니다.

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

로비 수명 주기

로비의 수명 주기는 보통 다음과 같은 절차를 따릅니다.

  • 사용자가 로비를 생성합니다. 이 사용자는 자동으로 로비에 참가하게 되며, 로비의 첫 멤버이자 오너가 됩니다.

  • 오너가 로비의 초기 상태를 설정하고, 다른 사용자를 로비에 참가하도록 초대할 수 있습니다.

  • 다른 사용자가 로비에 참가하거나 이탈할 수 있습니다. 연결된 상태에서 멤버는 자신의 상태 정보를 업데이트하고 다른 사용자를 초대할 수 있습니다.

  • 오너는 로비에서 멤버를 제거하거나 오너십 지위를 다른 멤버에게 양도할 수 있습니다.

  • 사용자는 로비를 이탈하거나 소멸시키지 않고 게임 세션을 플레이할 수 있습니다.

  • 최종적으로 오너가 로비를 소멸시킵니다.

로비 참가 또는 이탈하기

유효한 EOS_HLobbyDetails 핸들로 `EOS_Lobby_JoinLobby`를 호출하면, 핸들이 참조하는 로비에 사용자가 참가하려고 시도하게 됩니다. 사용자는 동시에 여러 개의 로비에 상주할 수 있습니다. 다른 로비에 참가하기 위해 기존 로비에서 이탈할 필요가 없습니다.

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

로비에 사용자 초대하기

로비에 있는 사용자는 EOS_Lobby_SendInvite 함수로 다른 사용자를 초대할 수 있습니다. 초대 보내기에 성공하면 로컬에서 EOS_Lobby_OnSendInviteCallback 유형의 콜백이 트리거됩니다. 타깃 사용자에게 초대가 도착하면 해당 사용자는 알림을 받습니다.

초대 거부하기

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

프로퍼티

ApiVersion

EOS_LOBBY_REJECTINVITE_API_LATEST

LobbyId

초대와 관련된 로비의 ID

LocalUserId

초대를 거절한 사용자의 ID

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

모든 초대 업데이트하기

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

프로퍼티

ApiVersion

EOS_LOBBY_QUERYINVITES_API_LATEST

LocalUserId

내가 가져오려는 초대의 오너인 사용자 ID

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

캐시에서 초대 가져오기

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

프로퍼티

ApiVersion

EOS_LOBBY_GETINVITECOUNT_API_LATEST

LocalUserId

내가 초대 횟수를 파악하려는 로컬 사용자

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

프로퍼티

ApiVersion

EOS_LOBBY_GETINVITEIDBYINDEX_API_LATEST

LocalUserId

초대를 소유한 로컬 사용자

Index

가져올 초대의 인덱스

EOS_Lobby_GetInviteIdByIndex`는 로컬 캐시에서도 실행되며, 호출에 성공하는 즉시 EOS_Success`를 반환합니다. 성공 시, 제공한 출력 파라미터에 초대 데이터의 사본 및 크기가 포함됩니다. 필요 없는 버퍼를 비우는 일은 각자의 책임입니다.

알림

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

로비에서 멤버 제거하기

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

프로퍼티

ApiVersion

EOS_LOBBY_KICKMEMBER_API_LATEST

LobbyId

멤버를 제거할 로비의 ID.

LocalUserId

제거를 요청한 로비 멤버의 ID. 이는 반드시 로비 오너여야 합니다.

EOS_ProductUserId TargetUserId

제거될 로비 멤버의 ID.

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

로비 검색하기

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

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

로비 ID로 검색하기

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

사용자 ID로 검색하기

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

어트리뷰트로 검색하기

로비를 찾는 가장 확실한 방법은 원하는 세팅의 서브셋을 검색하는 것입니다. 유저 인터페이스에서 사용자가 필터를 선택하는 방법에 대응될 수 있는데, 사용자의 기술과 다른 요인을 바탕으로 뒷단에서 자동 처리할 수도 있고, 양쪽 방법을 합쳐서 쓸 수도 있습니다.

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

비교 연산자

연산자

설명

모든 어트리뷰트 유형에 적용 가능한 비교

EOS_CO_EQUAL

검색값이 어트리뷰트와 정확히 같음.

EOS_CO_NOTEQUAL

검색값이 어트리뷰트와 정확히 같지 않음.

숫자 유형을 연산하는 비교

EOS_CO_GREATERTHAN

어트리뷰트가 검색값보다 큼.

EOS_CO_GREATERTHANOREQUAL

어트리뷰트가 검색값보다 크거나 같음.

EOS_CO_LESSTHAN

어트리뷰트가 검색값보다 작음.

EOS_CO_LESSTHANOREQUAL

어트리뷰트가 검색값보다 작거나 같음.

EOS_CO_DISTANCE

어트리뷰트가 formula abs(attribute - searchvalue) = 0 공식에 따라 검색값과 유사함.

스트링 유형을 연산하는 비교

EOS_CO_ANYOF

어트리뷰트가 세미콜론으로 구분된 스트링값 목록에 있음. 예: "This;OrThis;MaybeThis"

EOS_CO_NOTANYOF

어트리뷰트가 스트링 값 목록에 없음. 예: "NotThis;OrThisEither"

검색 결과 제한하기

가져올 수 있는 최대 검색 결과 한도를 정하려면 EOS_LobbySearch_SetMaxResults 함수를 사용합니다.

로비 정보 얻기

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

  • `EOS_Lobby_CopyLobbyDetailsHandle`은 현재 로비에 연결된 사용자가 사용할 수 있습니다.

  • `EOS_Lobby_CopyLobbyDetailsHandleByInviteId`는 로비 초대가 필요합니다.

  • `EOS_LobbySearch_CopySearchResultByIndex`는 로컬 사용자가 검색에서 발견한 로비에 적용 가능합니다.

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

  • 로비 ID(Lobby ID): 로비의 고유 식별자

  • 로비 오너(Lobby Owner): 로비의 현재 오너

  • 귄한 레벨(Permission Level): 누가 로비를 찾거나 참가할 수 있는지에 대한 제한(아래 "권한 레벨" 참조)

  • 가용 공간(Space Available): 현재 이용할 수 있는 개방 슬롯의 수

  • 최대 멤버(Max Members): 로비에 동시에 수용 가능한 최대 사용자 수

  • 로비 어트리뷰트(Lobby Attributes): 로비와 관련된 키값 쌍

  • 로비 멤버 어트리뷰트(Lobby Member Attributes): 각각의 개별 사용자와 관련된 키값 쌍

로비 오너의 ID를 찾으려면 EOS_LobbyDetails_GetLobbyOwner`를 호출합니다. EOS_LobbyDetails_Info 데이터 구조 형식의 로비 세부사항은 EOS_LobbyDetails_CopyInfo 함수로 확인할 수 있습니다. 획득한 EOS_LobbyDetails_Info`는 EOS SDK의 캐시 저장 정보의 사본입니다. 이 데이터를 소유하고 있으므로, 메모리 누수를 막으려면 반드시 EOS_LobbyDetails_Info_Release 함수로 해제해야 합니다. 해당 데이터는 스냅샷으로, 로비 정보를 받은 후 로비 정보가 변경되어도 업데이트되지 않습니다.

권한 레벨

로비 권한 레벨은 사용자가 로비를 찾고 참가하는 조건을 제어합니다. 오너는 `EOS_LobbyModification_SetPermissionLevel`을 호출하여 언제든지 권한 레벨을 바꿀 수 있습니다. 사용할 수 있는 세팅은 다음과 같습니다.

권한 레벨(마크로)

로비 작동방식

EOS_LPL_PUBLICADVERTISED

공개 로비입니다. 정원이 차지만 않았다면 어떤 사용자도 언제든 찾거나 이용할 수 있습니다.

EOS_LPL_JOINVIAPRESENCE

친구 전용 로비입니다. 공개 검색에 나오지 않으며, 오너의 친구만 참가할 수 있습니다.

EOS_LPL_INVITEONLY

비공개 로비입니다. 검색에 나오지 않습니다. 로비 멤버의 초대를 받아야만 참가할 수 있습니다.

로비 또는 사용자 정보 수정하기

사용자는 로비에 참가한 뒤 자신의 데이터를 수정할 수 있습니다. 추가로, 로비 오너는 로비 자체를 수정하거나 다른 사용자를 새 오너로 정할 수 있습니다. 이 과정은 전부 로비 수정 핸들(EOS_HLobbyModification 유형)을 얻기 위해 `EOS_Lobby_UpdateLobbyModification`을 호출하면 시작됩니다.

오너십 변경하기

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

로비 및 로비 멤버 프로퍼티

로비와 로비에 참가한 사용자는 EOS_Lobby_Attribute 데이터 유형이 지원하는 애플리케이션별 키값 어트리뷰트를 가질 수 있습니다. 이러한 어트리뷰트로는 숫자, 스트링 또는 boolean 데이터만 허용됩니다. EOS_Lobby_Attribute 데이터 구조는 다음과 같은 정보를 포함합니다.

필드

콘텐츠

Key

어트리뷰트를 식별하는 스트링입니다. 어트리뷰트 검색 시 시스템이 어트리뷰트를 이 스트링과 비교합니다.

Value

`Key`와 관련된 숫자, 스트링 또는 boolean 데이터입니다.

ValueType

`Value`가 가진 데이터 유형을 나타냅니다.

Visibility

EOS_ELobbyAttributeVisibility 세션으로 노출되거나 단순히 로컬에 저장되는 어트리뷰트입니다.

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

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

함수

효과

EOS_LobbyModification_SetPermissionLevel

로비의 권한 레벨을 설정하는 데 사용합니다.

EOS_LobbyModification_SetMaxMembers

이 함수는 로비에 동시에 입장할 수 있는 최대 인원을 변경합니다. 이 값의 허용 범위는 현재 로비에 있는 인원과 EOS_LOBBY_MAX_LOBBY_MEMBERS 사이의 값입니다.

EOS_LobbyModification_AddAttribute

로비 데이터에 새로운 키값 쌍을 추가합니다.

EOS_LobbyModification_RemoveAttribute

로비 데이터에서 키값 쌍을 제거합니다.

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

함수

효과

EOS_LobbyModification_AddMemberAttribute

특정 로비 멤버에게 새로운 키값 한 쌍을 추가합니다.

EOS_LobbyModification_RemoveMemberAttribute

특정 로비 멤버에게서 키값 한 쌍을 제거합니다.

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

이벤트 알림

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

로비 데이터 업데이트

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

사용자 데이터 업데이트

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

로비 멤버 상태

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

이벤트 유형

의미

EOS_LMS_JOINED

새로운 사용자가 로비에 참가했습니다. 곧 로비 멤버가 업데이트됩니다.

EOS_LMS_LEFT

기존 사용자가 로비를 이탈했고, 관련 특정 데이터가 제거되었습니다.

EOS_LMS_DISCONNECTED

기존 사용자가 예기치 않게 로비를 이탈했습니다.

EOS_LMS_KICKED

로비 오너가 특정 사용자를 로비에서 제거했습니다.

EOS_LSM_PROMOTED

이전 오너가 기존 사용자를 명시적으로 승급시켰거나, 로비 오너가 로비를 떠나면서 기존 사용자가 묵시적으로 승급되었습니다.

EOS_LMS_CLOSED

오너가 로비를 폐쇄했거나 오류로 인해 로비가 폐쇄되었습니다.

사용 제한

성능과 속도를 유지하기 위해 준수해야 하는 사용 제한에 대한 자세한 내용은 서비스 사용 제한 페이지를 확인하세요.