EOS SDK in C#

Epic Online Services (EOS) SDK には C に加えて #C のダウンロードもあります。このページでは、C# での EOS SDK における作業と C での EOS SDK における作業の実装の違いについて、いくつか概説します。使用する言語にかかわらず中核となる機能は同じですが、C# での SDK は次の点で設計が異なります。

• C# での EOS SDK は C# のベスト プラクティスに準拠し、オブジェクト指向の手順に従います。その際、非同期の操作を管理するために C スタイルのハンドルではなくハンドル オブジェクトを使用します。
• 命名規則は代表的な C# パターンに一致します。たとえば、C での EOS SDK の EOS_Auth_Login は、C# での EOS SDK で Epic.OnlineServices.Auth.AuthInterface.Login としてアクセス可能です。
• C での EOS SDK のデータ構造体は、互換性を確認するためにマクロベースの API バージョン番号が必要となります。これらの値は C# での EOS SDK に事前に入力されています。

C# での EOS SDK で作業するには、次を開発環境にインストールする必要があります。

• .NET Framework 3.5 以降 (または API 互換性のある同等のもの)

  注： 以前のバージョンでも動作する可能性はありますが、テストを行っていません。

C# での EOS SDK サンプルで作業するには、次を開発環境にインストールする必要があります。

• .NET Core 3.1
• Visual Studio 2019 以降

開発環境に必要なものについての詳細は、メインの「システム要件」ページを参照してください。

Epic Games アカウントの設定と EOS SDK の使用方法について「EOS 入門編」のドキュメントを参照してから、下記のガイダンスに進んでください。

また、Online Service の Web サイトで、C# での作業開始に焦点を当てた紹介ブログ「Epic Online Services (EOS) のご紹介」( dev.epicgames.com/news) で確認することもできます。

1. プロジェクトに C# での SDK ソース ファイルを含めます。

• (Unity ユーザー) これらのファイル (「Core」フォルダと「Generated」フォルダを含む) を「Assets」フォルダに配置します。

2. アプリケーションが対象のプラットフォームに適切なライブラリ バイナリ ファイルにアクセスできることを確認してください。

• (Unity ユーザー) 適切なライブラリ バイナリ ファイルを、対象のプラットフォームの「Assets」フォルダにコピーします。
• たとえば、Windows x64 の統合には「EOSSDK-Win64-Shipping.dll」を使用します。

3. C# での SDK は Epic.OnlineServices.Config で対象となるライブラリ バイナリ名を決定します。一部のプラットフォームでは便宜上、正確な名前を示すように事前構成されます。

• 対象のプラットフォームが事前構成されていない場合、ビルド エラーを避けるために構成とプロジェクトのシンボルに適切な変更を加えます。たとえば、Windows x64 を対象にする場合は EOS_PLATFORM_WINDOWS_64 を設定する必要があり、Windows x86 を対象にする場合は EOS_PLATFORM_WINDOWS_32 を設定する必要があります。

4. (Unity ユーザー) SDK を制御するための新しいスクリプトを作成します。この例では、名前 EOSSDKComponent を使用しています。

5. (Unity ユーザー) 必要に応じてコンポーネントを作成するには、[Add Component (コンポーネントを追加)] を選択してエンティティに割り当てます。ここでは、デモ目的で メイン カメラ に追加しています。

6. このコンポーネントに EOS SDK コードを記述します。例については、サンプル コード を参照してください。

製品 を設定して C# での SDK を統合したら、コードを書くことができます。SDK を初期化し、Tick メソッドを定期的に呼び出して SDK で実行できるかどうか、コールバックが実行できるかどうかを確認します。そして、アプリケーションを終了させる時に SDK をシャットダウンしてください。

SDK のライフサイクルは、主に初期化、ティック (通常操作)、そしてシャットダウンの 3 つに分けられます。

プラットフォーム インターフェース は SDK の入り口です。EOS を使用するためにはこのインターフェースのインスタンスが必要です。インスタンスを作成するには、アプリケーションに関する一部の基本情報とともに Epic.OnlineServices.Platform.PlatformInterface.Initialize を呼び出し、次に Epic.OnlineServices.Platform.PlatformInterface のインスタンスを取得するためにデベロッパー ポータルから取得した値で Epic.OnlineServices.Platform.PlatformInterface.Create を呼び出します。SDK とのやり取りに必要になるので、このインスタンスを格納します。 たとえば、認証を実行するには、最初に Epic.OnlineServices.Auth.AuthInterface のインスタンスが必要です。これは、Epic.OnlineServices.Platform.PlatformInterface インスタンスで GetAuthInterface() を呼び出すことで取得できます。

SDK で操作するためには、プラットフォーム インターフェース インスタンスで定期的に Epic.OnlineServices.Platform.PlatformInterface.Tick を呼び出す必要があります。これらの呼び出しはフレームごとに行う必要はありませんが、高い頻度で行ってください。100 ミリ秒ごとに 1 回の呼び出しが妥当と考えられますが、必要に応じて頻度は調整することができます。SDK のコールバックは Tick を呼び出す時にのみ実行できるため、すべての非同期操作はそれに依存します。

SDK が必要なくなった時は (通常はアプリケーションの終了時) 、 Epic.OnlineServices.Platform.PlatformInterface.Release を呼び出してプラットフォーム インターフェース インスタンスを解放し、次に Epic.OnlineServices.Platform.PlatformInterface.Shutdown を呼び出してシャットダウン プロセスを完了させて終了します。最後に、Epic.OnlineServices.Platform.PlatformInterface.Release を使用して SDK を終了状態にすると、それ以降は別のプラットフォーム インターフェース ハンドルを取得したり、SDK を再初期化することができなくなります。このことから、アプリケーションが終了するまで EOS SDK はシャットダウンしないようにしてください。

ほとんどのコールバック データ構造体と一部の戻り値は、 Epic.OnlineServices.Result を使用して SDK 操作の結果を伝達します。これを使用してエラーを処理したり、操作が予測どおりに実行されていることを確認してください。

SDK では、内部インターフェースを介して役に立つデバッグ情報を出力します。この機能を有効にするには、できるだけ早い段階で、なるべく SDK の起動後すぐに、希望する詳細度を示すパラメータを使用して Epic.OnlineServices.Logging.LoggingInterface.SetLogLevel を呼び出して Epic.OnlineServices.Logging.LoggingInterface を設定します。そして次に、コールバック関数を使用して Epic.OnlineServices.Logging.LoggingInterface.SetCallback でログ情報を受け取ります。この機能により内部操作の詳細がわかり、予想外の動作が発生した場合の原因を特定することができます。

C での SDK では、EOS_Leaderboards_CopyLeaderboardDefinitionByIndex などの一部の API は手動での解放が必要なデータの構造体を渡します。C# での SDK では、これらの構造体の解放について検討する必要がなく、ラッパーのマーシャリング コードによって自動的に処理されます。

C での SDK では、EOS_Presence_CreatePresenceModification などの一部の API は SDK ライブラリが所有するメモリにデータを設定できるハンドルを渡します。これらのハンドルは手動で解放する必要があります。C# での SDK では、これらのハンドルは基本となる型が Epic.OnlineServices.Handle のオブジェクトによって表され、管理外のデータを設定できる関数が含まれています。また、終了時に手動で呼び出す必要がある Release 関数も含まれています。

コンソールなどの一部のプラットフォームでは、SDK で独自のアロケート、再アロケート、および解放を行う機能を実装する必要があります。SDK はこれらの関数を非常に高い頻度で呼び出すため、管理しているコードのデリゲートを経由せずに SDK がこれらの関数に直接アクセスできる場合、パフォーマンス的な観点で大きな利点があります。

プラットフォームを Epic.OnlineServices.Platform.InitializeOptions で初期化するときは、これらの関数を SDK に渡すためのオプションがあります。その際は。次のやり方をお勧めします。

1. ネイティブ ライブラリを作成し、3 つのメモリ関数を実装します。
2. 3 つのメモリ関数のそれぞれについて、メモリ関数へのポインタを返すエクスポート関数を実装します。
3. プラットフォームを C# で初期化する前に、エクスポート関数を呼び出し、返された IntPtr 値を options 構造体に設定します。

次のサンプル コードは、ネイティブ ライブラリがどのように見えるかの構造を示しています。

また、次のサンプルコードは、C# バインディングがどのように見えるかを示しています。

現在、SDK はスレッドセーフではありません。SDK への呼び出しはすべて、アプリケーションのメイン スレッドから行うことを推奨します。現時点では async、await、Thread、Task、または類似するパターンを使用しないでください。

アプリケーションで EOS オーバーレイ を使用するには、グラフィック デバイスを作成する前に次の手順を実行します。

1. SDK ライブラリをメモリにロードします
2. EOS_Initialize で初期化します
3. EOS_Platform_Create を使用してプラットフォームを作成します

Unity でこれを行う場合は、低レベルのネイティブ レンダリング プラグイン を作成します。そして、少なくとも次のことを行う必要があります。

1. プレフィックスとして GfxPlugin を付けてネイティブ ライブラリを作成します。
2. SDK ライブラリをロードして EOS_Initialize と EOS_Platform_Create を正常に呼び出す「UnityPluginLoad(void*)」という名前のエクスポート関数を追加します。
3. エクスポート関数を追加して、作成したプラットフォーム インターフェース ハンドルを必要に応じて C# に戻します。これは、Epic.OnlineServices.Platform.PlatformInterface の新しいインスタンスを作成する場合に使用できます。

Unity ユーザーの場合、スタンドアローン ビルドで低レベルのネイティブ レンダリング プラグイン内の SDK の存続期間を制御し、エディタ ビルドでプラグインを除外して、動的バインディングを使用した MonoBehaviour 内の SDK の存続期間を制御することをお勧めします。

通常、C# での SDK は externDllImport バインディングを使用します。しかし、動的バインディングを使用する場合もあります。

動的バインディングを使用するには、次を実行します。

1. EOS_DYNAMIC_BINDINGS を定義します
2. SDK ライブラリを動的にロードし、ライブラリ ハンドルを取得します
3. アプリケーション セッションが開始したら、Epic.OnlineServices.Bindings.Hook を呼び出してライブラリ ハンドルと関数ポインタ ローダー デリゲートを渡します。
4. アプリケーション セッションが終了したら、Epic.OnlineServices.Bindings.Unhook を呼び出してライブラリを解放し、クリーンアップします。

たとえば、Windows で次のような extern 関数を定義する場合があります。

次に、SDK の使用を開始するには、ライブラリをロードし、動的バインディングを次のようにフックします。

アプリケーションが終了したら、動的バインディングのフックを解除し、次のコマンドでライブラリを解放します。

1.12 の時点では、C# での SDK のデフォルトの動作において、Unity エディタなどのエディタ環境に対して動的バインディングが必要となっています。これは、SDK ライブラリのオンデマンドのロードとアンロードを有効にし、ゲームがエディタで実行されるたびに SDK を初期化できるようにするためです。Unity で動的バインディングを使用する ためのより詳細なサンプルコードを以下に示します。

C# での SDK のサンプルは多岐にわたり、認証、プレゼンス、購入フロー、音声など、さまざまな Epic Online Services (EOS) 機能の実装を確認できます。さらに、プラットフォームの設定、サインイン、Unity EOS SDK コンポーネントの実装向けのサンプル コードも用意されています。

このセクションのサンプル コードはデモンストレーションとして、また C# での SDK への理解を深めることを目的に用意しました。

注： 下記のコードには SDK 1.15 以降が必要です。

これらのサンプルは、次のライブラリおよびアプリケーションを含む C# での SDK ダウンロードのフォルダに入っています。

「Common」には、SDK コードや他の便利な共有機能が含まれています。

「WpfCommon」には、すべての WPF サンプルに共通の機能が含まれています。

「VoiceCommon」には、すべての音声サンプルに共通の機能が含まれています。

SimpleAuth は、ログインしたユーザーの認証および プレゼンス に関連する機能の実行方法を示す WPF アプリケーションです。

SimpleOverlayPurchasing は、インゲームのオーバーレイを利用して、購入フローの開始および完了の方法を示す管理されている DirectX11 アプリケーションです。

VoiceServer は、音声クライアントと EOS の間で信頼できる音声サーバーとして機能する RESTful API サービスの実装方法を示すアプリケーションです。

VoiceClient は、ボイス ルームへの接続、オーディオ デバイスの切り替え、音声の送信、クライアントのミュート、サーバーのミュート、およびキックの方法を示す WPF アプリケーションです。

サンプルを実行するには、次をインストールする必要があります。

• .NET Core 3.1
• Visual Studio 2019 以降

アプリケーションに関連付けられている次の値も Samples/CSharp/Common/Settings.cs に設定する必要があります。

• ProductId
• SandboxId
• DeploymentId
• ClientId
• ClientSecret

また、LoginType も設定できます。ID および Token フィールドの使用は、ログイン タイプによって異なります。詳細は、「Auth.Credentials」および「Auth インターフェース」を参照してください。

デモで示されている SDK の機能は、サポートされている ID プロバイダのいずれでもユーザー認証に使用できます。

SimpleAuth は、ログインしたユーザーの認証およびプレゼンスに関連する機能の実行方法を示すサンプル アプリケーションです。

最初に、サインイン画面が提示されます。使用するサインインのタイプを選択できます。Developer タイプを選択し、デベロッパー認証ツール によって割り当てられた資格情報を使用してログインすることをお勧めします。

サインインすると、現在のプレゼンスを示すページとそれを変更できるフォームが表示されます。これにはオンライン ステータス、リッチ テキスト、現在のプレゼンスに関連するデータ エントリのフィールドが含まれています。

この機能は、Epic Games ストアにある製品のみが利用可能です。利用するにはストア パートナーとしてストアでオファーを設定している必要があります。

オーバーレイを機能させるためには、次のいずれかを実行済みである必要があります。

• Epic Games Launcher をインストールし、初めて実行した。
• EOSOVH dll ファイルをダウンロードし、レジストリ キー HKEY_CURRENT_USER\Software\Epic Games\EOS\OverlayPath を dll のあるディレクトリに設定した。

サンプルは、オーバーレイを購入フローで起動するため、自動的にサインインと必要な Ecom 機能を実行します。アウトプットを見て問題がないことを確認します。