EOS SDK Key Information

提供C和C#的Epic在线服务(EOS)SDK。

阅读时间10分钟

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

SDK 基本原理

Epic在线服务(EOS)SDK有两种版本:C和C#版本。

借助C语言的优势,我们可提供稳定的应用程序二进制接口(Application Binary Interface,ABI),以保证集成功能性,不受编译器选用、实现、调用规则、数据大小或对齐方式限制。

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

根据你的游戏客户端运行的平台,我们提供了不同类型的SDK供下载:

  • Windows、macOS、Linux - C版本EOS SDK以及C#版本EOS SDK。
  • 移动端(Mobile) - iOS版本EOS SDK和安卓版本EOS SDK。
  • 主机端(Consoles) - 为游戏主机平台提供了C版本EOS SDK以及C#版本EOS SDK的下载。
    主机端的SDK下载仅提供给那些通过平台持有者和Epic Games批准的开发人员。
    平台持有者是指:微软(Xbox One、Xbox Series X)、索尼(PlayStation 4、PlayStation 5)、任天堂(Switch)。
    如需下载主机版本的SDK并获得相关文档:
    • 查阅开发人员门户(dev.epicgames.com/dev-portal),了解如何向平台持有者申请主机开发人员访问权限。
    • 获得平台持有者批准后,你可以使用 Epic在线服务主机开发人员申请 表格向Epic Games提交申请,该表格位于eoshelp.epicgames.com

版本划分

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

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

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

接口句柄

EOS功能按照模块化的特色服务接口组合在一起。例如,大厅接口处理产品大厅的创建和交互,好友接口管理好友列表的功能,等等。

EOS SDK通过平台接口提供的不透明句柄公开其接口。接口句柄的生命周期与平台接口本身相当,且需要作为使用接口的每个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_UnrecognizedResponseSDK无法解析后端响应。
EOS_OperationWillRetry后端连接受损,SDK将重试。
EOS_IncompatibleVersion调用代码发送的API版本参数与SDK中的函数版本号不匹配。
EOS_Auth_TokenInvalid针对身份验证接口,本地身份验证会话已过期或已失效,用户需重新登录。

有关错误代码的更多信息,参见:EOS SDK错误代码

字符串

可作为输入和输出的字符串必须为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生态系统中的每个产品适用。

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

EOS SDK API参考

参见EOS API参考文档。

注意: 如要使用Epic在线服务(EOS)SDK,你的本地网络、路由器和防火墙必须允许对特定主机地址的访问。这些主机地址的完整列表,请参阅防火墙注意事项文档。