EOS Mod SDK

EOS エコシステムで mod を配布および管理するための API の説明です。

Mod SDK は、高度なユースケースのために Mod Marketplace と相互作用するためのインターフェースをゲーム デベロッパーに提供する Epic Online Services です。このページでは、Mod SDK の機能、潜在的なユースケースの概要を説明し、API インターフェースの記述を付けます。

現時点で Mod SDK は、デスクトップ プラットフォームおよび Epic Games ストアにある一部の製品でのみ利用できます。

Mod SDK の機能

Mod をインストールする

ゲームは Mod Marketplace から特定の mod を インストール するように Mod SDK にリクエストすることができます。アクションは Epic Games Launcher によって実行されます。プレイヤーの ライブラリ に mod がない場合、mod は自動的に追加されます。これは非同期操作です。mod がインストールされて準備が完了すると、コールバック関数によってゲームに通知されます。

Mod をアンインストールする

Mod uninstallation はユーザーのローカル ハード ドライブからインストールされた mod を取り除きますが、プレイヤーのライブラリからは mod を取り除きません。これは非同期操作です。mod ファイルが取り除かれると、コールバック関数によってゲームに通知されます。

Mod を更新する

更新 関数は mod を最新バージョンに更新するように Mod SDK にリクエストします。これは非同期操作です。更新が完了すると、コールバック関数によってゲームに通知されます。

Mod を列挙する

Mod SDK は Mod Marketplace でゲームに利用することができる mod のリストおよび現在ユーザーによってインストールされている mod のリストを提供することができます。1 つの Mod SDK API 関数が両方のリストを返します。ゲームは関数の引数を使用して、リクエストされたリストを指定します。これは非同期操作です。データが取得可能になりると、コールバック関数によってゲームに通知されます。

潜在的なユースケース

以下は、Mod SDK を使用することができる機能の例です。

マルチプレイヤー ゲームの mod 調整

クライアント ゲーム インスタンスがサーバー実行 mod に接続すると、クライアントとサーバーの両方が Mod SDK を使って、クライアントとサーバーの両方のマシンにインストールされている mod を調整して、不足している mod のリストを特定します。

サーバーは mod 列挙関数を呼び出して、インストールされている mod のリストを取得し、インストールされている mod の ID をシリアライズして、それらをクライアントに送信します。

クライアントはサーバーの mod リストをローカルにインストールされている mod と比較します。必要な mod がない場合、クライアントは mod インストールを呼び出して不足している mod をインストールします。

Ingame Mod Manager

mod の列挙、インストール、アンインストール、更新用の関数を使って、ゲーム デベロッパーはインゲーム mod マネージャを使用することができます。

列挙関数を使ってタイトルとバージョンで利用可能でインストールされている mod のリストを取得し、インストール関数およびアンインストール関数を使ってゲームへの追加またはゲームからの削除を行い、更新関数を使って mod を最新バージョンの状態にします。

Mod SDK API

このセクションでは、Mod SDK のデータ構造および関数について説明します。

Mod SDK の初期化およびシャットダウン

関数 EOS_Platform_Create を呼び出して、通常の方法で EOS SDK を初期化します。次に関数 EOS_Platform_GetModsInterface を呼び出して Mod SDK ハンドルを取得します。

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

データ構造

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

EOS_Mod_Identifier 構造体は、mod を一意に特定する複数の文字の組み合わせです。この構造体には mod のタイトルやバージョンなどの mod メタデータも一部含まれています。

フィールド ApiVersionEOS_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;
}

構造体 EOS_Mods_InstallModOptions はインストールする mod を説明します。フィールド bRemoveAfterExit は、ゲーム終了後に mod を削除するように Mod SDK に指示します。Mod をアンインストールしても、プレーヤーのライブラリから mod は削除されません。

フィールド ApiVersionEOS_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;
}

構造体 EOS_Mods_InstallModCallbackInfo には、リクエストされた mod とインストールの結果コードに関する情報が含まれています。

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

EOS_Mods_UninstallModOptions 構造体には mod アンインストール関数用のパラメータが含まれています。

フィルード ApiVersionEOS_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;
}

EOS_Mods_UninstallModCallbackInfo 構造体は、コールバック EOS_Mods_OnUninstallModCallback の引数タイプです。構造体にはアンインストールされた 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;
}

構造体 EOS_Mods_EnumerateModsOptions は mod 列挙クエリーを定義します。フィールド Game はゲーム識別子を指定します。フィールド Type は列挙するリストの種類を定義します。

フィールド ApiVersionEOS_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;
}

構造体 EOS_Mods_EnumerateModsCallbackInfo は mod 列挙コールバック関数の引数タイプを定義します。リクエストされた列挙に関する情報が含まれています。構造体のデータを使って関数 EOS_Mods_CopyModInfo を呼び出して mod リストのコピーを取得します。

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

EOS_Mods_CopyModInfoOptions 構造体には、列挙操作が通常に完了した後に受け取る mod リストに関する情報が含まれます。フィールド Type を同じ値に設定して、関数 EOS_Mods_EnumerateMods を呼び出します。

フィールド ApiVersion を値 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;
}

構造体 EOS_Mods_ModInfo にはインストールされている mod または利用可能なすべての mod に関する情報が含まれています。EOS_Mods_ModInfo の使用後に関数 EOS_Mods_ModInfo_Release を呼び出して、mod リスト データにアロケートされていたメモリを解放します。

フィールド ApiVersion を値 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;
}

構造体 EOS_Mods_UpdateModOptions には更新する mod に関する情報が含まれています。

フィールド ApiVersionEOS_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;
}

構造体 EOS_Mods_UpdateModCallbackInfo は、Mod SDK が mod 更新操作を完了した時に EOS_Mods_OnUpdateModCallback を呼び出すために渡される引数のデータ タイプを定義します。

列挙型変数

EOS_EModEnumerationType

enum EOS_EModEnumerationType
{
    /** Installed mods */
    EOS_MET_INSTALLED = 0,
    EOS_MET_AVAILABLE = 1
}

列挙型変数 EOS_EModEnumerationType は関数 EOS_Mods_EnumerateMods の const を定義します。EOS_MET_INSTALLED の値は、プレイヤーの PC にインストールされているすべての mod を意味します。EOS_MET_AVAILABLE の値はゲームの Mod Marketplace からインストール可能なすべての mod を意味します。

関数

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 は mod のインストールをリクエストする関数です。関数は、Mod SDK ハンドル、mod に関する情報を含む構造体 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 は mod をアンインストールするように Mod SDK に要求します。関数は、Mod SDK ハンドル、mod に関する情報を含む構造体 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);

ゲームは関数 EOS_Mods_EnumerateMods を呼び出して、Mod Marketplace でゲームに利用することができる mod のリストおよびインストールされた mod のリストを取得します。

EOS_Mods_OnEnumerateModsCallback は関数のコールバック タイプです。

EOS_Mods_CopyModInfo

EOS_DECLARE_FUNC(EOS_EResult) EOS_Mods_CopyModInfo(EOS_HMods Handle, const EOS_Mods_CopyModInfoOptions* Options, EOS_Mods_EnumeratedModsInfo** OutEnumeratedMods);

関数 EOS_Mods_CopyModInfo はゲーム リスト データ構造体へのポインタを取得するために使用します。EOS_Mods_EnumerateMods の呼び出しに使用したのと同じ値で EOS_Mods_CopyEnumeratedModsOptions 構造体のポインタを使って関数を呼び出します。

EOS_Mods_ModInfo_Release

EOS_DECLARE_FUNC(void) EOS_Mods_ModInfo_Release(EOS_Mods_ModInfo* EnumeratedModInfo);

mod リスト データを格納するために使用したメモリを解放するために関数 EOS_Mods_ModInfo_Release を呼び出します。

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

関数 EOS_Mods_UpdateMod は mod を最新バージョンに更新するように Mod SDK にリクエストします。更新が完了すると Mod SDK はコールバック タイプ EOS_Mods_OnUpdateModCallback を呼び出します。

コールバック

EOS_Mods_onInstallModCallback

EOS_DECLARE_CALLBACK(EOS_Mods_OnInstallModCallback, const EOS_Mods_InstallModCallbackInfo* Data);

コールバック EOS_Mods_OnInstallModCallback は、mod インストールが完了したときに Mod SDK に呼び出される関数を定義します。コールバックは 1 つの引数タイプ EOS_Mods_InstallModCallbackInfo* を受け取ります。

EOS_Mods_OnUninstallModCallback

EOS_DECLARE_CALLBACK(EOS_Mods_OnUninstallModCallback, const EOS_Mods_UninstallModCallbackInfo* Data);

コールバック EOS_Mods_OnUninstallModCallback は、mod アンインストールが完了したときに Mod SDK に呼び出される関数を定義します。コールバックは 1 つの引数タイプ EOS_Mods_UninstallModCallbackInfo* を受け取ります。

EOS_Mods_OnEnumerateModsCallback

EOS_DECLARE_CALLBACK(EOS_Mods_OnEnumerateModsCallback, const EOS_Mods_EnumerateModsCallbackInfo* Data);

Mod SDK は mod のリストの準備が完了するとコールバック EOS_Mods_OnEnumerateModsCallback を呼び出します。コールバックは実行された検索に関する情報を含む構造体 EOS_Mods_EnumerateModsCallbackInfo のポインタを受け取ります。 関数 EOS_Mods_CopyModInfo を呼び出して、mod リスト データのコピーを取得します。