Platform Interface

提供其他所有接口访问权的接口。

阅读时间9分钟

平台接口(Platform Interface) 处于 Epic在线服务 (EOS) SDK的核心地位,其包含访问并保持其他各个接口运行所需的句柄。启动应用程序时,可初始化SDK并获取平台接口的句柄。此句柄在SDK的生命周期中始终可用。

初始化SDK

使用Epic在线服务(EOS)SDK的第一步是将其初始化。在初始化期间,代码将识别产品,并可设置自定义内存分配函数。

配置和创建SDK

通过调用 EOS_Initialize 并使用 EOS_InitializeOptions 数据结构来初始化EOS SDK。按如下设置填充结构:

属性
ApiVersionEOS_INITIALIZE_API_LATEST
ProductName使用SDK的产品名称。名称字符串不能为空,支持的最大长度为64个字符。
ProductVersion使用SDK的应用程序的产品版本
ReservedNULL
AllocateMemoryFunction类型为 EOS_AllocateMemoryFunc 的自定义 malloc 函数,或为 NULL 。[REGION:note]此函数必须返回履行内存分配的指针。
ReallocateMemoryFunction类型为 EOS_ReallocateMemoryFunc 的自定义 realloc 函数,或为 NULL
ReleaseMemoryFunction类型为 EOS_ReleaseMemoryFunc 的自定义 free 函数,或为 NULL
SystemInitializeOptions用于特定系统的初始化的字段。如果提供则该信息将被传递到 EOS_<system>_InitializeOptions 结构, <system> 为要被初始化的系统。
OverrideThreadAffinity一个字段,填写的是 EOS_Initialize_ThreadAffinity 类型的线程关联性。如果提供了该信息,则在EOS SDK操作期间,创建任何线程时都将使用该信息。当设置为空时,EOS SDK将使用默认方案来确定线程关联性。 EOS_Initialize_ThreadAffinity 结构是一组关联性掩码(affinity mask),用于标识要使用的线程类别。
[/REGION]

EOS_Initialize 返回 EOS_EResult 来表明成功或失败。若SDK成功初始化,该值将为 EOS_Success ;否则将显示如 EOS_AlreadyConfigured 之类的错误。初始化SDK后,可创建 平台接口(Platform Interface)

申请获取主机SDK

开发者门户 持主机平台的开发者使用EOS SDK,包括对Playstation Network和Xbox Live在线服务上的用户进行身份验证。但是,开发人员必须首先向主机平台持有者确认他们的状态。每个平台持有者都提供了自己的确认程序。

  • 任天堂 Switch:任天堂开发者门户 上登录你的账号,依次点击 快速入门(Getting Started) > 任天堂Switch中间件(Nintendo Switch Middleware) > 虚幻引擎:了解更多(Unreal Engine: Learn More)。填写并提交表格。

  • Playstation 4:Playstation合作伙伴门户 上登录你的账号,打开 Playstation 4 DevNet,依次点击 开发(Development) > 工具和中间件(Tools & Middleware) > 工具和中间件目录(Tools & Middleware directory) > 虚幻引擎4。 点击 确认状态(Confirm Status) 按钮。

  • Xbox One: 请联系你的微软客户代表,让他们向 consoles@unrealengine.com 发送一封电子邮件,确认你的状态并提供您的电子邮件地址。

确认完你的状态后,你就有资格获得主机平台SDK的访问权限和支持服务。符合资格的申请人包括签订了EULA或定制许可的虚幻引擎合作伙伴,以及非虚幻引擎合作伙伴。

日志回调

SDK将记录各个复杂度级别的实用信息。使用 EOS_Logging_SetCallback 注册回调即可访问此输出。实现 EOS_LogMessageFunc 类型的函数以接收 EOS_LogMessage 数据结构。

  • Category: 用于说明日志消息类别的字符串(请参阅EOS_ELogCategoryAPI参考)
  • 消息(Message): 消息自身,字符串类型。
  • 级别(Level): 日志消息的详情级别(请参阅EOS_ELogLevelAPI参考)

可以使用 EOS_Logging_SetLogLevel 来调整日志详细级别。

平台接口·

平台接口可用于访问所有其他EOS SDK接口,保持接口运行。创建平台接口后,可用此接口获取其他接口的柄,或令其运行其逐帧更新代码,即 ticking

创建平台接口

使用包含下列信息的 EOS_Platform_Options 结构来调用 EOS_Platform_Create 函数,创建平台接口:

属性
ApiVersionEOS_PLATFORM_OPTIONS_API_LATEST
ReservedNULL
ProductIdEpic Games提供的游戏产品ID
SandboxIdTEpic Games提供的游戏沙盒ID
ClientCredentials分配给主机应用程序的客户端ID和客户端密钥对 [REGION:note]如最终用户游戏客户端等对外公开的应用程序将使用与受信任的游戏服务器后端不同的凭证。
bIsServer如果应用是以客户端形式运行并用于本地用户,则设置成 EOS_False ;如果是用作专用游戏服务器,则设置成 EOS_True
EncryptionKey用于文件加密的256位十六进制密钥(64个十六进制字符)
OverrideCountryCode已登录用户的重载国家/地区代码
OverrideLocaleCode已登录用户的重载本地代码
DeploymentIdEpic Games提供的游戏部署ID
Flags平台创建标记,表示为按位或 EOS_PF_ 标记的联合
CacheDirectory用于缓存临时数据的文件夹的绝对路径
TickBudgetInMilliseconds用于让 EOS_Platform_Tick 工作的以毫秒为单位的预算。当达到或者超过预算时(或者当没有可用的工作时) EOS_Platform_Tick 将会返回。 这样可以让你的游戏在多个任务堆积等待处理时在多个帧之间分摊SDK运作成本。零值代表着“执行所有任务。”
RTCOptionsEOS_Platform_RTCOptions 结构的指针,用于实时通信功能。使用NULL来禁用语音之类的实时通信功能。
IntegratedPlatformOptionsContainerHandle包含设立整合平台的所有选项的句柄。设为NULL时,将会使用为主机平台使用默认的整合平台方式。
[/REGION]

成功后, EOS_Platform_Create 返回柄至平台接口,类型为 EOS_HPlatform

在支持多个视图的应用程序(如编辑器)中,可能需要创建多个平台接口柄。若要支持多用户在同一设备上玩游戏(如分屏游戏),则不必创建多个平台接口柄。SDK支持多个平台接口实例,各个实例拥有各自的内部状态。获取到的其他接口对于获取这些接口时所用的平台接口来说是唯一的。请勿尝试对一个以上SDK自身实例进行初始化。

使用平台接口

拥有 EOS_HPlatform 句柄后便能通过其他EOS SDK接口的句柄访问函数来访问此类接口:

接口访问函数
成就EOS_Platform_GetAchievementsInterface
反作弊EOS_Platform_GetAntiCheatClientInterface
EOS_Platform_GetAntiCheatServerInterface
验证EOS_Platform_GetAuthInterface
连接EOS_Platform_GetConnectInterface
自定义邀请EOS_Platform_GetCustomInvitesInterface
ECOMEOS_Platform_GetEcomInterface
好友EOS_Platform_GetFriendsInterface
排行榜EOS_Platform_GetLeaderboardsInterface
大厅EOS_Platform_GetLobbyInterface
指标EOS_Platform_GetMetricsInterface
[模组] (/epic-games-store/services/mods)EOS_Platforms_GetModsInterface
P2PEOS_Platform_GetP2PInterface
玩家数据储存EOS_Platform_GetPlayerDataStorageInterface
在线状态EOS_Platform_GetPresenceInterface
进度快照EOS_Platform_GetProgressionSnapshotInterface
实时通信 (RTC)EOS_Platform_GetRTCInterface
EOS_Platform_GetRTCAdminInterface
报告EOS_Platform_GetReportsInterface
制裁EOS_Platform_GetSanctionsInterface
会话EOS_Platform_GetSessionsInfoInterface
统计EOS_Platform_GetStatsInterface
[标题储存] (GameServices/TitleStorage)EOS_Platform_GetTitleStorageInterface
用户信息EOS_Platform_GetUserInfoInterface

除提供其他接口的访问权,平台接口还负责保持其运行。在游戏主循环中逐帧调用 EOS_Platform_Tick 可确保异步函数持续更新。。

使用Launcher重启应用程序

EOS可以将 EOS_HPlatform 柄传递至 EOS_Platform_CheckForLauncherAndRestart 中,检查应用程序是否通过Launcher启动。若为否,则将通过Launcher重启应用程序。此操作将返回 EOS_EResult 及以下代码:

  • EOS_Success :应用程序正在通过Launcher重新启动。必须尽快终止当前应用程序进程,以便新启动的进程正常运行。
  • EOS_NoChange :若应用程序已通过Launcher启动,则无需其他操作。
  • EOS_UnexpectedError :LauncherCheck模块未能初始化,或是模块已尝试但未能重启应用程序。

此函数仅适用于商店中已发布、可通过Launcher访问的应用程序。

关闭SDK

要关闭游戏,须释放平台接口占用的内存及SDK占用的全局状态。首先,将 EOS_HPlatform 句柄传到 EOS_Platform_Release 函数将其关闭。然后,可调用 EOS_Shutdown 完成该进程并关闭。

调用 EOS_Shutdown后将无法重新初始化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覆盖的好友列表包含平台的好友

  • 用用户的原生平台在线状态镜像其本地Epic用户的状态

  • 用原生平台系统复制EOS大厅和EOS会话的游戏邀请

  • 为平台好友启用通过在线状态加入(join-via-presence) 本地用户的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)
{
// Create the generic container.
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;
}
// Configure platform-specific options.
const EOS_IntegratedPlatform_Steam_Options PlatformSpecificOptions =
{
EOS_INTEGRATEDPLATFORM_STEAM_OPTIONS_API_LATEST,
nullptr
};
// Add the configuration to the SDK initialization options.
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)
{
// Free the created container after SDK initialization.
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);
}