언리얼 엔진의 EOS SDK 업그레이드하기 | 언리얼 엔진 5.3 문서

개요

에픽 온라인 서비스(Epic Online Services, EOS) 소프트웨어 개발 키트(Software Development Kit, SDK) 는 게임 내에서 EOS에 액세스할 수 있게 해 주는 툴세트입니다. 다음 플러그인들을 포함한 다수의 언리얼 엔진(UE) 플러그인 작동이 EOS SDK에 의존합니다.

온라인 서브시스템 EOS 플러그인(OSS EOS)
온라인 서비스 EOS 플러그인(OSSv2 EOS)
EOS 음성 채팅 플러그인

이 페이지는 다음 내용을 설명합니다.

에픽 온라인 서비스에 대한 자세한 정보는 이 페이지의 추가 리소스 섹션을 참조하세요.

EOS SDK의 위치

EOS SDK 모듈은 다음 디렉터리에 있습니다.

UNREAL_ENGINE_ROOT/Engine/Source/ThirdParty/EOSSDK

이 EOS SDK 모듈을 종속성으로 추가함으로써 플러그인과 모듈은 EOS SDK에 종속됩니다.

EOS SDK 모듈과 관련된 모듈

특정 플랫폼용 EOS SDK를 비롯하여, 이 모듈의 특정 플랫폼용 익스텐션 몇 가지가 다음 디렉터리에 존재합니다.

UNREAL_ENGINE_ROOT/Engine/Platforms/<PLATFORM>/Source/ThirdParty/EOSSDK

EOS 공유 플러그인은 일반적인 EOS 기능을 노출하며, EOS SDK 런타임 라이브러리 초기화 및 셧다운을 담당합니다. EOS 공유 플러그인은 다음 디렉터리에 있습니다.

UNREAL_ENGINE_ROOT/Engine/Plugins/Online/EOSShared

EOS SDK 업그레이드

EOS SDK를 업그레이드하는 메서드는 3가지입니다.

메서드	설명
라이브러리 및 헤더 전체 업그레이드	최신 SDK 버전에서 새로운 API와 수정된 버그의 이점을 누리고 싶은 경우 선택할 수 있는 메서드입니다.
라이브러리 한정 업그레이드	최신 SDK 버전에서 수정된 버그의 이점을 누리고 싶지만, 새로운 API는 원하지 않는 경우 선택할 수 있는 메서드입니다.
프로젝트 오버라이드 업그레이드	엔진 모듈을 컴파일한 버전이 아닌 다른 버전의 EOS SDK로 프로젝트 모듈을 컴파일하고 싶은 경우 선택할 수 있는 메서드입니다.

라이브러리 및 헤더 전체 업그레이드

라이브러리 및 헤더 파일을 포함하여 SDK 전체를 업그레이드하는 메서드입니다. 새로운 헤더에 대해 엔진과 플러그인을 리빌드할 수 있으므로, 최신 SDK 출시 버전에서 사용 가능한 새 API와 버그 수정을 활용할 수 있습니다.

단계

EOS SDK의 전체 업그레이드 방법은 다음과 같습니다.

EOS 개발자 포털에서 원하는 EOS SDK 버전을 다운로드합니다.
Engine/Source/ThirdParty/EOSSDK/ 디렉터리에서 다음을 수행합니다.
- 이 디렉터리에 있는 EOSSDK.Build.cs 또는 다른 패킹되지 않은 파일을 삭제하지 마세요.
- Engine/Source/ThirdParty/EOSSDK/ 의 모든 서브 디렉터리를 삭제합니다.
새로운 SDK용 .zip 파일을 Engine/Source/ThirdParty/EOSSDK/ 에 압축 해제합니다. 이렇게 하면 Engine/Source/ThirdParty/EOSSDK/SDK 위치에 이름이 SDK 인 폴더가 생성됩니다.
추가적인 플랫폼 특정 SDK가 있으면 1~3단계를 반복합니다.
- Android 및 iOS: .zip 파일을 베이스 SDK보다 상위인 Engine/Source/ThirdParty/EOSSDK/ 에 압축 해제합니다.
- 기타 플랫폼: .zip 파일을 해당하는 Engine/Platforms/<PLATFORM>/Source/ThirdParty/EOSSDK/ 디렉터리의 각 플랫폼 익스텐션으로 압축 해제합니다.
Engine/Source/ThirdParty/EOSSDK/SDK/Bin/libEOSSDK-Mac-Shipping.dylib 파일을 Engine/Binaries/ThirdParty/EOSSDK/Mac/libEOSSDK-Mac-Shipping.dylib 위치로 옮깁니다.

EOS SDK 업데이트에는 브레이킹 체인지(호환성에 영향을 미칠 수 있는 큰 변경)나 필수 코드 변경이 포함될 수 있습니다. 필요한 코드 변경에 대한 자세한 정보는 EOS SDK 출시 노트를 참조고하세요.

EOS 엔진 플러그인의 API 버전

다수의 EOS 엔진 플러그인이 API_LATEST 를 사용하기보다는 EOS 옵션 구조체의 특정 API 버전을 세팅하는 방향으로 이주했습니다.

레거시 비헤이비어

EOS 엔진 플러그인은 EOS 옵션 구조체의 버전 번호로 API_LATEST 를 사용했었습니다. 따라서 전체 업그레이드 메서드를 사용하여 EOS SDK를 업그레이드하고 엔진 플러그인을 리빌드할 경우 SDK가 브레이킹 체인지를 일으키는 경우가 있었습니다. 이러한 브레이킹 체인지는 EOS SDK는 새 API 버전에서 정의된 비헤이비어 계약을 사용하는 반면, EOS SDK를 사용하는 엔진 플러그인은 플러그인이 원래 컴파일될 때 사용했던 헤더의 기존 API 버전에서 정의된 계약을 예상했기 때문에 발생하는 문제였습니다. 당시에는 모든 엔진 플러그인이 새 계약을 사용하도록 업데이트하는 것이 사용자의 책임이었습니다.

현재 비헤이비어

이제 API_LATEST 대신 플러그인 작성에 사용된 헤더에서 지정한 API 버전이 사용됩니다. 전체 업그레이드를 수행할 때 엔진 코드가 기존 헤더의 API 버전을 계속 사용한다는 뜻입니다. 그 결과 EOS SDK가 플러그인이 작성될 때 사용된 계약을 계속해서 이행하며, 엔진 플러그인이 라이브러리 한정 업그레이드를 진행할 때와 마찬가지로 작동합니다.

이렇게 하는 목적은 EOS를 사용하는 엔진 플러그인에서 SDK 업그레이드로 인한 브레이킹 체인지가 덜 유발되도록 하기 위해서입니다. 때때로 SDK가 옵션 구조체에서 필드 이름을 변경하거나 모두 제거하기도 합니다. SDK가 필드 이름을 변경하거나 제거하는 경우 새로운 헤더로 컴파일하면 실패할 수도 있습니다. 컴파일이 실패하면 기존 정의를 계속해서 사용할 수 있도록 기존 헤더에서 옵션 구조체 정의를 복사하여 코드에 붙여 넣어야 합니다.

예시

EOS SDK가 프로그램의 네트워크 상태를 세팅할 용도의 API를 추가했다고 가정해 보겠습니다. 새 SDK의 기본 상태는 '오프라인(Offline)'으로, 이는 이전 기본 상태인 '온라인(Online)'에서 변경된 브레이킹 체인지입니다. 엔진 플러그인이 API_LATEST 를 통과하기 때문에 엔진 플러그인을 새 SDK로 리빌드하면 SDK는 '오프라인'이 됩니다.

UE는 이 새로운 API를 지원하지 않으므로 네트워크 상태를 '온라인'으로 설정할 수 있는 방법이 없습니다. SDK는 '오프라인' 상태로 남으며, 작동하지 않게 됩니다.

만약 기존 API 버전(코드 작성에 사용된 헤더의 API_LATEST 의 값)이 통과되었다면, SDK는 호출자가 네트워크 상태 API가 추가되기 이전의 헤더를 사용하여 작성되었다는 사실을 파악하고 DLL 한정 업그레이드가 수행된 것처럼 계속 작동했을 것입니다.

API 버전 경고

원래 EOS 플러그인의 일반적인 패턴은 EOS 옵션 구조체를 사용한 부분 옆에 static_asserts 를 추가하는 것이었습니다. 이러한 어설트는 옵션 구조체의 API_LATEST 값이 변경되면 발동했으며, 변경 사항이 발생했다는 알림과 조치를 취하라는 메시지를 표시했습니다.

그러나 어설트 사용은 EOS SDK 전체(라이브러리 및 헤더) 업그레이드를 진행할 경우, API 버전 범프가 발생하면 컴파일이 실패할 수 있다는 뜻이기도 했습니다. 따라서 이 문제를 해결하기 위해 static_asserts 를 컴파일 시간에 경고를 표시하는 지원 중단 메커니즘으로 대체하였습니다.

경고 비활성화

API 버전 경고를 비활성화하려면 DefaultEngine.ini 와 같은 엔진 환경설정 파일에 다음 섹션을 추가합니다.

[EOSShared]
bEnableApiVersionWarnings=false;

라이브러리 한정 업그레이드

이 메서드는 라이브러리 파일만 업그레이드하고 헤더 파일은 업그레이드하지 않습니다. 라이브러리 한정 업그레이드를 진행하면 버그가 수정된 최신 SDK 출시 버전을 사용하거나, 다른 플랫폼 SDK 버전에 대해 빌드된 버전으로 SDK를 교체할 수 있습니다. 이 메서드는 헤더를 변경하지 않기 때문에 엔진이나 플러그인을 리빌드할 필요가 없습니다. SDK는 작성 기준 SDK 버전(헤더의 SDK 버전)과 동일하게 계속 작동합니다.

단계

EOS SDK의 라이브러리 한정 업그레이드 방법은 다음과 같습니다.

각 위치에서 다음 파일 타입이 있으면 모두 대체합니다.
- .dll
- .so
- .dylib
- 각 위치의 기타 플랫폼 특정 바이너리 파일
사용 중인 플랫폼에 따라 다음 단계를 수행합니다.
- Mac: Engine/Source/ThirdParty/EOSSDK 또는 Engine/Platforms/<PLATFORM>/Source/ThirdParty/EOSSDK 에 모든 바이너리 파일이 있는 다른 플랫폼과는 달리, Engine/Binaries/ThirdParty/EOSSDK 에 바이너리 파일이 있다는 점에 유의하세요. 이 경우 Engine/Binaries/ThirdParty/EOSSDK/Mac 에서 바이너리 파일을 업데이트하면 됩니다.
- Android: SDK/Bin/Android/Include 폴더는 그대로 두고, .aar 및 .lib 파일이 포함된 SDK/Bin/Android 의 하나 이상의 서브폴더만 업데이트하면 됩니다.
- iOS: SDK/Bin/IOS/EOSSDK.framework/Headers 폴더는 그대로 두고, SDK/Bin/IOS/EOSSDK.framework 폴더의 콘텐츠만 업데이트하면 됩니다.

프로젝트 오버라이드

프로젝트 오버라이드 메서드를 사용하면 프로젝트에서 자체적으로 EOS SDK를 제공할 수 있습니다. 이 메서드를 사용하면 엔진 모듈은 Engine/Source/ThirdParty/EOSSDK 에 있는 EOS SDK로 계속 컴파일되지만, 프로젝트 모듈은 엔진 또는 프로젝트 중 하나에서 SDK 헤더를 선택하여 컴파일할 수 있습니다. 이렇게 하면 EOS 공유 플러그인이 런타임에 엔진이 아니라 프로젝트에서 제공하는 EOS SDK 바이너리를 로드하는 것을 선호하므로 엔진 모듈을 포함한 모든 요소가 프로젝트가 제공하는 EOS SDK 바이너리로 실행됩니다.

단계

EOS SDK 프로젝트 오버라이드 방법은 다음과 같습니다.

본인의 프로젝트용으로 EOS SDK를 포함한 EOSSDK<PROJECT> 모듈을 직접 생성합니다.
- .Build.cs 파일이 RuntimeDependencies 엔트리를 추가하여 EOS SDK 바이너리를 <PROJECT>/Binaries/<PLATFORM> 으로 복사하도록 합니다. 또는 바이너리를 <PROJECT>/Binaries/<PLATFORM> 에 직접 체크인할 수도 있습니다.
프로젝트의 .Target.cs 파일에서 EOSSDK_USE_PROJECT_BINARY=1 을 설정합니다.
- 이렇게 하면 모놀리식 빌드가 엔진 EOS SDK 바이너리가 아닌 프로젝트 제공 바이너리에만 연결됩니다.
프로젝트 모듈의 경우 EOS SDK(엔진 모듈) 또는 프로젝트의 EOS SDK 오버라이드 모듈 중 하나를 선택하여 종속성으로 추가해야 합니다.
- 이 과정을 통해 프로젝트 모듈 컴파일에 사용하는 헤더 세트를 지정합니다.

추가 리소스

EOS SDK와 언리얼 엔진은 별개의 제품입니다. 언리얼 엔진에는 편의성을 위해 EOS SOK 빌드가 포함되어 있지만, 최신 버전 언리얼 엔진에 최신 버전 EOS SDK가 포함되지 않을 수도 있습니다. EOS SDK에 대한 자세한 정보는 다음 에픽 개발자 리소스를 참조하세요.

EOS 시작하기: 에픽게임즈 계정과 조직을 설정하고, EOS SDK를 다운로드하고, 콘솔용 EOS SDK에 액세스를 요청하는 단계입니다.
EOS SDK 핵심 정보: 다양한 SDK 다운로드 유형, 명명 규칙, 오류 처리와 같이 핵심적인 EOS SDK 정보입니다.
EOS SDK API 레퍼런스: EOS SDK의 전체 API 레퍼런스입니다.
EOS SDK 출시 노트: 새 API와 버그 수정 등 각 EOS SDK 출시 버전에 대한 출시 노트입니다.