플랫폼 인터페이스

플랫폼 인터페이스(Platform Interface) 는 에픽 온라인 서비스(Epic Online Services, EOS) SDK에서 핵심적인 부분을 차지하며, 다른 모든 인터페이스에 액세스하고 인터페이스를 실행 상태로 유지하는 데 필요한 핸들을 보유합니다. 애플리케이션을 시작할 때 SDK를 초기화하고 플랫폼 인터페이스의 핸들을 가져올 수 있습니다. 이 핸들은 SDK의 수명 동안 사용 가능합니다.

에픽 온라인 서비스(EOS) SDK를 사용하는 첫 단계는 바로 초기화입니다. 초기화할 때 코드가 제품을 식별하며, 커스텀 메모리 할당 기능을 설정할 수 있습니다.

EOS_InitializeOptions 데이터 구조체를 사용해 EOS_Initialize 를 호출하여 EOS SDK를 초기화합니다. 구조체를 다음과 같이 채웁니다.

EOS_Initialize 가 EOS_EResult 를 반환하면서 성공 또는 실패를 표시합니다. SDK가 초기화에 성공한 경우 이 값은 EOS_Success 가 되고, 초기화에 실패한 경우 이 값은 오류(예: EOS_AlreadyConfigured)를 표시합니다. SDK를 초기화한 후에 플랫폼 인터페이스 를 생성할 수 있습니다.

데브 포털은 EOS SDK를 사용하려는 콘솔 개발자를 지원합니다. 가령 PlayStation Network와 XBox Live 온라인 서비스에서 사용자를 인증하는 기능을 제공합니다. 하지만 개발자는 먼저 콘솔 플랫폼 제조사로부터 자신의 등록 상태부터 확인해야 합니다. 플랫폼 제조사마다 확인 절차가 다릅니다.

• Nintendo Switch: Nintendo 데브 포털에서 계정에 로그인한 후 시작하기(Getting Started) > Nintendo Switch 미들웨어(Nintendo Switch Middleware) > 언리얼 엔진: 자세히 알아보기(Unreal Engine: Learn More) 를 차례대로 클릭합니다. 양식을 작성하고 제출합니다.

• PlayStation 4: PlayStation 파트너 포털에서 계정에 로그인한 후 PlayStation 4 DevNet 으로 이동하여 개발(Development) > 툴 및 미들웨어(Tools & Middleware) > 툴 및 미들웨어 디렉터리(Tools & Middleware directory) > 언리얼 엔진 4(Unreal Engine 4) 를 차례대로 클릭합니다. 상태 확인(Confirm Status) 버튼을 클릭합니다.

• Xbox One: Microsoft 계정 담당자에게 연락하여 본인의 이메일 주소를 참조로 넣고 consoles@unrealengine.com으로 본인의 등록 상태를 확인하는 이메일을 보내 달라고 요청하세요.

등록 상태를 확인한 후부터 콘솔 SDK에 액세스하고 지원을 받을 수 있습니다. 자격이 주어지는 대상은 언리얼 엔진 EULA 또는 맞춤형 라이선스를 취득한 언리얼 엔진 파트너와 언리얼 엔진 파트너가 아닌 개발자를 모두 포함합니다.

SDK는 다양한 디테일 수준으로 유용한 정보를 기록합니다. EOS_Logging_SetCallback 을 사용하여 콜백을 등록하면 이 출력에 액세스할 수 있습니다. EOS_LogMessageFunc 유형의 함수를 구현하여 EOS_LogMessage 데이터 구조체를 수신합니다.

• 카테고리(Category): 로그 메시지의 카테고리에 해당하는 스트링(EOS_ELogCategory API 레퍼런스 참조)
• 메시지(Message): 스트링으로서 메시지 자체
• 레벨(Level): 로그 메시지의 디테일 수준(EOS_ELogLevel API 레퍼런스 참조)

EOS_Logging_SetLogLevel 을 사용하여 로깅 디테일 수준을 조정할 수 있습니다.

플랫폼 인터페이스(Platform Interface)는 다른 모든 EOS SDK 인터페이스에 액세스하고 해당 인터페이스를 실행 상태로 유지합니다. 플랫폼 인터페이스를 생성한 후에는 이를 사용하여 다른 인터페이스의 핸들을 얻거나 프레임별 업데이트 코드를 실행(티킹)하라고 지시할 수 있습니다.

EOS_Platform_Create 함수를 다음 정보가 포함된 EOS_Platform_Options 구조체로 호출하여 플랫폼 인터페이스를 생성합니다.

성공하면 EOS_Platform_Create 가 플랫폼 인터페이스에 핸들(EOS_HPlatform 유형)을 반환합니다.

EOS_HPlatform 핸들을 얻은 후에는 이 핸들을 사용하여 인터페이스 핸들 액세스 함수를 통해 다른 EOS SDK 인터페이스에 액세스할 수 있습니다.

플랫폼 인터페이스는 다른 인터페이스에 액세스할 수 있을 뿐만 아니라 해당 인터페이스를 모두 실행 상태로 유지할 수도 있습니다. 게임의 기본 루프에서 프레임마다 EOS_Platform_Tick 을 호출하여 비동기 함수가 지속적으로 업데이트되고 있는지 확인합니다.

EOS_HPlatform handle 을 EOS_Platform_CheckForLauncherAndRestart 에 전달하면 EOS는 에픽게임즈 런처에서 앱을 실행하는지 여부를 확인합니다. 앱을 실행하지 않으면 EOS_Platform_CheckForLauncherAndRestart 가 에픽게임즈 런처로 앱을 재시작합니다.

EOS_Platform_CheckForLauncherAndRestart 는 스토어에 퍼블리싱된 앱에만 해당되므로 런처를 통해 액세스할 수 있습니다.

참고:EOS_Platform_Create 호출 중 앱 실행에 사용된 명령줄이 검사됩니다. 에픽게임즈 런처에서 가져온 것으로 인식되면 환경 변수 EOS_PLATFORM_CHECKFORLAUNCHERANDRESTART_ENV_VAR 이 1 로 설정됩니다.

EOS_Platform_CheckForLauncherAndRestart 를 호출하기 전에 EOS_PLATFORM_CHECKFORLAUNCHERANDRESTART_ENV_VAR 를 명시적으로 해제하면 EOS_Platform_CheckForLauncherAndRestart API에서 앱을 강제로 재실행하게 할 수 있습니다.

참고: 환경 변수 EOS_PLATFORM_CHECKFORLAUNCHERANDRESTART_ENV_VAR 와 상호작용하는 데 사용되는 API는 운영체제에 따라 달라집니다.

• Windows에서는 SetEnvironmentVariable 및 GetEnvironmentVariable 를 사용해야 합니다.
• 다른 플랫폼에서는 setenv 및 getenv 를 사용해야 합니다.

그러면 EOS_EResult 가 반환되며 다음 코드를 표시합니다.

• EOS_Success : 런처를 통해 애플리케이션을 재실행 중입니다. 현재 애플리케이션 프로세스를 최대한 빨리 종료해야 새로 실행된 프로세스가 작동할 수 있습니다.
• EOS_NoChange : 애플리케이션이 이미 런처를 통해 실행된 경우 추가 조치가 필요 없습니다.
• EOS_UnexpectedError : LauncherCheck 모듈을 초기화하지 못했거나, 모듈이 애플리케이션을 재시작하려고 시도했지만 실패했습니다.

이 함수와 연관성이 있는 애플리케이션은 스토어에 퍼블리싱되어 런처를 통해 이미 액세스 가능한 애플리케이션뿐입니다.

게임을 종료하려면 SDK에서 보유 중인 글로벌 상태뿐 아니라 플랫폼 인터페이스에서 보유 중인 메모리도 해제해야 합니다. SDK를 종료하려면 먼저 EOS_HPlatform 핸들을 EOS_Platform_Release 함수에 전달합니다. 그런 다음 EOS_Shutdown 을 호출하여 프로세스를 끝내고 종료하면 됩니다.

게임의 상태나 네트워크 상태를 변경할 때는 플레이어의 애플리케이션(게임) 상태와 네트워크 상태를 설정해야 합니다. 이러한 설정을 통해 EOS SDK에 RTC 전환을 올바르게 수행하도록 알릴 수 있습니다.

애플리케이션 상태는 현재 게임이 일시 중단되었는지를 EOS SDK에 알리는 역할을 합니다.

애플리케이션 상태가 변경될 때는 EOS_Platform_SetApplicationStatus 가 호출되어야 합니다. 애플리케이션 상태는 NewStatus 파라미터를 사용하여 설정할 수 있습니다.

다음 애플리케이션 상태는 EOS_EApplicationStatus 구조체로 정의됩니다.

EOS_Platform_GetApplicationStatus 로도 현재 애플리케이션 상태를 확인할 수 있습니다.

이런 애플리케이션 변경은 플랫폼에 따라 속성이 달라집니다. 자세한 정보는 플랫폼별 문서를 참조하세요.

적절한 권한이 있는 경우에만 콘솔 문서에 액세스할 수 있습니다. 콘솔용 EOS SDK와 관련 문서에 액세스하는 방법에 대한 자세한 내용은 시작 단계: EOS SDK 다운로드 유형 문서를 참조하세요.

게임이 상태 전환을 할 때 RTC 방에서 어떤 동작을 수행할지는 여러분의 결정에 달려있습니다. 일반적으로는 모든 플랫폼에서 모든 RTC 방을 떠나고 일시 중단된 상태(백그라운드 모드)에서는 다시 참여하지 못하도록 하는 것입니다. 이 기본 동작은 BackgroundMode 옵션으로 제어할 수 있습니다. BackgroundMode 를 설정하는 방법에 대한 자세한 내용은 보이스 인터페이스 사용 문서의 백그라운드 모드 섹션을 참고하세요.

네트워크 상태는 플레이어의 네트워크 연결 상태를 설정합니다.

네트워크 상태가 변경될 때는 EOS_Platform_SetNetworkStatus 를 호출해야 합니다. 네트워크 상태는 NewStatus 파라미터를 사용하여 설정할 수 있습니다.

다음 네트워크 상태는 EOS_ENetworkStatus 구조체로 정의됩니다.

EOS_Platform_GetNetworkStatus 로도 현재의 네트워크 상태를 확인할 수 있습니다.

이런 네트워크 변경은 플랫폼에 따라 속성이 달라집니다. 자세한 정보는 플랫폼별 문서를 참조하세요.

적절한 권한이 있는 경우에만 콘솔 문서에 액세스할 수 있습니다. 콘솔용 EOS SDK와 관련 문서에 액세스하는 방법에 대한 자세한 내용은 시작 단계: EOS SDK 다운로드 유형 문서를 참조하세요.

일반적인 패턴은 네트워크 상태를 비활성화(EOS_NS_Disabled) 또는 오프라인(EOS_NS_Offline)으로 변경할 때 리소스를 지우고 더 이상의 방 참여를 방지하는 것입니다. EOS SDK는 기본적으로 이 작업을 수행하며, 모든 플랫폼에서 동일하게 적용됩니다. 로비 RTC는 중지된 RTC 방을 활성화하고 온라인 상태가 되면 다시 시작합니다. 그 외의 경우에는 다시 연결을 시도하지 않습니다.

참고: 네트워크를 켜고 끌 때, RTC는 webRTC 스레드를 다시 구성해야 하기 때문에 네트워크 중단이 발생할 수 있습니다.

SDK는 네이티브 플랫폼과 자동으로 통합할 수 있는 기능을 제공합니다. 이렇게 통합하면 게임에서 다음이 지원됩니다.

• EOS 오버레이의 친구 목록에 플랫폼 친구 포함

• 네이티브 플랫폼 현재상태로 로컬 에픽 사용자의 현재 상태 미러링

• 네이티브 플랫폼 시스템으로 EOS 로비와 EOS 세션의 게임 초대 리플리케이트

• 플랫폼 친구가 현재상태를 통해 로컬 사용자의 EOS 로비 또는 세션에 참가할 수 있도록 지원

• 게임 초대 알림을 표시하는 데 사용되는 컨트롤 시스템(게임 UI, 플랫폼 UI, EOS 오버레이)

사용할 플랫폼 통합을 환경설정하는 방법은 다음과 같습니다.

1. EOS_IntegratedPlatform_CreateIntegratedPlatformOptionsContainer 를 호출하여 플랫폼 옵션을 위한 새로운 임시 컨테이너를 생성합니다.

2. 플랫폼별 EOS_IntegratedPlatform_<Platform>_Options 구조체를 생성하여 사용할 옵션을 지정합니다.

3. EOS_IntegratedPlatformOptionsContainer_Add 를 호출하여 SDK 초기화를 위한 옵션을 등록합니다.

4. EOS_Platform_Create 가 성공적으로 호출되면 EOS_IntegratedPlatformOptionsContainer_Release 를 호출하여 임시 컨테이너를 해제합니다.