Choose your operating system:
Windows
macOS
Linux
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特定于平台的版本将包含详细说明,指导开发人员使用所支持平台的功能。
使用此插件之前,你必须配置以下设置:
-
使用Epic账号服务(Use Epic Account Services): 启用此设置后,EOS OSS插件将使用特定于平台的身份验证令牌,自动将用户登录到其Epic账号。这要求用户已将其Epic账号链接到其他平台的账号;如果未链接,日志会将此事件报告为错误。你可以将用户重定向到 账号链接页面 以完成此过程,其中用户可以登录并通过 账号(Accounts) 选项卡自行完成账号链接过程。
-
使用跨平台用户ID(Use Cross-platform User IDs): 此设置通过特定于平台的身份验证令牌启用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) 插件:
-
在
[OnlineSubsystemEOS]
分段中,验证或添加以下行,确保启用了在线子系统EOS:bEnabled=true
-
在
[OnlineSubsystem]
分段中,验证或添加以下行,确保EOS是你的默认平台:DefaultPlatformService=EOS
-
在
[/Script/Engine.GameEngine]
分段中,验证或添加以下行,确保引擎将使用EOS NetDriver:+NetDriverDefinitions=(DefName="GameNetDriver",DriverClassName="OnlineSubsystemEOS.NetDriverEOS",DriverClassNameFallback="OnlineSubsystemUtils.IpNetDriver")
-
如果你打算将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/OnlineSubsystemEOS.NetDriverEOS]
bIsUsingP2PSockets=true
EOS Plus设置(可选)
如果你想配置你的项目,以在EOS和另一个在线平台之间实现跨平台连接,请执行以下额外的修改:
-
在
[OnlineSubsystemEOSPlus]
分段中查找以下行,验证EOS Plus插件是否已启用:bEnabled=true
-
在
[OnlineSubsystem]
分段中,将默认在线平台从EOS
更改为EOSPlus
,然后添加其他在线平台的名称。在本示例中,我们将使用Steam作为第二个平台。完成操作后,你应该拥有以下行:DefaultPlatformService=EOSPlus NativePlatformService=Steam
-
引擎需要知道
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"
-AUTH_TYPE="ExchangeCode"
-AUTH_LOGIN="Empty"
-AUTH_PASSWORD="Exchange_Code_From_Launcher"
使用OnlineSubsystemEOSPlus登录
在OnlineSubsystemEOSPlus中使用自动登录(AutoLogin)和登录(Login)没有区别,另外,登录(Login)只需要在 FOnlineAccountCredentials 对象中为少数选定平台设置特定值。
任天堂Id和任天堂NSA Id
在任天堂平台上尝试使用OnlineSubsystemEOSPlus登录时,需要将FOnlineAccountCredentials::Type设置为"NintendoAccount",以便外部身份验证过程使用任天堂Id令牌,而不是默认使用的任天堂NSA Id令牌。
EOS SDK暴露了两种身份验证系统。使用Epic账户服务(EAS)登录时,可以访问电子商务、好友、在线状态和其他需要Epic账户的社交功能。使用EOS Connect for Game Services进行认证时,可以访问数据存储、大厅、会话、语音和其他游戏功能,以及可与任意支持的平台账户一起使用的其他游戏功能。
对于要使用大部分游戏相关函数的项目,需要EOS Connect(用于游戏服务)需要认证成功,而EAS认证是可选的。若要指定项目使用其中一个,在编辑器中项目设置(Project Settings)下的在线子系统EOS插件设置(Online Subsystem EOS Plugin)的跨平台运行设置(Crossplay Settings)分段中有两个选项可用。
设置 |
说明 |
---|---|
使用跨平台用户ID(Use Crossplatform User IDs) |
启用EOS Connect身份验证,并且是所有EOS游戏服务功能可用的必要条件。 |
使用Epic账号服务(Use Epic Account Services) |
启用EAS身份验证,并将Epic账号好友(Friends)、在线状态(Presence)和电子商务(Ecommerce)功能添加到EOS产品中。某些平台需要选择加入此附加功能。 |
外部身份验证
OnlineSubsystemEOSPlus用于处理EOS身份认证的登录方式与OnlineSubsystemEOS使用的登录方式不同。
它首先会复制已经传递给登录(Login)方法的FOnlineAccountCredentials对象(如果设置了可选值)。然后,系统将启动原生平台的用户登录过程(如果登录尚未完成)。这意味着使用选定的Steam账号登录,或要求在Xbox界覆层中进行用户选择。如果此初始平台登录不成功,登录过程将停止,同时触发已注册的OnLoginComplete委托,并提供有关错误的信息。
第一次平台登录成功后,如果启用了上一小节中提到的两个设置中的任何一个,则使用我们在开始时保存的凭证启动EOS登录。无论设置了哪个,这个新登录过程的第一部分都是相同的:我们将查询原生平台子系统,从而获取外部身份验证令牌。
Xbox
在某些平台中,外部身份验证可能需要进行一些后端设置。例如,在Xbox中,我们需要配置依赖方,并创建有效端点,以便在合作伙伴中心配置单点登录,详见此 文章 。我们有了端点地址后,需要在GDK的相应引擎配置选项中设置:
`[OnlineSubsystemGDK]`
LoginXSTSEndpoint="https://endpoint.address.com/endpoint/address/"
其他平台所需额外设置的其他示例可以在Engine\Platforms\SelectedPlatform\Source\ThirdParty\EOSSDK\Documentation\下的相应pdf文档中找到
成功检索到外部身份验证令牌后,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 平台可用,在其他平台尝试登录都会导致日志中出现以下身份验证错误:
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) 分段所述),否则日志中将出现另一错误:
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的所有其余功能。