세션 인터페이스

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

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

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

이 인터페이스를 사용할 때 고려해야 할 사항은

[보안 문서](GameServices/Sessions/MatchmakingSecurity)
를 참조하세요.

활성 세션

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

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

프로퍼티

ApiVersion

EOS_SESSIONS_COPYACTIVESESSIONHANDLE_API_LATEST

SessionName

세션 핸들을 가져올 세션의 이름

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

프로퍼티

ApiVersion

EOS_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`를 호출합니다.

프로퍼티

ApiVersion

EOS_SESSIONDETAILS_COPYINFO_API_LATEST

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

세션 생성

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

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

프로퍼티

ApiVersion

EOS_SESSIONS_CREATESESSIONMODIFICATION_API_LATEST

SessionName

세션의 이름, 이 사용자에 의해 생성된 세션 중 고유

BucketId

세션 검색을 위한 최고 레벨의 게임 전용 필터링 정보 이 기준은 가장 정적이고 거친 세팅으로 설정되어야 합니다. 종종 'GameMode:Region:MapName'과 같은 포맷을 갖습니다.

MaxPlayers

세션에 한 번에 허용되는 최대 플레이어 수

LocalUserId

세션과 관련된 사용자 ID

bPresenceEnabled

이 세션이 사용자의 현재상태 정보와 관련되는지 여부(보다 자세한 내용은 현재상태 인터페이스 참조)

'SessionId'

선택사항 생성 시 세션에 정기적으로 할당될 고유 ID를 오버라이드하려면 이 값을 설정하세요. 이것을 사용하여 다른 개발자 식별자와 연관된 값을 설정할 수도 있습니다. 이렇게 하면 세션에 추가 어트리뷰트를 추가할 필요가 없으며 세션은 '프라이빗 세션'을 찾기 위해 공개적으로 광고해야 합니다.

이 값은 반드시 애플리케이션 생태계 내에서 전역으로 고유해야 합니다. 그렇지 않으면 'EOS_Sessions_SessionAlreadyExists' 오류가 발생합니다.

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

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

프로퍼티

ApiVersion

EOS_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` 구조체와 함께 호출합니다.

프로퍼티

ApiVersion

EOS_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_UpdateSessionOptions 구조체로 `EOS_Sessions_UpdateSession`를 호출합니다.

프로퍼티

ApiVersion

EOS_SESSIONS_UPDATESESSION_API_LATEST

SessionModificationHandle

서버가 생성 또는 업데이트할 세션에 대한 핸들(EOS_HSessionModification)

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

EOS는 플레이 도중 세션 변경을 지원합니다. 종료되었지만 소멸하지 않은 세션도 업데이트를 받고 다시 시작할 수 있습니다. 이 행동의 일반적인 사용 사례는 한 맵이나 레벨에서 매치를 실행한 게임이 목록을 순환하며 다음 매치를 찾은 다음 새로 참여하거나 떠나는(심징어 매치 도중에도) 플레이어들과 함께 새 매치를 시작하는 것입니다.

커스텀 어트리뷰트

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

EOS_ESessionAttributeType

값 타입

EOS_AT_BOOLEAN

EOS_Bool

EOS_AT_INT64

int64_t

EOS_AT_DOUBLE

double

EOS_AT_STRING

const char* (널 종료 UTF8 스트링)

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

EOS_ESessionAttributeAdvertisementType

비저빌리티

EOS_SAAT_DontAdvertise

다른 사용자에게 보이지 않습니다.

EOS_SAAT_Advertise

다른 사용자에게 보입니다.

어트리뷰트 액세스

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

프로퍼티

ApiVersion

EOS_SESSIONDETAILS_GETSESSIONATTRIBUTECOUNT_API_LATEST

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

프로퍼티

ApiVersion

EOS_SESSIONDETAILS_COPYSESSIONATTRIBUTEBYINDEX_API_LATEST

AttrIndex

복사할 어트리뷰트의 인덱스

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

어트리뷰트 추가

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

프로퍼티

ApiVersion

EOS_SESSIONS_SESSIONATTRIBUTEDATA_API_LATEST

Key

어트리뷰트의 이름

Value

어트리뷰트의 값 또는 스트링인 경우 스트링에 대한 포인터

ValueType

Value`를 설명하는 EOS_ESessionAttributeType`

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

프로퍼티

ApiVersion

EOS_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` 구조체로 호출합니다.

프로퍼티

ApiVersion

EOS_SESSIONMODIFICATION_REMOVEATTRIBUTE_API_LATEST

Key

제거할 어트리뷰트의 이름(키)

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

세션에 플레이어 초대

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

프로퍼티

ApiVersion

EOS_SESSIONS_SENDINVITE_API_LATEST

SessionName

플레이어를 초대할 세션 이름

LocalUserId

초대장을 보내는 로컬 사용자

TargetUserId

초대되는 원격 사용자

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

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

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

초대 수락

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

프로퍼티

ApiVersion

EOS_SESSIONS_QUERYINVITES_API_LATEST

LocalUserId

초대를 요청하고 있는 로컬 사용자

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

프로퍼티

ApiVersion

EOS_SESSIONS_GETINVITECOUNT_API_LATEST

LocalUserId

캐시된 초대장을 가진 로컬 사용자

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

프로퍼티

ApiVersion

EOS_SESSIONS_GETINVITEIDBYINDEX_API_LATEST

LocalUserId

캐시된 초대장을 가진 로컬 사용자

Index

ID를 가져오려는 초대의 캐시 인덱스

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

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

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

초대 거부

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

프로퍼티

ApiVersion

EOS_SESSIONS_REJECTINVITE

LocalUserId

초대장을 거부하는 로컬 사용자

InviteId

초대 ID

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

원격 세션 검색

원격 세션을 찾으려면 검색을 구성하고 실행한 다음 결과를 검토해야 합니다.

검색 구성

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

프로퍼티

ApiVersion

EOS_SESSIONS_CREATESESSIONSEARCH_API_LATEST

MaxSearchResults

반환할 최대 검색 수

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

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

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

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

세션 ID 구성

특정 세션을 원하고 그 세션측 ID를 알면 검색 핸들과 다음과 같이 초기화된 EOS_SessionSearch_SetSessionIdOptions`로 EOS_SessionSearch_SetSessionId`를 호출합니다.

프로퍼티

ApiVersion

EOS_SESSIONSEARCH_SETSESSIONID_API_LATEST

SessionId

찾을 세션 ID

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

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

이렇게 환경설정하는 세션은 공개적으로 표시되므로, EOS 생태계 외부의 애플리케이션이 이를 발견할 수 있습니다. 이러한 애플리케이션은 세션 데이터를 사용하여 서버 또는 P2P 호스트의 IP 주소를 가져올 수 있으며, 손상을 일으키려 시도할 가능성이 있습니다.

사용자 ID 구성

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

프로퍼티

ApiVersion

EOS_SESSIONSEARCH_SETTARGETUSERID_API_LATEST

TargetUserId

세션 내에서 찾을 사용자 ID

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

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

공개적으로 표시되는 세션(EOS_OSPF_PublicAdvertised 또는 `EOS_OSPF_JoinViaPresence`로 환경설정된 세션)의 등록 사용자는 EOS 생태계 외부의 애플리케이션 등에 공개적으로 표시됩니다. 이러한 애플리케이션은 세션 데이터를 사용하여 서버 또는 P2P 호스트의 IP 주소를 발견할 수 있으며, 손상을 일으키려 시도할 가능성이 있습니다.

어트리뷰트 데이터 구성

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

프로퍼티

ApiVersion

EOS_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`를 호출합니다.

프로퍼티

ApiVersion

EOS_SESSIONSEARCH_FIND_API_LATEST

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

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

검색 결과 검토

특정 EOS_HSessionSearch 핸들에 대한 EOS_SessionSearch_GetSearchResultCount`와EOS_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`를 가지면 기존 세션에 참가할 수 있습니다.

프로퍼티

ApiVersion

EOS_SESSIONS_JOINSESSION_API_LATEST

SessionName

로컬 시스템이 세션에 사용할 고유 이름

SessionHandle

참가하고자 하는 세션에 대한 EOS_HSessionDetails 핸들

LocalUserId

세션에 참가하는 로컬 사용자

bPresenceEnabled

이 세션이 사용자의 현재상태 정보와 관련되는지 여부(보다 자세한 내용은 현재상태 인터페이스 참조)

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

플레이어 등록

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

프로퍼티

ApiVersion

EOS_SESSIONS_REGISTERPLAYERS_API_LATEST

SessionName

세션의 로컬 이름

PlayersToRegister

참가 플레이어에 대한 ID 배열

PlayersToRegisterCount

`PlayersToRegister`의 엘리먼트 수

작업이 완료되면 EOS_Sessions_OnRegisterPlayersCallback 타입 콜백 함수가 성공 또는 실패 여부를 나타내는 EOS_Sessions_RegisterPlayersCallbackInfo 파라미터로 실행됩니다. 호출이 성공하면 새로 등록된 플레이어는 다른 플레이어를 세션에 초대하는 능력 등 일부 세션 관리 기능에 액세스 권한을 얻습니다. EOS는 플레이어가 세션에 참가할 때 알림을 제공하지 않습니다. 참가 시 반드시 소유자에게 알리거나 소유자에게 플레이어의 성공적인 세션 참가를 탐지할 수단을 제공해야 합니다.

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

이 정보는 EOS 생태계 외부의 애플리케이션 등에 공개적으로 표시됩니다. 이러한 애플리케이션은 세션 데이터를 사용하여 서버 또는 P2P 호스트의 IP 주소를 발견할 수 있으며, 손상을 일으키려 시도할 가능성이 있습니다.

세션 나가기

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

플레이어 등록 해제

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

프로퍼티

ApiVersion

EOS_SESSIONS_UNREGISTERPLAYERS_API_LATEST

SessionName

세션의 로컬 이름

PlayersToUnregister

떠나는 플레이어에 대한 ID 배열

PlayersToUnregisterCount

`PlayersToUnregister`의 엘리먼트 수

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

플레이 시작 및 종료

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

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

프로퍼티

ApiVersion

EOS_SESSIONS_STARTSESSION_API_LATEST

SessionName

세션의 로컬 이름

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

프로퍼티

ApiVersion

EOS_SESSIONS_ENDSESSION_API_LATEST

SessionName

세션의 로컬 이름

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

세션 소멸

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

프로퍼티

ApiVersion

EOS_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

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

사용 제한

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

매치메이킹 보안 고려 사항

매치메이킹을 사용할 때의 보안 우려 사항과 모범 관행에 대한 정보는

[매치메이킹 보안](GameServices/Sessions/MatchmakingSecurity)
페이지를 참조하세요.