平台接口

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

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

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

EOS_Initialize 返回 EOS_EResult 以指示成功或失败。如果SDK初始化成功，该值将为 EOS_Success；否则，该值将指示错误，例如 EOS_AlreadyConfigured 。初始化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 函数，创建平台接口：

成功后， EOS_Platform_Create 将返回句柄到平台接口，类型为 EOS_HPlatform 。

你有 EOS_HPlatform 句柄后，可以用它获取通过句柄访问函数访问其他EOS SDK接口的权限。

除了能获取其他接口的访问权限，平台接口还可使所有这些接口保持运行。每帧从游戏的主循环中调用 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，你必须使用 SetEnvironmentVariable 和 GetEnvironmentVariable 。
• 对于其他平台，你必须使用 setenv 和 getenv 。

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

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

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

当你更改任一状态时，你必须设置玩家的应用程序（游戏）状态和网络状态。设置这些状态将提示 EOS SDK，确保RTC为你的游戏正确转换。

应用程序状态会告知EOS SDK游戏当前是否暂停。

必须在应用程序状态发生变化时调用 EOS_Platform_SetApplicationStatus 。可使用 NewStatus 参数设置应用程序状态。

以下应用程序状态通过 EOS_EApplicationStatus 结构定义：

也可使用 EOS_Platform_GetApplicationStatus 获取当前应用程序状态。

这些应用程序状态变更的性质取决于平台（有关更多信息，参见相关平台的文档）。

你只能在拥有适当权限的情况下访问控制台文档。请参阅入门步骤文档，获取有关如何访问控制台EOS SDK及其相关文档的更多信息。

当你的游戏在不同状态间转换时，你的游戏将如何处理RTC房间取决于你。常见做法是让所有平台离开所有RTC房间，并禁止在挂起状态（后台模式）下重新加入。你可以通过 BackgroundMode 选项控制此默认行为。有关如何设置 BackgroundMode 的更多信息，参见“使用语音接口”文档的后台模式小节。

网络状态可设置玩家网络连接的状态。

当网络状态发生变化时，你必须调用 EOS_Platform_SetNetworkStatus 。可使用 NewStatus 参数设置网络状态。

以下网络状态通过 EOS_ENetworkStatus 结构定义：

也可使用 EOS_Platform_GetNetworkStatus 获取当前网络状态。

这些网络状态变更的性质取决于平台（有关更多信息，参见相关平台的文档）。

你只能在拥有适当权限的情况下访问控制台文档。请参阅入门步骤文档，获取有关如何访问控制台EOS SDK及其相关文档的更多信息。

常见模式是当你将网络状态更改为禁用（ EOS_NS_Disabled ）或离线（ EOS_NS_Offline ）时，清除资源并防止进一步的房间加入。默认由EOS SDK完成此操作。每个平台的操作都是一样的。在前台和在线状态下，大厅RTC重启已暂停的RTC房间。否则它不会尝试重新连接。

注意 ：当你开启或关闭网络时，RTC可能出现网络中断，因为它必须重新配置其webRTC线程。

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 释放临时容器。