在线子系统EOS插件

Epic在线服务（Epic Online Services，EOS）是一套与引擎无关的系统，提供了一系列跨平台在线功能，包括：

• 以玩家为中心的功能，例如：

  • 成就

  • 排行榜

• 商业功能，例如：

  • 游戏内购买

• 社交功能，例如：

  • 语音通信

  • 好友列表

你可以通过在线子系统Epic在线服务（OSS EOS）插件在虚幻引擎项目中使用EOS。 在线子系统Epic在线服务（Epic Online Services）插件可帮助你与游戏中的Epic在线服务交互，而不必编写用来直接与EOS SDK交互的代码。 要使用此功能，你必须在EOS开发者门户（EOS Developer Portal）注册并配置你的产品，然后启用并配置一些插件来通过OSS接口公开EOS功能。

EOS插件概述

OSS EOS插件以在线子系统（Online Subsystem，OSS）插件为基础而编译。 在线子系统插件是一款通用插件，提供了访问各种在线服务的公共接口。 OSS EOS插件实现了通过Epic在线服务提供的特定功能，并将与EOS SDK的通信集成到插件中，从而扩展了OSS插件。 本页面介绍了OSS EOS插件的以下功能：

• 产品注册

• 启用插件

• 配置

• 登录

• 支持的接口

你也可以选择使用OSS EOS Plus插件扩展OSS EOS插件。 EOS Plus表示"EOS + 基础平台"，将EOS与另一个平台（例如Steam、主机平台等）相结合。 将EOS与另一个平台相结合提供了更多功能，例如自动会话镜像。 你可以在使用或不使用Epic账号服务（EAS）的情况下使用EOS Plus。

何时使用EOS Plus

如果你在Epic Games商城发行游戏，则需要使用OSS EOS插件；此外，无需使用EOS Plus。 如果你在另一个平台上发行游戏，请使用OSS EOS Plus插件以及OSS EOS插件。 本指南可能存在例外情况。 继续阅读本页面，确定适合你的项目的最佳插件组合。

如何使用OSS EOS

Epic开发者社区上的OSS EOS插件课程可指导你完成在虚幻引擎项目中使用OSS EOS的过程。

设置

使用Epic在线服务注册产品

Epic开发者资源文档为你提供了Epic游戏商城（EGS）、Epic在线服务、儿童网络服务（KWS）及相关工具的资源。 要利用OSS EOS插件，你必须首先使用Epic在线服务注册产品。 要使用EOS注册产品，请找到Epic开发者门户并执行入门步骤。 要特别指出的是，本指南概括了入门步骤的第1步中的产品注册过程。 稍后需要使用注册产品时提供的信息在虚幻引擎中配置OSS EOS插件。

虚幻引擎是使用EOS SDK的副本发行的，所以如果你想使用虚幻引擎随附的EOS SDK版本，不需要单独下载EOS SDK。 要使用不同版本的EOS SDK，请按照入门步骤的第2步中的说明操作，下载所需的EOS SDK版本。 下载所需版本的EOS SDK后，按照我们的升级EOS SDK文档上的说明操作，详细了解如何升级虚幻引擎使用的EOS SDK。

启用OSS EOS插件

要在项目中使用EOS，你必须在虚幻引擎中启用OSS EOS插件。 要启用OSS EOS插件，请执行以下步骤：

1. 找到编辑（Edit）> 插件（Plugins）。 这会打开插件浏览器，你可以在其中搜索要启用的插件。

2. 在插件浏览器中，找到并启用在线子系统EOS（Online Subsystem EOS）插件。

在线子系统EOS实现了Epic在线服务的在线子系统插件。 当你启用OSS EOS插件时，会默认启用以下额外的插件：

• EOS Plus

  • 将EOS与另一个平台相结合。

• EOS共享（EOS Shared）

  • 负责初始化和关闭EOS SDK。

  • 默认作为OSS EOS的依赖项启用。

• EOS语音聊天（EOS Voice Chat）

  • 通过EOS支持语音聊天。

启用所需插件后，你需要配置它们以在项目中使用。 以下某些配置步骤需要与产品相关的设置，或者需要向EOS注册产品之后接收的标识符。 这些内容在你的Epic开发者门户中可以取得。

配置OSS EOS插件

要继续，请确保你已经执行以下操作：

1. 使用Epic在线服务注册产品。

2. 启用OSS EOS插件。

要配置OSS EOS插件，请执行以下步骤：

1. 转到工具栏，点击编辑（Edit）> 项目设置（Project Settings）。

2. 找到插件（Plugins）> 在线子系统EOS（Online Subsystem EOS）。

点击查看大图。

EOS设置

这些设置与EOS的特定于平台的配置有关。 如需更多信息，请参阅EOS API参考页面中关于EOS_Platform_Options数据结构的部分。 下表介绍了每个EOS设置：

构件设置

构件设置包括你在EOS开发人员门户中注册的产品的设置。 你在此处配置的设置应该匹配你在EOS开发人员门户中注册的产品的设置。 你可以在EOS开发者门户上找到产品的设置。

要编辑构件设置（Artifact Settings），请执行以下步骤：

1. 点击EOS设置（EOS Settings）分段中构件（Artifacts）旁的添加元素（Add Element）按钮。 这会在EOS设置的构件数组中创建一个新元素。

2. 要自定义这个新构件的设置，请点击新创建的数组元素旁边的箭头。 如果这是数组中的第一个元素，其名称为Index[0]。

下表说明了可用的构件设置：

EOS Plus设置

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

在使用EOS Plus插件之前，你必须配置EOS Plus登录设置和跨平台游戏设置。

EOS Plus登录设置

下表说明了EOS Plus登录设置：

跨平台游戏设置

下表说明了跨平台游戏设置：

EOS插件的引擎配置

在开发人员门户上设置了你的产品并配置了插件之后，你就需要配置一些设置。 你可以在引擎配置层级中配置这些插件，例如DefaultEngine.ini。

OSS EOS配置设置

请在项目的DefaultEngine.ini文件中添加以下配置设置：

1. 检查是否在项目中启用了在线子系统EOS插件。

   C++

   [OnlineSubsystemEOS]
            bEnabled=true

   Copy full snippet(2 lines long)

2. 将EOS设置为项目的在线服务的默认平台。

   C++

   [OnlineSubsystem]
            DefaultPlatformService=EOS

   Copy full snippet(2 lines long)

3. 指定网络驱动程序。

   C++

   [/Script/Engine.Engine]
            !NetDriverDefinitions=ClearArray
            +NetDriverDefinitions=(DefName="GameNetDriver",DriverClassName="/Script/SocketSubsystemEOS.NetDriverEOSBase",DriverClassNameFallback="/Script/OnlineSubsystemUtils.IpNetDriver")
            +NetDriverDefinitions=(DefName="DemoNetDriver",DriverClassName="/Script/Engine.DemoNetDriver",DriverClassNameFallback="/Script/Engine.DemoNetDriver")

   Copy full snippet(4 lines long)

4. 将EOS的点对点套接字功能用于玩家托管的比赛。 此设置是可选的。

   C++

   [/Script/SocketSubsystemEOS.NetDriverEOSBase]
            bIsUsingP2PSockets=true

   Copy full snippet(2 lines long)

下面是上面介绍的针对OSS EOS的所有配置设置：

[OnlineSubsystemEOS]
	bEnabled=true

	[OnlineSubsystem]
	DefaultPlatformService=EOS

	[/Script/Engine.Engine]
	!NetDriverDefinitions=ClearArray
	+NetDriverDefinitions=(DefName="GameNetDriver",DriverClassName="/Script/SocketSubsystemEOS.NetDriverEOSBase",DriverClassNameFallback="/Script/OnlineSubsystemUtils.IpNetDriver")
	+NetDriverDefinitions=(DefName="DemoNetDriver",DriverClassName="/Script/Engine.DemoNetDriver",DriverClassNameFallback="/Script/Engine.DemoNetDriver")

从Epic Games启动器启动作品

如果你要从Epic Games启动器启动作品，需要在Epic Games商城（EGS）启动的所有Epic应用和Epic沙盒对的引擎配置文件层级中添加配置条目。 确保项目设置或引擎配置中的默认构件名称（Default Artifact Name）和构件名称（Artifact Name）匹配Epic在线服务开发者门户中的构件名称。

在EGS上发售作品时，将忽略默认构件名称。 EGS会始终改为传递它所使用的-epicapp命令行参数。 在不传递-epicapp的其他商城上发售时，默认构件名称会很实用。

EOS Plus配置设置

如果你想配置项目以在EOS和其他在线平台之间实现跨平台游戏，请将以下配置设置添加到项目的DefaultEngine.ini文件中：

1. 检查是否在项目中启用了在线子系统EOS Plus插件。

   • 前面说过，EOS Plus插件让你可以将EOS与其他的在线服务一起使用。

     C++

     [OnlineSubsystemEOSPlus]
               bEnabled=true

     Copy full snippet(2 lines long)

2. 将你的默认平台在线服务更改为EOS Plus。

   • 这会向引擎表明，你要将EOS与其他的平台服务一起使用。 此外，添加你想使用的额外原生平台在线服务。 在本例中，它设置为Steam，但可以是任何在线服务，包括主机在线服务。

     C++

     [OnlineSubsystem]
               DefaultPlatformService=EOSPlus
               ; Add your additional platform online services below
               NativePlatformService=Steam

     Copy full snippet(4 lines long)

3. 说明哪些网络ID类型与默认OSS兼容。

   • 这只需要在EOS/EOS Plus是默认OSS时设置。

     C++

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

     Copy full snippet(3 lines long)

4. 支持EOS与EOS Plus客户端之间的通信。

   • 例如，考虑这样一种情况：有一个EOS Plus玩家使用了另一个在线平台（例如Steam）登录，托管着一个EOS会话，然后一个EOS（非EOS Plus）客户端加入了前者的EOS会话。 纯EOS客户端需要此映射，以便EOS Plus网络ID能够正确路由到EOS，并反序列化为EOS网络ID。 此MappedUniqueNetIdTypes配置将被添加到与上一步所述配置相同的配置分段中。

     C++

     [/Script/OnlineSubsystemUtils.OnlineEngineInterfaceImpl]
              MappedUniqueNetIdTypes=(("EOSPlus","EOS"))

     Copy full snippet(2 lines long)

下面是上面介绍的针对EOS Plus的所有配置设置：

[OnlineSubsystemEOSPlus]
	bEnabled=true

	[OnlineSubsystem]
	DefaultPlatformService=EOSPlus
	NativePlatformService=Steam

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

OSS EOS如何查找构件

要在启动时选择为OSS EOS使用特定构建，你可以通过虚幻引擎命令行指定一系列设置，用于查找引擎配置中指定的构建，或默认的特定构建。 从虚幻引擎5.5开始，无论命令行中传递的沙盒ID和部署ID（通过-epicsandboxid和-epicdeploymentid参数传递）是什么，它们都会始终被使用。 之前，这些值只被用于在构件配置数组中查找匹配的条目。 无论在配置数组中找到什么构件条目，始终使用命令行沙盒和部署ID。

此行为可大致分为以下步骤：

1. 按照优先级降序，将ArtifactName定义为以下项目的值：

   • -EOSArtifactNameOverride=<...>

   • -EpicApp=<...>

   • 引擎所配置的DefaultArtifactName

2. 按照优先级降序，将SandboxId定义为以下项目的值：

   • -EpicSandboxIdOverride=<...>

   • -EpicSandboxId=<...>

   • 未指定

3. 按照优先级降序，将DeploymentId定义为以下项目的值：

   • -EpicDeploymentIdOverride=<...>

   • -EpicDeploymentId=<...>

   • 未指定

4. 如果已指定了SandboxId和DeploymentId，则搜索匹配全部ArtifactName、SandboxId和DeploymentId的构件。

5. 如果第4步失败或无法运行，但已指定了SandboxId，则搜索匹配ArtifactName和SandboxId的构件。

6. 如果第5步失败或无法运行，则搜索匹配ArtifactName的构件。

7. 如果第6步失败，则搜索ArtifactName为空的构件。

8. 如果第7步失败，则报告错误，未查找到构件。

9. 找到构件后：

   • 按照优先级降序，为SandboxId使用以下值：

     • 如已指定，则使用第2步中的值。

     • 使用第4-7步中查找到的构件条目的值。

   • 按照优先级降序，为DeploymentId使用以下值：

     • 如已指定，则使用第3步中的值。

     • 使用第4-7步中查找到的构件条目的值。

你可以在配置构件数组中为特定的ArtifactName、SandboxId和DeploymentId组合提供特定的构件条目。 如果你希望为每种组合使用不同的ClientId和/或EncryptionKey，这会非常有用。 另一方面，如果你想要设置一个始终使用的ClientId，那么你可以在配置构件数组中提供一个ArtifactName为空的构件条目。 这会强制上述行为始终使用构件名称为空的构件。

登录

有两种方法可在在线身份接口中开始登录过程：

• 自动登录（Auto Login）：需要你传递本地用户编号。

• 登录（Login）：需要你使用FOnlineAccountCredentials对象。

下一个小节介绍了如何在OSS EOS中使用自动登录或登录来使用户登录。

使用OSS EOS登录

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

• 类型

• ID

• 令牌

登录方法

这三个字段表示OSS EOS应该使用哪种身份验证方法，具体取决于其值。 以下小节提供了示例，说明如何设置可用的每种不同类型的身份验证：

• 账号门户

• 开发人员

• 交换代码

账号门户

• Type：AccountPortal

• ID：

• Token：

账号门户是最通用的登录方法，因为它不需要EOS开发者身份验证工具（Dev Auth Tool），也不需要让你的应用程序从Epic Games启动器打开。

利用此方法，如果你使用的是EOS SDK版本1.15或更高版本，发起登录调用时将显示游戏覆层UI。 如果未启用游戏覆层，将打开浏览器窗口。 用户需要在系统提示时输入Epic账号信息。 如果用户已经登录Epic Games，用户必须接受相关产品的访问范围。

由于凭证由用户在游戏覆层UI或浏览器中提供，你不需要提供ID或令牌。

开发人员

• Type：Developer

• ID：localhost:<PORT>

  • PORT是开发者身份验证工具中指定的端口

• Token：<CREDENTIALS_NAME>

  • CREDENTIALS_NAME在开发者身份验证工具中指定

"开发人员"是桌面平台上使用OSS EOS开发的推荐方法。 此方法需要运行Dev Auth工具。 请参阅Epic在线服务站点上的以下文档，详细了解开发者身份验证工具。

设置开发者身份验证工具后，记住你使用的端口和凭证名称，因为你需要用它们来填写FOnlineAccountCredentials对象的ID和Token字段，如上所述。 此登录方法会在发起登录调用时打开，并且系统会要求用户输入Epic Games账号信息。 如果用户已经登录Epic Games，用户必须接受相关产品的访问范围。 此步骤仅在用户首次登录时执行。

交换代码

• Type：ExchangeCode

• ID：

• Token：<EXCHANGE_CODE>

  • <EXCHANGE_CODE>由Epic Games启动器提供

你应该仅在你的应用程序从Epic Games启动器启动时才使用"交换代码"方法，因为它需要启动器提供的交换代码。 此方法不需要运行Dev Auth工具，你应该对游戏的发布版本使用此方法。

由于Epic Games启动器会提供交换代码令牌，你不需要提供ID或令牌。

登录成功

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

• OnLoginComplete：各种参数，包括登录是否成功，以及新通过身份验证的用户的UniqueNetId。

• OnLoginStatusChanged：各种参数，对应之前和当前的登录状态以及新通过身份验证的用户的UniqueNetId。

使用OSS EOS自动登录

要对在线子系统EOS使用自动登录，你必须在启动时将额外的命令行参数传递到游戏的可执行文件。 这些参数对应于原本传递给登录方法的FOnlineAccountCredentials对象中的三个字段。

上面登录中的参数对应如下所示的命令行参数：

登录方法

此小节包含所有三种登录方法所需的参数的示例，如上一小节所述。

账号门户

-AUTH_TYPE="accountportal"

开发人员

-AUTH_TYPE="developer" -AUTH_LOGIN="localhost:<PORT>" -AUTH_PASSWORD="<NAME_IN_DEV_AUTH_TOOL>"

此命令中的参数如下：

• <PORT>是你在开发者身份验证工具中配置的端口。

• <NAME_IN_DEV_AUTH_TOOL>是你在Dev Auth Tool中选择的凭证名称。

交换代码

-AUTH_TYPE="exchangecode" -AUTH_PASSWORD="<EXCHANGE_CODE_FROM_LAUNCHER>"

此命令中的参数如下：

• <EXCHANGE_CODE_FROM_LAUNCHER>是Epic Games启动器中的交换代码。

使用外部账号凭证的登录流程

此小节介绍使用外部账号的OSS EOS登录流程。 你必须启用EOS Plus才能使用外部账号登录。

如果Epic账号服务和连接接口（EOS_Connect）均已启用，将使用非EOS平台（例如Steam）的外部账号凭证调用EOS_Auth_Login。 如果此登录失败并返回用户无效的错误（EOS_InvalidUser），将调用EOS_Auth_LinkAccount。 此调用会提示用户通过Web浏览器或用户界面覆层登录Epic Games账号。 此登录将用户的Epic Games账号关联到外部非EOS账号。

如果未启用Epic账号服务，但启用了连接接口，将使用外部账号凭证调用EOS_Connect_Login。

身份验证接口（EOS_Auth）和连接接口都需要身份提供商配置。 要使用你预期的外部平台，请将其添加到EOS项目开发人员门户中的身份提供程序列表。 如果你在身份提供程序中正确配置了你的平台，EOS身份验证应该会成功完成并解锁所有EOS游戏功能的访问权限。 如需更多信息，请参阅关于身份提供商管理的Epic开发者资源文档。

使用Epic账号服务

如果启用此设置，登录过程会像同时启用了"使用跨平台用户ID"那样继续。 外部身份验证令牌会被添加到登录方法所需的一组凭证中，而EOS会尝试调用EOS_Auth_Login方法来验证身份。

接口

此小节提供了有关在线子系统EOS插件中实现的接口的更多信息。 如需详细了解其中每个接口，请参阅在线子系统文档。 OSS EOS插件支持以下EOS SDK接口：

支持的接口

会话

Bucket ID

在OSS EOS会话中，BucketId是特定于游戏的顶层筛选信息，用于搜索会话。 如需详细了解会话BucketId，请参阅关于会话的EOS文档。

BucketId可以使用添加到FOnlineSessionSettings::Settings的自定义特性设置为你的项目需要的内容。 为此，将以下内容添加到你的项目代码：

SessionSettings.Settings.Add(OSSEOS_BUCKET_ID_ATTRIBUTE_KEY, FOnlineSessionSetting(FString(TEXT("BUCKET_ID_PLACEHOLDER")), EOnlineDataAdvertisementType::ViaOnlineService));

其中：

• BUCKET_ID_PLACEHOLDER是你要使用的Bucket ID。

此自定义BucketId也需要以类似的方式被添加到会话搜索参数中。

统计数据

统计数据名称

OSS EOS会将所有统计数据名称转换为大写，然后再将其传递给EOS。 在EOS开发人员门户中配置你的项目时，务必将统计数据名称配置为大写名称，确保兼容OSS EOS。

已知问题

账号关联

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

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账号需要接受应用程序访问范围（如使用OSS EOS登录小节所述），否则日志中还将显示如下错误：

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的所有其他功能。