SDK集成

在游戏内访问EOS社交覆层和好友列表

如果你打算在2022年10月前在集成了Epic账号服务的主机上启动游戏,请通过eas-on-console-beta@epicgames.com与我们联系,以便协调发布计划。

概述

安装

EOS覆层通过Epic Games启动程序安装。游戏应用程序也可以使用EOS服务Redistributable安装工具将其作为先决条件的一部分安装。

SDK初始化

在初始化Direct3D前,务必要初始化EOS SDK并调用EOS_Platform_Create。 这让EOS覆层能够安装必要的图形API钩,以便在呈现给用户的每个游戏帧中渲染覆层。

对于Windows,EOS覆层为Direct3D9、Direct3D10和OpenGL提供试验性支持。要选择加入试验性功能,请在调用EOS_Platform_Create之前使用适当的值初始化EOS_Platform_Options中的 标记(Flags) 字段。

  • Direct3D9 - EOS_PF_WINDOWS_ENABLE_OVERLAY_D3D9

  • Direct3D10 - EOS_PF_WINDOWS_ENABLE_OVERLAY_D3D10

  • OpenGL - EOS_PF_WINDOWS_ENABLE_OVERLAY_OPENGL

在某些情况下,可能需要完全禁用覆层功能。例如,当开发人员在编辑器中运行游戏时,挂接编辑器的图形API会导致问题。传递给EOS_Platform_CreateEOS_Platform_Options已扩展为采用标记(Flags)成员,这是一个可容纳64个标记的位字段。目前有三个标记将禁用覆层:

  1. EOS_PF_LOADING_IN_EDITOR - 每当在UE4编辑器内运行(PIE)或Unity等游戏编辑器中使用EOS SDK时,都应设置此标记。

  2. EOS_PF_DISABLE_OVERLAY - 每当你想明确禁用覆层功能时,都应设置此标记。Ecom接口中的购买相关功能将不可用。

  3. EOS_PF_DISABLE_SOCIAL_OVERLAY - 每当你仅想明确禁用覆层功能的社交功能时,都应设置此标记。

兼容的渲染API和操作系统

Windows

可用性

API

当前可用

  • Direct3D 12

  • Direct3D 11

  • Vulkan

试验性

  • Direct3D 10

  • Direct3D 9

  • OpenGL

macOS

可用性

API

即将推出

  • Metal

  • Vulkan

  • OpenGL

Linux

可用性

API

即将推出

  • Vulkan

  • OpenGL

社交覆层

社交覆层 是可以在游戏内访问的 Epic在线服务 (EOS)UI。默认集成使用 shift-F3 访问社交覆层。社交覆层提供的主要功能是 好友列表(Friends List) ,提供 游戏管理玩家在线状态 功能。游戏管理使玩家能够邀请好友到游戏会话,或加入到好友的会话中。玩家在线状态提供关于他们在线状态、激活游戏和任何游戏定义在线状态富文本的详情。

处理独占输入模式

虽然社交覆层(或由EOS SDK管理的覆层,例如检出或身份验证)可见,但所有键盘和鼠标输入都可能被覆层消耗。 覆层应为仅基于用户意图可见。 基于此意图,用户希望与覆层交互,而不是与游戏交互。 这将导致游戏无法接收键盘或鼠标输入。

某些系统SDK用户输入法(例如Win32 API函数 ShowCursor)将在此期间改变行为。为了就此提供支持,并提供一般用户状态信息,游戏可以使用 EOS_UI_AddNotifyDisplaySettingsUpdated 来注册回调。 回调数据将包含可见和独占输入标记。 回调将始终在下一次 EOS_Platform_Tick 调用时触发,向游戏告知覆层的当前状态。

多个浏览器实例可以同时影响 可见 标记,例如,在购买时接收社交祝福。 更重要的用例是可见浏览器实例是否需要用户交互。 在这种情况下,独占输入标记将为true。 浏览器实例也必须可见,才能对独占输入标记产生影响。

本地化

用于社交覆层文本本地化的区域语言代码将来自以下两种来源之一:玩家在创建Epic账号时选择的语言,或游戏提供的覆盖值。 如果游戏使用覆盖值,那么无论用户在其Epic账号中选择了什么,此值均为所使用的值。 你也可以使用 EOS_Platform_SetOverrideLocaleCode 完成此操作。

在好友列表中使用玩家在线状态

在线状态服务(Presence Service) 将维护 在线状态 ,该状态与所有在线的用户好友共享,并且会在发生变化时更新。玩家的登录状态用于初始化和清除他们的 在线状态 。提供给 EOS_InitializeProductName 用于标识他们正在玩的游戏。该服务还将共享提供给 EOS_PresenceModification_SetRawRichTextRichText

作品负责控制自身的状态信息。Epic建议在开发期间将状态信息设置为代号,为最敏感的游戏提供额外的安全保障。默认游戏名称来自EOS_Initialize中的 ProductName 字段。

在线状态

当玩家使用 EOS_Auth_LoginEOS_Auth_Logout 连接或断开EOS服务时,玩家的在线状态设置为 在线(Online)离线(Offline)EOS_PresenceModification_SetStatus API可用于提供更离散的状态。 玩家好友状态会显示在社交覆层的好友(Friends)页面。

激活游戏

在状态面板中,显示的应用程序名称将直接通过提供给 EOS_InitializeProductName 共享。此应为主机的 语言设置 定义的产品名称。

在线状态富文本

在线状态富文本 应该为其他玩家提供一些游戏上下文。提供给 EOS_PresenceModification_SetRawRichText 的字符串将按原样共享。 它将作为好友页面(Friends Page)中好友状态的一部分显示。

在好友列表中使用游戏管理

游戏管理界面提供了 加入(Join) 按钮和 邀请(Invite) 按钮。它们的确切集成方式取决于游戏以及如何使用会话服务大厅服务。游戏还需要使用连接API将玩家账号与会话服务关联。

使用社交覆层时,你有两个实现选项:

  • 使用带有 bPResenceEnabled = true 的大厅或会话接口

    • 你可以使用这些功能,并且EOS保持加入和邀请的准确性

  • 不要使用大厅或会话接口并使用 SetJoinInfo

    • 你负责保持该值设置/为空,以反映你游戏的可加入性

加入按钮

玩家可通过加入(Join)按钮加入好友的游戏。与SDK的集成将取决于所使用的游戏管理服务。如果远程玩家的在线状态包含大厅ID、会话ID或加入信息字符串,则该按钮将启用。 此数据使用在线状态服务传输给所有好友。 当用户按下加入(Join)按钮时,所有三个标识符都有相关联的回调。预计游戏将在清理当前状态后尊重此用户意图。

使用大厅

使用大厅服务时,会自动传输大厅ID。 然后,游戏将使用 EOS_Lobby_AddNotifyJoinLobbyAccepted 来了解玩家何时点击加入(Join)按钮。 在清理之后,游戏必须使用提供的 UiEventId 通过 EOS_Lobby_CopyLobbyDetailsHandleByUiEventId 检索相关联的大厅,然后加入它。 如果加入失败,游戏预计将调用 EOS_UI_AcknowledgeEventId ,允许社交覆层刷新其状态。

使用会话匹配

使用会话匹配服务时,系统会自动传输会话ID。然后,游戏将使用 EOS_Sessions_AddNotifyJoinSessionAccepted 来了解玩家何时点击加入(Join)按钮。 在清理之后,游戏必须使用提供的 UiEventId 通过 EOS_Session_CopySessionHandleByUiEventId 检索相关联的会话,然后加入它。 如果加入失败,则游戏预计将调用 EOS_UI_AcknowledgeEventId ,允许社交覆层刷新其状态。

使用自定义服务

要手动为玩家设置 加入信息字符串(Join Info String) ,请使用 EOS_PresenceModification_SetJoinInfo 。开发人员可以根据需要自由定义 加入信息字符串(Join Info String) 的含义。

然后,游戏将使用 EOS_Presence_AddNotifyJoinGameAccepted 来了解玩家何时点击 加入(Join) 按钮。回调数据将包含加入信息字符串。

邀请按钮

邀请(Invite) 按钮使玩家可以邀请好友加入游戏。与SDK的集成将取决于所使用的游戏管理服务。 每种服务都有一个关联的通知回调。就像 加入(Join) 一样,游戏应该尽最大努力尊重用户意图。对于Epic Games启动程序的邀请功能,请务必将你的部署也映射到你的瑕疵

自定义邀请

对于不使用Epic匹配的作品,自定义邀请接口 用于发送和接收带有任意负载的邀请。单击邀请(Invite)按钮时,社交覆层将使用 EOS_CustomInvites_SendCustomInvite 发送自定义邀请。EOS_CustomInvites_AddNotifyCustomInviteReceivedEOS_CustomInvites_RemoveNotifyCustomInviteReceived 支持检测、自定义UI指示和自定义邀请处理。

使用大厅

点击邀请(Invite)按钮后,社交覆层将使用 EOS_Lobby_SendInvite 代表用户和游戏通过大厅服务发送邀请。游戏将使用 EOS_Lobby_AddNotifyLobbyInviteAccepted 来了解玩家何时在覆层中点击接受(Accept)按钮。回调数据中包含邀请ID,你可以用它来找到大厅接口中有关游戏的信息。

使用会话匹配

点击邀请(Invite)按钮后,社交覆层将使用 EOS_Sessions_SendInvite 代表用户和游戏通过会话接口发送邀请。游戏将使用 EOS_Sessions_AddNotifySessionInviteAccepted 来了解玩家何时在覆层中点击接受(Accept)按钮。回调数据中包含会话ID,你可以用它来找到会话接口中有关游戏的信息。

会议匹配注意事项

如果当前会话已满,邀请(Invite)按钮将不可用,如果两个用户在同一个会话中,则该按钮将被禁用。是否通过(Un)RegisterPlayer API调用来维护会话状态将取决于游戏。你可以通过修改会话来覆盖邀请状态,即改变会话的"允许邀请"状态。

覆层不处理竞争条件。接受邀请并不意味着用户将能够成功加入会话,只是很有可能加入。游戏仍然负责通过其他机制强制或调节客户端加入主机的行为,例如当两个客户端同时接受仅一个插槽的邀请时。

邀请的 生命周期 与它所属的会话相关,而不是与发送邀请的用户相关。用户可以离开会话,并在他们离开很久之后让他们的好友加入该会话。当它所绑定的会话结束时,邀请将被销毁。邀请的状态不会反映在社交覆层中,调用可能会失败。覆层将以消息框显示出现的错误。

原生平台好友

玩家可以使用社交覆层与他们的Epic好友和他们的原生平台好友无缝互动。为了在社交覆层中显示原生平台好友,游戏需要在EOS SDK初始化过程中提供IntegratedPlatform选项。如需集成详细信息,请参阅平台接口文档。

支持成就

社交覆层提供了成就用户接口。要利用这一点,务必在开发人员门户中正确设置数据。

成就的本地化遵循与社交覆层其余部分相同的规则,本文档顶部以及社交覆层概述对此进行了简要讨论。

如果成就标记为隐藏,则将使用锁定图标,但显示的文本将由社交覆层页面提供。 如果开发人员门户中未提供图标,则社交覆层页面将提供默认图标。