The Mod SDK is an Epic Online Services component that provides game developers with an interface to interact with the Mod Marketplace for advanced use cases. This document outlines the Mod SDK's capabilities and potential use cases, and documents the API interface.
At this time, this feature is only available for desktop platforms and for products that are part of the Epic Games store.
Mod SDK Capabilities
Installing Mods
A game can request the Mod SDK to install a specific mod from the Mod Marketplace. This action is performed by the Epic Games Launcher. If a player does not have the mod in their Library, the mod will be added automatically. This is an asynchronous operation, and the game will be notified with a callback function when the mod is installed and ready.
Uninstalling Mods
Mod uninstallation removes an installed mod from the user's local hard drive, but it does not remove the mod from the player's Library. This is an asynchronous operation, and the game will be notified with a callback function when mod files are removed.
Updating Mods
The update function requests that the Mod SDK update a mod to the latest version. This is an asynchronous operation, and the game will be notified via a callback function when the update is completed.
Enumerating Mods
The Mod SDK can provide a list of mods available for the game on the Mod Marketplace, as well as a list of the user's currently installed mods. A single Mod SDK API function returns both lists. The game specifies the requested list with a function argument. This is an asynchronous operation, and the game will be notified via callback when the data is available for retrieval.
Potential Use Cases
The following are examples of features that can make use of the Mod SDK:
Multiplayer Game Mod Reconciliation
When a client game instance connects to a server running mods, both the client and server use the Mod SDK to reconcile mods installed on both client and server machines and determine the list of missing mods.
The server calls the mod enumeration function to get a list of installed mods, then serializes the IDs of the installed mods and sends them to the client.
The client compares the server's list of mods with locally installed mods. If any required mods are missing, the client calls the mod install function to install the missing mods.
Ingame Mod Manager
The mod enumeration, installation, uninstallation, and update functions enable game developers to have an in-game mod manager.
Use the enumeration function to get lists of available and installed mods with titles and versions, then use install and uninstall functions to add or remove mods from a game, and use the update function to keep mods up-to-date with their latest versions.
Mod SDK API
This section documents data structures and functions of the Mod SDK.
Mod SDK Initialization and Shutdown
Initialize EOS SDK the usual way by calling the function EOS_Platform_Create. Then call the function EOS_Platform_GetModsInterface to obtain a Mod SDK handle.
/**
* Get a handle to the Mods Interface.
* @return EOS_HMods handle
*
* @see eos_mods.h
* @see eos_mods_types.h
*/
EOS_DECLARE_FUNC(EOS_HMods) EOS_Platform_GetModsInterface(EOS_HPlatform Handle);Data Structures
EOS_Mod_Identifier
struct EOS_Mod_Identifier
{
/** Version of the API */
int32_t ApiVersion;
/** Product namespace id in which this mod item exists */
const char* NamespaceId;
/* Item id of the Mod */
const char* ItemId;
/* Artifact id of the Mod */
const char* ArtifactId;
/** Represent mod item title. */
const char* Title;
/** Represent the mod item version. */
const char* Version;
}The struct EOS_Mod_Identifier is a combination of multiple strings that together uniquely identify a mod. The struct also carries a bit of mod metadata, including mod title and version.
Set the field ApiVersion to EOS_MOD_IDENTIFIER_API_LATEST.
EOS_Mods_InstallModOptions
struct EOS_Mods_InstallModOptions
{
/** Version of the API */
int32_t ApiVersion;
/** Account ID of the user for which the mod should be installed */
EOS_EpicAccountId LocalUserId;
/** The mod to install */
const EOS_Mod_Identifier* Mod;
/** Indicates whether the mod should be uninstalled after exiting the game or not. */
EOS_Bool bRemoveAfterExit;
}The struct EOS_Mods_InstallModOptions describes the mod to install. The field bRemoveAfterExit instructs Mod SDK to remove a mod after the game exits. Mod uninstallation will not remove the mod from a player's library.
Set the field ApiVersion to EOS_MODS_INSTALLMOD_API_LATEST.
EOS_Mods_InstallCallbackInfo
struct EOS_Mods_InstallModCallbackInfo
{
/** Result code for the operation. EOS_Success is returned if the installation was successful, otherwise one of the error codes is returned. */
EOS_EResult ResultCode;
/** Account ID of the user for which mod installation was requested */
EOS_EpicAccountId LocalUserId;
/** Context that was passed into to EOS_Mods_InstallMod */
void* ClientData;
/** Mod for which installation was requested */
const EOS_Mod_Identifier* Mod;
}The struct EOS_Mods_InstallModCallbackInfo contains information about a requested mod and the result code of the installation.
EOS_Mods_UninstallModOptions
struct EOS_Mods_UninstallModOptions
{
/** Version of the API */
int32_t ApiVersion;
/** Account ID of the user for which the mod should be uninstalled */
EOS_EpicAccountId LocalUserId;
/** The mod to uninstall */
const EOS_Mod_Identifier* Mod;
}The EOS_Mods_UninstallModOptions struct contains parameters for the mod uninstall function.
Set the field ApiVersion to EOS_MODS_UNINSTALLMOD_API_LATEST.
EOS_Mods_UninstallModCallbackInfo
struct EOS_Mods_UninstallModCallbackInfo
{
/** Result code for the operation. EOS_Success is returned if the uninstallation was successful, otherwise one of the error codes is returned. */
EOS_EResult ResultCode;
/** Account ID of the user for which mod uninstallation was requested */
EOS_EpicAccountId LocalUserId;
/** Context that was passed into to EOS_Mods_UninstallMod */
void* ClientData;
/** Mod for which uninstallation was requested */
const EOS_Mod_Identifier* Mod;
}The EOS_Mods_UninstallModCallbackInfo struct is the argument type for the callback EOS_Mods_OnUninstallModCallback. The struct contains information about the uninstalled mod.
EOS_Mods_EnumerateModsOptions
struct EOS_Mods_EnumerateModsOptions
{
/** Version of the API */
int32_t ApiVersion;
/** Account ID of the user for which the mod should be enumerated */
EOS_EpicAccountId LocalUserId;
/** Type of the mods to enumerate */
EOS_EModEnumerationType Type;
}The struct EOS_Mods_EnumerateModsOptions defines the mod enumeration query. The field Game points to a game identifier. The field Type defines the type of list to enumerate.
Set the field ApiVersion to EOS_MODS_ENUMERATEMODS_API_LATEST.
EOS_Mods_EnumerateModsCallbackInfo
struct EOS_Mods_EnumerateModsCallbackInfo
{
/** Result code for the operation. EOS_Success is returned if the enumeration was successful, otherwise one of the error codes is returned. */
EOS_EResult ResultCode;
/** Account ID of the user for which mod enumeration was requested */
EOS_EpicAccountId LocalUserId;
/** Context that was passed into to EOS_Mods_EnumerateMod */
void* ClientData;
/** Type of the enumerated mods */
EOS_EModEnumerationType Type;
}The struct EOS_Mods_EnumerateModsCallbackInfo defines the type of argument for a mod enumeration callback function. It contains information about the requested enumeration. Use the data from the struct to call the function EOS_Mods_CopyModInfo to get a copy of the mod list.
EOS_Mods_CopyModInfoOptions
struct EOS_Mods_CopyModInfoOptions
{
/** Version of the API */
int32_t ApiVersion;
/** Account ID of the user for which mods should be copied */
EOS_EpicAccountId LocalUserId;
/** Type of the enumerated mod to copy */
EOS_EModEnumerationType Type;
}The struct EOS_Mods_CopyModInfoOptions contains information about the mod list to receive after a successful enumeration operation. Set the field Type to the same value used to call the function EOS_Mods_EnumerateMods.
Set the field ApiVersion to value EOS_MODS_COPYMODINFO_API_LATEST.
EOS_Mods_ModInfo
struct EOS_Mods_ModInfo
{
/** API Version for the EOS_Mods_ModInfo struct */
int32_t ApiVersion;
/** The count of enumerated mods */
int32_t ModsCount;
/** The array of enumerated mods or NULL if no such type of mods were enumerated */
EOS_Mod_Identifier* Mods;
/** Type of the mods */
EOS_EModEnumerationType Type;
}The struct EOS_Mods_ModInfo contains information about installed mods or about all available mods. Call the function EOS_Mods_ModInfo_Release after you finish using EOS_Mods_ModInfo to release memory allocated for mod list data.
Set the field ApiVersion to the value EOS_MODS_MODINFO_API_LATEST.
EOS_Mods_UpdateModOptions
struct EOS_Mods_UpdateModOptions
{
/** Version of the API */
int32_t ApiVersion;
/** Account ID of the user for which the mod should be updated */
EOS_EpicAccountId LocalUserId;
/** The mod to update */
const EOS_Mod_Identifier* Mod;
}The struct EOS_Mods_UpdateModOptions contains information about a mod to update.
Set the field ApiVersion to EOS_MODS_UPDATEMOD_API_LATEST.
EOS_Mods_UpdateCallbackInfo
struct EOS_Mods_UpdateModCallbackInfo
{
/** Result code for the operation. EOS_Success is returned if the request to update was successful, otherwise one of the error codes is returned. */
EOS_EResult ResultCode;
/** Account ID of the user for which mod update was requested */
EOS_EpicAccountId LocalUserId;
/** Context that was passed into to EOS_Mods_UpdateMod */
void* ClientData;
/** Mod for which update was requested */
const EOS_Mod_Identifier* Mod;
}The struct EOS_Mods_UpdateModCallbackInfo defines the data type of the argument passed to callback EOS_Mods_OnUpdateModCallback when the Mod SDK finishes the mod update operation.
Enums
EOS_EModEnumerationType
enum EOS_EModEnumerationType
{
/** Installed mods */
EOS_MET_INSTALLED = 0,
EOS_MET_AVAILABLE = 1
}The Enum EOS_EModEnumerationType defines consts for the function EOS_Mods_EnumerateMods. A value of EOS_MET_INSTALLED means all mods installed on a player's PC. A value of EOS_MET_AVAILABLE means all mods available for installation from the game Mod Marketplace.
Functions
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 is a function to request mod installation. The function takes a Mod SDK handle, a struct EOS_Mods_InstallModOptions with information about the mod, a pointer to data that will be returned to the caller when the callback fires, and a pointer to the callback function.
EOS_Mods_OnInstallModCallback is the callback type for the function.
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);Function EOS_Mods_UninstallMod requests the Mod SDK to uninstall a mod. The function takes a Mod SDK handle, a struct EOS_Mods_UninstallModOptions with information about the mod, a pointer to data that will be returned to the caller when the callback fires, and a pointer to the callback function.
EOS_Mods_OnUninstallModCallback is the callback type for the function.
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);A game calls the function EOS_Mods_EnumerateMods to get a list of mods available for the game on the Mod Marketplace and a list of installed mods.
EOS_Mods_OnEnumerateModsCallback is the callback type for the function.
EOS_Mods_CopyModInfo
EOS_DECLARE_FUNC(EOS_EResult) EOS_Mods_CopyModInfo(EOS_HMods Handle, const EOS_Mods_CopyModInfoOptions* Options, EOS_Mods_EnumeratedModsInfo** OutEnumeratedMods);The function EOS_Mods_CopyModInfo is used to get a pointer to a game list data struct. Call the function with a pointer to the EOS_Mods_CopyEnumeratedModsOptions struct with the same values used for calling EOS_Mods_EnumerateMods.
EOS_Mods_ModInfo_Release
EOS_DECLARE_FUNC(void) EOS_Mods_ModInfo_Release(EOS_Mods_ModInfo* EnumeratedModInfo);Call the function EOS_Mods_ModInfo_Release to release memory used to store mod list data.
EOS_Mods_UpdateMod
EOS_DECLARE_FUNC(void) EOS_Mods_UpdateMod(EOS_HMods Handle, const EOS_Mods_UpdateModOptions* Options, void* ClientData, const EOS_Mods_OnUpdateModCallback CompletionDelegate);The function EOS_Mods_UpdateMod requests the Mod SDK to update a mod to the latest version. Mod SDK calls callback of type EOS_Mods_OnUpdateModCallback when the update is finished.
Callbacks
EOS_Mods_onInstallModCallback
EOS_DECLARE_CALLBACK(EOS_Mods_OnInstallModCallback, const EOS_Mods_InstallModCallbackInfo* Data);The callback EOS_Mods_OnInstallModCallback defines a function that will be called by the Mod SDK when mod installation completes. The callback receives 1 argument of the type EOS_Mods_InstallModCallbackInfo*.
EOS_Mods_OnUninstallModCallback
EOS_DECLARE_CALLBACK(EOS_Mods_OnUninstallModCallback, const EOS_Mods_UninstallModCallbackInfo* Data);The callback EOS_Mods_OnUninstallModCallback defines a function that will be called by the Mod SDK when mod uninstallation completes. The callback receives 1 argument of the type EOS_Mods_UninstallModCallbackInfo*.
EOS_Mods_OnEnumerateModsCallback
EOS_DECLARE_CALLBACK(EOS_Mods_OnEnumerateModsCallback, const EOS_Mods_EnumerateModsCallbackInfo* Data);The Mod SDK calls the callback EOS_Mods_OnEnumerateModsCallback when the list of mods is ready. The callback receives a pointer to a struct EOS_Mods_EnumerateModsCallbackInfo with information about the performed search.
Call the function EOS_Mods_CopyModInfo to get a copy of the mod list data.