Mods Overview

EOS 생태계에서 모드를 배포 및 관리하는 API

9 분 소요

모드 SDK(Mod SDK) 는 게임 개발자에게 모드 마켓플레이스(Mod Marketplace)와 상호작용할 수 있는 인터페이스를 제공하여 고급 사용 사례를 지원하는 에픽 온라인 서비스(Epic Online Services) 컴포넌트입니다. 이 문서는 모드 SDK의 기능과 사용 사례를 알려주고 API 인터페이스에 관해서도 설명합니다.

현재 이 기능은 데스크톱 플랫폼 및 에픽게임즈 스토어에 입점해있는 제품에서만 사용 가능합니다.

모드 SDK 기능

모드 설치

게임은 모드 마켓플레이스의 특정 모드를 설치 하도록 모드 SDK에 요청할 수 있습니다. 이 작업은 에픽게임즈 런처(Epic Games Launcher) 에서 수행됩니다. 플레이어의 라이브러리 에 해당 모드가 없는 경우 자동으로 추가됩니다. 이는 비동기 작업으로서, 모드가 설치되고 준비되면 콜백 함수를 통해 게임에 알려줍니다.

모드 제거

모드를 제거 하면 설치된 모드가 사용자의 로컬 하드 드라이브에서 제거되지만 플레이어의 라이브러리에서는 제거되지 않습니다. 이는 비동기 작업으로서, 모드 파일이 제거되면 콜백 함수를 통해 게임에 알려줍니다.

모드 업데이트

업데이트(Update) 기능은 모드를 최신 버전으로 업데이트하도록 모드 SDK에 요청합니다. 이는 비동기 작업으로서, 업데이트가 완료되면 콜백 함수를 통해 게임에 알려줍니다.

모드 나열

모드 SDK는 모드 마켓플레이스에서 게임에 사용 가능한 모드 목록과 현재 설치된 사용자 모드 목록을 제공할 수 있습니다. 모드 SDK API 함수 하나면 두 목록이 모두 반환됩니다. 게임이 함수 실행인자로 요청된 목록을 지정합니다. 이는 비동기 작업으로서, 데이터를 가져올 수 있을 때 콜백을 통해 게임에 알려줍니다.

가능한 사용 사례

다음은 모드 SDK를 사용할 수 있는 기능의 예시입니다.

멀티플레이어 게임 모드 버전 조정

클라이언트 게임 인스턴스가 모드를 실행 중인 서버에 연결될 경우, 클라이언트와 서버 둘 다 모드 SDK를 사용하여 클라이언트와 서버 머신에 설치된 모드의 버전을 조정하고 누락된 모드의 목록을 확인합니다.

서버가 모드 나열 함수를 호출하여 설치된 모드의 목록을 가져온 후 설치된 모드의 ID를 시리얼라이즈하여 클라이언트에 전송합니다.

클라이언트가 서버의 모드 목록을 로컬에 설치된 모드와 비교합니다. 필요한 모드가 누락된 경우 클라이언트가 모드 설치 함수를 호출하여 누락된 모드를 설치합니다.

게임 내 모드 매니저

모드 나열, 설치, 제거, 업데이트 함수를 통해 게임 개발자는 게임 내 모드 매니저를 이용할 수 있습니다.

나열 함수를 사용하여 설치된 사용 가능 모드의 목록을 타이틀 및 버전과 함께 가져옵니다. 그런 다음, 설치 및 제거 함수를 사용하여 게임에서 모드를 추가하거나 제거하고, 업데이트 함수를 사용하여 모드를 최신 버전으로 유지합니다.

모드 SDK API

이 섹션은 모드 SDK의 데이터 구조와 함수를 설명합니다.

모드 SDK 초기화 및 종료

EOS_Platform_Create 함수를 호출하여 일반적인 방법으로 EOS SDK를 초기화합니다. 그런 다음, 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;
/* 모드의 아이템 ID */
const char* ItemId;
/* 모드의 아티팩트 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;
/** 설치가 요청된 모드 */
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 함수의 상수를 정의합니다. 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