概述
安装
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_Create
的EOS_Platform_Options
已扩展为采用标记(Flags)成员,这是一个可容纳64个标记的位字段。目前有三个标记将禁用覆层:
EOS_PF_LOADING_IN_EDITOR
- 每当在UE4编辑器内运行(PIE)或Unity等游戏编辑器中使用EOS SDK时,都应设置此标记。EOS_PF_DISABLE_OVERLAY
- 每当你想明确禁用覆层功能时,都应设置此标记。Ecom接口中的购买相关功能将不可用。EOS_PF_DISABLE_SOCIAL_OVERLAY
- 每当你仅想明确禁用覆层功能的社交功能时,都应设置此标记。
兼容的渲染API和操作系统
Windows
可用性 | API |
---|---|
当前可用 |
|
试验性 |
|
macOS
可用性 | API |
---|---|
即将推出 |
|
Linux
可用性 | API |
---|---|
即将推出 |
|
社交覆层
社交覆层 是可以在游戏内访问的 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_Initialize
的 ProductName
用于标识他们正在玩的游戏。该服务还将共享提供给 EOS_PresenceModification_SetRawRichText
的 RichText
。
在线状态
当玩家使用 EOS_Auth_Login
和 EOS_Auth_Logout
连接或断开EOS服务时,玩家的在线状态设置为 在线(Online) 或 离线(Offline)。 EOS_PresenceModification_SetStatus
API可用于提供更离散的状态。 玩家好友状态会显示在社交覆层的好友(Friends)页面。
激活游戏
在状态面板中,显示的应用程序名称将直接通过提供给 EOS_Initialize
的 ProductName
共享。此应为主机的 语言设置 定义的产品名称。
在线状态富文本
在线状态富文本 应该为其他玩家提供一些游戏上下文。提供给 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_AddNotifyCustomInviteReceived
和 EOS_CustomInvites_RemoveNotifyCustomInviteReceived
支持检测、自定义UI指示和自定义邀请处理。
使用大厅
点击邀请(Invite)按钮后,社交覆层将使用 EOS_Lobby_SendInvite
代表用户和游戏通过大厅服务发送邀请。游戏将使用 EOS_Lobby_AddNotifyLobbyInviteAccepted
来了解玩家何时在覆层中点击接受(Accept)按钮。回调数据中包含邀请ID,你可以用它来找到大厅接口中有关游戏的信息。
使用会话匹配
点击邀请(Invite)按钮后,社交覆层将使用 EOS_Sessions_SendInvite
代表用户和游戏通过会话接口发送邀请。游戏将使用 EOS_Sessions_AddNotifySessionInviteAccepted
来了解玩家何时在覆层中点击接受(Accept)按钮。回调数据中包含会话ID,你可以用它来找到会话接口中有关游戏的信息。
邀请有效周期和警告
一个邀请的有效期与其所属的大厅或者会话相关,而不是发送它的玩家。因此,有可能当邀请的玩家加入了大厅或者会话,而邀请他们的好友却已经离开了。邀请只会在后端服务中销毁,而不是在收到邀请的客户端上。只有在邀请被使用过或者邀请的大厅/会话销毁之后才会销毁邀请。
如果一个邀请很长时间不被使用,原本与其关联的大厅或会话可能会被先销毁。在这种情况下,邀请也会失效。如果游戏客户端试图访问一个无效的邀请,当试图使用时,调用会失败。在邀请失效的情况下,玩家可能会看到以下几种错误:
- 无法找到邀请。(The invite is not found.)
- 游戏以满员。(The game is full.)
- 会话不存在。(The session doesn't exist anymore.)
由SDK识别到的错误会立刻反映在社交覆层中。然而,收到邀请的游戏客户端需要处理出现的所有错误/冲突。这应该在游戏客户端玩家接受邀请时操作。比如,你的游戏可能会通知玩家邀请的会话已经不可用。不论成功还是失败,游戏必须让社交覆层知道,邀请已经处理。要达到这一点,你的游戏必须调用 EOS_UI_AcknowledgeEventId()
。在这个API调用中,你的游戏必须包含错误代码。
会话匹配警告
如果当前会话已经满员,邀请按钮将不可用;如果要邀请的玩家已经在当前会话中,按钮也会禁用。你可以通过修改会话并改变其“允许邀请”的会话状态来修改邀请状态。会话中的所有客户端都必须通过 (Un)RegisterPlayer API调用来保持会话的状态。
原生平台好友
玩家可以使用社交覆层与他们的Epic好友和他们的原生平台好友无缝互动。为了在社交覆层中显示原生平台好友,游戏需要在EOS SDK初始化过程中提供IntegratedPlatform选项。如需集成详细信息,请参阅平台接口文档。
支持成就
社交覆层提供了成就用户接口。要利用这一点,务必在开发人员门户中正确设置数据。
成就的本地化遵循与社交覆层其余部分相同的规则,本文档顶部以及社交覆层概述对此进行了简要讨论。
如果成就标记为隐藏,则将使用锁定图标,但显示的文本将由社交覆层页面提供。 如果开发人员门户中未提供图标,则社交覆层页面将提供默认图标。