Platform Interface

他のすべてのインターフェースにアクセスできるインターフェースです。

9 分で読めます

Platform インターフェースEpic Online Services (EOS) SDK の中心的なインターフェースであり、他のインターフェースにアクセスするために必要なハンドルを含み、その実行状態を維持します。アプリケーションの起動時、SDK を初期化して、Platform インターフェースへのハンドルを取得できます。このハンドルは、SDK の存続期間中使用できます。

SDK を初期化する

Epic Online Services (EOS) SDK の使用する最初のステップは初期化です。初期化中に、コードは製品を特定し、カスタム メモリ割り当て関数をセットアップすることができます。

SDK を設定および作成する

EOS_InitializeOptions データ構造体で EOS_Initialize を呼び出して、EOS SDK を初期化します。構造体を次のように設定します。

プロパティ
ApiVersion EOS_INITIALIZE_API_LATEST
ProductName

SDK を使用する製品の名前。名前の文字列は、空白であってはならず、最大 64 文字までがサポートされています。

ProductVersion SDK を使用するアプリケーションの製品バージョン
Reserved NULL
AllocateMemoryFunction

カスタム malloc 関数 (EOS_AllocateMemoryFunc 型) または「NULL

この関数はメモリ配列を設定するポインタを返す必要があります。

ReallocateMemoryFunction

カスタム realloc 関数 (EOS_ReallocateMemoryFunc 型) または「NULL

ReleaseMemoryFunction カスタム free 関数 (EOS_ReleaseMemoryFunc 型) または「NULL」
SystemInitializeOptions

システム固有の初期化用フィールド。指定されている場合、情報は「EOS_<system>_InitializeOptions」構造体に渡されます。ここでの「<system>」とは初期化されるシステムのことです。

OverrideThreadAffinity

EOS_Initialize_ThreadAffinity タイプのスレッド アフィニティー初期化用のフィールド。この情報は (提供される場合) EOS SDK の操作中にスレッドを作成するときに使用されます。null に設定すると、EOS SDK はデフォルト スキームを使ってスレッド アフィニティーを決定します。EOS_Initialize_ThreadAffinity 構造体は使用するスレッドのカテゴリを特定するアフィニティー マークです。

EOS_Initialize は、成否を示す EOS_EResult を返します。SDK の初期化に成功した場合、値は EOS_Success になります。失敗した場合は EOS_AlreadyConfigured などのエラーを示す値になります。SDK を初期化した後、Platform インターフェース を作成することができます。

コンソール SDK へのアクセスをリクエストする

Developer Portal は、Playstation Network と XBox Live でのオンライン サービスでのユーザー認証機能など、EOS SDK を使用したいコンシューマー向けゲーム デベロッパーをサポートします。ただし、デベロッパーは最初に、コンシューマー向けプラットフォーム ホルダーでステータスを確認する必要があります。プラットフォーム ホルダーはそれぞれ独自の確認手順があります。

  • Nintendo Switch: Nintendo Developer Portal で自分のアカウントにログインし、[Getting Started] > [Nintendo Switch Middleware] > [Unreal Engine:Learn More] の順にクリックします。フォームに記入して送信します。

  • Playstation 4: Playstation Partners Portal で自分のアカウントにログインし、Playstation 4 DevNet[Development] > [Tools & Middleware] > [Tools & Middleware directory] > [Unreal Engine 4[ の順にクリックします。[Confirm Status (ステータスを確認)] ボタンをクリックします。

  • Xbox One: – Microsoft アカウント担当者に連絡し、 consoles@unrealengine.com にメールを送信してメールアドレスを参照するように依頼します。

ステータスを確認すると、コンソール SDK へのアクセスおよびサポートを受ける資格を得ることができます。この資格には、EULA またはカスタム ライセンスのいずれか、および Unreal Engine パートナー以外での Unreal Engine パートナーが含まれます。

コールバックをログ記録する

SDK は冗長性の様々なレベルで有益な情報を記録します。 コールバックを EOS_Logging_SetCallback で登録すると、この出力へのアクセスが許可されます。EOS_LogMessageFunc 型の関数を実装して EOS_LogMessage データ構造体を受け取ります。

  • Category:ログ メッセージのカテゴリに対応する文字列 (EOS_ELogCategory API リファレンスを参照してください)
  • Message:文字列としてのメッセージ
  • Level:ログ メッセージの冗長性レベル (EOS_ELogLevel API リファレンスを参照してください)

EOS_Logging_SetLogLevel を使用して、ログ記録の詳細レベルを調整することができます。

Platform インターフェース

Platform インターフェースは他のすべての EOS SDK インターフェースへのアクセスを提供し、その実行状態を維持します。Platform インターフェースを作成すると、そのインターフェースを使用して他のインターフェースへのハンドルを取得したり、「ticking」と呼ばれるフレームごとの更新コードを実行するように指示することができます。

Platform インターフェースを作成する

次の情報を含む EOS_Platform_Options 構造体を使用して EOS_Platform_Create 関数を呼び出し、Platform インターフェースを作成します。

プロパティ
ApiVersion EOS_PLATFORM_OPTIONS_API_LATEST
Reserved NULL
ProductId Epic Games によって提供されるゲームの製品 ID
SandboxId Epic Games によって提供される、ゲームのサンドボックス ID
ClientCredentials

ホスト アプリケーションに割り当てられたクライアント ID とクライアント シークレットのペア

エンドユーザー ゲーム クライアントなどの一般公開されているアプリケーションでは、信頼されているゲーム サーバー バックエンドとは異なる資格情報を使用します。

bIsServer

アプリケーションがローカル ユーザーのクライアントとして実行されている場合は EOS_False に設定します。専用ゲーム サーバーの場合は EOS_True を設定します。

EncryptionKey

16 進形式 (64 桁の 16 進数) でファイルを暗号化するための 256 ビットの暗号化キー

OverrideCountryCode ログインしたユーザーのオーバーライド国コード
OverrideLocaleCode ログインしたユーザーのオーバーライド ローカル コード
DeploymentId Epic Games によって提供されるゲームのデプロイ ID
Flags

EOS_PF_ フラグのビット単位または結合として表現される Platform 作成フラグ

CacheDirectory 一時データのキャッシュに使用されるフォルダへの絶対パス
TickBudgetInMilliseconds

EOS_Platform_Tick が処理を行うための予算 (ミリ秒単位で測定)。予算に達するか、または予算を超過した場合 (または可能な処理がない場合)、 EOS_Platform_Tick が返されます。実行する多数の処理がキューに入れられた場合、これを利用すると、ゲームで SDK の処理の負荷を複数のフレームにわたって償却できます。ゼロは「すべての可能な処理を実行する」と解釈されます。

RTCOptions

Real Time Communication 機能を使用するための EOS_Platform_RTCOptions 構造体に対するポインタ。NULL を使用すると、音声などの RTC 機能が無効になります。

IntegratedPlatformOptionsContainerHandle

統合プラットフォームをセットアップするためのすべてのオプションを含むハンドル。「NULL」に設定すると、ホスト プラットフォーム用のデフォルトの統合プラットフォームの動作が使用されます。

成功すると、EOS_Platform_Create は Platform インターフェースへのハンドル (EOS_HPlatform 型) を返します。

エディタなどの複数のビューをサポートするアプリケーションでは、複数の Platform インターフェース ハンドルの作成が必要になることがあります。しかし、これに対して分割画面方式のゲームなど、同一のデバイスでプレイする複数のユーザーをサポートする必要はありません。SDK は複数の Platform インターフェース インスタンスをサポートしますが、それぞれが独自の内部ステートを保持しています。取得する他のインターフェースは、それらを取得した Platform インターフェースに対して一意となっています。SDK 自体の複数のインスタンスを初期化しないでください。

Platform インターフェースを使用する

EOS_HPlatform ハンドルを取得したら、ハンドル アクセス関数を通じて他の EOS SDK インターフェースにアクセスできます。

インターフェースアクセス関数
AchievementsEOS_Platform_GetAchievementsInterface
Anti-CheatEOS_Platform_GetAntiCheatClientInterface
EOS_Platform_GetAntiCheatServerInterface
AuthenticationEOS_Platform_GetAuthInterface
ConnectEOS_Platform_GetConnectInterface
Custom InvitesEOS_Platform_GetCustomInvitesInterface
EcommerceEOS_Platform_GetEcomInterface
FriendsEOS_Platform_GetFriendsInterface
LeaderboardsEOS_Platform_GetLeaderboardsInterface
LobbyEOS_Platform_GetLobbyInterface
MetricsEOS_Platform_GetMetricsInterface
[Mods] (EpicGamesStore/TechFeaturesConfig/Mods)EOS_Platforms_GetModsInterface
P2PEOS_Platform_GetP2PInterface
Player Data StorageEOS_Platform_GetPlayerDataStorageInterface
PresenceEOS_Platform_GetPresenceInterface
Progression SnapshotEOS_Platform_GetProgressionSnapshotInterface
Real Time Communications (RTC)EOS_Platform_GetRTCInterface
EOS_Platform_GetRTCAdminInterface
ReportsEOS_Platform_GetReportsInterface
SanctionsEOS_Platform_GetSanctionsInterface
SessionsEOS_Platform_GetSessionsInfoInterface
StatsEOS_Platform_GetStatsInterface
[Title Storage] (GameServices/TitleStorage)EOS_Platform_GetTitleStorageInterface
User InfoEOS_Platform_GetUserInfoInterface

Platform インターフェースは、他のインターフェースにアクセスできるだけでなく、それらのインターフェースの実行状態を維持できます。ゲームのメイン ループで毎フレーム EOS_Platform_Tick を呼び出すと、非同期関数が継続して更新されます。

ランチャーでアプリケーションを再起動する

EOS_HPlatform ハンドルを EOS_Platform_CheckForLauncherAndRestart に渡すと、EOS はアプリケーションがランチャーを介して起動されたかどうかをチェックします。違う場合はランチャーからアプリケーションを再起動します。その際、次のコードを持つ EOS_EResult が返されます。

  • EOS_Success:アプリケーションはランチャーで再起動中です。現在のアプリケーションのプロセスは、新しく起動したプロセスを優先させるためにできるだけ早く終了する必要があります。
  • EOS_NoChange:すでにアプリケーションがランチャーから起動されている場合、追加操作は行われません。
  • EOS_UnexpectedError:LauncherCheck モジュールが初期化に失敗したか、アプリケーションの再起動に失敗しました。

この関数は、ストアで公開されていて、すでにランチャーからアクセス可能なアプリケーションにのみ関連しています。

SDK をシャットダウンする

ゲームを終了するには、Platform インターフェースによって保持されているメモリと、SDK によって保持されているグローバル ステートを解放する必要があります。シャットダウンするには、まず EOS_HPlatform ハンドルを EOS_Platform_Release 関数に渡します。その後、EOS_Shutdown を呼び出してプロセスを完了してシャットダウンします。

EOS_Shutdown を呼び出した後は、EOS SDK を再初期化することができません。それ以上の呼び出しは失敗します。

アプリケーションとネットワーク ステータス

アプリケーション ステータスが変わる時、EOS_Platform_SetApplicationStatus を呼び出す必要があります。これらは NewStatus パラメータを使用して設定することができます。

EOS_EApplicationStatus 構造体を使用して、次のアプリケーション ステータスが定義されます。

EOS_AS_BackgroundConstrained制限されたバックグラウンド。
EOS_AS_BackgroundUnconstrained制限されていないバックグラウンド。
EOS_AS_BackgroundSuspended一時停止されたバックグラウンド。
EOS_AS_ForegroundForeground

EOS_Platform_GetApplicationStatus を使用し、現在のアプリケーション ステータスを取得することもできます。

これらのアプリケーションの変更の特性は、プラットフォームによって異なります (詳細については、プラットフォーム固有のドキュメントを参照してください)。

ネットワーク ステータスが変わる時、EOS_Platform_SetNetworkStatus を呼び出す必要があります。ネットワーク ステータスは NewStatus パラメータを使用して設定することができます。

EOS_ENetworkStatus 構造体を使用して、次のネットワーク ステータスが定義されます。

EOS_NS_Disabledネットワークは使用できません。
EOS_NS_Offlineインターネットに接続できない可能性があります。ネットワークはまだ使用されていますが、おそらく障害が発生していると予想されます。
EOS_NS_Onlineインターネットに接続されているようです。

EOS_Platform_GetNetworkStatus を使用して現在のネットワーク ステータスを取得することもできます。

これらのネットワークの変更の特性は、プラットフォームによって異なります (詳細については、プラットフォーム固有のドキュメントを参照してください)。

注記: 特定のプラットフォームでは、デフォルトのネットワーク ステータスは EOS_NS_Disabled であり、ネットワークが利用可能な場合、EOS_Platform_SetNetworkStatus を呼び出す必要があります (詳細については、プラットフォーム固有のドキュメントを参照してください)。

プラットフォームのネイティブの統合

SDK には、ネイティブ プラットフォームと自動的に統合するための機能が用意されています。これらの統合を利用すると、ゲームで次のことが可能です。

  • プラットフォームのフレンドを、EOS オーバーレイのフレンド リストに含める

  • ネイティブ プラットフォームのプレゼンスを使用し、ローカルの Epic ユーザーのプレゼンスの状態をミラーリングする

  • ネイティブ プラットフォーム システムを使用し、EOS Lobbies および EOS Sessions のゲームの招待をレプリケートする

  • プラットフォームのフレンドに対し、ローカル ユーザーの EOS ロビーまたはセッションへのプレゼンスを使用した参加を有効にする

  • ゲームの招待の通知を表示するために使用されるシステム (Game UI、Platform UI、EOS オーバーレイ) を制御する

使用するプラットフォームの統合を構成するには:

  1. EOS_IntegratedPlatform_CreateIntegratedPlatformOptionsContainer を呼び出し、プラットフォーム オプション用の新しい一時コンテナを作成します。

  2. プラットフォーム固有の EOS_IntegratedPlatform_<Platform>_Options 構造体を作成し、使用する目的のオプションを指定します。

  3. EOS_IntegratedPlatformOptionsContainer_Add を呼び出し、SDK 初期化のためのオプションを登録します。

  4. EOS_Platform_Create の呼び出しが成功したら、EOS_IntegratedPlatformOptionsContainer_Release を呼び出すことで一時コンテナを解放します。

サンプル コード

static EOS_EResult CreateIntegratedPlatform(EOS_Platform_Options& PlatformOptions)
{
// Create the generic container.
const EOS_IntegratedPlatform_CreateIntegratedPlatformOptionsContainerOptions CreateOptions =
{
EOS_INTEGRATEDPLATFORM_CREATEINTEGRATEDPLATFORMOPTIONSCONTAINER_API_LATEST
};
const EOS_EResult Result = EOS_IntegratedPlatform_CreateIntegratedPlatformOptionsContainer(&CreateOptions, &PlatformOptions.IntegratedPlatformOptionsContainerHandle);
if (Result != EOS_EResult::EOS_Success)
{
return Result;
}
// Configure platform-specific options.
const EOS_IntegratedPlatform_Steam_Options PlatformSpecificOptions =
{
EOS_INTEGRATEDPLATFORM_STEAM_OPTIONS_API_LATEST,
nullptr
};
// Add the configuration to the SDK initialization options.
const EOS_IntegratedPlatform_Options Options =
{
EOS_INTEGRATEDPLATFORM_OPTIONS_API_LATEST,
EOS_IPT_Steam,
EOS_EIntegratedPlatformManagementFlags::EOS_IPMF_LibraryManagedByApplication | EOS_EIntegratedPlatformManagementFlags::EOS_IPMF_DisableSDKManagedSessions,
&PlatformSpecificOptions
};
const EOS_IntegratedPlatformOptionsContainer_AddOptions AddOptions =
{
EOS_INTEGRATEDPLATFORMOPTIONSCONTAINER_ADD_API_LATEST,
&Options
};
return EOS_IntegratedPlatformOptionsContainer_Add(PlatformOptions.IntegratedPlatformOptionsContainerHandle, &AddOptions);
}
static void FreeIntegratedPlatform(EOS_Platform_Options& PlatformOptions)
{
// Free the created container after SDK initialization.
if (PlatformOptions.IntegratedPlatformOptionsContainerHandle)
{
EOS_IntegratedPlatformOptionsContainer_Release(PlatformOptions. IntegratedPlatformOptionsContainerHandle);
PlatformOptions.IntegratedPlatformOptionsContainerHandle = nullptr;
}
}
void InitializeEosSdk()
{
EOS_Platform_Options PlatformOptions = {};
CreateIntegratedPlatform(PlatformOptions);
// ...
EOS_Platform_Create(&PlatformOptions);
FreeIntegratedPlatform(PlatformOptions);
}