模组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句柄。
数据结构
EOS_Mod_Identifier
EOS_Mod_Identifier
结构体由多个字符串组成,这些字符串共同构成了该模组的唯一标识.该结构体还携带一些模组元数据,包括模组标题和版本。
将字段 ApiVersion
设置为 EOS_MOD_IDENTIFIER_API_LATEST
。
EOS_Mods_InstallModOptions
EOS_Mods_InstallModOptions
结构体对要安装的模组进行了描述。字段bRemoveAfterExit指示模组SDK在游戏退出后删除一个模组。卸载模组不会从玩家的库中删除模组。
将字段 ApiVersion
设置为 EOS_MODS_INSTALLMOD_API_LATEST
。
EOS_Mods_InstallCallbackInfo
EOS_Mods_InstallModCallbackInfo
结构体包含被请求模组的信息以及安装的结果代码。
EOS_Mods_UninstallModOptions
EOS_Mods_UninstallModOptions
结构体包含模组卸载函数的参数。
将字段 ApiVersion
设置为 EOS_MODS_UNINSTALLMOD_API_LATEST
。
EOS_Mods_UninstallModCallbackInfo
EOS_Mods_UninstallModCallbackInfo
结构体是回调 EOS_Mods_OnUninstallModCallback
的参数类型。结构体包含已卸载模组的信息。
EOS_Mods_EnumerateModsOptions
EOS_Mods_EnumerateModsOptions
结构体定义了模组的枚举查询。Game
字段指向一个游戏标识符,Type
字段定义了要枚举的列表类型。
将字段ApiVersion设置为 EOS_MODS_ENUMERATEMODS_API_LATEST
。
EOS_Mods_EnumerateModsCallbackInfo
EOS_Mods_EnumerateModsCallbackInfo
结构体定义了模组枚举回调函数的参数类型。它包含了枚举请求的信息。使用来自该结构体的数据来调用函数 EOS_Mods_CopyModInfo
来获得模组列表的副本。
EOS_Mods_CopyModInfoOptions
EOS_Mods_CopyModInfoOptions
结构体包含了列举操作成功后要接收的模组列表的信息。将字段 Type
设置为调用函数 EOS_Mods_EnumerateMods
时使用的相同值。
将字段ApiVersion设置为 EOS_MODS_COPYMODINFO_API_LATEST
。
EOS_Mods_ModInfo
结构体 EOS_Mods_ModInfo
包含了有关已安装的模组或所有可用模组的信息。使用 EOS_Mods_ModInfo
后,调用函数 EOS_Mods_ModInfo_Release
来释放为模组列表数据分配的内存。
将字段 ApiVersion
设置为 EOS_MODS_MODINFO_API_LATEST
。
EOS_Mods_UpdateModOptions
结构体 EOS_Mods_UpdateModOptions
包含要更新的模组的信息。
将字段 ApiVersion
设置为 EOS_MODS_UPDATEMOD_API_LATEST
。
EOS_Mods_UpdateCallbackInfo
EOS_Mods_UpdateModCallbackInfo
结构体定义了模组SDK完成模组更新操作时,传递给回调 EOS_Mods_OnUpdateModCallback
的参数的数据类型。
枚举
EOS_EModEnumerationType
枚举 EOS_EModEnumerationType
定义了函数 EOS_Mods_EnumerateMods
的常量(consts)。EOS_MET_INSTALLED
是指安装到玩家PC上的所有模组。EOS_MET_AVAILABLE
指从游戏模组市场上可以安装的所有模组。
函数
EOS_Mods_InstallMod
EOS_Mods_InstallMod
是用于请求安装模组的函数。该函数接受一个模组SDK句柄、一个带有模组信息的 EOS_Mods_InstallModOptions
结构体、一个指向返回给调用者的数据的指针(回调函数触发时返回),以及一个指向回调函数的指针。
EOS_Mods_OnInstallModCallback
是函数的回调类型。
EOS_Mods_UninstallMod
EOS_Mods_UninstallMod
函数会请求模组SDK卸载模组。该函数获取一个模组SDK句柄、一个 EOS_Mods_UninstallModOptions
结构体(包含模组的信息)、一个指向返回给调用者的数据的指针(回调函数触发时返回)、以及一个指向回调函数的指针。
EOS_Mods_OnUninstallModCallback
是函数的回调类型。
EOS_Mods_EnumerateMods
游戏调用 EOS_Mods_EnumerateMods
函数来获取模组市场上可供游戏使用的模组列表以及已安装模组的列表。
EOS_Mods_OnEnumerateModsCallback
是该函数的回调类型。
EOS_Mods_CopyModInfo
函数 EOS_Mods_CopyModInfo
用于获取一个指向游戏列表数据结构的指针。用一个指向 EOS_Mods_CopyEnumeratedModsOptions
结构体的指针来调用函数,该指针的值与调用 EOS_Mods_EnumerateMods
的值相同。
EOS_Mods_ModInfo_Release
调用函数 EOS_Mods_ModInfo_Release
来释放用于存储模组列表数据的内存。
EOS_Mods_UpdateMod
函数 EOS_Mods_UpdateMod
请求模组SDK将模组更新到最新版本。模组SDK在更新完成时会调用 EOS_Mods_OnUpdateModCallback
类型的回调。
回调
EOS_Mods_onInstallModCallback
回调 EOS_Mods_OnInstallModCallback
定义了模组SDK在模组安装完成时调用的一个函数。回调接收一个 EOS_Mods_InstallModCallbackInfo*
类型的参数。
EOS_Mods_OnUninstallModCallback
回调 EOS_Mods_OnUninstallModCallback
定义了模组SDK在模组卸载完成时调用的一个函数。回调接收一个 EOS_Mods_UninstallModCallbackInfo
类型的参数。
EOS_Mods_OnEnumerateModsCallback
当模组列表准备好时,模组SDK会调用 EOS_Mods_OnEnumerateModsCallback
回调。回调接收一个指向 EOS_Mods_EnumerateModsCallbackInfo
的指针,其中包含关于已执行搜索的信息。
调用函数 EOS_Mods_CopyModInfo
来获取模组列表数据的副本。