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);