EOS SDK in C#

에픽 온라인 서비스(Epic Online Services, EOS)는 C SDK뿐 아니라 C# SDK도 지원합니다. 이 문서에서는 C# SDK를 사용하여 프로젝트와 EOS를 통합하는 방법을 알아보고 두 SDK 간의 구현 차이점을 살펴봅니다. 어떤 SDK를 사용하든 핵심 기능은 동일하지만 C# SDK는 다음과 같은 부분에서 다르게 디자인되어 있습니다.

• C# SDK는 C# 모범 사례를 준수하며 오브젝트 지향 접근법을 따릅니다. 오브젝트 지향 접근법에는 C 스타일 핸들이 아닌 핸들 오브젝트를 사용하여 비동기 작업을 관리하는 것이 포함됩니다.
• 명명 규칙이 일반적인 C# 패턴과 일치합니다. 예를 들어 C SDK의 EOS_Auth_Login 은 C# SDK에서 Epic.OnlineServices.Auth.AuthInterface.Login 으로 액세스 가능합니다.
• C SDK의 데이터 구조체는 호환성을 위해 매크로 기반 API 버전 번호가 필요합니다. 이 값은 C# SDK에 미리 채워져 있습니다.

C#에서 EOS SDK를 이용하려면 다음 개발 환경이 설치되어 있어야 합니다.

• .NET Framework 3.5 이상(또는 API가 호환되는 동급 프레임워크)

  참고: 예전 버전도 작동할 수도 있지만 테스트되지는 않음

C#에서 EOS SDK 샘플을 이용하려면 다음이 필요합니다.

• .NET Core 3.1
• Visual Studio 2019 이상

개발 환경 요구 사항에 대한 자세한 내용은 시스템 요구 사항 페이지를 참고하세요.

아래 지침을 따르기 전에 에픽게임즈 계정 설정 및 EOS SDK 작업에 대한 지침을 보려면 EOS 시작하기 문서를 참조하세요.

c#으로 시작하는 방법에 대한 설명은 EOS 웹사이트의 에픽 온라인 서비스 소개 dev.epicgames.com/news/ 페이지에서도 확인할 수 있습니다.

1. 프로젝트에 C# SDK 소스 파일을 포함합니다.

• (Unity 사용자) 이 파일(Core 폴더 및 Generated 폴더 포함)을 Assets 폴더에 넣습니다.

2. 타깃 플랫폼에 알맞은 라이브러리 바이너리 파일이 애플리케이션에서 액세스 가능하도록 합니다.

• (Unity 사용자) 알맞은 라이브러리 바이너리 파일을 타깃 플랫폼의 Assets 폴더로 복사합니다.
• 예를 들어 Windows x64 통합은 EOSSDK-Win64-Shipping.dll 을 사용합니다.

3. C# SDK는 Epic.OnlineServices.Config 에서 타기팅할 라이브러리 바이너리 이름을 결정합니다. 몇 가지 플랫폼은 편의상 사전 구성되어 올바른 이름을 가리킵니다.

• 타깃 플랫폼이 사전 구성되지 않은 경우 환경설정과 프로젝트 심볼을 적절하게 변경하여 빌드 오류를 방지하세요. 예를 들어 Windows x64를 타기팅하는 경우 EOS_PLATFORM_WINDOWS_64 를, Windows x86을 타기팅하는 경우 EOS_PLATFORM_WINDOWS_32 를 설정해야 합니다.

4. (Unity 사용자) SDK를 제어할 새 스크립트를 생성합니다. 아래 예시에서는 EOSSDKComponent 를 이름으로 사용합니다.

5. (Unity 사용자) 필요시 컴포넌트를 생성하려면 컴포넌트 추가(Add Component) 를 선택하여 엔티티에 할당합니다. 여기서는 시연을 위해 메인 카메라(Main Camera) 에 컴포넌트를 추가했습니다.

6. 이 컴포넌트에 EOS SDK 코드를 작성합니다. 다양한 예시를 보려면 샘플 코드를 참조하세요.

제품을 구성하고 C# SDK를 통합했다면 코드를 작성할 수 있습니다. SDK를 초기화하고 Tick 메서드를 정기적으로 호출하여 SDK 실행 및 콜백 실행이 가능한지 확인해야 하며, 애플리케이션이 끝나면 종료해야 합니다.

SDK의 라이프 사이클에는 세 가지 주요 부분이 있습니다. 초기화, 티킹(일반 작업), 종료입니다.

플랫폼 인터페이스는 SDK의 엔트리 포인트이며 EOS를 사용하려면 이 인터페이스의 인스턴스가 필요합니다. 인스턴스를 생성하려면 Epic.OnlineServices.Platform.PlatformInterface.Initialize 를 애플리케이션에 대한 기본 정보와 함께 호출한 다음 Epic.OnlineServices.Platform.PlatformInterface.Create 를 개발자 포털에서 제공된 값과 함께 호출하여 Epic.OnlineServices.Platform.PlatformInterface 인스턴스를 얻으면 됩니다. 이 인스턴스는 SDK와 상호작용하는 데 필요하므로 저장해 둡니다. 예를 들어 인증을 수행하려면 우선 Epic.OnlineServices.Auth.AuthInterface 의 인스턴스가 필요하며, 이 인스턴스는 Epic.OnlineServices.Platform.PlatformInterface 인스턴스에서 GetAuthInterface()를 호출하여 얻을 수 있습니다.

SDK를 작동하려면 플랫폼 인터페이스 인스턴스에서 정기적으로 Epic.OnlineServices.Platform.PlatformInterface.Tick 을 호출해야 합니다. 이 호출을 프레임마다 수행할 필요는 없지만 꽤 자주 수행해야 합니다. 보통 100밀리초마다 한 번 호출하는 것이 적절하지만, 정확한 빈도는 필요에 따라 조정할 수 있습니다. SDK 콜백은 Tick 을 호출할 때만 실행될 수 있으므로 모든 비동기 작업이 Tick에 의존합니다.

SDK가 필요 없어지는 경우(일반적으로 애플리케이션 종료 시) Epic.OnlineServices.Platform.PlatformInterface.Release 를 호출하여 플랫폼 인터페이스 인스턴스를 해제한 다음 Epic.OnlineServices.Platform.PlatformInterface.Shutdown 을 호출하여 종료 프로세스를 완료하면 SDK를 종료할 수 있습니다. 이 프로세스는 최종적입니다. 즉, Epic.OnlineServices.Platform.PlatformInterface.Release 는 SDK를 최종 상태로 전환하며, 이 시점부터는 다른 플랫폼 인터페이스 핸들을 획득하거나 해당 SDK를 재초기화할 수 없습니다. 그러므로 애플리케이션 종료 전까지는 EOS SDK를 종료하지 않는 것이 좋습니다.

대부분의 콜백 데이터 구조체 및 일부 반환 값은 Epic.OnlineServices.Result 를 사용하여 SDK 작업의 결과를 전달합니다. Epic.OnlineServices.Result를 사용하여 오류를 처리하고 작업이 예상대로 수행되는지 확인하세요.

SDK는 내부 인터페이스를 통해 유용한 디버깅 정보를 출력합니다. 이 기능을 활성화하려면 Epic.OnlineServices.Logging.LoggingInterface 를 최대한 빨리(가능하면 SDK 초기화 직후) 구성합니다. 그렇게 하려면 Epic.OnlineServices.Logging.LoggingInterface.SetLogLevel 을 필요한 레벨 오브 디테일을 나타내는 파라미터와 함께 호출한 다음 Epic.OnlineServices.Logging.LoggingInterface.SetCallback 을 로그 정보를 수신할 콜백 함수와 함께 호출합니다. 이 기능은 내부 작업에 대한 인사이트를 제공하여 예상치 못한 행동의 원인을 파악하는 데 도움을 줄 수 있습니다.

C SDK에서 EOS_Leaderboards_CopyLeaderboardDefinitionByIndex 같은 일부 API는 수동으로 해제되어야 하는 데이터 구조체를 전달합니다. C# SDK에서는 구조체가 래퍼의 마샬링 코드를 통해 자동으로 처리되므로 이런 구조체를 직접 해제할 필요가 없습니다.

C SDK에서 EOS_Presence_CreatePresenceModification 같은 일부 API는 SDK 라이브러리 소유의 메모리에 데이터를 설정할 수 있는 핸들을 전달합니다. 이 핸들은 수동으로 해제해야 합니다. C# SDK에서 이 핸들은 기반 유형이 Epic.OnlineServices.Handle 인 오브젝트로 나타나며, 비관리 데이터를 설정할 수 있는 함수를 포함합니다. 또한 이 핸들은 완료 시 수동으로 호출해야 하는 Release 함수도 포함합니다.

콘솔 같은 일부 플랫폼에 포함된 SDK의 경우 자체적인 allocate, reallocate, release 함수를 구현해야 합니다. SDK는 이런 함수를 굉장히 자주 호출합니다. 따라서 SDK가 관리 코드에서 델리게이트를 통해 라우팅되지 않고 직접 함수에 액세스 가능해야 높은 퍼포먼스를 얻을 수 있습니다.

플랫폼을 Epic.OnlineServices.Platform.InitializeOptions 로 초기화할 때는 SDK로 이런 함수를 전달할지 선택할 수 있습니다. 다음을 수행하는 것이 좋습니다.

1. 네이티브 라이브러리를 생성하고 3개의 메모리 함수를 구현합니다.
2. 3개의 메모리 함수 각각 메모리 함수의 포인터를 반환하는 익스포트 함수를 구현합니다.
3. C#으로 플랫폼을 초기화하기 전에 익스포트 함수를 호출한 다음 반환된 IntPtr 값을 옵션 구조체에 설정합니다.

다음 샘플 코드는 네이티브 라이브러리의 구조체 예시를 보여줍니다.

다음 샘플 코드는 C# 바인딩 예시를 보여줍니다.

SDK는 현재 스레드 세이프 방식이 아닙니다. 모든 SDK 호출은 애플리케이션의 메인 스레드에서 오는 것이 좋습니다. 현재는 async , await , Thread , Task 또는 기타 유사한 패턴을 사용하지 않는 것이 좋습니다.

애플리케이션에서 EOS 오버레이를 사용하려면 그래픽 디바이스가 생성되기 전에 다음을 완료하세요.

1. SDK 라이브러리를 메모리로 로드합니다.
2. EOS_Initialize로 초기화합니다.
3. EOS_Platform_Create로 플랫폼을 생성합니다.

Unity에서 이를 수행하는 한 가지 방법은 로우 레벨 네이티브 렌더링 플러그인을 생성하는 것입니다. 최소한 다음을 수행해야 합니다.

1. 이름 앞에 GfxPlugin 이 있는 네이티브 라이브러리를 생성합니다.
2. SDK 라이브러리를 로드하는 UnityPluginLoad(void*) 라는 이름의 익스포트 함수를 추가하고 EOS_Initialize 및 EOS_Platform_Create를 성공적으로 호출합니다.
3. 생성된 플랫폼 인터페이스 핸들을 필요시 C#으로 다시 반환할 익스포트 함수를 추가합니다. 이 함수는 새로운 Epic.OnlineServices.Platform.PlatformInterface 인스턴스를 생성하는 데 사용될 수 있습니다.

독립형 빌드가 저레벨 네이티브 렌더링 플러그인 내에서 SDK 수명을 제어하고, 에디터 빌드가 플러그인을 제외하여 다이내믹 바인딩이 있는 MonoBehaviour 내에서 SDK 수명을 제어하는 것이 Unity 사용자에게 가장 바람직합니다.

일반적으로 C# SDK는 extern DllImport 바인딩을 사용합니다. 그러나 다이내믹 바인딩을 사용해야 할 수도 있습니다.

다이내믹 바인딩을 사용하려면 다음을 수행합니다.

1. EOS_DYNAMIC_BINDINGS 를 정의합니다.
2. SDK 라이브러리를 동적으로 로드하고 라이브러리 핸들을 얻습니다.
3. 애플리케이션 세션이 시작되면 Epic.OnlineServices.Bindings.Hook 를 호출하여 라이브러리 핸들 및 함수 포인터 로더 델리게이트를 전달합니다.
4. 애플리케이션 세션이 끝나면 Epic.OnlineServices.Bindings.Unhook 를 호출하고 라이브러리를 해제하여 정리합니다.

예를 들어 Windows에서는 다음과 같은 extern 함수가 정의되어 있을 수도 있습니다.

그런 다음 SDK를 사용하기 위해 라이브러리를 로드하고 다음 코드를 통해 다이내믹 바인딩을 연결합니다.

애플리케이션이 종료되면 다음 코드를 통해 다이내믹 바인딩 연결을 끊고 라이브러리를 해제합니다.

1.12 기준으로 C# SDK의 디폴트 행동은 Unity 에디터 같은 에디터 환경에 다이내믹 바인딩을 요구하는 것입니다. 다이내믹 바인딩을 요구하는 것은 SDK 라이브러리를 온디맨드로 로드하고 언로드할 수 있도록 하고 에디터에서 게임이 실행될 때마다 SDK를 초기화할 수 있도록 하기 위해서입니다. Unity에서 다이내믹 바인딩을 사용하기 위한 보다 자세한 샘플 코드는 아래에 제시되어 있습니다.

인증, 현재상태, 구매 흐름, 보이스 같은 여러 가지 에픽 온라인 서비스(Epic Online Services, EOS) 기능 구현을 보여주는 C# SDK 샘플이 다양하게 준비되어 있습니다. 또한 플랫폼 구성, 로그인, Unity EOS SDK 컴포넌트 구현을 위한 샘플 코드도 있습니다.

이 섹션의 샘플 코드는 시연 목적으로 제공되었으며 C# SDK에 익숙해지는 데 도움이 됩니다.

참고: 아래 코드는 SDK 1.15 이상을 필요로 합니다.

샘플 프로젝트는 다음 라이브러리 및 애플리케이션이 포함된 C# SDK 다운로드 폴더 안에 있습니다.

일반(Common) 은 SDK 코드 및 기타 유용한 공유 기능을 포함합니다.

WPF 일반(WpfCommon) 은 모든 WPF 샘플에 공통되는 기능을 포함합니다.

보이스 일반(VoiceCommon) 은 모든 보이스 샘플에 공통되는 기능을 포함합니다.

간단 인증은 로그인된 사용자를 위해 인증 및 현재상태 관련 함수를 수행하는 방법을 보여주는 WPF 애플리케이션입니다.

간단 오버레이 구매는 인게임 오버레이를 활용하여 구매 흐름을 개시하고 완료하는 방법을 보여주는 관리형 DirectX11 애플리케이션입니다.

보이스 서버는 RESTful API 서비스를 구현하는 방법을 보여주는 애플리케이션입니다. 여기서 RESTful API 서비스는 보이스 클라이언트와 EOS 사이에서 신뢰할 수 있는 보이스 서버 역할을 하는 서비스입니다.

보이스 클라이언트는 보이스 룸 연결, 오디오 디바이스 전환, 오디오 전송, 클라이언트 음소거, 서버 음소거, 추방 등의 작업을 수행하는 방법을 보여주는 WPF 애플리케이션입니다.

샘플을 실행하려면 다음을 설치해야 합니다.

• .NET Core 3.1
• Visual Studio 2019 이상 버전

또한 Samples/CSharp/Common/Settings.cs 에서 애플리케이션과 연결된 다음 값을 설정해야 합니다.

• ProductId
• SandboxId
• DeploymentId
• ClientId
• ClientSecret

LoginType 을 설정할 수도 있습니다. ID(Id) 필드와 토큰(Token) 필드는 로그인 유형에 따라 다르게 사용됩니다. 자세한 정보는 Auth.Credentials 및 인증 인터페이스를 참조하세요.

시연된 SDK 함수 기능은 지원되는 모든 ID 제공자와 함께 사용자 인증을 위해 사용할 수 있습니다.

간단 인증(SimpleAuth) 은 로그인된 사용자를 위해 인증 및 현재상태 관련 함수를 수행하는 방법을 보여주는 샘플 애플리케이션입니다.

처음에는 로그인 화면이 표시되면서 사용할 로그인 유형을 선택할 수 있습니다. 개발자 유형을 사용하여 개발자 인증 툴에서 할당한 크리덴셜로 로그인하는 것이 좋습니다.

로그인하면 현재상태를 표시하는 페이지와 현재상태를 변경할 수 있는 양식이 나타납니다. 이 양식에는 온라인 상태, 리치 텍스트, 그리고 현재상태와 연결된 데이터 엔트리를 입력할 수 있는 필드가 포함되어 있습니다.

간단 오버레이 구매 기능은 에픽게임즈 스토어 제품에서만 사용 가능합니다. 또한 이 기능을 사용하려면 스토어 파트너여야 하며 스토어에 구성한 제품이 있어야 합니다.

오버레이가 작동하려면 다음 중 하나를 수행한 상태여야 합니다.

• 에픽게임즈 런처를 설치하고 최초로 실행합니다.
• EOSOVH DLL 파일을 다운로드하고 레지스트리 키 HKEY_CURRENT_USER\Software\Epic Games\EOS\OverlayPath 를 DLL이 있는 디렉터리로 설정합니다.

이 샘플은 자동으로 로그인하고 필수 ecom 함수를 수행하여 구매 흐름에 오버레이를 실행합니다. 출력되는 내용을 잘 보고 문제가 없는지 확인하세요.