EOS 오버레이는 에픽게임즈 런처를 통해 설치됩니다. 또한 게임 애플리케이션은 EOS 서비스 재배포 가능 인스톨러를 사용하여 EOS 오버레이를 필수 구성 요소의 일부로 설치할 수도 있습니다.

Direct3D를 초기화하기 전에 EOS SDK를 초기화하고 EOS_Platform_Create 를 호출하는 것이 중요합니다. 그래야 EOS 오버레이가 사용자에게 제공되는 각 게임 프레임에 맞게 오버레이를 렌더링하는 데 필요한 그래픽 API 후크를 설치할 수 있습니다.

오버레이 기능을 완전히 비활성화하는 것이 바람직한 경우도 있습니다. 예를 들어 개발자가 에디터에서 게임을 실행하고 에디터의 그래픽 API를 후킹했더니 문제가 발생하는 경우가 이에 해당합니다. EOS_Platform_Create 로 전달되는 EOS_Platform_Options 는 64개 플래그를 위한 공간이 있는 비트 필드인 플래그 멤버를 수용하도록 확장되었습니다. 현재 오버레이를 비활성화하는 플래그는 3개가 있습니다.

1. EOS_PF_LOADING_IN_EDITOR - 이 플래그는 UE4의 에디터에서 플레이(Play in Editor, PIE) 또는 Unity 등의 게임 에디터에서 EOS SDK를 사용할 때마다 설정해야 합니다.
2. EOS_PF_DISABLE_OVERLAY - 이 플래그는 오버레이 기능을 명시적으로 비활성화하고자 할 때마다 설정해야 합니다. Ecom 인터페이스의 구매 관련 기능에서는 오류가 발생합니다.
3. EOS_PF_DISABLE_SOCIAL_OVERLAY - 이 플래그는 오버레이 기능의 소셜 기능만 명시적으로 비활성화하고자 할 때마다 설정해야 합니다.

소셜 오버레이(Social Overlay) 는 인게임에서 액세스할 수 있는 에픽 온라인 서비스(Epic Online Services, EOS) UI입니다. 디폴트 통합에서는 Shift+F3 을 사용하여 소셜 오버레이에 액세스합니다. 소셜 오버레이의 주요 기능으로는 게임 관리 및 플레이어 현재상태 를 제공하는 친구 목록 이 있습니다. 게임 관리는 플레이어가 게임 세션에 친구를 초대하거나 이미 게임 세션에 참가 중인 친구들과 함께할 수 있도록 합니다. 플레이어 현재상태는 온라인 상태, 활성 게임, 게임에서 정의된 모든 서식 있는 현재상태 텍스트에 대한 세부사항을 제공합니다.

소셜 오버레이나 체크아웃, 인증 등 EOS SDK에서 관리하는 오버레이가 표시된 동안 오버레이에서 모든 키보드와 마우스 입력을 사용할 가능성도 있습니다. 오버레이는 사용자의 의도에 맞춰서만 표시되어야 합니다. 사용자는 이러한 의도에 따라 게임이 아닌 오버레이와 상호작용하기를 원합니다. 이에 따라 게임은 키보드나 마우스 입력을 받지 못하게 됩니다.

Win32 API 함수 ShowCursor 와 같이 이러한 상황에서 행동을 변경하는 시스템 SDK 사용자 입력 메서드가 몇 가지 있습니다. 이를 지원하고 일반적인 사용자 상태 정보를 제공하기 위해 게임에서 EOS_UI_AddNotifyDisplaySettingsUpdated 를 사용하여 콜백을 등록할 수 있습니다. 콜백 데이터에는 표시(Visible) 플래그와 전용 입력(Exclusive Input) 플래그가 모두 포함됩니다. 콜백은 언제나 다음 EOS_Platform_Tick 호출에서 실행되어 모든 오버레이의 현재상태를 게임에 알립니다.

브라우저 인스턴스가 여러 개면 표시 플래그에 동시에 영향을 줄 수 있습니다. 예를 들면, 구매 중에 소셜 토스트를 받을 수 있습니다. 이보다 더 중요한 사용 사례는 표시된 브라우저 인스턴스가 사용자 상호작용을 원하는 경우입니다. 이때는 전용 입력 플래그 값이 true가 됩니다. 브라우저 인스턴스도 표시되어 있어야 전용 입력 플래그에 영향을 줄 수 있습니다.

소셜 오버레이의 텍스트를 현지화하는 데 사용되는 로케일 코드는 두 가지 소스 중 하나에서 나옵니다. 소스는 플레이어가 에픽 계정 생성 시 선택한 언어 또는 게임에서 제공한 오버라이드 값일 수 있습니다. 게임에서 오버라이드 값을 사용하면, 사용자가 에픽 계정 내에서 선택한 언어와 관계없이 이 값을 사용합니다. 이는 EOS_Platform_SetOverrideLocaleCode 를 사용하여 수행할 수 있습니다.

현재상태 서비스(Presence Service) 는 온라인 상태인 사용자 친구 모두에게 공유되고 변경 시 업데이트되는 현재상태(Presence State) 를 유지합니다. 플레이어의 로그인 상태는 온라인 상태(Online State) 를 개시하고 제거하는 데 사용됩니다. EOS_Initialize 에 제공되는 ProductName 은 플레이 중인 게임을 파악하는 데 사용됩니다. 서비스는 EOS_PresenceModification_SetRawRichText 에 제공된 RichText 도 공유합니다.

플레이어의 온라인 상태는 플레이어가 EOS_Auth_Login 및 EOS_Auth_Logout 을 사용하여 EOS 서비스에 접속하거나 서비스에서 접속을 해제할 때 온라인(Online) 또는 오프라인(Offline) 으로 설정됩니다. EOS_PresenceModification_SetStatus API는 보다 구체적인 상태를 제공할 때 사용합니다. 플레이어 친구의 상태는 소셜 오버레이의 친구 페이지에 표시됩니다.

상태 패널 내에 표시되는 앱 이름은 EOS_Initialize 에 제공한 ProductName 에서 바로 공유됩니다. 이는 호스트의 언어 설정(Language Settings) 에 정의된 제품 이름입니다.

서식 있는 현재상태 텍스트(Rich Presence Text) 는 다른 플레이어에게 게임 컨텍스트를 제공합니다. EOS_PresenceModification_SetRawRichText 에 제공된 스트링이 그대로 공유됩니다. 이는 친구 페이지 내에 친구 상태의 일부로 표시됩니다.

게임 관리 인터페이스에는 참가(Join) 버튼과 초대(Invite) 버튼이 있습니다. 두 버튼이 구체적으로 통합되는 방식은 게임에 따라, 또한 세션 서비스 또는 로비 서비스를 사용하는 방식에 따라 다릅니다. 또한 게임에서는 연결 API를 사용하여 플레이어의 계정을 세션 서비스에 연결해야 합니다.

플레이어는 참가(Join) 버튼을 사용하여 친구의 게임에 참가할 수 있습니다. SDK 통합은 어떤 게임 관리 서비스를 사용 중인지에 따라 다릅니다. 원격 플레이어 현재상태에 로비 ID(Lobby ID), 세션 ID(Session ID), 참가 정보 문자열(Join Info String) 중 하나가 포함되면 버튼이 활성화됩니다. 이 데이터는 현재상태 서비스를 사용하는 모든 친구에게 전송됩니다. 사용자가 참가 버튼을 누르는 경우 세 식별자 모두 이와 관련된 콜백이 있습니다. 게임은 현재상태가 클린업될 때마다 사용자의 의도에 맞춰 콜백을 최대한 수행해야 합니다.

로비 ID는 로비 서비스를 사용할 때 자동으로 전송됩니다. 그러면 게임은 플레이어가 참가 버튼을 누르는 시점을 파악하기 위해 EOS_Lobby_AddNotifyJoinLobbyAccepted 를 사용합니다. 클린업될 때마다 게임에서는 EOS_Lobby_CopyLobbyDetailsHandleByUiEventId 를 통해 관련 로비를 얻고 해당 로비에 참가하기 위해 제공된 UiEventId 를 사용해야 합니다. 참가에 실패하면 게임에서는 EOS_UI_AcknowledgeEventId 를 호출하여 소셜 오버레이가 그 상태를 새로고침하게 만듭니다.

세션 ID는 세션 매치메이킹 서비스(Sessions Matchmaking Service)를 사용할 때 자동으로 전송됩니다. 그러면 게임에서는 플레이어가 참가 버튼을 누르는 시점을 파악하기 위해 EOS_Sessions_AddNotifyJoinSessionAccepted 를 사용합니다. 클린업될 때마다 게임에서는 EOS_Session_CopySessionHandleByUiEventId 를 통해 관련 세션을 얻고 해당 세션에 참가하기 위해 제공된 UiEventId 를 사용해야 합니다. 참가에 실패하면, 게임에서는 EOS_UI_AcknowledgeEventId 를 호출하여 소셜 오버레이가 그 상태를 새로고침하게 만듭니다.

플레이어를 위해 수동으로 참가 정보 스트링 을 설정하려면 EOS_PresenceModification_SetJoinInfo 를 사용합니다. 개발자는 참가 정보 스트링 의 의미를 원하는 대로 정의할 수 있습니다.

그러면 게임은 플레이어가 참가 버튼을 누르는 시점을 파악하기 위해 EOS_Presence_AddNotifyJoinGameAccepted 를 사용합니다. 콜백 데이터에는 참가 정보 스트링이 포함됩니다.

플레이어는 초대(Invite) 버튼을 사용하여 친구를 게임에 초대할 수 있습니다. SDK 통합은 어떤 게임 관리 서비스를 사용 중인지에 따라 다릅니다. 각 게임 관리 서비스마다 연관된 알림 콜백이 있습니다. 참가 에서와 마찬가지로 게임은 사용자의 의도에 최대한으로 맞춰야 합니다. 에픽게임즈 런처의 초대 기능을 실행하려면 디플로이를 아티팩트에 매핑해야 합니다.

에픽 매치메이킹을 사용하지 않는 타이틀의 경우 커스텀 초대 인터페이스 를 사용하여 임의의 페이로드와 함께 초대를 송수신할 수 있습니다. 초대 버튼을 클릭하면, 소셜 오버레이에서 EOS_CustomInvites_SendCustomInvite 를 사용하여 커스텀 초대를 전송합니다. EOS_CustomInvites_AddNotifyCustomInviteReceived 및 EOS_CustomInvites_RemoveNotifyCustomInviteReceived 를 사용하면 탐지, 커스텀 UI 표시 및 커스텀 초대 처리가 가능합니다.

초대 버튼을 클릭하면 소셜 오버레이에서 사용자와 게임을 대신하여 EOS_Lobby_SendInvite 를 사용하여 로비 서비스를 통해 초대를 전송합니다. 게임은 EOS_Lobby_AddNotifyLobbyInviteAccepted 를 사용하여 플레이어가 오버레이에서 수락(Accept)을 클릭하는 시점을 파악합니다. 콜백 데이터에 포함되는 초대 ID는 로비 인터페이스 내에서 게임에 대한 정보를 찾는 데 사용할 수 있습니다.

초대 버튼을 클릭하면 사용자와 게임을 대신하여 소셜 오버레이가 세션 인터페이스에서 EOS_Sessions_SendInvite 를 사용하여 초대를 전송합니다. 게임은 플레이어가 오버레이에서 수락(Accept)을 클릭하는 시점을 파악하기 위해 EOS_Sessions_AddNotifySessionInviteAccepted 를 사용합니다. 콜백 데이터에 포함되는 세션 ID는 세션 인터페이스 내에서 게임에 대한 정보를 찾는 데 사용할 수 있습니다.

초대의 수명은 초대를 보낸 플레이어가 아니라 해당 로비 또는 세션에 따라 달라집니다. 따라서 플레이어가 로비나 세션을 떠나고 한참이 지난 뒤에 친구를 그 로비나 세션에 참가하도록 초대하는 것도 가능합니다. 초대는 백엔드 서비스에서만 소멸되며, 수신하는 게임 클라이언트에서는 소멸되지 않습니다. 초대가 사용되거나 초대하는 로비나 세션이 소멸되면 초대가 소멸됩니다.

초대가 너무 오래 사용되지 않으면 원래 초대하려던 로비 또는 세션은 소멸된 뒤일 수 있습니다. 그 경우 초대는 만료됩니다. 게임 클라이언트가 만료된 초대에 액세스하려 하면, 초대를 사용하려 할 때 호출이 실패합니다. 초대가 만료되었을 때 플레이어에게는 다음과 같은 오류가 표시될 수 있습니다.

• 초대를 찾을 수 없습니다.
• 게임이 다 찼습니다.
• 세션이 더 이상 존재하지 않습니다.

SDK에서 인식하는 오류는 소셜 오버레이로 즉시 버블링됩니다. 하지만 수신하는 게임 클라이언트는 발생하는 모든 오류 및 경쟁 조건을 처리해야 합니다. 이 처리는 수신하는 게임 클라이언트의 플레이어가 초대를 수락한 이후에 행해야 합니다. 예를 들어 게임에서 플레이어에게 더 이상 해당 초대를 통해 세션을 사용할 수 없다고 알릴 수 있습니다. 그러면 게임은 성공 여부와 무관하게 초대가 처리되었다고 소셜 오버레이에 알려야 합니다. 그렇게 하려면 게임에서 EOS_UI_AcknowledgeEventId() 를 호출해야 합니다. 게임은 이 API 호출에 모든 오류 코드를 포함해야 합니다.

현재 세션이 다 찼을 때는 초대 버튼을 사용할 수 없으며, 초대받은 플레이어가 초대받은 세션에 이미 참가해 있다면 초대 버튼은 비활성화됩니다. 세션 변경을 통해 세션의 '초대 허용' 상태를 바꿔서 초대 상태를 오버라이드할 수도 있습니다. 세션의 모든 클라이언트는 (Un)RegisterPlayer API 호출을 통해 세션 상태를 유지해야 합니다.

플레이어는 소셜 오버레이를 사용하여 에픽 친구 및 네이티브 플랫폼 친구와 끊김 없이 소통할 수 있습니다. 소셜 오버레이에 네이티브 플랫폼 친구를 표시하려면 게임이 EOS SDK 초기화 과정에서 통합 플랫폼 옵션을 제공해야 합니다. 통합에 관해 자세히 알아보려면 플랫폼 인터페이스 문서를 참고하세요.

소셜 오버레이는 업적 유저 인터페이스를 제공합니다. 이 인터페이스를 사용하려면 데브 포털에서 적절하게 데이터를 설정해야 합니다.

업적 현지화는 이 문서의 앞부분과 소셜 오버레이 개요 섹션에서 간단히 설명한 대로 나머지 소셜 오버레이와 같은 규칙을 따릅니다.

업적이 숨겨진 업적으로 표시된 경우 잠긴 아이콘이 사용되지만, 표시되는 텍스트는 소셜 오버레이 페이지에서 제공합니다. 데브 포털 내에서 아이콘이 제공되지 않았다면 소셜 오버레이 페이지에서 디폴트 아이콘을 제공합니다.

Q: EOS SDK의 동적 라이브러리 바이너리를 어디에 배치해야 할까요?

EOS SDK의 모든 동적 라이브러리 바이너리를 동일한 디렉터리에 배치해야 합니다. EOS SDK는 이러한 바이너리를 자동으로 로드합니다. PlayStation에 대한 안내는 PlayStation 4용 EOS SDK 및 PlayStation 5용 EOS SDK 문서를 참고하세요.

Q: 통합 중에 EOS SDK의 어떤 로깅 레벨을 사용하는 것이 좋을까요?

초기 통합 단계에서는 EOS SDK의 상세한 세부 정보를 캐치하기 위해 Verbose 로깅 레벨을 사용하는 것이 좋습니다. 문제를 보고할 때는 전체 로그 파일을 포함하세요.

Q: EOS 오버레이가 열려 있는 동안 게임 입력을 어떻게 처리해야 하나요?

게임은 컨트롤러 입력 이벤트를 EOS_UI_ReportInputState API를 통해 EOS SDK로 전달합니다. 게임은 오버레이가 표시될 때 EOS SDK가 입력을 독점적으로 처리하도록 해야 합니다. 이렇게 하면 컨트롤러 입력이 오버레이와 게임의 자체 메뉴 간에 동시에 이동하는 것을 방지할 수 있습니다. 게임은 아날로그 스틱 이동을 해당하는 D-Pad 위/아래/왼쪽/오른쪽 버튼으로 변환해야 합니다. 버튼 상태는 연합으로 결정되어야 합니다. 아래의 예제 코드 스니펫을 참조하세요.

Q: SubmitGraphicsCommands 콜백을 통해 반환된 명령 버퍼 데이터가 GPU에 의해 완전히 처리될 때까지 GPU는 재처리되지 않은 데이터를 계속해서 처리하나요?

네, SubmitGraphicsCommands 콜백을 통해 반환된 명령 버퍼에 대해 수명 보증이 있습니다. 명령 버퍼는 GPU가 처리할 때까지 남아 있습니다. SDK는 동기화 기본 요소를 명령 버퍼에 삽입하고 그 수명을 내부적으로 관리합니다. 유일한 함정은 EOS_UI_PrePresent 를 계속 호출하고 동기화 기본 요소를 GPU에 전송하지 않는 경우입니다. 이렇게 하면 언젠가는 프로세스에서 버퍼가 부족해질 수 있습니다.