Platform インターフェース は Epic Online Services (EOS) SDK の中心的なインターフェースであり、他のインターフェースにアクセスするために必要なハンドルを含み、その実行状態を維持します。アプリケーションの起動時、SDK を初期化して、Platform インターフェースへのハンドルを取得できます。このハンドルは、SDK の存続期間中使用できます。
SDK を初期化する
Epic Online Services (EOS) SDK を使用するための最初のステップは、SDK の初期化です。初期化中に、コードは product を特定し、カスタム メモリ割り当て関数をセットアップすることができます。
SDK を設定および作成する
EOS_InitializeOptions データ構造体で (/api-ref/functions/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 5:(https://partners.playstation.net/) で自分のアカウントにログインし、Playstation 4 DevNet で [Development] > [Tools & Middleware] > [Tools & Middleware directory] > [Epic Online Services] の順にクリックします。[Confirm Status (ステータスを確認)] ボタンをクリックします。
-
Xbox One および Series X: – 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 インターフェースにアクセスできます。
| インターフェース | アクセス関数 |
|---|---|
| Achievements | EOS_Platform_GetAchievementsInterface |
| Anti-Cheat | EOS_Platform_GetAntiCheatClientInterface |
EOS_Platform_GetAntiCheatServerInterface | |
| Authentication | EOS_Platform_GetAuthInterface |
| Connect | EOS_Platform_GetConnectInterface |
| Custom Invites | EOS_Platform_GetCustomInvitesInterface |
| Ecommerce | EOS_Platform_GetEcomInterface |
| Friends | EOS_Platform_GetFriendsInterface |
| Leaderboards | EOS_Platform_GetLeaderboardsInterface |
| Lobby | EOS_Platform_GetLobbyInterface |
| Metrics | EOS_Platform_GetMetricsInterface |
| Mods | EOS_Platforms_GetModsInterface |
| P2P | EOS_Platform_GetP2PInterface |
| Player Data Storage | EOS_Platform_GetPlayerDataStorageInterface |
| Presence | EOS_Platform_GetPresenceInterface |
| Progression Snapshot | EOS_Platform_GetProgressionSnapshotInterface |
| Real Time Communications (RTC) | EOS_Platform_GetRTCInterface |
EOS_Platform_GetRTCAdminInterface | |
| Reports | EOS_Platform_GetReportsInterface |
| Sanctions | EOS_Platform_GetSanctionsInterface |
| Sessions | EOS_Platform_GetSessionsInfoInterface |
| Stats | EOS_Platform_GetStatsInterface |
| Title Storage | EOS_Platform_GetTitleStorageInterface |
| User Info | EOS_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_Foreground | Foreground |
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 オーバーレイ) を制御する
使用するプラットフォームの統合を構成するには：
-
EOS_IntegratedPlatform_CreateIntegratedPlatformOptionsContainerを呼び出し、プラットフォーム オプション用の新しい一時コンテナを作成します。 -
プラットフォーム固有の
EOS_IntegratedPlatform_<Platform>_Options構造体を作成し、使用する目的のオプションを指定します。 -
EOS_IntegratedPlatformOptionsContainer_Addを呼び出し、SDK 初期化のためのオプションを登録します。 -
EOS_Platform_Createの呼び出しが成功したら、EOS_IntegratedPlatformOptionsContainer_Releaseを呼び出すことで一時コンテナを解放します。