Sessions Interface

세션 기반 매치메이킹을 처리하는 인터페이스

28 분 소요

에픽 온라인 서비스(EOS) 에서 플레이어는 세션 인터페이스(Sessions Interface) 를 통해 온라인 게임 세션을 호스팅하고, 검색하고, 세션과 인터랙션합니다. 세션은 게임 시작 전에 특정 플레이어 슬롯 수를 채운 다음, 게임이 종료되면 해체될 정도로 짧을 수도 있고, 여러 맵 또는 레벨의 매치를 순환하는 게임을 지속해서 추적할 정도로 길 수도 있습니다. 세션 인터페이스는 백엔드 서비스 검색 및 매치메이킹 기능을 지원하는 게임 전용 데이터도 관리합니다.

세션을 사용하려면 플랫폼 인터페이스 함수 EOS_Platform_GetSessionsInterface 를 통해 EOS_HSessions 핸들을 얻어야 합니다. 모든 세션 인터페이스 함수는 첫 파라미터로 이 핸들을 요청합니다. EOS_HPlatform 핸들이 콜백에 티킹하여 요청이 완료됐을 때 트리거하는지 확인해야 합니다.

이 인터페이스를 사용할 때 고려해야 할 사항은 보안 문서 를 참조하세요.

활성 세션

활성 세션은 모든 세션 인터페이스 역할의 핵심입니다. 애플리케이션은 복수의 활성 세션을 동시에 가질 수 있으며 각각 고유한 로컬 이름으로 식별됩니다. 예를 들어 로컬 플레이어와 친구들이 함께 다른 팀과 매치를 하도록 해 주는 '파티'라는 세션이 있는 동시에 그 친구들 중 일부 또는 전부가 또 다른 플레이어와 현재 매치를 진행 중인 '게임'이라는 세션이 있을 수 있습니다. 각 세션은 참여 중인 플레이어의 시스템에서 자체 EOS_HActiveSession 핸들을 갖습니다. 플레이어가 세션을 생성하거나 온라인 검색 또는 초대를 통해 세션에 참가할 때마다 플레이어의 장치에 활성 세션이 형성됩니다. 활성 세션은 로컬로 존재하기 때문에 로컬 애플리케이션은 활성 세션이 필요 없어지면 반드시 제거해야 합니다. 호스트가 활성 세션을 제거하지 않으면 백엔드 서비스 서버가 세션 파괴 지연을 일으켜서 다른 플레이어가 온라인 검색 도중 세션을 잘못 발견할 우려가 있습니다.

활성 세션의 이름, 생성하거나 참가한 로컬 사용자의 ID, 현재 상태, 세션 세부사항에 대한 레퍼런스(EOS_SessionDetails_Info 에 대한 const 포인터), 기타 사용자 정의 데이터 속성 등 고레벨 정보(타입 EOS_ActiveSession_Info )의 사본을 얻으려면 우선 다음으로 초기화된 로컬 함수 EOS_Sessions_CopyActiveSessionHandleEOS_Sessions_CopyActiveSessionHandleOptions 로 호출하여 활성 세션 핸들(타입 EOS_HActiveSession )을 얻어야 합니다.

프로퍼티
ApiVersionEOS_SESSIONS_COPYACTIVESESSIONHANDLE_API_LATEST
SessionName세션 핸들을 얻을 세션의 이름

이 핸들로 EOS_ActiveSession_CopyInfo 를 호출할 수 있습니다. 또한 EOS_ActiveSession_CopyInfoOptions 를 다음과 같이 초기화하여 전달해야 합니다.

프로퍼티
ApiVersionEOS_ACTIVESESSION_COPYINFO_API_LATEST

이 함수 역시 로컬로 실행되며 성공 시 세션의 EOS_ActiveSession_Info 데이터 사본을 만듭니다. 필요가 없게 되면 사본을 EOS_ActiveSession_Info_Release 로 제거해야 합니다.

세션 세부사항

로컬로 생성하거나 검색, 초대 또는 다른 사용자의 현재상태 데이터를 통해 발견한 활성 세션은 EOS_SessionDetails_Info 라는 내부 데이터 구조체에 저장됩니다. 여기에는 다음과 같은 세션의 기본 세부사항이 포함되어 있습니다.

  • 세션 ID

  • 호스트 주소

  • 세션에 개방된 슬롯 수

또한 이 구조체는 다른 구조체 EOS_SessionDetails_Settings 에 대한 포인터를 포함하여 세션의 상태에 대해 보다 구체적인 정보를 제공합니다. 이는 다음을 포함합니다.

  • 버킷 ID(Bucket ID) 라는 최고 레벨 필터링 기준. 게임에 고유한 ID로 종종 'GameMode:Region:MapName' 같은 포맷을 갖습니다.

  • 세션에 허용된 총 연결 수

  • 진행 중 참가 세팅

  • 개인정보 세팅

세션 세부사항 액세스하기

EOS_ActiveSession_Info 데이터 구조체가 있다면 SessionDetails 변수가 해당 세션의 EOS_SessionDetails_Info 에 대한 액세스를 부여합니다. 아닌 경우 EOS_HSessionDetails 핸들을 사용하여 EOS_SessionDetails_CopyInfo 를 호출하고 EOS_SessionDetails_Info 데이터의 사본을 얻을 수 있습니다. 다음 정보가 들어 있는 EOS_SessionDetails_CopyInfoOptions 구조체로 EOS_SessionDetails_CopyInfo 를 호출합니다.

프로퍼티
ApiVersionEOS_SESSIONDETAILS_COPYINFO_API_LATEST

성공하면 세션의 EOS_SessionDetails_Info 사본을 반환합니다. 여기에는 세션 ID, 호스트 주소, 세션에 개방된 슬롯의 수가 포함됩니다. 이 정보가 필요 없게 되면 EOS_SessionDetails_Info_Release 를 호출하여 제거해야 합니다.

세션 생성하기

세션을 생성하려면 두 단계를 거칩니다.

첫째는 세션에 대한 초기 상태와 세팅을 EOS_Sessions_CreateSessionModification 함수를 통해 로컬로 구성하는 것입니다. 다음 정보와 함께 EOS_Sessions_CreateSessionModificationOptions 구조체를 전달해야 합니다.

프로퍼티
ApiVersionEOS_SESSIONS_CREATESESSIONMODIFICATION_API_LATEST
SessionName세션의 이름, 이 사용자에 의해 생성된 세션 중 고유함
BucketId세션 검색을 위한 최고 레벨의 게임 전용 필터링 정보. 이 기준은 가장 정적이고 대략적인 세팅으로 설정되어야 합니다. 종종 'GameMode:Region:MapName'과 같은 포맷을 갖습니다.
MaxPlayers언제든 세션에 허용되는 최대 플레이어 수
LocalUserId세션과 관련된 사용자 ID
bPresenceEnabled이 세션이 사용자의 현재상태 정보와 관련되는지 여부(자세한 내용은 현재상태 인터페이스 참조)
SessionId(선택 사항) 생성 시 세션에 정기적으로 할당될 고유 ID를 오버라이드하려면 이 값을 설정합니다. 이것을 사용하여 다른 개발자 식별자와 연관된 값을 설정할 수도 있습니다. 이렇게 하면 세션에 추가 어트리뷰트를 추가할 필요가 없으며 세션은 '프라이빗 세션'을 찾기 위해 공개적으로 알려야 합니다. 이 값은 반드시 애플리케이션 생태계 내에서 전역으로 고유해야 합니다. 그렇지 않으면 'EOS_Sessions_SessionAlreadyExists' 오류가 발생합니다.
bSanctionsEnabled이 세션이 제재를 받은 사용자의 세션 참여를 차단하는지 여부입니다. 해당 사용자의 JoinRegisterPlayers 호출이 성공하지 못하게 합니다. 자세한 내용은 제재 인터페이스 문서를 참조하세요.

EOS_Sessions_CreateSessionModification 호출이 성공하면 EOS_Success 가 반환되며 제출한 디폴트 EOS_HSessionModification 은 유효한 핸들을 포함하게 됩니다.

둘째로 원하는 대로 수정될 때까지 세션의 초기 설정을 계속 수정합니다. 세션 수정 섹션을 참조하세요. 그런 다음 아래와 같이 초기화된 EOS_Sessions_UpdateSessionOptions 구조체로 EOS_Sessions_UpdateSession 을 호출하여 생성 프로세스를 완료할 수 있습니다.

프로퍼티
ApiVersionEOS_SESSIONS_UPDATESESSION_API_LATEST
SessionModificationHandle생성 또는 업데이트할 세션에 대한 핸들(EOS_HSessionModification )

EOS_Sessions_UpdateSession 은 비동기이며 완료 시 EOS_Sessions_UpdateSessionCallbackInfo 데이터 구조체와 함께 델리게이트(타입 EOS_Sessions_OnUpdateSessionCallback )를 호출합니다. 성공하면 제공한 로컬 이름이 서버의 검색 가능한 고유 ID 스트링과 쌍으로 연결됩니다.

세션 수정하기

기존 세션을 수정하려면 먼저 EOS_Sessions_UpdateSessionModification 을 디폴트 EOS_HSessionModification 오브젝트에 대한 포인터 및 다음과 같이 초기화된 EOS_Sessions_UpdateSessionModificationOptions 구조체와 함께 호출합니다.

프로퍼티
ApiVersionEOS_SESSIONS_UPDATESESSIONMODIFICATION_API_LATEST
SessionName수정할 세션 이름

호출이 성공하면 EOS_Success 가 반환되며 로컬 세션이 수정이 적용됩니다. 또한 제공한 EOS_HSessionModification 오브젝트는 이제 유효한 핸들이 됩니다. 세션 소유자인 경우 이 핸들을 사용하여 EOS_Sessions_UpdateSession 을 호출함으로써 로컬 변경 사항을 백엔드의 세션 버전에 적용할 수 있습니다. 이 함수는 신규 세션(아직 서버에 생성되지 않은 세션) 및 기존 세션에서 작동합니다. 다음 함수는 세션의 여러 측면을 수정합니다.

함수이펙트
EOS_SessionModification_SetHostAddress이는 서버에 도달하는 데 필요한 데이터를 포함한 스트링을 변경합니다. 호스트 주소가 반드시 IP 주소일 필요는 없습니다. 소켓 ID, URL 또는 기타 어트리뷰트도 됩니다.
EOS_SessionModification_SetBucketId버킷 ID는 주요 검색 기준입니다. 모든 검색에 필요한 게임 전용 정보를 포함합니다. 예를 들어 'GameMode:Region:MapName' 같은 포맷이 버킷 ID 형성에 사용될 수 있습니다.
EOS_SessionModification_SetMaxPlayers세션에 허용되는 최대 플레이어 수를 설정할 때 사용합니다.
EOS_SessionModification_SetJoinInProgressAllowed이 함수로 플레이어가 이미 시작된 세션에 참가 가능한지 여부를 결정할 수 있습니다. 자세한 내용은 플레이 시작 및 종료하기 섹션을 참조하세요.
EOS_SessionModification_SetPermissionLevel이 함수는 세션의 개인정보 세팅을 다음 중 하나로 바꿀 수 있습니다. * EOS_OSPF_PublicAdvertised : 세션이 모든 플레이어에게 표시되며 검색 결과에 나타납니다. * EOS_OSPF_JoinViaPresence : 세션 ID를 포함하는 사용자의 현재상태 정보를 생성할 권한이 있는 플레이어만 이 세션을 찾을 수 있습니다. * EOS_OSPF_InviteOnly : 이 세션은 초대받은 플레이어만 이용 가능합니다.
EOS_SessionModification_AddAttribute커스텀 어트리뷰트(타입 EOS_SessionDetails_AttributeData )를 세션에 추가합니다. 자세한 내용은 커스텀 어트리뷰트 섹션을 참조하세요.
EOS_SessionModification_RemoveAttribute커스텀 어트리뷰트를 세션에서 제거합니다. 자세한 내용은 커스텀 어트리뷰트 섹션을 참조하세요.

세션 소유자인 경우 로컬에서 세션을 변경한 다음 백엔드 서비스에서 세션을 업데이트할 수 있습니다. 그렇게 하려면 다음 정보가 들어 있는 EOS_Sessions_UpdateSessionOptionsEOS_Sessions_UpdateSession 를 호출합니다.

프로퍼티
ApiVersionEOS_SESSIONS_UPDATESESSION_API_LATEST
SessionModificationHandle서버에서 생성 또는 업데이트할 세션에 대한 핸들(EOS_HSessionModification )

이 작업이 완료되면 EOS_Sessions_UpdateSessionCallbackInfo 데이터 구조체로 콜백 함수(타입 EOS_Sessions_OnUpdateSessionCallback )를 호출합니다.

커스텀 어트리뷰트

세션은 어트리뷰트(Attribute) 라는 사용자 정의 데이터를 포함할 수 있습니다. 각 어트리뷰트에는 스트링 키, 값, 값 타입을 나타내는 열거형 변수, 비저빌리티 세팅으로 작용하는 이름이 있습니다. 현재 지원되는 변수 타입은 다음과 같습니다.

EOS_ESessionAttributeType값 타입
EOS_SAT_BOOLEANEOS_Bool
EOS_SAT_INT64int64_t
EOS_SAT_DOUBLEdouble
EOS_SAT_STRINGconst char* (널 종료 UTF8 스트링)

사용 가능한 비저빌리티 타입은 다음과 같습니다.

EOS_ESessionAttributeAdvertisementType비저빌리티
EOS_SAAT_DontAdvertise다른 사용자에게 보이지 않습니다.
EOS_SAAT_Advertise다른 사용자에게 보입니다.

어트리뷰트 액세스하기

EOS_SessionDetails_GetSessionAttributeCount 를 유효한 EOS_HSessionDetails 핸들 및 다음 정보를 포함하는 EOS_SessionDetails_CopySessionAttributeByIndexOptions 로 호출하여 세션에 얼마나 많은 어트리뷰트가 있는지 알 수 있습니다.

프로퍼티
ApiVersionEOS_SESSIONDETAILS_GETSESSIONATTRIBUTECOUNT_API_LATEST

어트리뷰트 사본을 얻으려면 EOS_SessionDetails_CopySessionAttributeByIndex 를 유효한 EOS_HSessionDetails 핸들 및 다음과 같이 초기화된 EOS_SessionDetails_CopySessionAttributeByIndexOptions 로 호출합니다.

프로퍼티
ApiVersionEOS_SESSIONDETAILS_COPYSESSIONATTRIBUTEBYINDEX_API_LATEST
AttrIndex복사할 어트리뷰트의 인덱스

성공하면 EOS_Success 를 반환하며 출력 파라미터에 요청한 어트리뷰트 인덱스에 해당하는 EOS_SessionDetails_Attribute 구조체 사본이 포함됩니다. 이 구조체는 EOS_Sessions_AttributeData 데이터 구조체에 어트리뷰트의 값과 타입을, EOS_ESessionAttributeAdvertisementType 열거형 값에 비저빌리티를 포함합니다. 이 데이터가 필요 없게 되면 EOS_SessionDetails_Attribute_Release 로 제거해야 합니다.

어트리뷰트 추가하기

EOS_Sessions_AttributeData 데이터 구조체에 다음 정보를 입력하여 추가하거나 변경할 어트리뷰트를 구성할 수 있습니다.

프로퍼티
ApiVersionEOS_SESSIONS_SESSIONATTRIBUTEDATA_API_LATEST
Key어트리뷰트의 이름
Value어트리뷰트의 값. 스트링인 경우 스트링에 대한 포인터
ValueTypeValue 를 설명하는 EOS_ESessionAttributeType

이 데이터가 준비되면 EOS_SessionModification_AddAttribute 를 호출하여 어트리뷰트를 추가합니다. EOS_HSessionModification 핸들 및 다음과 같이 초기화된 EOS_SessionModification_AddAttributeOptions 를 제출해야 합니다.

프로퍼티
ApiVersionEOS_SESSIONMODIFICATION_ADDATTRIBUTE_API_LATEST
SessionAttribute원하는 변경을 포함하는 EOS_Sessions_AttributeData 에 대한 const 포인터
AdvertisementType이 어트리뷰트가 공개적으로 표시되는지 여부를 나타내는 EOS_ESessionAttributeAdvertisementType

EOS_SESSIONMODIFICATION_MAX_SESSION_ATTRIBUTES (현재 64)개까지 한 세션에 저장할 수 있으며 각 어트리뷰트의 이름 길이는 최대 EOS_SESSIONMODIFICATION_MAX_SESSION_ATTRIBUTE_LENGTH (현재 32)자입니다.

이 함수는 추가하거나 업데이트할 어트리뷰트를 구성하기만 합니다. 어트리뷰트를 실제로 추가하거나 업데이트하지 않으며, 세션과 어떤 방식으로도 인터랙션하지 않습니다. 이 섹션 상단에 설명된 EOS_Sessions_UpdateSession 을 호출해야 합니다.

어트리뷰트 제거하기

어트리뷰트를 제거하려면 EOS_SessionModification_RemoveAttribute 를 세션에 대한 EOS_HSessionModification 핸들 및 다음 정보를 포함한 EOS_SessionModification_RemoveAttributeOptions 구조체로 호출합니다.

프로퍼티
ApiVersionEOS_SESSIONMODIFICATION_REMOVEATTRIBUTE_API_LATEST
Key제거할 어트리뷰트의 이름(키)

이 함수는 제거할 특정 어트리뷰트를 구성하기만 합니다. 어트리뷰트를 실제로 제거하지 않으며, 세션과 어떤 방식으로도 인터랙션하지 않습니다. 이 섹션 상단에 설명된 EOS_Sessions_UpdateSession 을 호출해야 합니다.

세션에 플레이어 초대하기

다른 플레이어를 활성 세션으로 초대하려면 등록된 세션 구성원이 다음 데이터를 포함하는 EOS_Sessions_SendInviteOptions 구조체로 EOS_Sessions_SendInvite 를 호출합니다.

프로퍼티
ApiVersionEOS_SESSIONS_SENDINVITE_API_LATEST
SessionName플레이어를 초대할 세션 이름
LocalUserId초대를 보내는 로컬 사용자
TargetUserId초대되는 원격 사용자

서버가 초대 요청을 처리하면 EOS_Sessions_OnSendInviteCallback 타입 콜백이 결과 코드를 포함한 EOS_Sessions_SendInviteCallbackInfo 구조체를 실행합니다. 이 결과는 초대 전송 프로세스에 오류가 없는 경우 성공으로 표시됩니다. 이 성공은 원격 사용자가 초대를 수락했거나 보았다는 것을 뜻하지는 않습니다.

에픽게임즈 런처의 초대 기능을 위해서는 디플로이를 아티팩트에도 매핑해야 합니다.

(#초대ID로세션받기) 원격 사용자는 초대가 도착하면 알림을 받게 되며, 페이로드는 초대된 사용자 ID와 초대 자체의 ID를 모두 제공합니다. 수령 시 EOS_Sessions_CopySessionHandleByInviteId 를 사용하여 초대로부터 EOS_HSessionDetails 핸들을 얻습니다. 이 핸들을 사용하여 관련된 세션에 대한 세션 세부사항에 액세스 권한을 얻을 수 있으며, 초대를 수락 또는 거부할 수도 있습니다. 핸들 사용이 끝나면 EOS_SessionDetails_Release 를 호출하여 제거합니다.

이 알림을 받으려면 EOS_Sessions_AddNotifySessionInviteReceived 로 콜백을 등록해야 합니다. 이 작업은 일반적으로 스타트업 시에 한 번만 하면 됩니다. 이후에는 초대가 전달될 때마다 콜백이 실행될 것입니다. 알림이 필요 없게 되면 EOS_Sessions_RemoveNotifySessionInviteReceived 를 호출하여 콜백을 제거합니다.

초대 수락하기

세션 인터페이스에는 초대 수락만을 담당하는 함수가 없습니다. 초대에서 얻은 EOS_HSessionDetails 핸들로 표준 방법을 사용하여 세션에 참가할 수 있습니다. 보류 중인 모든 초대 목록을 요청하려면 EOS_Sessions_QueryInvitesOptions 데이터 구조체를 다음과 같이 초기화하여 EOS_Sessions_QueryInvites 를 호출합니다.

프로퍼티
ApiVersionEOS_SESSIONS_QUERYINVITES_API_LATEST
LocalUserId초대를 요청하고 있는 로컬 사용자

이 작업은 비동기입니다. 완료되면 EOS_Sessions_QueryInvitesCallbackInfo 데이터 구조체로 콜백 함수(EOS_Sessions_OnQueryInvitesCallback 타입)를 호출합니다. 성공하면 EOS는 사용자의 보류 중인 모든 초대를 로컬로 캐싱합니다. EOS_Sessions_GetInviteCount 를 사용하여 캐시에 있는 초대 수를 결정할 수 있습니다. 다음 정보와 함께 EOS_Sessions_GetInviteCountOptions 구조체를 전달합니다.

프로퍼티
ApiVersionEOS_SESSIONS_GETINVITECOUNT_API_LATEST
LocalUserId캐싱된 초대를 가진 로컬 사용자

이 함수는 로컬로 실행되며 현재 캐시에 있는 초대 수를 나타내는 uint32_t 를 반환합니다. 캐싱된 초대 ID를 얻으려면 다음 정보가 들어 있는 EOS_Sessions_GetInviteIdByIndexOptions 구조체로 EOS_Sessions_GetInviteIdByIndex 를 호출합니다.

프로퍼티
ApiVersionEOS_SESSIONS_GETINVITEIDBYINDEX_API_LATEST
LocalUserId캐싱된 초대를 가진 로컬 사용자
IndexID를 얻으려는 초대의 캐시 인덱스

EOS_Sessions_GetInviteIdByIndexEOS_Success 를 반환하면 전달한 출력 파라미터가 초대 ID를 널 종료 문자 스트링과 해당 스트링의 길이를 포함합니다.

초대 ID 스트링의 최대 길이는 EOS_SESSIONS_INVITEID_MAX_LENGTH (현재 64)입니다.

에서 설명했듯이 EOS_Sessions_CopySessionHandleByInviteId 함수는 관련된 세션에 대한 세션 세부사항 데이터에 액세스를 부여하는 EOS_HSession 핸들을 제공합니다. 세션에 참가하여 초대를 수락하거나, 초대를 무시하거나 또는 거부할 수 있습니다. EOS_HSession 핸들 사용이 끝나면 EOS_SessionDetails_Release 를 호출하여 제거합니다.

초대 거부하기

초대를 거부하려면 다음과 같이 초기화된 EOS_Sessions_RejectInviteOptionsEOS_Sessions_RejectInvite 를 호출합니다.

프로퍼티
ApiVersionEOS_SESSIONS_REJECTINVITE
LocalUserId초대를 거부하는 로컬 사용자
InviteId초대 ID

완료되면 EOS_Sessions_OnRejectInviteCallback 콜백 함수에 성공 또는 실패 여부를 나타내는 EOS_Sessions_RejectInviteCallbackInfo 데이터 구조체로 호출을 받습니다. 초대를 거부하면 시스템에서 이를 영구적으로 삭제합니다.

원격 세션 검색하기

원격 세션을 찾으려면 검색을 환경설정하고 검색을 실행한 다음, 결과를 검토해야 합니다.

검색 환경설정하기

검색을 시작하려면 우선 EOS_Sessions_CreateSessionSearch 를 호출하여 검색 핸들을 생성합니다. 다음과 같이 초기화된 EOS_Sessions_CreateSessionSearchOptions 구조체를 전달합니다.

프로퍼티
ApiVersionEOS_SESSIONS_CREATESESSIONSEARCH_API_LATEST
MaxSearchResults반환할 최대 검색 수

이 함수는 로컬로 실행되며 성공 시 디폴트 검색 핸들(타입 EOS_HSessionSearch )을 채웁니다. 다음 단계는 핸들을 환경설정하여 필요한 기준으로 특정 검색을 실시하는 것입니다. EOS는 세션에 대해 세 가지 검색 방법을 제공합니다.

  • 세션 ID: 알고 있는 ID로 단일 세션을 검색합니다.

  • 사용자 ID: 알고 있는 사용자와 관련된 모든 세션을 찾습니다. 현재는 로컬 사용자에 한정되어 있습니다.

  • 어트리뷰트 데이터: 사용자 정의 필터링 기준과 일치하는 모든 세션을 검색합니다.

세션 ID 환경설정하기

특정 세션을 원하고 그 서버 측 ID를 알고 있다면 검색 핸들 및 다음과 같이 초기화된 EOS_SessionSearch_SetSessionIdOptionsEOS_SessionSearch_SetSessionId 를 호출합니다.

프로퍼티
ApiVersionEOS_SESSIONSEARCH_SETSESSIONID_API_LATEST
SessionId찾을 세션 ID

세션 ID 검색을 환경설정하는 데 필요한 유일한 단계입니다. 다른 검색 방법과 달리 검색 결과를 하나만 표시합니다.

EOS_OSPF_PublicAdvertised 또는 EOS_OSPF_JoinViaPresence 로 표시된 세션만 이 방식으로 찾을 수 있습니다.

사용자 ID 환경설정하기

알고 있는 사용자에 관련된 모든 세션을 찾으려면 검색 핸들 및 다음 정보를 포함한 EOS_SessionSearch_SetTargetUserIdOptionsEOS_SessionSearch_SetTargetUserId 를 호출합니다.

프로퍼티
ApiVersionEOS_SESSIONSEARCH_SETTARGETUSERID_API_LATEST
TargetUserId세션 내에서 찾을 사용자 ID

사용자 ID 검색을 환경설정하는 데 필요한 유일한 단계입니다. 로그인한 로컬 사용자여야 합니다.

애플리케이션은 로컬에서 인증된 사용자 또는 퍼블릭 세션에 등록된 원격 사용자만 찾을 수 있습니다.

어트리뷰트 데이터 환경설정하기

세션을 찾는 가장 강력한 방법은 검색 파라미터 세트를 바탕으로 검색하는 것입니다. 이 파라미터가 필터 역할을 합니다. 사용자가 특정 게임 타입이나 맵을 선택하게 하는 파라미터 등 일부 파라미터는 사용자에게 노출됩니다. 한편 매치에서 적절한 상대를 찾을 때 사용되는 플레이어의 예상 실력 등 일부 파라미터는 가려집니다. 이 검색 방법은 여러 파라미터를 가질 수 있으며 모든 파라미터를 통과하는 세션만 검색할 것입니다. 검색 파라미터를 구성하려면 검색 핸들 및 다음 정보를 포함한 EOS_SessionSearch_SetParameterOptionsEOS_SessionSearch_SetParameter 를 호출합니다.

프로퍼티
ApiVersionEOS_SESSIONSEARCH_SETPARAMETER_API_LATEST
Parameter세션과 연관된 어트리뷰트에 비교할 값과 키
ComparisonOp비교의 타입

이 함수는 여러 번 호출되어 복수의 필터를 구성할 수 있으며 세션이 검색 결과에 나타나려면 모든 필터를 만족해야 합니다. 다음 표에는 사용 가능한 비교 타입, 값 타입, 만족해야 하는 조건이 나열되어 있습니다.

ComparisonOp허용되는 값 타입성공 조건
EOS_CO_EQUAL모두어트리뷰트가 검색 값과 같음
EOS_CO_NOTEQUAL모두어트리뷰트가 검색 값과 같지 않음
EOS_CO_GREATERTHAN수 타입어트리뷰트가 검색 값보다 큼
EOS_CO_GREATERTHANOREQUAL수 타입어트리뷰트가 검색 값보다 크거나 같음
EOS_CO_LESSTHAN수 타입어트리뷰트가 검색 값보다 작음
EOS_CO_LESSTHANOREQUAL수 타입어트리뷰트가 검색 값보다 작거나 같음
EOS_CO_DISTANCE수 타입필터 아님. 어트리뷰트가 다음에 얼마나 가까운지에 따라 정렬됨. 검색 값 또는 Abs(AttributeValue - SearchValue)
EOS_CO_ANYOF스트링어트리뷰트가 세미콜론 단락 목록(예시: 'This;OrThis;MaybeThis')의 구성 항목과 일치
EOS_CO_NOTANYOF스트링어트리뷰트가 세미콜론 단락 목록(예시: 'NotThis;OrThisEither')의 구성 항목과 일치하지 않음

검색 실행하기

검색을 실행하려면 검색 핸들 및 다음과 같이 초기화된 EOS_SessionSearch_FindOptions 구조체와 함께 EOS_SessionSearch_Find 를 호출합니다.

비동기 작업입니다. 완료되면 EOS_SessionSearch_OnFindCallback 타입 콜백 함수가 성공 또는 실패 여부를 알리는 EOS_SessionSearch_FindCallbackInfo 구조체를 받습니다. 완료에 성공하면 EOS 캐시로부터 검색 결과의 사본을 받습니다.

EOS는 복수의 EOS_SessionSearch_Find 작업의 병렬 실행을 지원합니다.

검색 결과 검토하기

주어진 EOS_HSessionSearch 핸들에 대한 EOS_SessionSearch_GetSearchResultCountEOS_SessionSearch_CopySearchResultByIndex 는 개별 EOS_HSessionDetails 핸들을 통해 세션 디테일을 하나씩 반환합니다.

검색을 성공적으로 완료하면 검색 핸들로 EOS_SessionSearch_GetSearchResultCount 를 사용하여 검색에서 반환된 결과 수를 얻습니다. EOS_SessionSearch_CopySearchResultByIndex 를 호출하여 인덱스에서 활성 세션과 관련된 EOS_HSessionDetails 핸들의 사본을 얻을 수 있습니다. 이 핸들은 세션 세부사항 데이터에 액세스를 제공합니다. 이를 사용하여 세션에 대한 정보를 로컬 사용자에게 표시하거나 자체 게임 로직을 사용하여 세션에 참가할지 여부를 결정할 수 있습니다. 이 데이터가 필요 없게 되면 반드시 EOS_HSessionDetails 핸들을 EOS_SessionDetails_Release 로 제거해야 합니다.

세션 참가하기

EOS_Sessions_JoinSession 을 호출하고 EOS_Sessions_JoinSessionOptions 구조체를 다음 정보로 제공하여 세션에 대해 유효한 EOS_HSessionDetails 핸들을 가지면 기존 세션에 참가할 수 있습니다.

프로퍼티
ApiVersionEOS_SESSIONS_JOINSESSION_API_LATEST
SessionName로컬 시스템이 세션에 사용할 고유 이름
SessionHandle참가하고자 하는 세션에 대한 EOS_HSessionDetails 핸들
LocalUserId세션에 참가하는 로컬 사용자
bPresenceEnabled이 세션이 사용자의 현재상태 정보와 관련되는지 여부(보다 자세한 내용은 현재상태 인터페이스 참조)

작업이 완료되면 EOS_Sessions_OnJoinSessionCallback 타입 콜백 함수가 성공 또는 실패 여부를 나타내는 EOS_Sessions_JoinSessionCallbackInfo 를 받습니다. 작업이 성공하면 EOS에서 참가하는 클라이언트의 시스템에 활성 세션을 생성합니다. 이 새 세션은 로컬로 소유되며 참가하는 사용자는 필요가 없어질 경우 이를 소멸시킬 책임을 집니다.

플레이어 등록하기

플레이어가 세션에 참가하면 세션 소유자는 해당 플레이어를 세션에 등록할 책임이 있습니다. 이렇게 하면 백엔드 서비스가 플레이어 수를 알 수 있어서 세션이 가득 찼을 때 세션을 알리는 일을 막을 수 있습니다. EOS는 EOS_Sessions_RegisterPlayers 함수를 통해 여러 플레이어의 등록을 한 번에 수락합니다. 소유 클라이언트 측에서 이 함수를 다음 데이터가 포함된 EOS_Sessions_RegisterPlayersOptions 구조체로 호출합니다.

프로퍼티
ApiVersionEOS_SESSIONS_REGISTERPLAYERS_API_LATEST
SessionName세션의 로컬 이름
PlayersToRegister참가 플레이어에 대한 ID 배열
PlayersToRegisterCountPlayersToRegister 의 엘리먼트 수

작업이 완료되면 EOS_Sessions_OnRegisterPlayersCallback 타입 콜백 함수가 다음 데이터를 포함하는 EOS_Sessions_RegisterPlayersCallbackInfo 파라미터로 실행됩니다.

프로퍼티
ResultCode성공 또는 실패를 나타내는 결과 코드
Registered Players성공적으로 등록된 플레이어 목록
Registered Players Count등록된 플레이어 수
Sanctioned Players제재로 인해 등록되지 못한 플레이어 목록
Sanctioned Players Count제재로 인해 등록되지 못한 플레이어 수

호출이 성공하면 새로 등록된 플레이어는 다른 플레이어를 세션에 초대하는 기능 등 일부 세션 관리 기능의 액세스 권한을 얻습니다. 제재를 받은 플레이어가 한 명 이상 등록을 거부당해도 오류가 반환되지 않는다는 점에 주의하세요. SanctionedPlayers 목록을 수동으로 확인해야 합니다. 자세한 내용은 제재 적용하기를 참조하세요. EOS는 플레이어가 세션에 참가할 때 알림을 제공하지 않습니다. 참가 시 반드시 소유자에게 알리거나 소유자에게 플레이어의 성공적인 세션 참가를 탐지할 수단을 제공해야 합니다.

사용자가 공개적으로 표시된 세션(EOS_OSPF_PublicAdvertised 또는 EOS_OSPF_JoinViaPresence 로 환경설정된 세션)으로 등록하면 다른 사람들이 EOS_SessionSearch_SetTargetUserId 로 이 세션을 찾을 수 있습니다.

세션 나가기

세션 인터페이스에는 세션 나가기를 담당하는 함수가 없습니다. 세션을 나가려면 표준 방법을 통해 로컬 이름을 사용하여 로컬 세션을 소멸시켜야 합니다.

플레이어 등록 해제하기

플레이어가 세션을 떠나면 세션 소유자는 해당 플레이어를 세션에서 등록 해제할 책임이 있습니다. 이렇게 하면 다음 플레이어가 참가할 수 있도록 서버가 플레이어 슬롯을 개방합니다. EOS는 EOS_Sessions_UnregisterPlayers 함수를 통해 여러 플레이어의 등록 해제를 한 번에 수락합니다. 소유 클라이언트 측에서 이 함수를 다음 데이터가 포함된 EOS_Sessions_UnregisterPlayersOptions 구조체로 호출합니다.

프로퍼티
ApiVersionEOS_SESSIONS_UNREGISTERPLAYERS_API_LATEST
SessionName세션의 로컬 이름
PlayersToUnregister떠나는 플레이어에 대한 ID 배열
PlayersToUnregisterCountPlayersToUnregister 의 엘리먼트 수

작업이 완료되면 EOS_Sessions_OnUnregisterPlayersCallback 타입 콜백 함수가 성공 또는 실패 여부를 나타내는 EOS_Sessions_UnregisterPlayersCallbackInfo 파라미터로 실행됩니다. 호출이 성공하면 백엔드 서비스는 해당 플레이어가 처음 등록됐을 때 받았던 세션 관리 액세스 권한을 철회합니다. 예를 들어 세션에 등록되지 않은 플레이어는 다른 플레이어가 참여하도록 초대할 수 없습니다. EOS는 플레이어가 세션을 떠날 때 알림을 제공하지 않습니다. 떠날 때 반드시 소유자에게 알리거나 소유자에게 플레이어의 세션 이탈 또는 연결 해제를 탐지할 수단을 제공해야 합니다.

플레이 시작 및 종료하기

플레이어는 로컬 활성 세션에 대한 매치가 시작 또는 끝났음을 선언할 수 있습니다. 만약 세션 맵이 로컬 플레이어가 소유한 백엔드 서비스에서 세션에 매핑한다면 백엔드 버전 또한 플레이를 시작하거나 끝낼 것입니다. 세션에서 참가 처리 중(Join in Progress) 이 비활성화되어 있는 경우 플레이 도중 백엔드 서비스는 자동으로 세션 참가 시도를 거부할 것입니다. 자세한 내용은 세션 수정하기 섹션을 참조하세요. 세션을 시작하는 것은 일반적으로 매치가 시작되었음을 뜻하지만 이 기능의 구체적인 사용법은 게임 개발자에게 달려 있습니다.

플레이를 시작하려면 다음과 같이 초기화된 EOS_Sessions_StartSessionOptionsEOS_Sessions_StartSession 를 호출합니다.

프로퍼티
ApiVersionEOS_SESSIONS_STARTSESSION_API_LATEST
SessionName세션의 로컬 이름

작업이 완료되면 EOS_Sessions_OnStartSessionCallback 타입 콜백 함수가 성공 또는 실패 여부를 나타내는 EOS_Sessions_StartSessionCallbackInfo 데이터 구조체로 실행됩니다. 작업이 성공하면 세션은 다음 정보를 포함하는 EOS_Sessions_EndSessionOptionsEOS_Sessions_EndSession 을 호출하여 플레이를 끝낼 때까지 '진행 중'으로 여겨집니다.

프로퍼티
ApiVersionEOS_SESSIONS_ENDSESSION_API_LATEST
SessionName세션의 로컬 이름

완료되면 EOS_Sessions_OnEndSessionCallback 콜백 함수가 성공 또는 실패 여부를 나타내는 EOS_Sessions_EndSessionCallbackInfo 데이터 구조체로 호출을 받습니다. 성공하면 세션은 더 이상 '진행 중'으로 여겨지지 않으며 다시 플레이어의 참가를 허용하게 됩니다. 세션을 끝내더라도 플레이어를 제거하거나 세션을 소멸시키지 않습니다. 시작 전 상태로 돌아가며 사용 가능한 상태로 남습니다. 다시 플레이를 시작할 수도 있습니다. 세션을 소멸시키려면 EOS_Sessions_EndSession 을 호출할 필요가 없습니다.

세션 소멸하기

세션이 필요 없게 되면 반드시 EOS_Sessions_DestroySession 을 사용하여 소멸시켜야 합니다. 소유 클라이언트 측에서 이 함수를 다음 정보가 포함된 EOS_Sessions_DestroySessionOptions 데이터 구조체로 호출합니다.

프로퍼티
ApiVersionEOS_SESSIONS_DESTROYSESSION_API_LATEST
SessionName소멸시킬 세션 이름

소멸 작업이 완료되면 EOS_Sessions_OnDestroySessionCallback 타입의 콜백을 EOS_Sessions_DestroySessionCallbackInfo 데이터 구조체로 받게 됩니다. 성공하면 세션은 소멸하며 해당 세션 이름을 다시 사용할 수 있게 됩니다. 그러나 이 시스템의 비동기적 특성으로 인해 EOS_Sessions_DestroySession 을 호출했으나 백엔드 서비스가 아직 세션을 소멸시키지 않았을 때 플레이어가 요청을 할 수 있습니다. 이 경우 소멸 작업을 시작한 이후에도 세션 참가 요청을 받을 수 있습니다. 이 플레이어를 거부하거나 네트워크를 종료하여 플레이어가 기능을 상실한 세션에 참가하지 않도록 해야 합니다.

원격 클라이언트에서 세션 관리 미러링하기,

세션 인터페이스에서 세션 소유자(세션을 생성한 사용자)는 세션이 백엔드 서비스에 존재하는 한 세션 상태를 관리할 수 있습니다. 세션의 라이프 사이클은 생성으로 시작되어 파괴로 끝납니다. 두 이벤트 사이에 세션 인터페이스가 세션을 변경하고, 개인정보 세팅을 바꾸고, 초대를 보내고, 플레이어가 참가하고 떠날 때 등록하거나 등록 해제하고, 매치를 시작, 플레이, 종료할 수 있습니다. 세션의 라이프 사이클은 고정되어 있지 않습니다. 예를 들어 세션은 언제든 데이터를 수정할 수 있으며, 여러 차례 매치를 시작하고 끝낼 수 있습니다.

일반적으로 세션 소유자만 백엔드 서비스의 세션 데이터를 변경할 수 있습니다. 그러나 세션에 참가하는 원격 클라이언트는 세션에 대해 자체적인 로컬 뷰를 가지며, 이 뷰는 백엔드 버전에 대한 데이터 업데이트를 자동으로 받지 않습니다. 원격 클라이언트가 다음 함수 호출을 미러링하여 로컬 뷰를 백엔드 세션과 동기화하는 것은 필수 사항이 아니지만 원격 클라이언트에게 유익할 수 있습니다.

  • EOS_Sessions_StartSession

  • EOS_Sessions_EndSession

  • EOS_Sessions_RegisterPlayers

  • EOS_Sessions_UnregisterPlayers

위 함수는 백엔드 서비스 버전에 영향을 미치지 않고 원격(소유자가 아닌) 클라이언트에서 세션의 로컬 상태를 변경할 것입니다.

제재 적용하기

EOS 제재를 사용 중인 경우 플레이어가 세션 참여 또는 등록을 시도할 때 세션 인터페이스를 통해 제재를 적용할 수 있습니다.

제재 적용은 세션 생성 시에 EOS_Sessions_CreateSessionModificationOptions 구조체의 bSanctionsEnabled 멤버 값에 따라 활성화됩니다. bSanctionsEnabled 가 true인 경우 생성된 세션이 제재를 적용합니다. 자세한 내용은 세션 생성하기를 참조하세요.

플레이어가 restrict_matchmaking 제재를 받은 경우 EOS_Sessions_RegisterPlayers 가 해당 플레이어를 세션에 등록하지 않습니다. 어떤 플레이어가 등록에 실패했는지 판단하려면 EOS_Sessions_RegisterPlayersCallbackInfo 구조체의 SanctionedPlayers 구성원을 확인해야 합니다. 자세한 내용은 플레이어 등록하기를 참조하세요. EOS_Sessions_JoinSession 함수는 restrict_matchmaking 제재를 받은 플레이어를 참여시키지 않으며 참여 시도가 있는 경우 오류를 반환합니다. 자세한 내용은 제재 인터페이스 문서를 참조하세요

사용 제한

사용자는 세션 인터페이스를 통해 온라인 게임 세션을 호스팅하고, 검색하고, 세션과 인터랙션할 수 있습니다. 세션은 게임 시작 전에 특정 플레이어 슬롯 수를 채운 다음 게임이 종료되면 해체될 정도로 짧을 수도 있고, 여러 맵 또는 레벨의 매치를 순환하는 게임을 지속해서 추적할 정도로 길 수도 있습니다. 세션 인터페이스는 백엔드 서비스 검색 및 매치메이킹 기능을 지원하는 게임 전용 데이터도 관리합니다.

스로틀링, 사용 할당량, 모범 사례에 대한 일반적인 정보는 서비스 사용 제한을 참조하세요.

세션에 적용되는 일반적인 제한은 다음과 같습니다.

기능제한
동시 플레이어세션당 1,000명
세션 어트리뷰트세션당 100개
어트리뷰트 이름 길이1,000자

세션 인터페이스를 통한 사용자 인터랙션에서 따라야 하는 제한은 다음과 같습니다.

기능제한디플로이별 제한
세션 생성분당 요청 30개분당 1CCU별 요청 30개
세션 삭제분당 요청 30개분당 1CCU별 요청 30개
세션 업데이트분당 요청 30개분당 1CCU별 요청 30개
플레이어 추가 또는 제거분당 요청 100개분당 1CCU별 요청 30개
세션 시작 또는 중지분당 요청 30개분당 1CCU별 요청 30개
사용자 초대분당 요청 100개분당 1CCU별 요청 30개
세션 필터링분당 요청 30개분당 1CCU별 요청 30개

추가로 사용자 속도별 제한이 있습니다. 스로틀 조절을 방지하려면 다음 제한 사항을 고려하세요.

기능사용자 제한
단일 사용자가 한 번에 참여할 수 있는 세션 수16

매치메이킹 보안 고려 사항

매치메이킹(Matchmaking) 기능을 사용하려면 플레이어 식별자 또는 서버 IP 주소 같은 정보 세트를 가져와서 해당 데이터를 다른 잠재적 플레이어에게 브로드캐스팅해야 합니다. 일반적으로 세션 데이터의 구성 요소는 다음과 같습니다.

  1. EOS_SessionModification_SetHostAddress 를 사용하여 설정되거나 EOS 서비스에서 자동으로 탐지한 호스트 IP 주소 입니다. 이 주소는 게임 참여 시도 시 필수적입니다.

  2. 세션에 등록된 모든 플레이어의 EOS 제품 사용자 ID(Product User ID) 입니다.

  3. EOS_SessionModification_AddAttribute 를 사용하여 세션에 추가된 모든 커스텀 어트리뷰트입니다. 이 어트리뷰트는 개발자가 설정한 어떤 것이든 될 수 있습니다.

매치메이킹은 게임 데이터를 가져와서 검색 가능한 인덱스를 생성하기 때문에 세션 생성 시 어떤 데이터가 노출되는지 항상 의식해야 합니다. 전용 서버가 있는 게임의 경우 서버의 IP 주소를 노출하며, P2P 세션의 경우 최종 사용자의 IP 주소를 노출할 수도 있습니다.

세션을 생성할 때 EOS_SessionModification_SetPermissionLevel 을 사용하여 세션의 권한 레벨 을 지정할 수 있습니다. 세션의 3가지 보안 레벨은 다음과 같습니다.

보안 레벨설명
EOS_OSPF_PublicAdvertised세션이 시작되지 않았거나 세션이 진행 중 참여를 허용하는 경우 클라이언트는 세션 ID를 모르더라도 검색 결과의 세션을 가져오고 세션 정보를 읽을 수 있습니다. 고유한 세션 식별자에 액세스 가능한 클라이언트/플레이어는 세션이 참여 불가능한 상태여도 세션 정보를 볼 수 있습니다.
EOS_OSPF_JoinViaPresence고유한 세션 식별자에 액세스 가능한 클라이언트/플레이어는 세션 정보를 볼 수 있습니다. 일반적으로 이 정보는 현재상태 데이터를 통해 공유되지만 다른 방식으로도 공유 가능합니다.
EOS_OSPF_InviteOnly세션의 기존 멤버가 명시적으로 세션에 초대한 플레이어만 세션 정보를 볼 수 있습니다.

모범 사례

  • 필요한 노출량이 최소가 되도록 세션 범위를 지정하세요.

  • 세션을 찾는 모든 사람에게 노출되면 안 되는 정보를 세션 어트리뷰트에 추가하지 마세요.

  • JoinViaPresence를 사용하는 경우 세션 ID를 플레이어/UI로부터 숨기세요. 세션 ID가 노출되면 세션 데이터에 액세스할 수 있게 됩니다.

  • 게임이 JoinInProgress를 지원하지 않는 경우 서버가 EOS_Sessions_StartSession으로 세션을 시작하도록 하여 게임 진행 중에는 검색에서 세션이 제외되게 하세요.