SDK Integration

게임 안에서 EOS 소셜 오버레이 및 친구 목록에 액세스합니다.

9 분 소요

개요

설치

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

SDK 초기화

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

Windows에서 EOS 오버레이는 실험단계로 Direct3D9, Direct3D10, OpenGL을 지원합니다. 실험단계 기능을 사용하도록 허용하려면 EOS_Platform_Create 를 호출하기 전에 EOS_Platform_OptionsFlags 필드를 적절한 값으로 초기화합니다.

  • Direct3D9 - EOS_PF_WINDOWS_ENABLE_OVERLAY_D3D9
  • Direct3D10 - EOS_PF_WINDOWS_ENABLE_OVERLAY_D3D10
  • OpenGL - EOS_PF_WINDOWS_ENABLE_OVERLAY_OPENGL

오버레이 기능을 완전히 비활성화하는 것이 바람직한 경우도 있습니다. 예를 들어 개발자가 에디터에서 게임을 실행하고 에디터의 그래픽 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 - 이 플래그는 오버레이 기능의 소셜 기능만 명시적으로 비활성화하고자 할 때마다 설정해야 합니다.

호환되는 렌더링 API 및 운영 체제

Windows

가용성API
Available Now* Direct3D 12 * Direct3D 11 * Vulkan
Experimental* Direct3D 10 * Direct3D 9 * OpenGL

macOS

가용성API
Coming Soon* Metal * Vulkan * OpenGL

Linux

가용성API
조만간 지원* Vulkan * OpenGL

소셜 오버레이

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

활성 게임

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

서식 있는 현재상태 텍스트

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

친구 목록에서 게임 관리 사용하기

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

소셜 오버레이 사용 시, 다음과 같은 두 가지 방식으로 구현할 수 있습니다.

  • bPResenceEnabled = true 와 함께 로비 또는 세션 인터페이스 사용
    • 이러한 기능을 사용할 수 있으며 EOS에서 초대 및 참가의 정확성을 유지합니다.
  • 로비 또는 세션 인터페이스를 사용하지 않고 SetJoinInfo 사용
    • 게임의 참가 허용 여부에 따라 해당 값을 설정하거나 비워 두는 것은 개발자 여러분의 몫입니다.

참가 버튼

플레이어는 참가 버튼을 사용하여 친구의 게임에 참가할 수 있습니다. 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 를 사용합니다. 콜백 데이터에는 참가 정보 스트링이 포함됩니다.

초대 버튼

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

커스텀 초대

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

로비 사용하기

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

세션 매치메이킹 사용하기

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

세션 매치메이킹 주의 사항

초대 버튼은 현재 세션이 가득 찼을 경우 사용할 수 없으며 두 사용자가 같은 세션에 있으면 비활성화됩니다. (Un)RegisterPlayer API 호출을 통해 세션 상태를 유지하는 것은 게임에 달려 있습니다. 세션 변경을 통해 세션의 '초대 허용' 상태를 바꿔서 초대 상태를 오버라이드할 수도 있습니다.

오버레이는 레이스 조건을 처리하지 않습니다. 초대를 수락하면 사용자가 성공적으로 세션에 참가할 가능성이 높지만 반드시 성공적인 참가를 보장하는 것은 아닙니다. 자리가 하나뿐일 때 두 클라이언트가 동시에 초대를 수락하는 등의 경우 게임은 다른 메커니즘을 통해 클라이언트의 호스트 참가 활동을 실행하거나 조정해야 합니다.

초대의 수명(Lifetime) 은 초대를 보낸 사용자가 아니라 해당 세션에 따라 달라집니다. 사용자가 세션을 떠나고 한참이 지난 뒤에 친구를 해당 세션으로 초대하는 것도 가능합니다. 초대가 결부된 세션이 끝나면 초대는 소멸됩니다. 초대의 상태는 소셜 오버레이에 반영되지 않으며, 호출이 실패할 수도 있습니다. 오버레이에서는 발생하는 오류를 모두 메시지 박스에 표시합니다.

네이티브 플랫폼 친구

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

업적 지원

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

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

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