1. Epic GamesDeveloper
  3. EOS在线子系统(OSS)插件

EOS在线子系统(OSS)插件

关于Epic在线服务插件的概述。

EOS在线子系统(OSS)插件

我们已注意到 Google 披露的 WebRTC 版本中存在的漏洞（更多信息请参见此处），并正在调查它对 EOS SDK 的影响以及接下来应采取的措施。

Epic在线服务（Epic Online Services）(EOS)是一种与引擎无关的系统，提供了一系列跨平台在线功能，包括：以玩家为中心的功能（如成就和排行榜），商业功能（如购买游戏内项目的能力），以及社交功能（如语音通信和好友列表）。

虚幻引擎（Unreal Engine） 可以帮助你通过 在线子系统（Online Subsystem） (OSS)插件在项目中实现EOS，而无需直接使用EOS SDK编写代码。"在线子系统"插件在虚幻引擎的所有公开的在线服务中提供了通用的接口。要使用此功能，开发人员必须向 Epic账号服务（Epic Account Services）(EAS)注册并配置其产品，然后启用并配置几个插件以通过OSS接口公开EOS功能。

有关EAS和EOS的更多信息，请参阅Epic在线服务开发人员文档。

设置

要开始在你的项目中利用EOS，必须首先启用EOS OSS插件。转到 编辑（Edit） 菜单，然后选择 插件（Plugins） 以打开 插件浏览器（Plugin Browser），即可找到这些插件。

在 插件浏览器（Plugin Browser） 中，找到并启用 在线子系统EOS（Online Subsystem EOS） 和 EOS共享（EOS Shared）。要通过EOS添加语音聊天支持，请同时启用 EOS RTC IVoiceChat 插件。

启用这些插件后，你将需要配置插件。以下某些配置步骤需要与产品相关的设置，或者需要向EOS注册产品之后接收的标识符。

如果你尚未向EOS注册你的产品，可以在Epic开发人员门户上注册。

EOS设置

以下设置与EOS的特定于平台的配置相关。有关更多详情，请参阅有关 平台选项 数据结构的EOS API参考页面。

  • 缓存目录（Cache Dir）： 这是EOS存储临时数据的位置。

  • 默认构件名称（Default Artifact Name）： 在 Epic Games商城 上发行并通过 Epic Games启动程序 运行的游戏将使用构件名称来查找设置数据。此字段将指定默认名称。

  • 更新函数预算（以毫秒为单位）（Tick Budget in Milliseconds）：此设置将确立EOS操作的每个更新函数时间限制。你可以将此值设置为零，以删除限制。

  • 启用覆层（Enable Overlay）： 用于启用或禁用所有覆层。一些覆层可能特定于平台，如电子商务覆层，它仅对于Epic Games商城上的作品发行有效。

  • 启用社交覆层（Enable Social Overlay）： 社交覆层将显示有关好友、成就和额外身份验证步骤的信息。你可以单独禁用此覆层，而将其他覆层保持启用。如果关闭了 启用覆层（Enable Overlay），此设置将不起作用。

  • 需要由Epic Games商城启动（Require Being Launched by Epic Games Store）： 对于Epic Games商城上发行的作品，激活此设置将导致游戏在启动之前验证所有权，并要求通过Epic Games商城启动。如果最终用户尝试使用其他方法启动游戏，游戏的进程将终止，并通过Epic Games启动程序自行重新启动。

  • 构件（Artifacts）： Epic Games商城支持单个产品有多个构件。例如，你的产品可以有单独的内部构件，分别用于开发、测试以及你的客户使用的发布版本。此数组包含每个具名构件的设置。数组中必须有至少一个构件，并且 默认构件名称（Default Artifact Name） 值必须匹配某个数组元素的名称。请参阅构件设置，了解有关这些设置的更多信息。

构件设置

你在这里配置的构件设置应匹配你的已注册产品的设置。你可以在开发人员门户（需要登录）上找到你的产品的设置。

  • 构件名称（Artifact Name）： 这是构件的名称。例如，MyGameStaging 或 MyGameRelease。

  • 客户端ID（Client ID）： 此ID应以"xyz"作为开头的前3个字符。

  • 客户端密钥（Client Secret）： 这是用于验证你的 客户端ID（Client ID） 的密码。

  • 产品ID（Product ID）： EOS SDK会使用此ID识别你的产品。

  • 沙盒ID（Sandbox ID）： 该构件属于带有此ID值的沙盒。通常，产品只有单个沙盒ID。

  • 部署ID（Deployment ID）： 每个构件的部署ID是不同的。例如，你有 MyGameStaging 和 MyGameRelease 构件，它们将各自有自己的部署ID。

  • 加密密钥（Encryption Key）： 将数据上传到EOS服务时，这个64字节的十六进制字符串用于将数据加密。与其他设置不同，EOS并不管理此加密密钥，并且它不存储在你的产品设置中。该密钥是你的游戏所独有的，不为Epic Games所知，目的是保护用户的数据隐私。

EOS Plus插件设置

EOS Plus 是一个试验性的OSS插件，将EOS SDK的功能与另一个在线平台（如Xbox Live、PlayStation、Steam等）的功能组合为单个兼容跨平台连接的在线子系统。

要使用此插件，你必须首先在开发人员门户中为你想支持的每个平台注册并配置你的产品。EOS SDK特定于平台的版本将包含详细说明，指导开发人员使用所支持平台的功能。

EOS OSS会将所有统计数据（Stat）名称转换为大写字符，然后再传递给EOS。当你在EOS开发者门户中配置项目时，请确保设置为大写字符，以便与EOS OSS兼容。

使用此插件之前，你必须配置以下设置：

  • 使用Epic账号进行EOS登录（需要关联账号）： 启用此设置后，EOS OSS插件将使用特定于平台的身份验证令牌，自动将用户登录到其Epic账号。这要求用户已将其Epic账号链接到其他平台的账号；如果未链接，日志会将此事件报告为错误。你可以将用户重定向到账号链接页面以完成此过程，其中用户可以登录并通过 账号（Accounts） 选项卡自行完成账号链接过程。

  • 使用跨平台用户ID进行EOS登录（不使用Epic账号）： 此设置通过特定于平台的身份验证令牌启用EOS连接功能。

  • 将统计数据映射到EOS（Mirror Stats to EOS）： 如果启用此选项，EOS Plus会将所有统计数据信息的副本发送到EOS OSS插件。

  • 将成就映射到EOS（Mirror Achievements to EOS）： 如果激活此选项，EOS Plus会将所有成就数据的副本发送到EOS OSS插件。

  • 使用跨平台连接会话（Use Crossplay Sessions）： 需要此设置，才能玩跨平台网络游戏。它还会使EOS会话界面成为主会话界面。

  • 将在线状态映射到EOS（Mirror Presence to EOS）： 此选项将确定EOS Plus插件是否还将在线状态数据发送到EOS OSS插件。在线状态数据仅在使用Epic账号服务时可用。

项目设置

你在开发人员门户上设置了产品并配置了插件后，需要在项目的 DefaultEngine.ini 文件中配置一些设置。

引擎设置

执行以下步骤，配置你的项目以使用 在线子系统EOS（Online Subsystem EOS） 插件：

  1. 在 [OnlineSubsystemEOS] 分段中，验证或添加以下行，确保启用了在线子系统EOS：

                 bEnabled=true

  2. 在 [OnlineSubsystem] 分段中，验证或添加以下行，确保EOS是你的默认平台：

                 DefaultPlatformService=EOS

  3. 在 [/Script/Engine.GameEngine] 分段中，验证或添加以下行，确保引擎将使用EOS NetDriver：

                 +NetDriverDefinitions=(DefName="GameNetDriver",DriverClassName="OnlineSubsystemEOS.NetDriverEOS",DriverClassNameFallback="OnlineSubsystemUtils.IpNetDriver")

  4. 如果你打算将EOS的P2P套接字功能用于玩家托管的比赛，请验证或添加以下行到 [/Script/OnlineSubsystemEOS.NetDriverEOS] 分段：

                 bIsUsingP2PSockets=true

现在，你的 DefaultEngine.ini 文件应在相应的分段中包含以下行：

		[OnlineSubsystemEOS]
		bEnabled=true

		[OnlineSubsystem]
		DefaultPlatformService=EOS

		[/Script/Engine.GameEngine]
	+NetDriverDefinitions=(DefName="GameNetDriver",DriverClassName="OnlineSubsystemEOS.NetDriverEOS",DriverClassNameFallback="OnlineSubsystemUtils.IpNetDriver")

		[/Script/SocketSubsystemEOS.NetDriverEOS]
		bIsUsingP2PSockets=true

EOS Plus设置（可选）

如果你想配置你的项目，以在EOS和另一个在线平台之间实现跨平台连接，请执行以下额外的修改：

  1. 在 [OnlineSubsystemEOSPlus] 分段中查找以下行，验证EOS Plus插件是否已启用：

                 bEnabled=true

  2. 在 [OnlineSubsystem] 分段中，将默认在线平台从 EOS 更改为 EOSPlus，然后添加其他在线平台的名称。在本示例中，我们将使用Steam作为第二个平台。完成操作后，你应该拥有以下行：

                 DefaultPlatformService=EOSPlus
             NativePlatformService=Steam

  3. 引擎需要知道 EOS 和 EOSPlus 网络ID类型是兼容的，才能启用这些平台之间的交互。将以下行添加到 [/Script/OnlineSubsystemUtils.OnlineEngineInterfaceImpl] 分段：

                 +CompatibleUniqueNetIdTypes=EOS
             +CompatibleUniqueNetIdTypes=EOSPlus

现在，你的 DefaultEngine.ini 文件应在相应的分段中包含以下行。你还可能需要将 Steam 替换为不同的在线平台名称：

	[OnlineSubsystemEOSPlus]
	bEnabled=true

	[OnlineSubsystem]
	DefaultPlatformService=EOSPlus
	NativePlatformService=Steam

	[/Script/OnlineSubsystemUtils.OnlineEngineInterfaceImpl]
	+CompatibleUniqueNetIdTypes=EOS
	+CompatibleUniqueNetIdTypes=EOSPlus

[OnlineSubsystem] 分段中的 DefaultPlatformService 设置将替换你之前设置的值。

EOS 语音通信

你可以配置 大厅（Lobby） 会话以创建链接的语音聊天室。加入大厅的用户（包括大厅创建者）将自动加入该语音聊天室。要配置此设置，请将 FOnlineSessionSettings::bUseLobbiesIfAvailable 和 FOnlineSessionSettings::bUseLobbiesVoiceChatIfAvailable 值都设置为 true。

单独的用户可以使用其IVoiceChatUser接口实例控制与语音聊天室的交互，你可以使用 FOnlineSubsystemEOS::GetVoiceChatUserInterface 检索这些实例。

IVoiceChatUser接口会启用与本地硬件、在线聊天室和其他语音聊天用户的交互。你可以选择输入或输出设备，更改音量水平，将特定用户屏蔽或禁言，并注册事件（如玩家加入或离开通道，开始或停止谈话，等等）。

使用 FOnlineSubsystemEOS::GetVoiceChatUserInterface 时，系统将处理初始化、连接，并自动登录。但是，根据你集成 IVoiceChat 的方式，你仍可以手动加入和离开可信服务器通道。请参阅EOSVoiceChat插件文档的 [可信服务器集成] 分段，了解更多信息。

登录

至于要使用怎样的方法来处理用户身份验证，这取决于是否使用基本的OnlineSubsystemEOS插件，或者是否与OnlineSubsystemEOSPlus一起使用。有两种方法可以在在线身份验证界面（Online Identity Interface）中启动登录过程。

方法 说明
自动登录（AutoLogin） 需要传递本地用户号。
登录（Login） 需要 FOnlineAccountCredentials 对象。

在下一小节中，你将了解如何在上述两种插件中使用两种方法让用户登录。

使用OnlineSubsystemEOS登录

除了提供有效的本地用户号外，登录方法还需要传递 FOnlineAccountCredentials 对象。此结构体有三个字段：

  • 类型（Type）
  • Id
  • 令牌（Token）

这三个字段将表明OnlineSubsystemEOS插件应使用哪种身份验证方法，具体取决于各个字段的值。以下是如何设置所有不同类型身份验证的示例：

账户门户

  • 类型（Type）：AccountPortal
  • Id：
  • 令牌（Token）：

使用这种方法时，在调用登录时会创建一个浏览器窗口，提示用户输入Epic账户信息。用户在该浏览器中登录其Epic账户后，系统会提示他们接受相关产品的访问范围。这种方法不需要运行开发验证工具（Dev Auth Tool）。

开发人员

  • 类型（Type）：开发人员
  • Id：localhost:（其中是指开发人员身份验证工具（Dev Auth Tool）中指定的 端口 ）。
  • 令牌（Token）：CredentialsName

此方法需要运行EOS 开发人员身份验证工具 （Dev Auth Tool）。请参阅以下开发人员身份验证工具。

设置开发人员身份验证工具后，请记住你使用的 端口（Port） 和 凭证名称（Credentials Name） ，因为填写上述 FOnlineAccountCredentials 对象的 Id 和 令牌（Token） 字段时需要用到。

此登录方法将在进行登录调用时打开，并且将要求用户输入自己的Epic Games账号信息。

如果用户已经在该浏览器中登录Epic Games，系统将要求用户接受相关产品的访问范围（此步骤仅在用户第一次登录时出现）。

这是在台式机平台中使用OnlineSubsystemEOS进行开发期间推荐使用的方法。

交换代码

  • 类型（Type） ："ExchangeCode"
  • Id :
  • 令牌（Token） ："<exchange code>"（其中 <exchange code> 是Epic启动程序提供的 交换代码 ）

仅当应用程序通过Epic启动程序启动时才应使用此方法，因为需要它提供的交换代码。此方法不需要运行开发人员身份验证工具，你将在游戏的发行版本中使用此方法。

登录成功

如果其中任一方法成功完成，登录过程将以注册所有必要的EOS通知服务（登录状态、好友和自己的在线状态更新以及身份验证刷新）并触发以下注册委托而结束：

方法 说明
OnLoginComplete 参数包括登录是否成功，以及新身份验证用户的UniqueNetId。
OnLoginStatusChanged 参数对应于此前和当前的登录状态，以及新身份验证用户的UniqueNetId。

使用OnlineSubsystemEOS自动登录

为了让 自动登录（AutoLogin） 方法在OnlineSubsystemEOS中运行，你需要将命令行参数添加到游戏的执行中，这些参数直接转换为 FOnlineAccountCredentials 对象中的三个字段，否则传递给登录（Login）方法。

需要设置全部三个参数 才能使自动登录运行，即使有些参数不会使用（例如在账号门户或交换代码方法中）。参数如下：

  • 类型 = AUTH_TYPE
  • Id = AUTH_LOGIN
  • 令牌 = AUTH_PASSWORD

下面是上一小节中介绍的三种登录方法所需参数的一些示例。在不违反上一小节中所述 要求 的前提下，如果将这些内容添加到游戏执行命令中，那么登录将成功处理。（开发人员验证工具，Epic Games启动程序）

开发人员

	-AUTH_TYPE="Developer"
	-AUTH_LOGIN="localhost:<port>"
	-AUTH_PASSWORD="CredentialsName"

ExchangeCode

	-AUTH_TYPE="ExchangeCode"
	-AUTH_LOGIN="Empty"
	-AUTH_PASSWORD="Exchange_Code_From_Launcher"

使用OnlineSubsystemEOSPlus登录

在OnlineSubsystemEOSPlus中使用自动登录（AutoLogin）和登录（Login）没有区别，另外，登录（Login）只需要在 FOnlineAccountCredentials 对象中为少数选定平台设置特定值。

外部身份验证

OnlineSubsystemEOSPlus用于处理EOS身份认证的登录方式与OnlineSubsystemEOS使用的登录方式不同。

它首先会复制已经传递给登录（Login）方法的FOnlineAccountCredentials对象（如果设置了可选值）。然后，系统将启动原生平台的用户登录过程（如果登录尚未完成）。这意味着使用选定的Steam账号登录，或要求在Xbox界覆层中进行用户选择。如果此初始平台登录不成功，登录过程将停止，同时触发已注册的OnLoginComplete委托，并提供有关错误的信息。

第一次平台登录成功后，如果启用了上一小节中提到的两个设置中的任何一个，则使用我们在开始时保存的凭证启动EOS登录。无论设置了哪个，这个新登录过程的第一部分都是相同的：我们将查询原生平台子系统，从而获取外部身份验证令牌。

使用跨平台用户ID

如果此设置已启用，而"使用Epic账号服务（Using Epic Account Services）"未启用，则外部身份验证令牌将添加到登录方法所需的凭证集中，并且EOS将尝试通过调用EOS_Connect_Login方法进行身份验证。

以下是需要在EOS项目开发门户（EOS Project Dev Portal）中进行更多设置的地方。要成功完成EOS身份验证，需要将相关平台添加到本文所述的身份提供商（Identity Providers）列表中。正确设置身份提供商后，EOS身份验证应该会成功完成，解锁对所有EOS游戏功能的访问。

使用Epic账号服务

如果启用此设置，登录过程将继续，就像启用了"使用跨平台用户ID（Using Crossplatform User IDs）"一样。外部身份验证令牌将添加到登录方法所需的凭证集中，并且EOS将尝试通过调用EOS_Auth_Login方法进行身份验证。此方法需要将Epic Games账号链接到将用于EOS身份验证的平台账号。

目前，登录过程中的 账号关联（Account linking） 仅在 Steam 平台可用，在其他平台尝试登录都会导致日志中出现以下身份验证错误：

Log Error

	LogEOSSDK: Warning: LogEOS: Error response received from backend. ServiceName=[OAuth], OperationName=[TokenGrant], Url=[<Redacted>], HttpStatus=[400], ErrorCode=[errors.com.epicgames.account.oauth.authorization_pending], NumericErrorCode=[1012], ErrorMessage=[The authorization server request is still pending as the end user has yet to visit and enter the verification code.], CorrId=[...]

在未来的版本中，此功能将在其他平台可用。同时，你可以通过Epic Games账号设置"连接（Connections）"分段中的"账号（Accounts）"选项卡手动完成账号链接。

链接过程中使用的Epic账号需要接受应用程序访问范围（如 使用OnlineSubsystemEOS登录（Login with OnlineSubsystemEOS） 分段所述），否则日志中将出现另一错误：

Log Error

	LogEOSSDK: Warning: LogEOS: Error response received from backend. ServiceName=[OAuth], OperationName=[TokenGrant], Url=[<Redacted>], HttpStatus=[400], ErrorCode=[errors.com.epicgames.oauth.scope_consent_required], NumericErrorCode=[58005], ErrorMessage=[The user has not consented to required scopes.], CorrId=[...]

账号链接并接受范围后，如果EOS身份验证配置正确，则登录将成功完成，应用程序将可以使用EAS的所有其余功能。

Ask questions and help your peers Developer Forums

Write your own tutorials or read those from others Learning Library

On this page