UI接口

用于访问覆层功能的接口

如果你计划在2022年10月前在主机上发布一款集成了Epic账户服务(EAS)的游戏,请联系我们eas-on-console-beta@epicgames.com确定你的发行计划。

Epic在线服务(EOS)支持通过

[覆层](EpicGamesStore/TechFeaturesConfig/EOSOverlay)
系统实现与产品相独立的窗口系统;这些覆层使用户能够独立于产品访问各种功能。UI接口(UI Interface)通过提供状态更新,显示或隐藏覆层,调整显示和热键偏好设置来管理与覆层的交互。

从1.5版本的SDK开始,在所有的用户信息调用中,国家信息(country)相关的代码都被废弃。

如需访问UI接口,你需要通过平台接口函数 EOS_Platform_GetUIInterface 获取 EOS_HUI 句柄。所有UI接口函数都需要此句柄作为其第一个参数。你必须确保 EOS_HPlatform 句柄处于更新状态,以便在操作完成时触发回调。

每个覆层都独立于产品运行,并与所有其他EOS产品以统一的方式运行。UI接口无法直接控制覆层,无法从它们读取数据或向它们写入数据,但它可以命令它们显示或隐藏自身,检测某个覆层当前是否可见,获取或设置用于显示或隐藏某个覆层的用户热键。

UI接口正在开发中,目前仅支持好友列表页面,而它只是社交覆层的一小部分;未来版本的EOS SDK将进一步支持横跨多个覆层的其他页面。

显示或隐藏覆层

如需显示好友列表页,请使用 EOS_UI_ShowFriendsOptions 数据结构调用 EOS_UI_ShowFriends,初始化方法如下:

Property

Value

int32_t ApiVersion

API Version: Set this to EOS_UI_SHOWFRIENDS_API_LATEST.

EOS_EpicAccountId LocalUserId

The Epic Account ID of the user whose friend list is being shown.

完成后,你的回调函数(类型是 EOS_UI_OnShowFriendsCallback)将接收到一个调用,其中包含一个 EOS_UI_ShowFriendsCallbackInfo 数据结构。

如需隐藏好友列表页,请使用包含以下信息的 EOS_UI_HideFriendsOptions 结构调用 EOS_UI_HideFriends

Property

Value

int32_t ApiVersion

API Version: Set this to EOS_UI_HIDEFRIENDS_API_LATEST.

EOS_EpicAccountId LocalUserId

The Epic Account ID of the user whose friend list is being shown.

操作完成后,EOS会运行你的回调函数(类型是 EOS_UI_OnHideFriendsCallback),向它传递一个 EOS_UI_HideFriendsCallbackInfo 类型的参数。

这些操作可能会更改覆层系统的整体可视性状态,但不一定每次都会这样。例如,假如覆层系统之前不可见,那么显示好友列表页面可以使覆层系统变为可见,但如果系统已经在显示好友列表或其他页面,则系统可能已经可见。同样,如果某个页面是最后一个显示的页面,则隐藏该页面可能会导致整个覆层系统变得不可见,但情况并非总是如此。请查看检测Overlay的当前可视性状态一节,深入了解覆层系统在某个时间点是否可见。

检测可视性状态

UI接口提供了两种级别的可视性状态信息。

第一种是覆层系统本身。当某个覆层中至少有一个页面显示时,系统整体上被视为可见的。此信息在制定某些高级决策时会非常有用,例如将输入路由到何处,或者何时暂停模拟。

第二种是针对单个页面的。这有助于了解代码是否应该发出指令,以便打开或关闭页面,或者用于确定玩家是否能够看到他们可能需要的信息。

覆层系统可视性状态

EOS SDK允许开发人员注册回调函数,以便报告覆层系统的整体可视性状态。如需注册你的回调(类型为 EOS_UI_OnDisplaySettingsUpdatedCallback),请在加载EOS SDK时调用 EOS_UI_AddNotifyDisplaySettingsUpdated,并传入经过正确初始化的 EOS_UI_AddNotifyDisplaySettingsUpdatedOptions 数据结构:

Property

Value

int32_t ApiVersion

API Version: Set this to EOS_UI_ADDNOTIFYDISPLAYSETTINGSUPDATED_API_LATEST.

你的回调将在平台接口的当前Tick或下一次Tick期间执行。通过跟踪你在此回调过程中接收到的值,你可以随时了解覆层系统的最新可视性状态。

在关闭时,请用 EOS_UI_RemoveNotifyDisplaySettingsUpdated 以及 EOS_UI_AddNotifyDisplaySettingsUpdated 最初注册时返回的 EOS_NotificationId 来移除回调。

单独页面可视性状态

所有可以被UI接口显示或隐藏的页面都有专门的函数来报告其可视性状态。如果是好友列表页面,请调用 EOS_UI_GetFriendsVisible,并以以下方式初始化 EOS_UI_GetFriendsVisibleOptions

Property

Value

int32_t ApiVersion

API Version: Set this to EOS_UI_GETFRIENDSVISIBLE_API_LATEST.

EOS_EpicAccountId LocalUserId

The Epic Account ID of the user whose overlay is being updated.

EOS_UI_GetFriendsVisible 会返回 EOS_Bool,表示页面是否可见。

获取并设置热键

用户可以用热键显示或隐藏覆层。热键支持页面切换,因此它既可以显示页面也可以隐藏页面。

要定义热键,必须选择一个主键以及一个或多个修改键。主键可以是 F1F12空格退格键(Backspace)结束键(Escape)Tab。修改键包括 ShiftControlAlt

要描述热键,请使用 EOS_UI_EKeyCombination。你可以通过逐位"或"(OR)运算来构建一个热键组合,并使用 EOS_UI_IsValidKeyCombination 来验证它是否可以作为热键,示例代码如下:

// 将 ProposedHotKey 设置成 Alt-Shift-Tab。
EOS_UI_EKeyCombination ProposedHotKey = EOS_UI_EKeyCombination::EOS_UIK_Alt | EOS_UI_EKeyCombination::EOS_UIK_Shift | EOS_UI_EKeyCombination::EOS_UIK_Tab;

// 询问UI接口 ProposedHotKey 是否可以接受。
if (EOS_UI_IsValidKeyCombination(ProposedHotKey) == EOS_TRUE)
{
    // ProposedHotKey 有效。
}

UI接口提供了一些函数,可用于检查特定页面的当前热键,将热键设置为新值,或将其重置为系统默认值(使用 EOS_UI_EKeyCombination::EOS_UIK_NONE)。

请调用 EOS_UI_GetToggleFriendsKey 获取好友列表页面的当前热键。EOS_UI_GetToggleFriendsKeyOptions 参数配置如下:

Property

Value

int32_t ApiVersion

API Version: Set this to EOS_UI_GETTOGGLEFRIENDSKEY_API_LATEST.

如需设置(或重置)好友列表页面的热键,请使用 EOS_UI_SetToggleFriendsKeyOptionsEOS_UI_SetToggleFriendsKeyOptions 初始化方法如下:

Property

Value

int32_t ApiVersion

API Version: Set this to EOS_UI_SETTOGGLEFRIENDSKEY_API_LATEST.

EOS_UI_EKeyCombination KeyCombination

The new key combination which will be used to toggle the friends overlay. The combination can be any set of modifiers and one key. A value of EOS_UIK_None will cause the key to revert to the default.