플랫폼 인터페이스(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_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에서 보유 중인 글로벌 상태뿐 아니라 플랫폼 인터페이스에서 보유 중인 메모리도 해제해야 합니다. SDK를 종료하려면 먼저 EOS_HPlatform
핸들을 EOS_Platform_Release
함수에 전달합니다. 그런 다음 EOS_Shutdown
을 호출하여 프로세스를 끝내고 종료하면 됩니다.
EOS_Shutdown
을 호출하고 나면 EOS SDK를 다시 초기화할 수 없으므로 향후 EOS SDK에 대한 호출이 모두 실패하게 됩니다.
애플리케이션 및 네트워크 상태
게임의 상태나 네트워크 상태를 변경할 때는 플레이어의 애플리케이션(게임) 상태와 네트워크 상태를 설정해야 합니다. 이러한 설정을 통해 EOS SDK에 RTC 전환을 올바르게 수행하도록 알릴 수 있습니다.
애플리케이션 상태
애플리케이션 상태는 현재 게임이 일시 중단되었는지를 EOS SDK에 알리는 역할을 합니다.
애플리케이션 상태가 변경될 때는 EOS_Platform_SetApplicationStatus
가 호출되어야 합니다. 애플리케이션 상태는 NewStatus
파라미터를 사용하여 설정할 수 있습니다.
다음 애플리케이션 상태는 EOS_EApplicationStatus
구조체로 정의됩니다.
EOS_AS_BackgroundSuspended | 이 값은 애플리케이션이 플랫폼에 의해 일시 중단된 상태로 전환되었음을 SDK에 알립니다. "백그라운드 모드"라고도 합니다. |
EOS_AS_Foreground | 이 값은 애플리케이션이 일시 중단된 상태에서 재개되었음을 SDK에 알립니다. 모든 플랫폼에서 기본적으로 활성 상태입니다. |
EOS_Platform_GetApplicationStatus
로도 현재 애플리케이션 상태를 확인할 수 있습니다.
이런 애플리케이션 변경은 플랫폼에 따라 속성이 달라집니다. 자세한 정보는 플랫폼별 문서를 참조하세요.
적절한 권한이 있는 경우에만 콘솔 문서에 액세스할 수 있습니다. 콘솔용 EOS SDK와 관련 문서에 액세스하는 방법에 대한 자세한 내용은 시작 단계: EOS SDK 다운로드 유형 문서를 참조하세요.
게임이 상태 전환을 할 때 RTC 방에서 어떤 동작을 수행할지는 여러분의 결정에 달려있습니다. 일반적으로는 모든 플랫폼에서 모든 RTC 방을 떠나고 일시 중단된 상태(백그라운드 모드)에서는 다시 참여하지 못하도록 하는 것입니다. 이 기본 동작은 BackgroundMode
옵션으로 제어할 수 있습니다. BackgroundMode
를 설정하는 방법에 대한 자세한 내용은 보이스 인터페이스 사용 문서의 백그라운드 모드 섹션을 참고하세요.
네트워크 상태
네트워크 상태는 플레이어의 네트워크 연결 상태를 설정합니다.
네트워크 상태가 변경될 때는 EOS_Platform_SetNetworkStatus
를 호출해야 합니다. 네트워크 상태는 NewStatus
파라미터를 사용하여 설정할 수 있습니다.
다음 네트워크 상태는 EOS_ENetworkStatus
구조체로 정의됩니다.
EOS_NS_Disabled | 네트워크가 사용될 수 없습니다. |
EOS_NS_Offline | 플레이어가 인터넷에 연결되어 있지 않을 수도 있습니다. 네트워크는 여전히 사용할 수 있지만 실패할 가능성이 높습니다. |
EOS_NS_Online | 플레이어가 인터넷에 연결되어 있는 것으로 보입니다. |
EOS_Platform_GetNetworkStatus
로도 현재의 네트워크 상태를 확인할 수 있습니다.
이런 네트워크 변경은 플랫폼에 따라 속성이 달라집니다. 자세한 정보는 플랫폼별 문서를 참조하세요.
적절한 권한이 있는 경우에만 콘솔 문서에 액세스할 수 있습니다. 콘솔용 EOS SDK와 관련 문서에 액세스하는 방법에 대한 자세한 내용은 시작 단계: EOS SDK 다운로드 유형 문서를 참조하세요.
일반적인 패턴은 네트워크 상태를 비활성화(EOS_NS_Disabled
) 또는 오프라인(EOS_NS_Offline
)으로 변경할 때 리소스를 지우고 더 이상의 방 참여를 방지하는 것입니다. EOS SDK는 기본적으로 이 작업을 수행하며, 모든 플랫폼에서 동일하게 적용됩니다. 로비 RTC는 중지된 RTC 방을 활성화하고 온라인 상태가 되면 다시 시작합니다. 그 외의 경우에는 다시 연결을 시도하지 않습니다.
참고: 네트워크를 켜고 끌 때, RTC는 webRTC 스레드를 다시 구성해야 하기 때문에 네트워크 중단이 발생할 수 있습니다.
PlayStation 4, PlayStation 5, Nintendo Switch 및 Xbox의 경우 네트워크 상태는 기본적으로 EOS_NS_Disabled
로 설정됩니다. 네트워크가 온라인 상태인 경우 EOS_Platform_SetNetworkStatus
로 네트워크 상태를 EOS_NS_Online
을로 업데이트해야 합니다. 자세한내용은관련 플랫폼별 문서를 참고하세요
네이티브 플랫폼 통합
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
를 호출하여 임시 컨테이너를 해제합니다.