UI 인터페이스

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

2022년 10월 이전에 에픽 계정 서비스가 통합된 콘솔용 게임을 출시할 계획이라면 eas-on-console-beta@epicgames.com으로 연락하여 출시 계획을 조율하세요.

에픽 온라인 서비스 (EOS)는

[오버레이](EpicGamesStore/TechFeaturesConfig/EOSOverlay)
시스템을 통해 제품에 구애받지 않는 오버레이 창을 지원합니다. 사용자는 이 오버레이 창에서 제품에 구애받지 않고 다양한 기능에 액세스할 수 있습니다. 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 를 호출합니다.

Property

Value

int32_t ApiVersion

API Version: Set this to EOS_UI_SHOWFRIENDS_API_LATEST.

EOS_EpicAccountId LocalUserId

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

Property

Value

int32_t ApiVersion

API Version: Set this to EOS_UI_HIDEFRIENDS_API_LATEST.

EOS_EpicAccountId LocalUserId

The Epic Online Services Account ID of the user whose friend list is being shown.

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

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

비저빌리티 상태 감지

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

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

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

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

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

Property

Value

int32_t ApiVersion

API Version: Set this to EOS_UI_ADDNOTIFYDISPLAYSETTINGSUPDATED_API_LATEST.

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

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

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

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

Property

Value

int32_t ApiVersion

API Version: Set this to EOS_UI_GETFRIENDSVISIBLE_API_LATEST.

EOS_EpicAccountId LocalUserId

The Epic Online Services Account ID of the user whose overlay is being updated.

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

단축키 가져오기 및 설정

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

단축키를 정의하려면 메인 키와 하나 이상의 모디파이어 키를 선택해야 합니다. 메인 키로 사용할 수 있는 키로는 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 파라미터를 다음과 같이 구성합니다.

Property

Value

int32_t ApiVersion

API Version: Set this to EOS_UI_GETTOGGLEFRIENDSKEY_API_LATEST.

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

Property

Value

int32_t ApiVersion

API Version: Set this to EOS_UI_SETTOGGLEFRIENDSKEY_API_LATEST.

EOS_UI_EKeyCombination KeyCombination

The 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.