通过构建单个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 | 该函数可释放内存。这些均有一个相应的 Create 或 Copy 函数。 |
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 | 针对身份验证接口,本地身份验证会话已过期或已失效,用户需重新登录。 |
有关错误代码的更多信息,参见: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,你的本地网络、路由器和防火墙必须允许对特定主机地址的访问。这些主机地址的完整列表,请参阅防火墙注意事项文档。