平台接口

用于向其他所有接口授予访问权限的接口。

阅读时间11分钟

平台接口Epic在线服务 (EOS)SDK的核心,拥有你访问所有其他接口并让这些接口保持运行的所需句柄。当你的应用启动后,你可以初始化SDK,并获取平台接口的句柄。该句柄在SDK的生命周期内可用。

初始化SDK

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

配置和创建SDK

使用 EOS_InitializeOptions 数据结构调用 EOS_Initialize,初始化EOS SDK。按如下方式填充结构:

属性
ApiVersionEOS_INITIALIZE_API_LATEST
ProductName使用SDK的产品的名称。名称字符串不得为空,长度最多为64个字符。
ProductVersion使用SDK的应用的产品版本
ReservedNULL
AllocateMemoryFunction你的自定义 malloc 函数,类型为 EOS_AllocateMemoryFunc,或 NULL
此函数必须返回遵循内存对齐的指针。
ReallocateMemoryFunction你的自定义 realloc 函数,类型为 EOS_ReallocateMemoryFunc,或 NULL
ReleaseMemoryFunction你的自定义 free 函数,类型为 EOS_ReleaseMemoryFunc,或NULL
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 5:**在PlayStation合作伙伴门户登录你的账号,前往 PlayStation 4 DevNet ,并依次点击 开发(Development) > 工具和中间件(Tools & Middleware) > 工具和中间件(Tools & Middleware)目录 > Epic在线服务(Epic Online Services) 。点击 确认身份(Confirm Status) 按钮。

  • **Xbox One和Series X:**联系你的Microsoft账号代表,让他们发送电子邮件到consoles@unrealengine.com,确认你的身份并引用你的电子邮件地址。

你的身份得到确认后,你将有资格获得控制台SDK的访问权限和支持。资格对象涵盖虚幻引擎合作伙伴(依据终端用户许可协议或自定义许可)和非虚幻引擎合作伙伴。

日志回调

SDK会以不同冗长度级别记录实用信息。 使用 EOS_Logging_SetCallback 注册回调,可访问此输出。 实现 EOS_LogMessageFunc 类型的函数,以接收 EOS_LogMessage 数据结构。

  • 类别 :与日志消息类别对应的字符串(参见EOS_ELogCategory API参考)
  • 消息 :消息本身作为字符串。
  • 级别 :日志消息的冗长度级别(参见EOS_ELogLevel API参考)

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

平台接口

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

创建平台接口

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

属性
ApiVersionEOS_PLATFORM_OPTIONS_API_LATEST
ReservedNULL
ProductIdEpic Games提供的游戏产品ID
SandboxIdEpic Games提供的游戏沙盒ID
ClientCredentials分配给主机应用的客户端ID和客户端密钥对
公开的应用(例如最终用户游戏客户端)将使用与可信游戏服务器后端不同的凭据。
bIsServer如果应用作为本地用户客户端运行,则设置为 EOS_False 。对于专用游戏服务器,设置为 EOS_True
EncryptionKey用于文件加密的256位十六进制密钥(64个十六进制字符)
OverrideCountryCode已登录用户的覆盖国家/地区代码
OverrideLocaleCode已登录用户的覆盖本地代码
DeploymentIdEpic Games提供的游戏部署ID
Flags平台创建标记,表示为按位或 EOS_PF_ 标记的并集
CacheDirectory将用于缓存临时数据的文件夹的绝对路径
TickBudgetInMillisecondsEOS_Platform_Tick 完成其工作的预算,以毫秒为单位。当达到或超出预算(没有可用工作)时,将返回 EOS_Platform_Tick 。如果有大量工作排队等待处理,这将允许你的游戏在多个帧中分摊SDK工作的开销。零解释为“执行所有可用工作”。
RTCOptionsEOS_Platform_RTCOptions 结构的指针,用于使用实时通信功能。使用NULL可禁用实时通信(RTC)功能,如语音。
IntegratedPlatformOptionsContainerHandle一个句柄,包含用于设置集成平台的所有选项。设置为NULL时,将使用主机平台的默认集成平台行为。

成功后, 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
电子商务EOS_Platform_GetEcomInterface
好友EOS_Platform_GetFriendsInterface
排行榜EOS_Platform_GetLeaderboardsInterface
大厅EOS_Platform_GetLobbyInterface
指标EOS_Platform_GetMetricsInterface
模组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
作品存储EOS_Platform_GetTitleStorageInterface
用户信息EOS_Platform_GetUserInfoInterface

除了能获取其他接口的访问权限,平台接口还可使所有这些接口保持运行。每帧从游戏的主循环中调用 EOS_Platform_Tick ,确保异步函数持续更新。

通过启动程序重新启动应用

当你将 EOS_HPlatform handle 传递到 EOS_Platform_CheckForLauncherAndRestart 时,EOS会检查Epic Games启动程序是否启动应用。如果Epic Games启动程序未启动应用, EOS_Platform_CheckForLauncherAndRestart 会通过Epic Games启动程序重新启动应用。

EOS_Platform_CheckForLauncherAndRestart 仅适用于商店中已发布从而可通过启动器访问的应用程序。

注意 :在调用 EOS_Platform_Create 期间,检查用于启动应用的命令行。若识别为其来自Epic Games启动程序,则环境变量 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,你必须使用 SetEnvironmentVariableGetEnvironmentVariable
  • 对于其他平台,你必须使用 setenvgetenv

此操作将返回 EOS_EResult 及以下代码:

  • EOS_Success :Epic Games启动程序正在重新启动应用。你必须尽快终止当前应用进程,以便新启动的进程正常运行。
  • EOS_NoChange :Epic Games启动程序已重新启动应用。你无需进行操作。
  • EOS_UnexpectedErrorLauncherCheck 模块未能初始化,或模块已尝试但未能重启应用程序。

关闭SDK

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

你调用EOS_Shutdown后,你将无法重新初始化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及其相关文档的更多信息。

当你的游戏在不同状态间转换时,你的游戏将如何处理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_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覆层的好友列表中包含平台好友

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

  • 通过原生平台系统复制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 释放临时容器。

示例代码