Sessions Interface

에픽 온라인 서비스(Epic Online Services, EOS) 에서 플레이어는 세션 인터페이스(Sessions Interface) 를 통해 온라인 게임 세션을 호스팅하고, 검색하고, 세션과 상호작용합니다. 세션은 게임 시작 전에 특정 플레이어 슬롯 수를 채운 다음 게임이 종료되면 해체될 정도로 짧을 수도 있고, 여러 맵 또는 레벨의 매치를 순환하는 게임을 지속해서 추적할 정도로 길 수도 있습니다. 세션 인터페이스는 백엔드 서비스 검색 및 매치메이킹 기능을 지원하는 게임 전용 데이터도 관리합니다. 매치메이킹을 위해 고려해야 하는 것에 대한 자세한 내용은 매치메이킹 보안 고려 사항 섹션을 참고하세요. 이 문서는 세션 인터페이스에 대한 정의와 헤더에 대해 설명합니다. 전체 목록은 세션 인터페이스 API 레퍼런스 문서를 참조하세요.

세션 인터페이스에 액세스하려면 플랫폼 인터페이스 함수인 EOS_Platform_GetSessionsInterface 를 통해 EOS_HSessions 핸들을 얻어야 합니다. 모든 세션 인터페이스 함수는 첫 파라미터로 이 핸들을 요청합니다. EOS_HPlatform 핸들이 콜백에 티킹하여 요청이 완료됐을 때 트리거하는지 확인해야 합니다. 티킹에 대한 자세한 내용은 C# EOS SDK 문서를 참조하세요.

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

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

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

이 함수 역시 로컬로 실행되며 성공 시 세션의 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 를 호출합니다.

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

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

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

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

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

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

활성 세션에서 가져올 수 있는 플레이어 데이터는 다음과 같습니다.

• 등록된 총 플레이어 수
• 등록된 플레이어의 제품 사용자 ID(PUID)

EOS_ActiveSession_GetRegisteredPlayerCount 을 호출하면 활성 세션에 연결된 등록된 총 플레이어 수를 가져올 수 있습니다. 다음 정보가 포함된 ActiveSessionGetRegisteredPlayerCountOptions 로 EOS_ActiveSession_GetRegisteredPlayerCount 를 호출합니다.

등록된 플레이어를 통해 활성 세션을 반복하여 등록된 플레이어 각각의 제품 사용자 ID(PUID)를 가져올 수 있습니다. 다음 정보가 포함된 ActiveSessionGetRegisteredPlayerByIndexOptions 로 EOS_ActiveSession_GetRegisteredPlayerByIndex 를 호출합니다.

성공 시 활성 세션에 지정된 인덱스에 플레이어의 제품 사용자 ID(PUID)가 반환됩니다.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

특정 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 를 가지면 기존 세션에 참가할 수 있습니다.

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

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

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

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

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

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

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

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

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

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

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

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

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

소멸 작업이 완료되면 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_GAME_ACCESS 제재가 적용된 경우 해당 플레이어는 안티 치트의 보호를 받는 게임의 멀티플레이어 세션에서 자동으로 추방됩니다. 자세한 내용은 안티 치트를 참고하세요.

EOS_Sessions_JoinSession 함수는 RESTRICT_MATCHMAKING 제재가 적용된 플레이어의 참가를 허용하지 않으며, 참가 시도가 있는 경우 EOS_Sessions_PlayerSanctioned 오류를 반환합니다. 하지만 EOS_Sessions_RegisterPlayers 함수는 다수의 플레이어를 지원하며, EOS_Sessions_JoinSession 과 달리 제재당한 플레이어 한 명 이상이 제재가 활성화된 세션에 등록을 시도해도 오류를 반환하지 않습니다. 대신 모든 플레이어가 등록되도록 응답 오브젝트를 확인해야 합니다. 세션에 제재가 활성화된 경우, 등록하지 못한 모든 제재받은 플레이어는 EOS_Sessions_RegisterPlayersCallbackInfo 결과 구조체의 SanctionedPlayers 멤버 목록에 나열됩니다. 자세한 내용은 플레이어 등록 섹션을 참고하세요.

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

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

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

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

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

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

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

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

3. EOS_SessionModification_AddAttribute 를 사용하여 세션에 추가된 모든 커스텀 어트리뷰트입니다. 이 어트리뷰트는 개발자에 의해 설정됩니다.

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

참고: 호스트 IP 주소가 노출되는 것에 대해 염려하신 다면 EOS_SessionModification_SetHostAddress 를 사용하여 P2P 인터페이스를 사용할 때 P2P 소켓 ID와 같은 다른 정보로 호스트 주소를 설정할 수 있습니다.

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

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

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

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

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

Q: 방금 생성한 서버를 찾을 수 없는 이유는 무엇인가요?
A: 인덱싱을 새로고침하는 데 2초가 걸리기 때문에 즉시 서버를 찾지 못할 수도 있습니다.

Q: 동료나 친구와 동일한 서버 목록을 볼 수 없는 이유는 무엇인가요?
A: 매치메이킹에는 두 명의 사용자가 동시에 동일한 서버 목록을 가져오지 못하도록 2초의 지연시간이 설정되어 있습니다. 이 고의적인 지터링은 서버의 효율성에 영향을 미칠 수 있는 경쟁 조건을 방지합니다.

Q: 내 게임에 설정된 세션을 확인하고 싶습니다. 내 게임의 모든 세션을 어떻게 볼 수 있나요?
A: 개발자 포털에서 게임의 세션 목록을 찾을 수 있습니다. 개발자 포털(dev.epicgames.com/portal)에 로그인하고 왼쪽 사이드바의 제품 섹션에서 제품을 선택하고 게임 서비스(Game Services) > MULTIPLE > 매치메이킹(Matchmaking) 으로 이동하세요.