온라인 서비스 세션 인터페이스(Online Services Session Interface) 는 온라인 게임 세션의 생성, 관리 및 소멸을 처리합니다. 세션 은 플레이어의 머신이나 데디케이티드 서버에서 실행되는 게임의 온라인 매치를 나타냅니다. 세션에는 다음과 같은 참여 정책이 있을 수 있습니다.
- 초대 전용(Invite Only): 초대받은 플레이어만 세션에 참여할 수 있습니다.
- 친구 전용(Friends Only): 세션 멤버의 친구만 세션에 참여할 수 있습니다.
- 공개(Public): 누구나 세션을 찾고 참여할 수 있습니다.
플레이어가 특정 게임 모드나 맵을 검색할 수 있는 필터 역할을 하는 프로퍼티 세트를 사용하여 공개 세션을 정의할 수 있습니다.
API 개요
다음 테이블에서는 세션 인터페이스에 포함된 함수에 대한 개괄적인 설명을 확인할 수 있습니다.
| 함수 | 설명 |
|---|---|
| 세션 얻기 | |
GetAllSessions |
사용자가 속한 모든 세션에 대한 레퍼런스 배열을 얻습니다. |
GetSessionByName |
제공된 이름으로 세션에 대한 레퍼런스를 얻습니다. |
GetSessionById |
제공된 ID 핸들로 세션에 대한 레퍼런스를 얻습니다. |
| 현재상태 | |
GetPresenceSession |
사용자의 현재상태 세션으로 현재 설정된 세션에 대한 레퍼런스를 얻습니다. |
IsPresenceSession |
주어진 ID의 세션이 사용자의 현재상태 세션으로 설정되어 있는지 여부를 결정합니다. |
SetPresenceSession |
사용자의 현재상태 세션으로 주어진 ID의 세션을 설정합니다. |
ClearPresenceSession |
사용자 현재상태 세션을 지웁니다. |
| 세션 관리 | |
CreateSession |
제공된 파라미터를 사용하여 새 세션을 생성합니다. |
UpdateSessionSettings |
제공된 이름으로 식별되는 세션에 대한 세팅을 업데이트합니다. |
LeaveSession |
제공된 이름으로 식별되는 세션을 나가고 선택에 따라 세션을 소멸합니다. |
FindSessions |
제공된 파라미터와 일치하는 세션을 세션 서비스에 쿼리합니다. |
JoinSession |
제공된 세션 ID로 세션에 참여합니다. |
StartMatchmaking |
매치메이킹 프로세스를 시작합니다. 주어진 검색 필터와 일치하는 세션을 찾아 참여하며, 일치하는 세션이 없는 경우, 제공된 파라미터를 사용하여 세션을 생성합니다. |
AddSessionMember |
제공된 이름으로 식별되는 세션에 사용자를 새 세션 멤버로 추가합니다. |
RemoveSessionMember |
제공된 이름으로 식별되는 세션에서 사용자를 제거합니다. |
| 초대 | |
SendSessionInvite |
제공된 모든 사용자에게 제공된 이름으로 식별되는 세션에 대한 초대를 전송합니다. |
GetSessionInviteById |
제공된 초대 ID로 식별되는 세션 초대에 대한 레퍼런스를 얻습니다. |
GetAllSessionInvites |
사용자가 수신한 모든 세션 초대에 대한 레퍼런스 배열을 얻습니다. |
RejectSessionInvite |
제공된 초대 ID로 식별되는 세션 초대를 거부합니다. |
| 이벤트 리스닝 | 다음 함수의 결과로 이벤트가 트리거됩니다. |
OnSessionJoined |
세션 참여 시 |
OnSessionLeft |
세션 나가기 또는 세션 소멸 시 |
OnSessionUpdated |
세션 세팅 업데이트 시 또는 세션 업데이트 이벤트를 수신할 때마다 |
OnSessionInviteReceived |
세션 초대 수신 시 |
OnUISessionJoinRequested |
세션 초대 수락 시 또는 플랫폼 UI를 통해 세션 참여 시 |
프로세스 흐름
세션 라이프 사이클
- 원하는 세팅을 사용하여 새 세션을 생성합니다.
- 세션 수명 동안 언제든 세션이 나타내는 온라인 매치의 프로퍼티 변경사항을 반영하도록 세션을 업데이트할 수 있습니다. 이러한 변경사항에는 다음이 포함될 수 있습니다.
- 세션이 검색에 표시되는 방식 또는 표시 여부와 관련된 파라미터 변경
- 게임이 진행 상태가 된 후 새 플레이어의 세션 참여 제한
- 세션을 찾은 플레이어가 세션에 참여할 수 있습니다.
- 세션 참여로 획득한 정보를 사용하여 새 플레이어가 세션 호스트 또는 데디케이티드 서버에 연결할 수 있습니다.
- 연결한 다음에는 플레이어가 세션에 등록해야 합니다. 이 프로세스는 향후 릴리즈에서 엔진이 자동으로 처리합니다.
- 게임을 플레이합니다.
- 게임이 종료되면 플레이어가 세션을 나갈 수 있으며, 플레이어가 오너 또는 호스트인 경우에는 세션을 소멸할 수 있습니다.
- 호스트나 서버에서 연결을 해제한 다음에는 세션에서 플레이어 또는 플레이어들의 등록을 해제해야 합니다. 이 프로세스는 향후 릴리즈에서 엔진이 자동으로 처리합니다.
생성하기
세션 라이프 사이클의 첫 단계는 원하는 파라미터로 세션을 생성하는 것입니다. 이러한 파라미터에는 CreateSession 함수의 bIsLANSession 및 bAllowSanctionedPlayers 처럼 세션의 수명 동안 일정하게 유지되는 파라미터와 SessionSettings 함수에서 제공하는 옵션처럼 언제든지 업데이트할 수 있는 파라미터가 포함됩니다.
사용자당 최대 하나의 세션이 현재상태 세션(Presence Session) 으로 설정될 수 있습니다. 즉, 현재상태 인터페이스를 통해 노출된 대로 사용자의 현재상태 정보에 나타나고 친구나 팔로워에게 표시된다는 뜻입니다. 사용자가 많은 세션의 멤버라면, 현재상태 세션으로 표시되는 세션은 SetPresenceSession 으로 변경할 수 있는데, 일부 플랫폼 구현에서는 이 함수 기능을 사용할 수 없을 수도 있습니다.
찾기
사용자는 몇 가지 방식으로 새 세션을 찾을 수 있습니다.
검색
FindSessions 를 을 통해 사용자는 친구가 있는 세션을 찾기 위해 원하는 세션의 커스텀 세팅이나 특정 사용자 ID와 일치하는 태그 등의 검색 파라미터를 정의할 수 있습니다. 그러면 각각 캐시된 세션 정보를 나타내는 세션 ID 목록이 반환되며, 사용자는 GetSessionById 로 이 목록을 검색하고 액세스할 수 있습니다.
초대
사용자는 다른 사용자로부터 세션 초대를 받을 수 있습니다. 초대받은 사용자는 GetSessionInviteById 로 초대에 액세스하여 세션에 대한 정보를 확인할 수 있습니다. 그런 다음, 사용자는 초대 정보를 통해 제공된 세션 ID로 세션에 참여할지 결정합니다.
현재상태
특정 플랫폼 UI에서는 사용자에게 친구가 참여한 세션에 대한 정보를 보여줄 수도 있습니다.
참여하기
사용자가 검색, 초대 또는 현재상태를 통해 세션에 대한 정보를 획득한 다음에는 JoinSession 을 호출하여 참여를 시도할 수 있습니다. 또한, SetPresenceSession 을 사용하여 이 새로운 세션을 현재상태 세션으로 설정할지 여부도 선택할 수 있습니다.
매치메이킹
StartMatchmaking 을 호출하여 세션에 참여하는 방법도 있습니다. 이 함수는 CreateSession 과 FindSessions 함수가 조합된 역할을 합니다. StartMatchmaking 은 사전 정의된 검색 필터 세트와 일치하는 세션을 찾고, 일치하는 세션을 찾을 수 없으면 주어진 정보로 세션을 생성합니다.
세션에 참여한 후에는, 매치 참여에 필요한 플랫폼별 연결 정보를 반환하는 IOnlineServices::GetResolvedConnectString 을 호출할 수 있습니다. 그러면 이 함수로 획득한 스트링은 플레이어를 매치로 보내기 위해 APlayerController::ClientTravel 또는 UWorld::ServerTravel 로 전달됩니다. 이동이 성공하면 플레이어가 해당 세션에 추가되며 AddSessionMember 가 호출되어 플레이어가 세션에 등록됩니다.
초대
세션을 생성하거나 참여하여 세션에 참여한 다음에는 SendSessionInvite 를 통해 다른 플레이어에게 세션 정보를 전송할 수 있습니다. 이는 같은 온라인 매치에 친구들을 모으기에 좋은 방법입니다. 초대받은 플레이어는 GetAllSessionInvites 로 세션 정보에 액세스하여 주어진 사용자의 모든 초대에 액세스하거나 GetSessionInviteById 로 특정 초대에 대한 정보를 얻을 수 있습니다. 또한, 해당 초대 ID를 파라미터로 전달함으로써 RejectSessionInvite 를 호출하여 세션 초대를 거부할 수도 있습니다.
업데이트하기
세션 수명 동안 언제든지 UpdateSessionSettings 를 호출하여 세션 세팅을 업데이트할 수 있습니다. 다음과 같은 세팅을 포함한 다양한 세팅을 업데이트할 수 있습니다.
- 세션의 최대 플레이어 수
- 세션 참여 정책:
- 초대 전용
- 친구 전용
- 공개
- 새 플레이어 액세스 제한
- 커스텀 세팅 및 사용자 정의 파라미터 추가, 수정 또는 제거
나가기 및 소멸
LeaveSession 을 호출하여 세션을 나갈 수 있습니다. 세션의 오너가 세션을 나가면서 백엔드 서비스에서 해당 세션을 제거하고자 한다면, 추가 파라미터 bDestroySession 을 true 로 설정하면 됩니다. 이렇게 설정하면 세션의 다른 모든 멤버도 세션에서 강제로 나가게 됩니다.
예시
OnlineServices 인스턴스에 대한 레퍼런스를 통해 세션 인터페이스에 액세스할 수 있습니다. 여기서부터 세션 인터페이스 인터페이스의 함수 기능이 노출됩니다. 세션 인터페이스에 액세스하고 동기 및 비동기 작업을 수행하는 몇 가지 예시를 살펴볼 수 있습니다.
이름으로 세션 얻기
UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices();
UE::Online::ISessionsPtr SessionsInterface = OnlineServices->GetSessionsInterface();
UE::Online::FGetSessionByName::Params Params;
Params.SessionName = FName(TEXT("MySession"));
UE::Online::TOnlineResult<UE::Online::FGetSessionByName> Result = SessionsInterface->GetSessionByName(MoveTemp(Params));
if(Result.IsOk())
{
TSharedRef<const UE::Online::ISession> Session = Result.GetOkValue().Session;
// 이세 세션에서 정보를 읽을 수 있습니다.
}
연습
-
지정된 파라미터 없이
GetServices를 호출하여 기본 온라인 서비스를 사용합니다.UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices(); -
기본 온라인 서비스를 위한 세션 인터페이스에 액세스합니다.
UE::Online::ISessionsPtr SessionsInterface = OnlineServices->GetSessionsInterface(); -
GetSessionByName호출에 필요한 파라미터를 사용하여FGetSessionByName구조체를 초기화합니다.UE::Online::FGetSessionByName::Params Params; Params.SessionName = FName(TEXT("MySession")); -
이전 단계에서 파라미터를 전달하는
GetSessionByName을 호출하고 그 결과를 저장합니다.UE::Online::TOnlineResult<UE::Online::FGetSessionByName> Result = SessionsInterface->GetSessionByName(MoveTemp(Params)); -
함수 호출에서 오류가 발생하지 않았고 결과에 액세스할 수 있다는 사실을 확인한 후
GetSessionByName호출 결과를 처리합니다.if(Result.IsOk()) { TSharedRef<const UE::Online::ISession> Session = Result.GetOkValue().Session; // 이세 세션에서 정보를 읽을 수 있습니다. }
세션 세팅 업데이트하기
UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices();
UE::Online::ISessionsPtr SessionsInterface = OnlineServices->GetSessionsInterface();
UE::Online::FUpdateSessionSettings::Params Params;
Params.LocalAccountId = AccountId;
Params.SessionName = FName(TEXT("MySession"));
Params.Mutations.bAllowNewMembers = false;
SessionsInterface->UpdateSessionSettings(MoveTemp(Params))
.OnComplete([this](const UE::Online::TOnlineResult<UE::Online::FUpdateSessionSettings>& Result)
{
if (Result.IsError())
{
const UE::Online::FOnlineError OnlineError = Result.GetErrorValue();
// 업데이트 실패. OnlineError를 처리합니다.
return;
}
// 업데이트 성공
});
연습
-
지정된 파라미터 없이
GetServices를 호출하여 기본 온라인 서비스를 사용하고 기본 온라인 서비스를 위한 세션 인터페이스에 액세스합니다.UE::Online::IOnlineServicesPtr OnlineServices = UE::Online::GetServices(); UE::Online::ISessionsPtr SessionsInterface = OnlineServices->GetSessionsInterface(); -
UpdateSessionSettings호출에 필요한 파라미터를 사용하여 구조체를 초기화합니다.UE::Online::FUpdateSessionSettings::Params Params; Params.LocalAccountId = AccountId; Params.SessionName = FName(TEXT("MySession")); Params.Mutations.bAllowNewMembers = false; -
오류가 발생한 경우에는 오류 또는 쿼리된 통계를 처리하여, 람다 함수를 통해 오케이가 반환된 경우에는 그 결과를 처리하여
UpdateSessionSettings.OnComplete콜백을 처리합니다.SessionsInterface->UpdateSessionSettings(MoveTemp(Params)) .OnComplete([this](const UE::Online::TOnlineResult<UE::Online::FUpdateSessionSettings>& Result) { if (Result.IsError()) { const UE::Online::FOnlineError OnlineError = Result.GetErrorValue(); // 업데이트 실패. OnlineError를 처리합니다. return; } // 업데이트 성공 });
온라인 서브시스템에서 코드 변환하기
온라인 서비스 세션 인터페이스는 온라인 서브시스템 세션 인터페이스가 소유한 모든 코드를 담당합니다.
추가 정보
헤더 파일
필요에 따라 Sessions.h 헤더 파일에서 직접 추가 정보를 참조하세요. Sessions.h 세션 인터페이스 헤더 파일은 다음 디렉터리에 있습니다.
UNREAL_ENGINE_ROOT\Engine\Plugins\Online\OnlineServices\Source\OnlineServicesInterface\Public\Online
UE 소스 코드를 획득하는 방법에 대한 지침은 언리얼 엔진 소스 코드 내려받기 문서를 참조하세요.
함수 파라미터 및 반환 타입
파라미터 전달 방법 및 / 함수 반환 시 결과 처리 방법을 포함한 함수 파라미터 및 반환 타입에 대한 설명은 온라인 서비스 개요 페이지의 함수 섹션을 참조하세요.
