Online Services の概要

Online Services プラグインとそのインターフェースでは、PlayStation Network、Xbox Live、Epic、Steam などのさまざまなオンライン サービスの機能にアクセスするための共通の方法が提供されます。Online Services プラグインの設計により、デベロッパーは、複数のプラットフォーム向けに提供されるゲーム、または複数のオンライン サービスをサポートするゲームを扱う際に、それぞれサポートされているサービスに対して構成上の調整のみを行うだけで済みます。

設計理念

Online Services プラグインは、サポート対象の機能をグループ化するサービス別のモジュラー インターフェース に分かれています。それぞれがサポートするインターフェースと機能グループの一覧については、このページの「インターフェース」の表を参照してください。

Online Services プラグインは、さまざまなサービスとの非同期通信を処理するように設計されています。こうしたシステムとの相互処理にかかる時間は、ネットワーク通信速度、サーバー遅延、バックエンド サービスにおける予測不能な時間が原因で予測することができません。この問題を解決するために、Online Services インターフェースでは、ハンドルへの OnComplete イベントのコールバックが呼び出されることを保証するすべてのリモート操作に向けた TOnlineAsyncOpHandle を返します。

それぞれの機能グループには、それらをサポートする各オンライン サービス上にインターフェースが用意されています。特定のオンライン サービスでサポートされない機能は Errors::NotImplemented を OnComplete コールバックから返します。この機能により、デベロッパーはすべてのオンライン サービスに対して同じコードを使用できます。

イベント コールバックおよびリッスン

OnComplete コールバックでは次の機能が提供されます。

• リクエストが完了したときにそのリクエストに応答する。
• 実行中のリクエストに対してクエリを行う。
• 単一のコード パスを使用する。

最後のポイントは、デベロッパーが合否のためのさまざまな条件を検知するカスタム コードを記述する必要がなくなるため重要です。

コールバックの形式

OnComplete コールバック (Online Services のイベント コールバック) またはイベント リスニングのパラメータを引き渡す方法に応じて、適切なデリゲートが自動的に構築されます。次の例では、Stats インターフェースからの QueryStats 関数を使用して、this のタイプに応じてさまざまなデリゲート作成関数が呼び出されます。

Stats->QueryStats(MoveTemp(Params)).OnComplete(this, &MyClass::OnQueryStatsComplete);
Copy full snippet

Stats->QueryStats(MoveTemp(Params)).OnComplete(this, &MyClass::OnQueryStatsComplete);

または、この例では OnStatsUpdated を使用しています。

Stats->OnStatsUpdated().Add(this, &MyClass::OnStatsUpdated);
Copy full snippet

Stats->OnStatsUpdated().Add(this, &MyClass::OnStatsUpdated);

これらの例では、次のような動作になります。

• これが UObject の場合は、基盤となるデリゲートの CreateUObject が呼び出されます。
• これが TSharedFromThis の場合は、CreateThreadSafeSP または CreateSP (スレッドセーフではないシェアードポインタの場合) が呼び出されます。
• その他の場合は CreateRaw が呼び出されます。

一般的には、最も安全なデリゲート作成の関数呼び出しが使用されます。

インターフェース

Online Services プラグインには、次のインターフェースが含まれています。

関数

それぞれのインターフェースにはさまざまな同期/非同期関数が含まれています。ここでは、関数へのパラメータの引き渡し方法と、関数から返された結果の処理方法について概要を説明します。特定のインターフェース関数の詳細については、「Unreal Engine C++ API Reference」の「Online Services Interface」モジュールを参照してください。

パラメータ

Online Services インターフェース関数のパラメータは、それぞれの関数に関連する構造体の Params メンバーを使って作成されます。その後、これらのパラメータは UE の std::move と同等の MoveTemp とともに、または {} で区切られたリストを介して、関連する関数に引き渡されます。

戻り型

Online Services インターフェースで定義される関数には次の 3 つの戻り型があります。

• TOnlineResult
• TOnlineAsyncOpHandle
• TOnlineEvent

TOnlineResult

同期関数では TOnlineResult<T> を返します。T は当該の関数に関連する構造体です。戻り値が成功かどうかを判断するために、IsOk または IsError を呼び出します。これらはいずれも、結果がアクセス可能であるか、エラーが発生するかを示すブール値を返します。最後に、IsOk が True を返した場合は、GetOkValue への呼び出しを使って T::Result にアクセスできます。同様に IsError が True を返した場合は、GetErrorValue への呼び出しを使って FOnlineError にアクセスできます。

TOnlineAsyncOpHandle

非同期通信を必要とする関数は TOnlineAsyncOpHandle<T> を返します。このハンドルに OnComplete コールバックを加えることで、このハンドル内でのステートの最終的な変更 (適切に完了、失敗、タイムアウトなど) をリッスンします。コールバックの TOnlineResult<T> パラメータには成功した結果のデータか、関数が失敗した理由を示す FOnlineError が含まれます。このコールバックではユニークな関数を受け入れるため、ラムダ関数が使用されている場合は、ユニークなポインタと高負荷のデータ型がラムダのキャプチャ範囲に移動されることがあります。

TOnlineEvent

イベント リスニングに使用される関数は TOnlineEvent<T> を返します。TOnlineAsyncOpHandle と同じように、Add 関数を使ってイベント コールバックをリッスンできます。その後、条件に一致するイベントが検出された際に、Add がそのコールバックをシグネチャ T とともに起動します。同じイベントには複数のコールバックを追加できます。Add を呼び出すと FOnlineEventDelegateHandle が返されます。このデリゲート コールバックはこのハンドルが破壊された際にバインドが解除されるため、このイベントをリッスンしているシステムのライフサイクル中に有効な状態を維持し、関連システムの破壊に伴って、このハンドルでの Unbind の適切な破壊/呼び出しを行う必要があります。

Online Services または Online Subsystem を使用する

現在、Unreal Engine (UE) にはオンライン サービスへのアクセスに、Online Services と Online Subsystem の 2 つのフレームワークを使用することができます。このセクションをお読みになり、プロジェクトに適したフレームワークを判断してください。

Online Services

Online Services プラグインはシッピング タイトルでテストされていません。UE 5.1 の時点で、Online Services プラグインはエンジンの今後のバージョンでのシッピングを目的とした、デベロッパー向けの API 完了版です。Epic では、独自のバックエンドをターゲットとするデベロッパー、または 5.1 より後の UE アップグレードをシッピング前にプロジェクトに多数取り入れることを予定しているデベロッパーの方に向けて、Online Services の使用を推奨しています。

Online Subsystem

Online Subsystem は、近日シッピングする予定のタイトルの場合、または UE 5.1 より後のエンジン アップグレードをプロジェクトに取り入れることを予定していない場合に使用します。

コンフィギュレーション

Online Services プラグインのベース モジュールは OnlineServices です。このモジュールではサービス特有のモジュールを定義して、UE に登録します。オンライン サービスへのアクセスは、すべてこのモジュールを介して行われます。初期化の際には、OnlineServices が「DefaultEngine.ini」で指定されたオンライン サービス モジュールをロードしようとします。オンライン サービスを有効にして、デフォルトのオンライン サービスを指定するには、次のコードを「DefaultEngine.ini」ファイルに追加します。

[OnlineServices]
DefaultServices=<DEFAULT_PLATFORM_IDENTIFIER>
Copy full snippet

[OnlineServices] DefaultServices=<DEFAULT_PLATFORM_IDENTIFIER>

DEFAULT_PLATFORM_IDENTIFIER は、次のサポート対象プラットフォームの識別子のいずれかと置き換える必要がある変数です。

• Null
• Epic
• Xbox
• PSN
• Nintendo
• Steam
• Google
• GooglePlay
• Apple
• AppleGameKit
• Samsung
• Oculus
• Tencent

「DefaultEngine.ini」で指定された「DefaultServices」は、パラメータが指定されていない場合に、関数 UE::Online::GetServices で使用できます。

TSharedPtr<IOnlineServices> GetServices(EOnlineServices OnlineServices = EOnlineServices::Default, FName InstanceName = NAME_None);
Copy full snippet

TSharedPtr<IOnlineServices> GetServices(EOnlineServices OnlineServices = EOnlineServices::Default, FName InstanceName = NAME_None);

追加のオンライン サービスは、UE::Online::GetServices への呼び出しによるリクエストを通じてオンデマンドでロードされます。識別子が無効な場合やモジュールのロードに失敗した場合は、null が返されます。

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

各種 Online Services インターフェースのヘッダ ファイルは、次のエンジン ディレクトリにあります。

UNREAL_ENGINE_ROOT/Engine/Plugins/Online/OnlineServices/Source/OnlineServicesInterface/Public/Online
Copy full snippet

UNREAL_ENGINE_ROOT/Engine/Plugins/Online/OnlineServices/Source/OnlineServicesInterface/Public/Online

このディレクトリのヘッダ ファイルで Online Services と各種インターフェースの詳細を確認することをお勧めします。

それぞれの Online Services インターフェース ドキュメント ページには、Online Services プラグインの使用を開始する際に役立つサンプル コードかサンプル プロセスのいずれかが含まれています。

コンソール コマンドでインターフェースを実行する

Online Services インターフェースはコンソール コマンドでも実行できます。Online Services プラグインのコンソール コマンドとその構文の詳細については、「Online Services コンソール コマンド」ドキュメントを参照してください。