Mods Overview

用于在EOS生态系统中发布和管理模组的API

阅读时间9分钟

模组SDK(Mod SDK)Epic在线服务 的一个组件,它为游戏开发者提供了一个与 模组商城 交互并实现高级用例的接口。本文档介绍了模组SDK的功能、潜在用例,并记录了API接口。

目前,该功能仅适用于桌面平台和Epic游戏商城的产品。

模组SDK的功能

安装模组

游戏可以请求模组SDK从模组市场 安装 特定的模组。该操作由 Epic Games启动器 执行。如果一个玩家的 中没有模组,模组将会自动添加。这是一个异步操作,当模组安装完毕并准备就绪时,游戏会通过一个回调函数接收到通知。

卸载模组

模组 卸载 功能会从用户的本地硬盘驱动器中删除已安装的模组。卸载模组不会从玩家的库中删除模组。这是一个异步操作。当模组文件被删除时,游戏将通过一个回调函数得到通知。

更新模组

更新 函数会请求模组SDK将一个模组更新到最新版本。这是一个异步操作。更新操作完成后,游戏将通过一个回调函数得到通知。

列举模组

模组SDK可以分别列出模组市场上可供游戏安装的模组以及已安装的模组。有一个Mod SDK API函数会返回这两个列表。游戏通过函数参数来指定请求的列表。这是一个异步操作。当数据可用并准备好进行检索时,游戏将通过回调获得通知。

潜在用例

以下是可以用到模组SDK的功能示例:

多人游戏模组协调

当客户端游戏实例连接到一个运行了模组的服务器后,客户端和服务器端都会通过模组SDK来协调安装在客户端和服务器机器上的模组,并确定丢失的模组列表。

服务器会调用模组列举函数来获得已安装的模组列表,然后会将已安装模组的ID序列化并将它们发送给客户端。

客户端会比较服务器的模组列表和本地安装的模组。如果模组丢失,客户端会调用模组安装函数来安装丢失的模组。

游戏内模组管理器

模组的列举、安装、更新和卸载功能使游戏开发者能够拥有一个游戏内模组管理器。

使用列举功能来获取可用的和已安装模组的信息,包括其标题和版本。使用安装和卸载功能在游戏中添加或删除模组。使用更新功能来更新模组。

模组SDK接口

本节介绍模组SDK的数据结构和功能。

模组SDK的初始化和关闭

初始化EOS SDK的通常方式是调用 EOS_Platform_Create 函数。然后调用函数 EOS_Platform_GetModsInterface 来获得模组SDK句柄。

/**
* 获取模组界面的句柄。
* @return EOS_HMods handle
*
* @see eos_mods.h
* @see eos_mods_types.h
*/
EOS_DECLARE_FUNC(EOS_HMods) EOS_Platform_GetModsInterface(EOS_HPlatform Handle);

数据结构

EOS_Mod_Identifier

struct EOS_Mod_Identifier
{
/** API版本 */
int32_t ApiVersion;
/** 此模组项所在的产品名称空间ID */
const char* NamespaceId;
/* 模组的Item ID */
const char* ItemId;
/* 模组的Artifact ID */
const char* ArtifactId;
/** 表示模组项的标题。 */
const char* Title;
/** 表示模组项的版本。 */
const char* Version;
}

EOS_Mod_Identifier 结构体由多个字符串组成,这些字符串共同构成了该模组的唯一标识.该结构体还携带一些模组元数据,包括模组标题和版本。

将字段 ApiVersion 设置为 EOS_MOD_IDENTIFIER_API_LATEST

EOS_Mods_InstallModOptions

struct EOS_Mods_InstallModOptions
{
/** API版本 */
int32_t ApiVersion;
/** 应安装模组的用户的帐号ID */
EOS_EpicAccountId LocalUserId;
/** 要安装的模组 */
const EOS_Mod_Identifier* Mod;
/** 退出游戏后是否卸载模组。 */
EOS_Bool bRemoveAfterExit;
}

EOS_Mods_InstallModOptions 结构体对要安装的模组进行了描述。字段bRemoveAfterExit指示模组SDK在游戏退出后删除一个模组。卸载模组不会从玩家的库中删除模组。

将字段 ApiVersion 设置为 EOS_MODS_INSTALLMOD_API_LATEST

EOS_Mods_InstallCallbackInfo

struct EOS_Mods_InstallModCallbackInfo
{
/** 操作的返回代码。如果安装成功,将返回EOS_Success,否则将返回一个错误代码。 */
EOS_EResult ResultCode;
/** 请求安装模组的用户的帐号ID */
EOS_EpicAccountId LocalUserId;
/** 传给EOS_Mods_InstallMod的上下文 */
void* ClientData;
/** 请求安装的Mod */
const EOS_Mod_Identifier* Mod;
}

EOS_Mods_InstallModCallbackInfo 结构体包含被请求模组的信息以及安装的结果代码。

EOS_Mods_UninstallModOptions

struct EOS_Mods_UninstallModOptions
{
/** API版本 */
int32_t ApiVersion;
/** 要卸载模组的用户的帐号ID */
EOS_EpicAccountId LocalUserId;
/** 要卸载的模组 */
const EOS_Mod_Identifier* Mod;
}

EOS_Mods_UninstallModOptions 结构体包含模组卸载函数的参数。

将字段 ApiVersion 设置为 EOS_MODS_UNINSTALLMOD_API_LATEST

EOS_Mods_UninstallModCallbackInfo

struct EOS_Mods_UninstallModCallbackInfo
{
/** 操作的返回代码。 如果卸载成功,则返回EOS_Success,否则返回一个错误代码。 */
EOS_EResult ResultCode;
/** 请求卸载模组的用户的帐户ID */
EOS_EpicAccountId LocalUserId;
/** 传给EOS_Mods_UninstallMod的上下文 */
void* ClientData;
/** 请求卸载的模组 */
const EOS_Mod_Identifier* Mod;
}

EOS_Mods_UninstallModCallbackInfo 结构体是回调 EOS_Mods_OnUninstallModCallback 的参数类型。结构体包含已卸载模组的信息。

EOS_Mods_EnumerateModsOptions

struct EOS_Mods_EnumerateModsOptions
{
/** API版本 */
int32_t ApiVersion;
/** 应该列举模组的用户的账号ID */
EOS_EpicAccountId LocalUserId;
/** 要列举的模组的类型 */
EOS_EModEnumerationType Type;
}

EOS_Mods_EnumerateModsOptions 结构体定义了模组的枚举查询。Game 字段指向一个游戏标识符,Type 字段定义了要枚举的列表类型。

将字段ApiVersion设置为 'EOS_MODS_ENUMERATEMODS_API_LATEST`。

EOS_Mods_EnumerateModsCallbackInfo

struct EOS_Mods_EnumerateModsCallbackInfo
{
/** 操作的返回代码。 如果列举成功,则返回EOS_Success,否则返回一个错误代码。 */
EOS_EResult ResultCode;
/** 请求模组列举的用户的帐户ID */
EOS_EpicAccountId LocalUserId;
/** 传给EOS_Mods_EnumerateMod的上下文 */
void* ClientData;
/** 列举的模组的类型 */
EOS_EModEnumerationType Type;
}

EOS_Mods_EnumerateModsCallbackInfo 结构体定义了模组枚举回调函数的参数类型。它包含了枚举请求的信息。使用来自该结构体的数据来调用函数 EOS_Mods_CopyModInfo 来获得模组列表的副本。

EOS_Mods_CopyModInfoOptions

struct EOS_Mods_CopyModInfoOptions
{
/** API版本 */
int32_t ApiVersion;
/** 要为其复制模组的用户的帐户ID */
EOS_EpicAccountId LocalUserId;
/** 要复制的被列举模组的类型 */
EOS_EModEnumerationType Type;
}

EOS_Mods_CopyModInfoOptions 结构体包含了列举操作成功后要接收的模组列表的信息。将字段 Type 设置为调用函数 EOS_Mods_EnumerateMods 时使用的相同值。

将字段ApiVersion设置为 EOS_MODS_COPYMODINFO_API_LATEST

EOS_Mods_ModInfo

struct EOS_Mods_ModInfo
{
/** EOS_Mods_ModInfo结构体的API版本 */
int32_t ApiVersion;
/** 列举模组的数量 */
int32_t ModsCount;
/** 列举模组的数组,如果没有列举出该类型的模组,则返回NULL */
EOS_Mod_Identifier* Mods;
/** 模组类型 */
EOS_EModEnumerationType Type;
}

结构体 EOS_Mods_ModInfo 包含了有关已安装的模组或所有可用模组的信息。使用 EOS_Mods_ModInfo 后,调用函数 EOS_Mods_ModInfo_Release 来释放为模组列表数据分配的内存。

将字段 ApiVersion 设置为 EOS_MODS_MODINFO_API_LATEST

EOS_Mods_UpdateModOptions

struct EOS_Mods_UpdateModOptions
{
/** API版本 */
int32_t ApiVersion;
/** 要为其更新模组的用户的账号ID */
EOS_EpicAccountId LocalUserId;
/** 要更新的模组 */
const EOS_Mod_Identifier* Mod;
}

结构体 EOS_Mods_UpdateModOptions 包含要更新的模组的信息。

将字段 ApiVersion 设置为 EOS_MODS_UPDATEMOD_API_LATEST

EOS_Mods_UpdateCallbackInfo

struct EOS_Mods_UpdateModCallbackInfo
{
/** 操作的返回代码。 如果更新请求成功,则返回EOS_Success,否则返回一个错误代码。 */
EOS_EResult ResultCode;
/** 请求模组更新的用户的帐户ID */
EOS_EpicAccountId LocalUserId;
/** 传给EOS_Mods_UpdateMod的上下文 */
void* ClientData;
/** 请求更新的模组 */
const EOS_Mod_Identifier* Mod;
}

EOS_Mods_UpdateModCallbackInfo 结构体定义了模组SDK完成模组更新操作时,传递给回调 EOS_Mods_OnUpdateModCallback 的参数的数据类型。

枚举

EOS_EModEnumerationType

enum EOS_EModEnumerationType
{
/** 安装的模组 */
EOS_MET_INSTALLED = 0,
EOS_MET_AVAILABLE = 1
}

枚举 EOS_EModEnumerationType 定义了函数 EOS_Mods_EnumerateMods 的常量(consts)。EOS_MET_INSTALLED 是指安装到玩家PC上的所有模组。EOS_MET_AVAILABLE 指从游戏模组市场上可以安装的所有模组。

函数

EOS_Mods_InstallMod

EOS_DECLARE_FUNC(void) EOS_Mods_InstallMod(EOS_HMods Handle, const EOS_Mods_InstallModOptions* Options, void* ClientData, const EOS_Mods_OnInstallModCallback CompletionDelegate);

EOS_Mods_InstallMod 是用于请求安装模组的函数。该函数接受一个模组SDK句柄、一个带有模组信息的 EOS_Mods_InstallModOptions 结构体、一个指向返回给调用者的数据的指针(回调函数触发时返回),以及一个指向回调函数的指针。

EOS_Mods_OnInstallModCallback 是函数的回调类型。

EOS_Mods_UninstallMod

EOS_DECLARE_FUNC(void) EOS_Mods_UninstallMod(EOS_HMods Handle, const EOS_Mods_UninstallModOptions* Options, void* ClientData, const EOS_Mods_OnUninstallModCallback CompletionDelegate);

EOS_Mods_UninstallMod 函数会请求模组SDK卸载模组。该函数获取一个模组SDK句柄、一个 EOS_Mods_UninstallModOptions 结构体(包含模组的信息)、一个指向返回给调用者的数据的指针(回调函数触发时返回)、以及一个指向回调函数的指针。

EOS_Mods_OnUninstallModCallback 是函数的回调类型。

EOS_Mods_EnumerateMods

EOS_DECLARE_FUNC(void) EOS_Mods_EnumerateMods(EOS_HMods Handle, const EOS_Mods_EnumerateModsOptions* Options, void* ClientData, const EOS_Mods_OnEnumerateModsCallback CompletionDelegate);