Platform Interface

다른 모든 인터페이스에 액세스할 권한을 부여하는 인터페이스입니다.

9 분 소요

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

SDK 초기화하기

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

SDK 생성 및 구성하기

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

프로퍼티
ApiVersionEOS_INITIALIZE_API_LATEST
ProductNameSDK를 사용하는 제품의 이름입니다. 이름 스트링은 비워 둘 수 없으며 64자까지 입력할 수 있습니다.
ProductVersionSDK를 사용하는 애플리케이션의 제품 버전
ReservedNULL
AllocateMemoryFunctionEOS_AllocateMemoryFunc 유형 또는 NULL 의 커스텀 malloc 함수
이 함수는 메모리 정렬을 수행하는 포인터를 반환해야 합니다.
ReallocateMemoryFunctionEOS_ReallocateMemoryFunc 유형 또는 NULL 의 커스텀 realloc 함수
ReleaseMemoryFunctionEOS_ReleaseMemoryFunc 유형 또는 NULL의 커스텀 free 함수
SystemInitializeOptions시스템별 초기화를 위한 필드입니다. 이 필드에 정보를 입력하면 정보가 EOS_<system>_InitializeOptions 구조체에 전달됩니다. 여기에서 <system> 은 초기화할 시스템입니다.
OverrideThreadAffinityEOS_Initialize_ThreadAffinity 유형인 스레드 선호도 초기화를 위한 필드입니다. 이 정보가 제공된 경우 EOS SDK 작업 도중 스레드를 생성할 때 사용됩니다. null로 설정한 경우 EOS SDK는 스레드 선호도를 결정하기 위해 디폴트 스킴을 사용합니다. EOS_Initialize_ThreadAffinity 구조체는 사용할 스레드 카테고리를 식별하는 선호도 마스크 세트입니다.

EOS_InitializeEOS_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 을 사용하여 로깅 디테일 레벨을 조정할 수 있습니다.

플랫폼 인터페이스

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

플랫폼 인터페이스 생성하기

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

프로퍼티
ApiVersionEOS_PLATFORM_OPTIONS_API_LATEST
ReservedNULL
ProductId게임의 제품 ID로, 에픽게임즈에서 제공
SandboxId게임의 샌드박스 ID로, 에픽게임즈에서 제공
ClientCredentials호스트 애플리케이션에 할당된 클라이언트 ID 및 클라이언트 암호 쌍
최종 사용자 게임 클라이언트처럼 공개적으로 노출된 애플리케이션은 신뢰할 수 있는 게임 서버 백엔드와는 다른 크리덴셜을 사용합니다.
bIsServer애플리케이션이 로컬 사용자가 있는 클라이언트로 실행될 경우 EOS_False 로 설정합니다. 전용 게임 서버의 경우에는 EOS_True 로 설정합니다.
EncryptionKey16진수 형식으로 파일을 암호화하는 256비트 암호화 키(16진수 64자)
OverrideCountryCode로그인한 사용자의 오버라이드 국가 코드
OverrideLocaleCode로그인한 사용자의 오버라이드 로컬 코드
DeploymentId게임의 디플로이 ID로, 에픽게임즈에서 제공
FlagsEOS_PF_ 플래그의 비트 연산 OR 유니언으로 표현되는 플랫폼 생성 플래그
CacheDirectory임시 데이터를 캐시하는 데 사용될 폴더의 절대 경로
TickBudgetInMillisecondsEOS_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] (EpicGamesStore/TechFeaturesConfig/Mods)EOS_Platforms_GetModsInterface
P2PEOS_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] (GameServices/TitleStorage)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 오버레이)

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

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

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

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

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

샘플 코드

static EOS_EResult CreateIntegratedPlatform(EOS_Platform_Options& PlatformOptions)
{
// 일반 컨테이너를 생성합니다.
const EOS_IntegratedPlatform_CreateIntegratedPlatformOptionsContainerOptions CreateOptions =
{
EOS_INTEGRATEDPLATFORM_CREATEINTEGRATEDPLATFORMOPTIONSCONTAINER_API_LATEST
};
const EOS_EResult Result = EOS_IntegratedPlatform_CreateIntegratedPlatformOptionsContainer(&CreateOptions, &PlatformOptions.IntegratedPlatformOptionsContainerHandle);
if (Result != EOS_EResult::EOS_Success)
{
return Result;
}
// 플랫폼별 옵션을 환경설정합니다.
const EOS_IntegratedPlatform_Steam_Options PlatformSpecificOptions =
{
EOS_INTEGRATEDPLATFORM_STEAM_OPTIONS_API_LATEST,
nullptr
};
// SDK 초기화 옵션에 환경설정을 추가합니다.
const EOS_IntegratedPlatform_Options Options =
{
EOS_INTEGRATEDPLATFORM_OPTIONS_API_LATEST,
EOS_IPT_Steam,
EOS_EIntegratedPlatformManagementFlags::EOS_IPMF_LibraryManagedByApplication | EOS_EIntegratedPlatformManagementFlags::EOS_IPMF_DisableSDKManagedSessions,
&PlatformSpecificOptions
};
const EOS_IntegratedPlatformOptionsContainer_AddOptions AddOptions =
{
EOS_INTEGRATEDPLATFORMOPTIONSCONTAINER_ADD_API_LATEST,
&Options
};
return EOS_IntegratedPlatformOptionsContainer_Add(PlatformOptions.IntegratedPlatformOptionsContainerHandle, &AddOptions);
}
static void FreeIntegratedPlatform(EOS_Platform_Options& PlatformOptions)
{
// SDK 초기화 후 생성된 컨테이너를 해제합니다.
if (PlatformOptions.IntegratedPlatformOptionsContainerHandle)
{
EOS_IntegratedPlatformOptionsContainer_Release(PlatformOptions. IntegratedPlatformOptionsContainerHandle);
PlatformOptions.IntegratedPlatformOptionsContainerHandle = nullptr;
}
}
void InitializeEosSdk()
{
EOS_Platform_Options PlatformOptions = {};
CreateIntegratedPlatform(PlatformOptions);
// ...
EOS_Platform_Create(&PlatformOptions);
FreeIntegratedPlatform(PlatformOptions);
}