概要
Epic Online Services (EOS) Software Development Kit (SDK) とは、ゲーム内で EOS へのアクセスを可能にする一連のツールです。次のような一部の Unreal Engine (UE) プラグイン は EOS SDK が機能することに依存しています。
- Online Subsystem EOS プラグイン (OSS EOS)
- Online Services EOS プラグイン (OSSv2 EOS)
- EOS Voice Chat プラグイン
このページでは、以下の方法について説明します。
Epic Online Services の詳細については、このページの「追加リソース」セクションを参照してください。
EOS SDK の場所
EOS SDK モジュールは次のディレクトリに保存されます。
UNREAL_ENGINE_ROOT/Engine/Source/ThirdParty/EOSSDK
プラグインおよびモジュールにこの EOS SDK モジュールを依存関係として追加することで、それらを EOS SDK に依存させることができます。
EOS SDK モジュール関連のモジュール
このモジュールには複数のプラットフォーム固有の拡張機能が備わっており、次のディレクトリにプラットフォーム固有の EOS SDK が含まれています。
UNREAL_ENGINE_ROOT/Engine/Platforms/<PLATFORM>/Source/ThirdParty/EOSSDK
EOS Shared プラグインでは共通の EOS 機能が公開されます。また、このプラグインでは EOS SDK ランタイム ライブラリの初期化と終了も行われます。EOS Shared プラグインは次のディレクトリにあります。
UNREAL_ENGINE_ROOT/Engine/Plugins/Online/EOSShared
EOS SDK をアップグレードする
EOS SDK のアップグレードには以下の 3 つの方法があります。
方法 | 説明 |
---|---|
ライブラリとヘッダの完全アップグレード | 最新の SDK バージョンによる新しい API とバグ修正のメリットを得るには、この方法を選択します。 |
ライブラリのみのアップグレード | 最新の SDK バージョンによるバグ修正 (新しい API は除く) のメリットを得るには、この方法を選択します。 |
プロジェクトのオーバーライドによるアップグレード | エンジン モジュールをコンパイルした EOS SDK のバージョンとは異なるバージョンに対してプロジェクト モジュールをコンパイルする場合は、この方法を選択します。 |
ライブラリとヘッダの完全アップグレード
この方法では、ライブラリとヘッダ ファイルを含む SDK 全体がアップグレードされます。これによってエンジンとプラグインを新しいヘッダに対してリビルドすることができるため、最新の SDK リリースに含まれる新しい API とバグ修正をすべて利用することができます。
手順
EOS SDK の完全アップグレードを行うには、次のステップを実行します。
- EOS デベロッパー ポータル から希望の EOS SDK バージョンをダウンロードします。
- 「
Engine/Source/ThirdParty/EOSSDK/
」ディレクトリで次を実行します。- このディレクトリに保存されている「
EOSSDK.Build.cs
」またはその他のルーズ ファイルは削除しないでください。 - 「
Engine/Source/ThirdParty/EOSSDK/
」のすべてのサブディレクトリを削除します。
- このディレクトリに保存されている「
- 新しい SDK の
.zip
ファイルを「Engine/Source/ThirdParty/EOSSDK/
」に抽出します。これにより、「SDK
」という名前のフォルダが「Engine/Source/ThirdParty/EOSSDK/SDK
」に作成されます。 - ほかにも追加するプラットフォーム固有の SDK がある場合は、上記のステップ 1 ~ 3 を繰り返します。
- Android および iOS:
.zip
ファイルを SDK のベース ディレクトリの「Engine/Source/ThirdParty/EOSSDK/
」に抽出します。 - 他のプラットフォーム:
.zip
ファイルをそれぞれの「Engine/Platforms/<PLATFORM>/Source/ThirdParty/EOSSDK/
」にある各プラットフォーム固有の拡張機能に抽出します。
- Android および iOS:
- 「
Engine/Source/ThirdParty/EOSSDK/SDK/Bin/libEOSSDK-Mac-Shipping.dylib
」ファイルを「Engine/Binaries/ThirdParty/EOSSDK/Mac/libEOSSDK-Mac-Shipping.dylib
」に移動します。
EOS SDK の更新には破壊的コード変更や必須のコード変更が含まれる場合があります。必須のコード変更の詳細については、「EOS SDK のリリース ノート」を参照することをお勧めします。
EOS エンジン プラグインの API バージョン
多くの EOS エンジン プラグインは、API_LATEST
を使用するのではなく、EOS オプション構造体の固有の API バージョンの設定に移行済みです。
以前の動作
EOS エンジン プラグインでは、以前は API_LATEST
を EOS オプション構造体におけるバージョン番号として使用していました。この結果、完全アップグレードの方法で EOS SDK をアップグレードしてエンジン プラグインをリビルドした際に、SDK によって「破壊的変更 (互換性を破る変更)」が生じる場合があります。こうした破壊的変更は、EOS SDK では新しい API バージョンで定義された動作コントラクトを使用する一方で、その EOS SDK を使用するエンジン プラグインでは、そのプラグインのコンパイル時にもともと対象としたヘッダ ファイルからのより古い API バージョンで定義されたコントラクトを想定していることが原因で発生します。これが発生した場合は、新しいコントラクトを使用するように、すべてのエンジン プラグインをユーザーの責任において更新する必要がありました。
現在の動作
現在は、API_LATEST
の代わりに、プラグインの作成時に対象としたヘッダで指定されている API バージョンが使用されます。つまり、完全アップグレードを実行しても、エンジン コードでは古いヘッダからの API バージョンが使用されることを意味します。結果として、EOS SDK ではプラグインの作成時に対象としたコントラクトが引き続き使用されます。これによって、エンジン プラグインはライブラリのみのアップグレードを行ったときと同じように動作します。
これは、EOS を使用するエンジン プラグインを SDK アップグレードによる破壊的変更の影響を受けにくくすることを目的としています。場合によっては、SDK によってオプション構造体のフィールド名が変更されたり、それらがすべて削除されたりすることがあります。SDK によってフィールド名が変更されたり削除されたりした場合は、新しいヘッダでのコンパイルが失敗する可能性があります。コンパイルが失敗した場合は、オプション構造体の定義を古いヘッダからコピーしてコードに貼り付けて、古い定義が引き続き使用されるようにします。
例
プログラムのネットワーク ステートを設定するための API が EOS SDK によって追加された状況を考えてみましょう。以前のデフォルト ステートであった「オンライン」が、破壊的変更によって新しい SDK ではデフォルトで「オフライン」になりました。エンジン プラグインは API_LATEST
をパスするため、新しい SDK に対してこれらのエンジン プラグインをリビルドすると、SDK は「オフライン」になります。
UE にはこの新しい API のサポートが存在しないため、ネットワークのステートを「オンライン」に設定することができません。このため、SDK は「オフライン」ステートのままになり、機能しなくなります。
古い API バージョン (コードの作成に使用されたヘッダの API_LATEST
値) がパスされていれば、SDK ではネットワーク ステート API の追加よりも前のヘッダに対して作成されたものによって呼び出されたことを認識して、DLL のみのアップグレードが行われたかのように処理を続けたはずです。
API バージョンの警告
EOS プラグインの以前の共通パターンは、EOS オプション構造体が使用されている場所の隣に static_asserts
を加えることでした。これらのアサートは、そのオプション構造体の API_LATEST
の値が変更したときに発行されました。これによって変更に関する警告が発せられ、必要なアクションを促すプロンプトが表示されました。
残念ながら、アサートを使用することで、EOS SDK の完全アップグレード (ライブラリとヘッダのアップグレード) を実行した場合に、こうした API バージョンの差異が生じてコンパイルが失敗する可能性もありました。これを修正するために、当社では static_asserts
を、コンパイル時に警告を発する「非推奨に似た」メカニズムに置き換えました。
サイレンス警告
API バージョンの警告を無音 (サイレンス) にするには、「DefaultEngine.ini
」などの任意のエンジン コンフィギュレーション ファイルに次のセクションを追加します。
[EOSShared]
bEnableApiVersionWarnings=false;
ライブラリのみのアップグレード
この方法ではライブラリ ファイルのみがアップグレードされて、ヘッダ ファイルはアップグレードされません。これによって最新の SDK リリースに含まれるバグ修正のメリットを得たり、SDK を異なるプラットフォーム SDK バージョンに対してビルドされたバージョンに切り替えたりすることができます。ヘッダは変更されないため、この方法ではエンジンやプラグインのリビルドは必要ありません。SDK は、その作成時に対象とした SDK バージョン (ヘッダの SDK バージョン) での動作と同じように引き続き動作します。
手順
EOS SDK のライブラリのみのアップグレードを行うには、次のステップを実行します。
- 次のファイル形式をそれぞれの場所で置き換えます。
.dll
.so
.dylib
- それぞれの場所にある他のプラットフォーム固有のバイナリ ファイル。
- 使用するプラットフォームに応じて次を実行します。
- Mac の場合: バイナリは「
Engine/Binaries/ThirdParty/EOSSDK
」にあります。「Engine/Source/ThirdParty/EOSSDK
」や「Engine/Platforms/<PLATFORM>/Source/ThirdParty/EOSSDK
」といった他のプラットフォームの場所とは異なることに注意してください。この場合は「Engine/Binaries/ThirdParty/EOSSDK/Mac
」でバイナリを更新するだけで済みます。 - Android の場合: 「
SDK/Bin/Android/Include
」フォルダはそのままにして、.aar
および.lib
ファイルを含む「SDK/Bin/Android
」の他のサブフォルダのみを更新します。 - iOS の場合: 「
SDK/Bin/IOS/EOSSDK.framework/Headers
」フォルダは無視して、「SDK/Bin/IOS/EOSSDK.framework
」フォルダの他のコンテンツのみを更新します。
- Mac の場合: バイナリは「
プロジェクトのオーバーライド
プロジェクトをオーバーライドする方法では、プロジェクトで独自の EOS SDK を提供することができます。この方法では、エンジン モジュールを「Engine/Source/ThirdParty/EOSSDK
」に含まれる EOS SDK に対して引き続きコンパイルできますが、プロジェクト モジュールでは、エンジンまたはプロジェクトからの SDK ヘッダに対してコンパイルするように選択することができます。その後、エンジン モジュールを含むすべてが、プロジェクトで提供される EOS SDK バイナリに対して実行されます。これは、EOS Shared プラグインでは、ランタイム時にエンジン提供の EOS SDK バイナリではなく、プロジェクト提供の EOS SDK バイナリが優先的にロードされるためです。
手順
EOS SDK のプロジェクトのオーバーライドを行うには、次のステップを実行します。
- プロジェクトの EOS SDK を含む独自の
EOSSDK<PROJECT>
モジュールを作成します。.Build.cs
ファイルにより、EOS SDK バイナリを「<PROJECT>/Binaries/<PLATFORM>
」にコピーするRuntimeDependencies
エントリが追加されることを確認します。もしくは、バイナリを「<PROJECT>/Binaries/<PLATFORM>
」に直接登録することもできます。
- プロジェクトの
.Target.cs
ファイルでEOSSDK_USE_PROJECT_BINARY=1
を設定します。- これにより、モノリシック (単一) ビルドで、エンジン EOS SDK バイナリに対してはリンクされず、プロジェクト提供のもののみにリンクされることが確実になります。
- プロジェクト モジュールについては、EOS SDK (モジュール全体) を追加するか、プロジェクトの EOS SDK オーバーライド モジュールを依存関係として追加するかを選択します。
- これによって、プロジェクト モジュールによるコンパイル時に対象とする一連ヘッダが指定されます。
製品名
EOS SDK の製品名は、プロジェ クトの「DefaultEngine.ini
」などのエンジンのコンフィギュレーション ファイルで設定することができます。EOS SDK の製品名は、EOS オーバーレイのプレゼンス情報に表示される名前です。EOS SDK の製品名がエンジンのコンフィギュレーションで設定されていない場合は、デフォルトでプロジェクト名が使用されます。
EOS SDK の製品名を設定する
製品名を設定するには、プロジェクトの「DefaultEngine.ini
」に以下を追加します。
[EOSSDK]
ProductName="<PRODUCT_NAME>"
ここで、<PRODUCT_NAME>
は製品の名前です。たとえば、「MyProduct」を製品名として追加するには、以下をプロジェクトの「DefaultEngine.ini
」に追加します。
[EOSSDK]
ProductName="MyProduct"
追加リソース
EOS SDK と Unreal Engine はそれぞれ異なる製品です。Unreal Engine には EOS SDK のビルドが便宜上含まれていますが、Unreal Engine の最新版に必ずしも EOS SDK の最新版が含まれるとは限りません。EOS SDK の詳細については、次の「Epic デベロッパーのためのリソース ドキュメント」を参照してください。
- 「使用開始の手順」:Epic Games アカウントと組織を設定する手順や、EOS SDK をダウンロードして、コンソール向けに EOS SDK へのアクセスをリクエストする方法について説明します。
- 「EOS SDK の主要情報」:利用可能なさまざまな SDK ダウンロード、命名規則、エラー処理などを含む、EOS SDK の基本的な情報について説明します。
- 「EOS SDK API リファレンス」:EOS SDK の完全な API リファレンスです。
- 「EOS SDK のリリース ノート」:新しい API とバグ修正を含む各 EOS SDK リリースのリリース ノートです。