什么是Epic在线服务(EOS)?

Epic在线服务(EOS)是一个免费的跨平台服务,能让你快速、简单、可靠地发布、运营、扩展高品质游戏。

我们可以使用一个SDK创建易于开发人员和用户使用的生态系统。无论你选择以何种方式构建和发布游戏,创建人和开发人员均会受益。玩家可跨不同平台与好友一起玩此类游戏,感受到相同的游戏品质。我们的使命是尽可能提高SDK的可迁移性,使其能够在任何引擎、任何商城上运行,甚至可以整合到任何主流平台上。

这些服务包括这两种游戏服务,且可以与我们的 Epic账号服务Epic游戏商城 相集成。

SDK基本原理

EOS SDK有两种版本:C和C#包装器。

因为注重C语言,我们可提供稳定的应用程序二进制界面(ABI),以保证集成功能性,不受编译器选用、实现、调用规则、数据大小或对齐方式限制。

此方法还允许为SDK单独进行代码修复,以限制开发期间发生中断的情况,同时辅助维护SDK生命周期,不必在发布补丁和更新后重新编译应用程序。此外,注重C API将迫使我们更加从容地接触公共API。

EOS SDK目前支持以下平台:

  • Nintendo Switch

  • PlayStation

  • Xbox

  • iOS

  • Android

  • Windows

  • Mac

  • Linux

版本划分

EOS SDK版本划分可保证即使API出现变更,也可向后兼容使用旧版SDK的产品。每个界面、函数和数据类型增均有一个相关联的版本。

有新的SDK版本发布时,SDK会识别旧版本并提供支持,同时对旧版本的数据和函数调用作出适当响应。这可能包括内部调用函数的原始版本、将原始输入结构体迁移到更新的形式,或是在可能的情况下所设置的合理默认值。

使用SDK的老产品在不更新的情况下,也可以维持对EOS的兼容性。

界面句柄

EOS功能按照模块化的特色服务界面组合在一起。例如,大厅界面处理产品大厅的创建与交互;[好友界面]](EpicAccountServices/Friends)管理好友列表功能等等。

EOS SDK通过[平台界面]](interfaces /Platform)提供的不透明句柄公开其界面。界面句柄的生命周期与平台界面本身相当,且需要作为使用界面的每个API函数的第一个参数。

命名规范

为帮助传达用法和意图,EOS SDK界面使用一致的命名规范和前缀:

规则

用途

Create

该函数可分配内存,预期将与 Release 函数配对。

Copy

从之前调用的 Query 函数中检索缓存数据,预期将与 Release 函数配对。

Release

该函数可释放内存。这些均有一个相应的 CreateCopy 函数。

Query

在未指定时间段内,与后端服务异步交互。可能会根据连接性对这些调用进行限制或重试。

Get

在缓存数值不需要结构体且仅为数值时使用。针对需要缓冲区的字符串纳入 Get

函数签名

EOS SDK中的每个函数都有一个类似且可预测的签名:

  • 句柄始终是界面的第一参数。

    • 对于C#来说,你无需传送句柄参数。

  • "选项"数据结构体封装了函数的所有参数,且包含API版本信息。

  • 最后,异步函数具有一个应用程序专用回调函数,可接受用户定义的上下文信息,以供回调函数处理。此回调函数会在异步运行最终成功或失败时运行,同时也可能为了响应连接问题引起的延迟而运行。

错误处理

来自EOS C SDK函数的错误代码使用类型`EOS_EResult`来包含常见错误数值和某个单一界面的特定错误。例如,带有 EOS_Success 数值的枚举类型 EOS_EResult 显示为 EOS_EResult::EOS_Success

对于 C# 来说,那些通过使用结果(Result)类型来包含常见错误数值和特定界面错误的错误代码略有不同。与C SDK示例相比,带有 Success 数值的枚举类型 Result 显示为 Result.Success

常见错误以 EOS_<ErrorCode> 形式出现,同时特定界面错误代码显示为 EOS_<Interface>_<ErrorCode>。以下举一些示例:

错误代码

意义

EOS_InvalidParameters

至少有一个传入函数的未设置或无效输入参数。

EOS_InvalidUser

该操作需要有一名用户,且所提供的用户是无效或未指定的。

EOS_MissingPermissions

后端系统因访问限制拒绝请求。

EOS_UnrecognizedResponse

SDK无法解析后端响应。

EOS_OperationWillRetry

后端连接受损,SDK将重试。

EOS_IncompatibleVersion

调用代码发送的API版本参数与SDK中的函数版本号不匹配。

EOS_Auth_TokenInvalid

针对身份验证界面,本地身份验证会话已过期或已失效,用户需重新登录。

字符串

可作为输入和输出的字符串必须为UTF-8格式。

内存分配

当SDK函数需为回调函数提供数据结构体时,SDK会为数据分配内存,并在回调函数完成后立即释放内存。如需缓存一份相应的数据副本,则必须在回调函数的生命周期内进行复制。此外,如果系统需要自定义内存分配器,必须在创建SDK期间指定分配器。

名称中带有动词 Get 的SDK函数也拥有可供其使用的内存。与回调一样,如果希望后续可访问数据,必须复制数据。

名称中带有动词`Copy`的SDK函数例外。这些函数会返回已缓存数据副本,并预期调用者会获取副本所有权。C SDK绝不会放出此副本,所以用户必须在关闭SDK前调用相应的‘Release'函数。C# SDK不需要手动释放已复制的结构体,因为包装器会自动为你完成相应操作。

服务使用限制

为向所有用户提供稳定可靠的生态系统,Epic在线服务(EOS)实现了客户端请求速率限制和服务用量配额。SDK API与你的代码正确集成时,永远不会达到请求限制和用量配额上限。

但请注意这些限制,同时关注SDK日志输出。在内部测试期间,应该检查任何错误日志输出,核准EOS函数未返回 EOS_TooManyRequests 结果,或关于错误使用模式的警告。

客户端请求限制和服务用量配额同步生效,用于限制个体产品对整个EOS生态系统的影响。

请求限制

当EOS SDK检测到后端服务调用请求过快,本地客户端会拒绝带有 EOS_TooManyRequests 错误代码的API调用,从而进行自我限制。

后端服务具有类似功能,可拒绝那些已超过使用参考上限的个体客户端或托管服务器的请求。EOS SDK会将其报告为 EOS_TooManyRequests,并使用HTTP数据中的指定时间处理重试逻辑。

服务用量配额

每项服务会以每个部署为基础应用用量配额,以确保后端服务始终具有可供产品使用的有效容量。

可根据在线并发用户数量为每个部署设置固定或调整配额,具体依服务类型而定。所有配额同样对EOS生态系统中的每个产品适用。

如果应用程序达到后端服务的使用配额上限,则之后发起的新资源分配请求将会失败,直到使用频率降低到可接受的水平以下。