UI Interface

오버레이 기능에 액세스하는 인터페이스

6 분 소요

에픽 온라인 서비스 (EOS)는 오버레이 시스템을 통해 제품에 구애받지 않는 오버레이 창을 지원합니다. 사용자는 이 오버레이 창에서 제품에 구애받지 않고 다양한 기능에 액세스할 수 있습니다. UI 인터페이스(UI Interface) 는 상태 정보를 업데이트하고, 오버레이를 표시하거나 숨기며, 디스플레이 및 단축키 설정을 변경하는 방식으로 오버레이와의 상호작용을 관리하는 데 사용됩니다.

SDK 1.5부터 모든 사용자 정보 호출에 국가 코드는 더 이상 사용되지 않습니다.

UI 인터페이스에 액세스하려면 플랫폼 인터페이스 함수인 EOS_Platform_GetUIInterface 를 통해 EOS_HUI 핸들을 획득해야 합니다. 모든 UI 인터페이스 함수는 첫 파라미터로 이 핸들을 요청합니다. EOS_HPlatform 핸들이 콜백에 티킹하여 작업이 완료됐을 때 트리거하는지 확인해야 합니다.

각 오버레이는 제품과 무관하게 작동하며 다른 모든 EOS 제품과 균등한 방식으로 작동합니다. UI 인터페이스는 오버레이를 직접 제어하지 않으며, 오버레이의 데이터를 읽거나 오버레이에 데이터를 쓰지 못합니다. 그러나 UI 인터페이스는 명령을 통해 오버레이를 표시하거나 숨기고, 해당 오버레이가 표시되어 있는지 감지하며, 오버레이를 표시하거나 숨기는 사용자 단축키를 얻거나 설정할 수 있습니다.

UI 인터페이스는 아직 완성되지 않은 상태이며, 현재로서는 더 큰 소셜 오버레이에 속하는 친구 목록 페이지만 지원합니다. 향후의 EOS SDK 버전에서는 여러 오버레이에 대한 지원 범위가 다른 페이지까지 확장될 예정입니다.

오버레이 표시 또는 숨기기

친구 목록 페이지를 표시하려면 다음과 같이 초기화된 EOS_UI_ShowFriendsOptions 데이터 구조로 EOS_UI_ShowFriends 를 호출합니다.

PropertyValue
int32_t ApiVersionAPI Version: Set this to EOS_UI_SHOWFRIENDS_API_LATEST.
EOS_EpicAccountId LocalUserIdThe Epic Online Services Account ID of the user whose friend list is being shown.

이 작업이 완료된 즉시 EOS_UI_OnShowFriendsCallback 타입 콜백 함수는 EOS_UI_ShowFriendsCallbackInfo 데이터 구조가 포함된 호출을 수신합니다.

친구 목록 페이지를 숨기려면 다음 정보가 포함된 EOS_UI_HideFriendsOptions 구조로 EOS_UI_HideFriends 를 호출합니다.

PropertyValue
int32_t ApiVersionAPI Version: Set this to EOS_UI_HIDEFRIENDS_API_LATEST.
EOS_EpicAccountId LocalUserIdThe Epic Online Services Account ID of the user whose friend list is being shown.

이 작업이 완료되면 EOS는 EOS_UI_OnHideFriendsCallback 타입 콜백 함수를 실행하여 EOS_UI_HideFriendsCallbackInfo 타입의 파라미터를 콜백 함수에 전달합니다.

이러한 작업으로 오버레이 시스템의 전체적인 비저빌리티 상태를 변경할 수 있지만, 매번 변경할 필요는 없습니다. 예를 들어 친구 목록 페이지를 표시하면 숨김 상태인 오버레이 시스템이 표시되지만, 오버레이 시스템에서 이미 친구 목록 페이지나 다른 페이지가 표시되었다면 오버레이 시스템도 이미 표시된 상태이므로 비저빌리티 상태를 변경할 필요가 없습니다. 마찬가지로, 마지막으로 표시된 페이지를 숨기는 경우 전체 오버레이 시스템이 숨겨지지만, 항상 그런 것은 아닙니다. 오버레이 시스템이 일정한 시점에 표시되는지 여부를 확실하게 알 수 있는 방법은 오버레이의 현재 비저빌리티 상태 감지 섹션을 참조하세요.

차단 및 신고

EOS_UI_ShowBlockPlayerEOS_UI_ShowReportPlayer 는 게임이 신고 또는 차단을 선택하는 대화 상자를 오버레이로 표시하도록 트리거합니다. 플레이어는 대화 상자를 사용하여 타깃 플레이어를 신고 또는 차단하기로 확정하거나, 신고 또는 차단 조치를 취소할 수 있습니다.

EOS_UI_ShowReportPlayer 를 사용할 때는 소셜 기능을 불러와서 사용하는 것이고, 이 기능은 게임의 일부가 아니라는 내용을 인게임에서 플레이어에게 확실히 전달하세요. 예를 들면 다음과 같습니다. RTCP 음성 채팅방에서 멤버가 사용할 수 있는 '신고' 버튼입니다.

EOS_UI_ShowBlockPlayerOptions 파라미터를 다음과 같이 구성합니다.

프로퍼티
int32_t ApiVersionAPI 버전: EOS_UI_SHOWBLOCKPLAYER_API_LATEST로 설정하세요.
EOS_EpicAccountId LocalUserId다른 플레이어의 차단을 요청하는 플레이어의 에픽 온라인 서비스 계정 ID입니다.
EOS_EpicAccountId TargetUserId차단될 플레이어의 에픽 온라인 서비스 계정 ID입니다.

EOS_UI_ShowReportPlayerOptions 파라미터를 다음과 같이 구성합니다.

프로퍼티
int32_t ApiVersionAPI 버전: EOS_UI_SHOWREPORTPLAYER_API_LATEST로 설정하세요.
EOS_EpicAccountId LocalUserId신고를 요청하는 플레이어의 에픽 온라인 서비스 계정 ID입니다.
EOS_EpicAccountId TargetUserId신고된 플레이어의 에픽 온라인 서비스 계정 ID입니다.

비저빌리티 상태 감지

UI 인터페이스는 두 가지 레벨의 비저빌리티 상태 정보를 제공합니다.

첫 번째는 오버레이 시스템 자체의 상태 정보입니다. 하나의 오버레이에 하나 이상의 페이지가 표시되면 오버레이 시스템이 보이는 것으로 간주됩니다. 이 정보는 입력의 라우팅 위치나 시뮬레이션 일시정지 시기 같은 특정한 고수준의 결정을 내릴 때 매우 유용할 수 있습니다.

두 번째는 개별 페이지의 상태 정보입니다. 이 정보는 코드가 페이지를 열거나 닫는 명령을 내려야 하는 시기나 플레이어에게 필요한 정보가 보이는지 여부를 파악하는 데 유용합니다.

오버레이 시스템 비저빌리티 상태

EOS SDK에서는 개발자가 오버레이 시스템의 전반적인 비저빌리티 상태 보고용 콜백 함수를 등록할 수 있습니다. EOS_UI_OnDisplaySettingsUpdatedCallback 타입 콜백 함수를 등록하려면 EOS SDK를 로드할 때 EOS_UI_AddNotifyDisplaySettingsUpdated 를 호출하고 올바르게 초기화된 EOS_UI_AddNotifyDisplaySettingsUpdatedOptions 데이터 구조로 전달합니다.

PropertyValue
int32_t ApiVersionAPI Version: Set this to EOS_UI_ADDNOTIFYDISPLAYSETTINGSUPDATED_API_LATEST.

콜백 함수는 플랫폼 인터페이스의 현재 틱 또는 다음 틱 시점에 실행됩니다. 이 콜백 과정에서 수신한 값을 트래킹하면 언제든 오버레이 시스템의 최신 비저빌리티 상태를 알 수 있습니다.

종료 단계에서 원래 콜백 함수를 등록할 때 EOS_UI_AddNotifyDisplaySettingsUpdated 가 반환했던 EOS_UI_RemoveNotifyDisplaySettingsUpdatedEOS_NotificationId 로 콜백을 제거합니다.

개별 페이지 비저빌리티 상태

UI 인터페이스가 표시하거나 숨길 수 있는 각 페이지에는 비저빌리티 상태를 보고하는 자체 함수가 있습니다. 친구 목록 페이지의 경우 다음과 같이 초기화된 EOS_UI_GetFriendsVisibleOptionsEOS_UI_GetFriendsVisible 을 호출합니다.

PropertyValue
int32_t ApiVersionAPI Version: Set this to EOS_UI_GETFRIENDSVISIBLE_API_LATEST.
EOS_EpicAccountId LocalUserIdThe Epic Online Services Account ID of the user whose overlay is being updated.

EOS_UI_GetFriendsVisible 는 이 페이지의 비저빌리티 상태를 나타내는 EOS_Bool 을 반환합니다.

소셜 오버레이 일시정지

도착하는 소셜 오버레이 프로세스 알림입니다. 이 행동을 일시정지하려면 EOS_UI_PauseSocialOverlay 를 사용하세요. 컷신 또는 로딩 중에 유용합니다. EOS_UI_IsSocialOverlayPaused 를 사용하면 이전에 설정한 일시정지 스테이트를 얻을 수 있습니다.

EOS_UI_PauseSocialOverlayOptions 파라미터를 다음과 같이 구성합니다.

프로퍼티
int32_t ApiVersionAPI 버전: EOS_UI_PAUSESOCIALOVERLAY_API_LATEST 로 설정하세요.
EOS_Bool bIsPaused오버레이의 원하는 bIsPaused 스테이트입니다.

단축키 구하기 및 설정

사용자는 단축키를 사용하여 오버레이 페이지를 표시하거나 숨길 수 있습니다. 단축키는 토글 방식으로 작동하므로 페이지를 표시하는 데 사용되는 단축키로 페이지를 숨길 수도 있습니다.

단축키를 정의하려면 메인 키와 하나 이상의 모디파이어 키를 선택해야 합니다. 메인 키로 사용할 수 있는 키로는 F1 ~F12 , Space , Backspace , Escape , 그리고 Tab 이 있습니다. 모디파이어 키로 사용할 수 있는 키로는 Shift , Control , Alt 등이 있습니다.

단축키를 기술하는 데는 EOS_UI_EKeyCombination 을 사용할 수 있습니다. 다음 샘플 코드에 보이는 것처럼 OR 비트 연산으로 키 조합을 빌드하고 EOS_UI_IsValidKeyCombination 을 사용하여 단축키로 허용되는 키 조합인지 검증할 수 있습니다.

// ProposedHotKey를 Alt-Shift-Tab으로 설정합니다.
EOS_UI_EKeyCombination ProposedHotKey = EOS_UI_EKeyCombination::EOS_UIK_Alt | EOS_UI_EKeyCombination::EOS_UIK_Shift | EOS_UI_EKeyCombination::EOS_UIK_Tab;
// ProposedHotKey가 허용되는지 UI 인터페이스에 묻습니다.
if (EOS_UI_IsValidKeyCombination(ProposedHotKey) == EOS_TRUE)
{
// ProposedHotKey가 유효한 키 조합입니다.
}

UI 인터페이스는 해당 페이지에 적용되는 현재 단축키를 확인하거나, 현재 단축키를 새로운 값으로 변경하거나 또는 EOS_UI_EKeyCombination::EOS_UIK_None 을 사용하여 단축키를 시스템 디폴트값으로 리셋할 수 있는 함수를 지원합니다.

친구 목록 페이지의 현재 단축키를 얻으려면 EOS_UI_GetToggleFriendsKey 를 호출합니다. EOS_UI_GetToggleFriendsKeyOptions 파라미터를 다음과 같이 구성합니다.

PropertyValue
int32_t ApiVersionAPI Version: Set this to EOS_UI_GETTOGGLEFRIENDSKEY_API_LATEST.

친구 목록 페이지의 단축키를 설정 또는 리셋하려면 다음과 같이 초기화된 EOS_UI_SetToggleFriendsKeyOptions 와 함께 EOS_UI_SetToggleFriendsKeyOptions 를 사용합니다.

PropertyValue
int32_t ApiVersionAPI Version: Set this to EOS_UI_SETTOGGLEFRIENDSKEY_API_LATEST.
EOS_UI_EKeyCombination KeyCombinationThe new key combination which will be used to toggle the friends overlay. The combination can be any set of modifiers and one key. A value of EOS_UIK_None will cause the key to revert to the default.