플랫폼 인터페이스(Platform Interface) 는 에픽 온라인 서비스(Epic Online Services, EOS) SDK에서 핵심적인 부분을 차지하며, 다른 모든 인터페이스에 액세스하고 인터페이스를 실행 상태로 유지하는 데 필요한 핸들을 보유합니다. 애플리케이션을 시작할 때 SDK를 초기화하고 플랫폼 인터페이스의 핸들을 가져올 수 있습니다. 이 핸들은 SDK의 수명 동안 사용 가능합니다.
SDK 초기화하기
에픽 온라인 서비스(EOS) SDK를 사용하는 첫 단계는 바로 초기화입니다. 초기화할 때 코드가 제품을 식별하며, 커스텀 메모리 할당 기능을 설정할 수 있습니다.
SDK 생성 및 구성하기
EOS_InitializeOptions 데이터 구조체를 사용해 EOS_Initialize 를 호출하여 EOS SDK를 초기화합니다. 구조체를 다음과 같이 채웁니다.
| 프로퍼티 | 값 |
|---|---|
ApiVersion | EOS_INITIALIZE_API_LATEST |
ProductName | SDK를 사용하는 제품의 이름입니다. 이름 스트링은 비워 둘 수 없으며 64자까지 입력할 수 있습니다. |
ProductVersion | SDK를 사용하는 애플리케이션의 제품 버전 |
Reserved | NULL |
AllocateMemoryFunction | EOS_AllocateMemoryFunc 유형 또는 NULL 의 커스텀 malloc 함수 이 함수는 메모리 정렬을 수행하는 포인터를 반환해야 합니다. |
ReallocateMemoryFunction | EOS_ReallocateMemoryFunc 유형 또는 NULL 의 커스텀 realloc 함수 |
ReleaseMemoryFunction | EOS_ReleaseMemoryFunc 유형 또는 NULL의 커스텀 free 함수 |
SystemInitializeOptions | 시스템별 초기화를 위한 필드입니다. 이 필드에 정보를 입력하면 정보가 EOS_<system>_InitializeOptions 구조체에 전달됩니다. 여기에서 <system> 은 초기화할 시스템입니다. |
OverrideThreadAffinity | EOS_Initialize_ThreadAffinity 유형인 스레드 선호도 초기화를 위한 필드입니다. 이 정보가 제공된 경우 EOS SDK 작업 도중 스레드를 생성할 때 사용됩니다. null로 설정한 경우 EOS SDK는 스레드 선호도를 결정하기 위해 디폴트 스킴을 사용합니다. EOS_Initialize_ThreadAffinity 구조체는 사용할 스레드 카테고리를 식별하는 선호도 마스크 세트입니다. |
EOS_Initialize 가 EOS_EResult 를 반환하면서 성공 또는 실패를 표시합니다. SDK가 초기화에 성공한 경우 이 값은 EOS_Success 가 되고, 초기화에 실패한 경우 이 값은 오류(예: EOS_AlreadyConfigured)를 표시합니다. SDK를 초기화한 후에 플랫폼 인터페이스 를 생성할 수 있습니다.
콘솔 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 구조체로 호출하여 플랫폼 인터페이스를 생성합니다.
| 프로퍼티 | 값 |
|---|---|
ApiVersion | EOS_PLATFORM_OPTIONS_API_LATEST |
Reserved | NULL |
ProductId | 게임의 제품 ID로, 에픽게임즈에서 제공 |
SandboxId | 게임의 샌드박스 ID로, 에픽게임즈에서 제공 |
ClientCredentials | 호스트 애플리케이션에 할당된 클라이언트 ID 및 클라이언트 비밀 키 쌍 최종 사용자 게임 클라이언트처럼 공개적으로 노출된 애플리케이션은 신뢰할 수 있는 게임 서버 백엔드와는 다른 크리덴셜을 사용합니다. |
bIsServer | 애플리케이션이 로컬 사용자가 있는 클라이언트로 실행될 경우 EOS_False 로 설정합니다. 전용 게임 서버의 경우에는 EOS_True 로 설정합니다. |
EncryptionKey | 16진수 형식으로 파일을 암호화하는 256비트 암호화 키(16진수 64자) |
OverrideCountryCode | 로그인한 사용자의 오버라이드 국가 코드 |
OverrideLocaleCode | 로그인한 사용자의 오버라이드 로컬 코드 |
DeploymentId | 게임의 디플로이 ID로, 에픽게임즈에서 제공 |
Flags | EOS_PF_ 플래그의 비트 연산 OR 유니언으로 표현되는 플랫폼 생성 플래그 |
CacheDirectory | 임시 데이터를 캐시하는 데 사용될 폴더의 절대 경로 |
TickBudgetInMilliseconds | EOS_Platform_Tick 이 작업을 수행하기 위한 밀리초 단위의 예산입니다. 예산이 충족되거나 초과되는 경우(또는 가능한 작업이 없을 경우) EOS_Platform_Tick 이 반환됩니다. 이렇게 되면 큐에 등록된 처리 예정 작업이 많을 경우 게임이 SDK 작업 비용을 여러 프레임에 분할하여 처리할 수 있습니다. 0은 '가능한 모든 작업 수행'으로 해석됩니다. |
RTCOptions | 리얼타임 커뮤니케이션(Real Time Communication) 기능을 사용하기 위한 EOS_Platform_RTCOptions 구조체의 포인터입니다. NULL을 사용하면 보이스(Voice) 같은 RTC 기능이 비활성화됩니다. |
IntegratedPlatformOptionsContainerHandle | 통합 플랫폼을 설정하기 위한 모든 옵션을 포함하는 핸들입니다. NULL로 설정하면 호스트 플랫폼의 디폴트 통합 플랫폼 행동이 사용됩니다. |
성공하면 EOS_Platform_Create 가 플랫폼 인터페이스에 핸들(EOS_HPlatform 유형)을 반환합니다.
에디터와 같은 멀티 뷰를 지원하는 애플리케이션에서는 여러 개의 플랫폼 인터페이스 핸들을 생성하는 것이 좋습니다. 그러나 분할 화면 게임처럼 동일한 디바이스에서 여러 명의 사용자가 플레이하는 기능을 지원할 때는 여러 개의 핸들을 생성하지 않아도 됩니다. SDK는 여러 개의 플랫폼 인터페이스 인스턴스를 지원하며, 인스턴스마다 자체 내부 상태가 있습니다. 얻게 된 다른 인터페이스는 해당 인터페이스를 얻는 플랫폼 인터페이스에서 각각 고유합니다. SDK 자체의 인스턴스를 둘 이상 초기화하면 안 됩니다.
플랫폼 인터페이스 사용하기
EOS_HPlatform 핸들을 얻은 후에는 이 핸들을 사용하여 인터페이스 핸들 액세스 함수를 통해 다른 EOS SDK 인터페이스에 액세스할 수 있습니다.
| 인터페이스 | 액세스 함수 |
|---|---|
| 업적(Achievements) | EOS_Platform_GetAchievementsInterface |
| 안티 치트(Anti-Cheat) | EOS_Platform_GetAntiCheatClientInterface |
EOS_Platform_GetAntiCheatServerInterface | |
| 인증(Authentication) | EOS_Platform_GetAuthInterface |
| 연결(Connect) | EOS_Platform_GetConnectInterface |
| 커스텀 초대(Custom Invites) | EOS_Platform_GetCustomInvitesInterface |
| 전자상거래(Ecommerce) | EOS_Platform_GetEcomInterface |
| 친구(Friends) | EOS_Platform_GetFriendsInterface |
| 리더보드(Leaderboards) | EOS_Platform_GetLeaderboardsInterface |
| 로비(Lobby) | EOS_Platform_GetLobbyInterface |
| 메트릭스(Metrics) | EOS_Platform_GetMetricsInterface |
| 모드(Mods) | EOS_Platforms_GetModsInterface |
| P2P | EOS_Platform_GetP2PInterface |
| 플레이어 데이터 스토리지(Player Data Storage) | EOS_Platform_GetPlayerDataStorageInterface |
| 현재상태(Presence) | EOS_Platform_GetPresenceInterface |
| 프로그레션 스냅샷(Progression Snapshot) | EOS_Platform_GetProgressionSnapshotInterface |
| 리얼타임 커뮤니케이션(Real Time Communications, RTC) | EOS_Platform_GetRTCInterface |
EOS_Platform_GetRTCAdminInterface | |
| 신고(Reports) | EOS_Platform_GetReportsInterface |
| 제재(Sanctions) | EOS_Platform_GetSanctionsInterface |
| 세션(Sessions) | EOS_Platform_GetSessionsInfoInterface |
| 통계(Stats) | EOS_Platform_GetStatsInterface |
| 타이틀 스토리지(Title Storage) | EOS_Platform_GetTitleStorageInterface |
| 사용자 정보(User Info) | EOS_Platform_GetUserInfoInterface |
플랫폼 인터페이스는 다른 인터페이스에 액세스할 수 있을 뿐만 아니라 해당 인터페이스를 모두 실행 상태로 유지할 수도 있습니다. 게임의 기본 루프에서 프레임마다 EOS_Platform_Tick 을 호출하여 비동기 함수가 지속적으로 업데이트되고 있는지 확인합니다.
###런처를 사용하여 애플리케이션 재시작하기
EOS는 EOS_HPlatform 핸들을 EOS_Platform_CheckForLauncherAndRestart 에 전달하여 애플리케이션이 런처를 통해 실행되었는지 확인합니다. 그렇게 실행되지 않은 경우 런처를 통해 애플리케이션을 재시작합니다. 그러면 EOS_EResult 가 반환되며 다음 코드를 표시합니다.
EOS_Success: 런처를 통해 애플리케이션을 재실행 중입니다. 현재 애플리케이션 프로세스를 최대한 빨리 종료해야 새로 실행된 프로세스가 작동할 수 있습니다.EOS_NoChange: 애플리케이션이 이미 런처를 통해 실행된 경우 추가 조치가 필요 없습니다.EOS_UnexpectedError: LauncherCheck 모듈을 초기화하지 못했거나, 모듈이 애플리케이션을 재시작하려고 시도했지만 실패했습니다.
이 함수와 연관성이 있는 애플리케이션은 스토어에 퍼블리싱되어 런처를 통해 이미 액세스 가능한 애플리케이션뿐입니다.
SDK 종료하기
게임을 종료하려면 SDK에서 보유 중인 글로벌 상태뿐 아니라 플랫폼 인터페이스에서 보유 중인 메모리도 해제해야 합니다. SDK를 종료하려면 먼저 EOS_HPlatform 핸들을 EOS_Platform_Release 함수에 전달합니다. 그런 다음 EOS_Shutdown 을 호출하여 프로세스를 끝내고 종료하면 됩니다.
EOS_Shutdown 을 호출하고 나면 EOS SDK를 다시 초기화할 수 없으므로 향후 EOS SDK에 대한 호출이 모두 실패하게 됩니다.
애플리케이션 및 네트워크 상태
애플리케이션 상태가 변경될 때는 EOS_Platform_SetApplicationStatus 가 호출되어야 합니다. 애플리케이션 상태는 NewStatus 파라미터를 사용하여 설정할 수 있습니다.
다음 애플리케이션 상태는 EOS_EApplicationStatus 구조체로 정의됩니다.
EOS_AS_BackgroundConstrained | 백그라운드가 제한됩니다. |
EOS_AS_BackgroundUnconstrained | 백그라운드가 제한되지 않습니다. |
EOS_AS_BackgroundSuspended | 백그라운드가 정지됩니다. |
EOS_AS_Foreground | 포그라운드 |
EOS_Platform_GetApplicationStatus 로도 현재 애플리케이션 상태를 확인할 수 있습니다.
이런 애플리케이션 변경은 플랫폼에 따라 속성이 달라집니다. 자세한 정보는 플랫폼별 문서를 참조하세요.
네트워크 상태가 변경될 때는 EOS_Platform_SetNetworkStatus 가 호출되어야 합니다. 네트워크 상태는 NewStatus 파라미터를 사용하여 설정할 수 있습니다.
다음 네트워크 상태는 EOS_ENetworkStatus 구조체로 정의됩니다.
EOS_NS_Disabled | 네트워크가 사용될 수 없습니다. |
EOS_NS_Offline | 인터넷에 연결되어 있지 않을 수도 있습니다. 네트워크를 계속 사용할 수는 있지만 실패할 것으로 예상됩니다. |
EOS_NS_Online | 인터넷에 연결되어 있는 것으로 보입니다. |
EOS_Platform_GetNetworkStatus 로도 현재의 네트워크 상태를 확인할 수 있습니다.
이런 네트워크 변경은 플랫폼에 따라 속성이 달라집니다. 자세한 정보는 플랫폼별 문서를 참조하세요.
참고: 특정 플랫폼에서는 디폴트 네트워크 상태가 EOS_NS_Disabled 이며, 네트워크가 사용 가능할 때 EOS_Platform_SetNetworkStatus 를 호출해야 합니다. 자세한 내용은 플랫폼별 문서를 참고하세요.
네이티브 플랫폼 통합
SDK는 네이티브 플랫폼과 자동으로 통합할 수 있는 기능을 제공합니다. 이렇게 통합하면 게임에서 다음이 지원됩니다.
-
EOS 오버레이의 친구 목록에 플랫폼 친구 포함
-
네이티브 플랫폼 현재상태로 로컬 에픽 사용자의 현재 상태 미러링
-
네이티브 플랫폼 시스템으로 EOS 로비와 EOS 세션의 게임 초대 리플리케이트
-
플랫폼 친구가 현재상태를 통해 로컬 사용자의 EOS 로비 또는 세션에 참가할 수 있도록 지원
-
게임 초대 알림을 표시하는 데 사용되는 컨트롤 시스템(게임 UI, 플랫폼 UI, EOS 오버레이)
사용할 플랫폼 통합을 환경설정하는 방법은 다음과 같습니다.
-
EOS_IntegratedPlatform_CreateIntegratedPlatformOptionsContainer를 호출하여 플랫폼 옵션을 위한 새로운 임시 컨테이너를 생성합니다. -
플랫폼별
EOS_IntegratedPlatform_<Platform>_Options구조체를 생성하여 사용할 옵션을 지정합니다. -
EOS_IntegratedPlatformOptionsContainer_Add를 호출하여 SDK 초기화를 위한 옵션을 등록합니다. -
EOS_Platform_Create가 성공적으로 호출되면EOS_IntegratedPlatformOptionsContainer_Release를 호출하여 임시 컨테이너를 해제합니다.