Common User プラグイン
Common User プラグインは、C++、ブループリント スクリプティング、および Online Subsystem (OSS) またはその他のオンライン バックエンドに共通のインターフェースを提供します。これは、Lyra Starter Game の一部として配布され、どのようなプロジェクトでもスタンドアローンのプラグインとして使用できます。
設計理念
OSS は、ログイン、認証、およびマルチプレイヤー セッションなど、プラットフォーム固有の機能にアクセスするための汎用インターフェースとして設計されています。通常の Unreal Engine コードから呼び出せる標準インターフェースを提供し、さまざまな処理を行います。汎用の柔軟性を備えたライブラリであるため、通常のゲームプレイ セッションの高レベルなフローは直接サポートしていません。Common User は、ユーティリティ機能を提供するオプションのプラグインであり、エンゲージメント画面、ゲーム コントローラーの処理、マルチプレイヤー ゲームのホスティングなどのサポート機能に役立ちます。
Common User の機能は、C++ またはブループリントから呼び出すことができる エンジンのサブシステム を使用して公開されます。Lyra Starter Game は、これらの機能を利用する方法やゲームに統合する方法の例を示します。Common User は、実験的機能である Online Services インターフェース などのその他のシステムに加え、既存の OSS と連携します。ゲーム プラグイン内で定義されているため、変更したりサブクラス化したりして、独自のオンライン システムと連携させることができます。Common User は、リーダーボードやアチーブメントなど、多くのゲーム関連のオンライン機能をサポートするように更新される予定です。現時点では、複数のプラットフォームで商業マルチプレイヤー ゲームのシッピングに求められる、中核的な処理 (ログイン、認証、セッション) のサポートを提供しています。
プラグインをインストールする
ゲームにプラグインをインストールするには、以下の操作を行います。
- Unreal Engine Github または Unreal Engine ランチャーの [Learn (ラーニング)] タブから Lyra Starter Game のコンテンツおよびソース コードを取得します。
Common User は、ブループリントのみのプロジェクトで使用するように設計されていません。
エンジンの正式リリースに含まれていないプラットフォームへのアクセスを利用している場合は、そのプラットフォームを含むバージョンのサンプルを利用する必要があります。
-
システムの「
c:Lyra/Plugins
」フォルダを見つけ、「CommonUser」フォルダをゲームのプロジェクト フォルダにコピーします。 -
エディタ内でツールバーに移動し、 [Edit (編集)] > [Plugins (プラグイン)] をクリックし、プラグイン ブラウザの検索で、 Common User プラグインを検索し、有効にします。
プロジェクトに必要な、プラットフォーム固有のオンライン サービス プラグインを有効にする必要があります。
-
プロジェクトを再コンパイルし、サブシステムを有効にします。
-
「
c:Lyra/Config
」フォルダおよび「c:Lyra/Platforms/PlatformName/Config
」フォルダにある.ini
ファイルを確認し、独自の .ini ファイルで使用する値をコピーします。
Lyra コンフィグ ファイル内の設定やコメントは、独自のプロジェクトの構成設定をセットアップする一般的なガイドとして、また、エディタ内の [Project Settings (プロジェクト設定)] は、一部の変更をコミットするために使用できます。詳細については、「Lyra のスケーラビリティ プロファイルおよびデバイス プロファイル」を参照してください。
- これで、ブループリントで Common User サブシステムにアクセスできるようになりました。C++ のサポートを有効にするには、ModuleName.Build.cs ファイルの PrivateDependencyModuleNames セクションに CommonUser を追加する必要があります。
詳細は「Unreal Engine Modules」を参照してください。
Online Services インターフェースを使用する
デフォルトでは、Common User プラグインは UE4 で利用可能な既存の Online Subsystem インターフェースを使用します。
UE5 の今後のリリースでは、このインターフェースは新しい Online Services インターフェース (OSSv2) に置き換わり、非同期コマンドやエラー処理が改善される予定です。
Online Services は実験的機能であるため、Common User プラグインの初回リリースではデフォルトで利用するように設定されていません。新しいインターフェースを使用するようにプラグインを入れ替えるには、CommonUser.Build.cs を修正し、bUseOnlineSubsystemV1 のブーリアンの値を false に変更して、ゲームの Config/DefaultEngine.ini コンフィグ ファイルに移動し、次の行を追加します。
[/Script/Engine.OnlineEngineInterface]
bUseOnlineServicesV2=true
これにより、新しいインターフェースを使用するのに必要なビルド依存関係が有効になります。EOS OnlineServices を利用するには、[OnlineSubsystemEOS] のセクションを含むすべてのコンフィグ ファイルの Epic Online Services(EOS) OnlineSubsystem を無効にする必要があります。
たとえば、「Lyra/Config/Custom/EOS/DefaultEngine.ini
」ファイルでは bEnabled のブール値を false
に設定しなければなりません。
[OnlineSubsystemEOS]
bEnabled=false
エンジンの将来のリリースと互換性を持つよう設計されたゲームには、実験的機能の Online Services インターフェースを使用することをお勧めします。カスタムのオンライン バックエンドを開発している場合、または EOS をメインのバックエンドとして使用する予定の場合は、Online Services のサポートを有効にすることができます。
Lyra および Common User
Lyra は、C++ とブループリントの両方で Common User プラグインとインタラクションを行います。このプラグインによって提供されるシステムを Lyra がどのように使用するかについて、一部の例を以下に示します。
-
CommonGame C++ プラグインには、 CommonGameInstance(
UCommonGameInstance
) などのクラスが含まれています。ゲーム固有の GameInstance サブクラスは、CommonGameInstance クラスから継承を行って CommonUser プラグインおよび CommonUI プラグインの機能と統合できます。異なる UI システムを備えたプロジェクトの統合方法の例として、クラス内でそのコードを使用できます。 -
LyraFrontEndStateComponent(
ULyraFrontendStateComponent
) は、ソース コードから直接 CommonUser サブシステムにアクセスします。このクラスは、メイン メニュー (W_LyraFrontEnd) が表示される前に、CommonUI を使用してプラットフォーム固有の Press Start (Start を押す) 画面 (W_LyraStartup) を表示するロジックの一部です。 -
W_LyraStartup などの複数のウィジェットは、CommonUserSubsystem に直接アクセスし、関数または非同期ノードを使用してユーザー操作を処理します。
-
LyraUserFacingExperienceDefinition(
ULyraUserFacingExperienceDefinition
) クラスは、マルチプレイヤーの FPS に標準的なメニュー オプションを備えたゲーム セッションの起動方法を記述するものです。これは W_HostSessionScreen などのウィジェットに使用され、セッションの説明を作成するために使用されます。この説明は、ゲーム セッションをホストするため、またはゲームセッションに参加するために CommonSessionSubsystem に渡されます。
Lyra スターター ゲームは、 Epic Online Services (EOS) サブシステムの実行可能なサンプルとして設計されています。デフォルトでは、Lyra は Null サブシステムを使用します。これは、エディタ内またはローカル エリア ネットワーク内のマルチプレイヤーのみをサポートしています。EOS のサポートを有効にするには、パッケージ化ビルドの作成時に LyraGameEOS ターゲットを使用するか、または次のオプションをコマンドラインに追加します。
-customconfig=EOS
これによって、EOS 固有のコンフィグ ファイルが「c:Lyra/Config/Custom/EOS
」ディレクトリからロードされます。これらのコンフィグ ファイルは、プロジェクトに固有の EOS 識別子を使用するように修正する必要があります。
プラグイン サブシステム
Common User サブシステム
Common User サブシステム (UCommonUserSubsystem
) は、ユーザー ログイン、認証、および権限チェックの操作を処理するよう設計されています。これらの操作は、プレイヤーのプロフィールに関連付けて保存されたゲームなどの機能を利用するのに必要です。オンラインに対応したゲームでは、ユーザー ログインは他のオンライン機能を動作させる前に必要となるため、最初に発生するステップです。
Common User サブシステムは、 Identity などの OSS インターフェースの初期化を処理し、他のサブシステムやゲームプレイのコードへのアクセスを提供します。このサブシステムは、個々のユーザーの状態を記述するために使用される列挙および構造を定義します。
以下の表で、システムを通じて使用される重要なタイプについて確認できます。
システム タイプ名 | 説明 |
---|---|
ECommonUserOnlineContext | 操作に使用する、より低レベルのオンライン システムを識別する列挙。ブループリントおよび高レベルの C++ コードは、一般にデフォルトのコンテキスト (Game) を使用し、複数のソースからの情報を組み合わせます。独自の認証レイヤーを備えたコンソールなどのプラットフォームでは、明示的にプラットフォームにアクセスするために Platform コンテキストを使用できます。その後、Service コンテキストを使用することで、プラットフォーム レイヤーをベースとして動作し、クロスプレイのような機能を提供する EOS などのサービスに明示的にアクセスできます。 |
UCommonUserInfo | システムによって管理される、個々のユーザーの状態を保存するために使用されるオブジェクト。各ユーザーは独自の一意のネット ID を持ち、この ID は PlayerState などのクラスのユーザーを識別するために使用されます。シングル プレイヤー ゲームには 1 つの User Info しかありませんが、ローカル マルチプレイヤー ゲームには、プラットフォーム固有のユーザー (または、複数のローカル ユーザーをサポートしないプラットフォーム上ではゲスト) に対応する複数の User Info オブジェクトが存在する場合があります。 |
ECommonUserInitializationState | ユーザーの全体的なログイン/初期化状態を説明します。この状態は、以下の「ユーザーの初期化フロー」で説明するログイン ステップをユーザーが進むに従って変更されます。 |
ECommonUserPrivilege | ゲームプレイ セッションの一部としてユーザーが実行する可能性がある、異なる機能およびアクションを説明する列挙。 |
ECommonUserAvailability | 権限またはその他の機能の提供状況に関する全般的なレベルを説明します。たとえば、ユーザーがアカウントの認証を行ったものの、インターネット接続が現在オフラインの場合、権限の提供状況である CanPlayOnline は CurrentlyUnavailable に設定されます。 |
ユーザーの初期化フロー
ユーザーのログインおよび認証は、複雑で複数のステップを伴う、プラットフォーム固有のプロセスであり、その実行には数秒かかります。以下では、ユーザーの初期化フローに伴うステップの順序を示します。
-
ゲームをプレイする人は、ユーザーとして識別される必要があります。PC やモバイルのプラットフォームでは、これはゲームの開始前に行われ、ユーザーの ID は起動プロセスから送信されます。複数のログイン ローカル ユーザーをサポートするコンソールなどのプラットフォームでは、エンゲージメント画面 (Press Start) を使用し、ユーザーがゲームをプレイするのに使用する物理コントローラーを識別する必要があります。
-
ユーザーは、プラットフォームのインターフェースを使用してログインし、認証される必要があります。最初に識別されたユーザーに対してはこれが自動的に実行される場合がありますが、プラットフォーム固有の画面を表示し、物理コントローラーをプラットフォームのユーザーに明示的にマッピングしなければならない場合もあります。
-
そのユーザーに対する権限をクエリし、ユーザーがゲームをプレイする権限を持っているかどうかを判定する必要があります。これらの権限には、有効なソフトウェア ライセンスや禁止されたアカウントを確認するプラットフォーム固有のチェックが含まれます。
-
LoggedInLocalOnly の初期状態になります。ユーザーはローカルでゲームをプレイできます。また、ゲームを保存するなど、プロフィールに関連する操作への完全なアクセス権を持ちます。ただし、オンラインでのプレイや、その他のネットワーク権限の使用はできない場合があります。オンラインでの初期化完了には、追加のステップが必要です。
-
ユーザーは、(場合によっては異なるオンライン サービスを使用して) ログインし、2 回目の認証が必要になる場合があります。
-
オンライン プレイに使用する、そのユーザーの異なる権限セットを個別にクエリする必要があります。これには、有効なサブスクリプションや年齢制限のチェックが含まれます。
-
権限チェックの 2 番目のセットの合格後、ユーザーはオンライン プレイに対して完全に初期化され (LoggedInOnline)、マルチプレイヤー セッションの作成またはマルチプレイヤー セッションへの参加ができるようになります。
-
プロセス内のどのステップでも、ユーザーはプラットフォームによって強制的にログアウトされる場合があります。これにより、ゲームの保存など、プロフィールに関連するアクションができなくなるため、ゲームの再起動が必要になる場合があります。多くの場合、これによって初期化フロー全体の再起動が必要になります。
Common User サブシステムの主な目的は、この処理に伴う複雑さを個々のゲームで無視する機能を提供することです。
ユーザーの初期化をリクエストする
Common User サブシステムにはステート マシンが組み込まれており、初期化プロセス内のユーザーのステップを継続的に追跡します。このプロセスの開始に使用できる方法は複数あります。
ユーザーの初期化方法 | 説明 |
---|---|
Initialize for Local Play Login for Online Play | これらのブループリント ノードをウィジェットのイベント グラフまたはその他のブループリントに配置し、特定のローカル プレイヤーおよび物理コントローラーに対するログイン (ローカルのみまたはオンライン) をリクエストできます。これは最もシンプルなセットアップであり、初期化の成功時または失敗時に完全な実行ピンをアクティベートします。 |
OnUserInitializeComplete | ブループリントまたは C++ のいずれかからバインドできるデリゲートで、ユーザーが初期化を完了するたびにアクティベートされます。 |
TryToInitializeUser | OnUserInitializeComplete デリゲートを最終的に実行する、より高度な初期化プロセスを開始するのに使用される関数です。 |
Listen for Login Key Input | 初期エンゲージメント画面 (Press Start) を作成するため、またはローカル マルチプレイヤーにコントローラーを追加できるようにするための関数。これは、特定のコントローラー ボタンまたはキーボード キーをリッスンする一時的な入力ハンドラを登録し、正しいパラメータを使用して TryToInitializeUser を呼び出すことによって行われます。 |
LoginLocalUser | 初期化を手動で管理する場合に、C++ から呼び出せる関数。 |
これらの関数は Lyra メニュー ウィジェット (W_LyraStartup) および C++ で使用され、複数ユーザーのプラットフォームで明示的なエンゲージメント画面を表示するか、または PC およびモバイル プラットフォーム向けに controller_0 の user_0 に自動的にログインを試行します。 これは、ShouldWaitForStartInput 関数を呼び出すことで実行します。ただし、シングル プレイヤーのゲームを作成している場合は、常にエンゲージメント画面を表示することがあるでしょう。オンライン セッションを開始できる W_ExperieceSelectionScreen などのウィジェットでは、オンライン プレイのための明示的なログインがリクエストされる場合があります。
ユーザーはすでにローカルの初期化を完了しているはずであるため、このオンライン ログインにはコントローラーのパラメータがありません。
その他の操作
Common User サブシステムには、特定のユーザーのクエリや特定のユーザーの情報の変更に使用できる、便利な関数が他にも用意されています。Common User サブシステムを使用してブループリント関数を確認できます。また、詳細については、CommonUserSubsystem.h ファイルを参照してください。
Common User サブシステム関数 | 説明 |
---|---|
OnHandleSystemMessage | オンライン機能に関連するエラー メッセージを表示するようにバインドできるデリゲート。Lyra の UCommonGameInstance クラスは、シンプルなエラーのポップアップを表示します。また、SendSystemMessage を使用してこの UI をゲームプレイ コードからトリガーできます。 |
OnUserPrivilegeChanged | ユーザーの権限の変更を処理するようにバインドできるデリゲート。これは、ネットワーク接続が失われた場合など、ゲームレベルでの処理を実現するのに使用されます。 |
GetUserInfoForLocalPlayerIndex GetUserInfoForPlatformUserIndex GetUserInfoForUniqueNetId | ユーザーに関する情報をクエリするための主な方法。ネットワーク ID、表示ニックネーム、および権限をクエリできる CommonUserInfo オブジェクトを返します。 |
GetOnlineIdentity GetOnlineSubsystem | キャッシュされたインターフェース データにアクセスするためにゲームプレイのコードまたは他のサブシステムによって使用される、低レベルのラッパー関数。これらの関数は、使用しているオンライン インターフェースに固有のものです。 |
Common Session サブシステム
Common Session サブシステム(UCommonSessionSubsystem) は、オンラインのゲームプレイ セッションの作成、検索、参加など、オンライン機能にアクセスするためのシンプルなインターフェースを提供するように設計されています。OSS セッション インターフェース は、プラットフォームのネイティブのマッチメイキング インターフェースや EOS のようなクロス プラットフォーム システムとインタラクションできる、プラットフォームに依存しないラッパーを提供します。 ゲームやプラットフォームによって、マルチプレイヤー セッションは専用サーバーで物理的にホストされる場合もあれば、自身もゲームをプレイするプレイヤーによってホストされる場合もあります。プレイヤーがホスト (リッスン) するサーバーは、コンソールまたはユーザーが所有する PC で実行され、ピアツーピア (P2P) の NAT トラバーサル (EOS など) の形式を使用してアクセスする必要があります。 すべてのマルチプレイヤー ゲームプレイ セッションの目的は、ゲームの 2 つのインスタンスを互いに接続し、 Unreal Engine ネットワーキング システムのあらゆる機能を利用できるようにすることです。しかし、2 つのインスタンスを接続する前に、仲介を行う構造 (状況により、「ロビー」や「セッション」の名称で知られる) を作成およびクエリする必要があります。
セッションの初期化をリクエストする
Common Session サブシステムを使用し、セッションの初期化に利用できる方法は複数ありますが、利用可能な基本的な選択肢を以下の表に示します。
初期化方法 | 説明 |
---|---|
HostSession | 特定のゲームプレイ モードとロードされるマップについて説明する Host Request を使用して呼び出すことができます。これは、オンラインのバックエンドに登録しない、シングル プレイヤー セッションの作成に使用できます。そのため、UI ではそれぞれの違いを把握する必要がありません。セッションが作成されると、指定されたマップがロードされ、ゲームプレイが開始されます。 |
FindSessions | 検索リクエストと一致する、参加可能なセッションのリストをオンライン システムに要求するために呼び出すことができます。Request (UCommonSession_SearchSessionRequest ) および SearchingPlayer (APlayerController ) パラメータを受け入れ、入力された引数を満たす、公開されたマッチメイキング ゲームを探します。検索が完了すると、Request オブジェクトに実装された OnSearchFinished デリゲートが呼び出されます。また、検索結果のオブジェクト (Request オブジェクトに基づいて入力されたもの) を使用してセッションに参加できます。 |
JoinSession | 検索結果のオブジェクトを取得し、マルチプレイヤー セッションへの接続および参加を試みます。成功した場合、ゲームはそのピアまたは専用サーバーに接続し、ネットワーク クライアントとしてゲームへの参加を試みます。 |
QuickPlaySession | ホストのパラメータに一致する既存の公開セッションを検索するプロセスを開始し、可能な場合はセッションに参加します。この方法は、ほかの 3 つの初期化関数を組み合わせたもので、ホストのリクエストを使用して呼び出されます。セッションに参加できない場合は、新しいセッションを開始します。CommonSessionSubsystem は基本的な実装を提供しますが、ゲームでは必要に応じて、ゲーム固有のサブクラス内でクイックプレイに関連する関数をオーバーライドできます。 |
Lyra は、以下に示す複数のウィジェット ブループリントの Common Session サブシステムとインタラクションを行います。
ウィジェット ブループリント | 説明 |
---|---|
W_ExperienceSelectionScreen | セッションのホストか検索のどちらかを選択することに加え、クイック プレイを処理します。 |
W_SessionBrowserScreen | 既存のセッションの検索および既存のセッションへの参加を処理します。 |
W_HostSessionScreen | ホスティング ルールの指定、および新しいローカルまたはマルチプレイヤー セッションの作成を許可します。 |
これらのウィジェットは、「c:Lyra/Source/LyraGame/GameModes
」ディレクトリにあるLyraUserFacingExperienceDefinition クラスのアセットに依存します。このクラスは、ゲーム内で使用できる特定のマップおよびゲームプレイ モードのタイプを定義します。Lyra のソース コードには、プレイヤーがゲームを離脱した場合やログインに失敗した場合に、セッションがメモリ内で適切にクリーン アップされるチェックも含まれています。
CommonSession サブシステム と Lyra はどちらも、EOS Lobby インターフェース を使用して P2P でホストされるセッションを検索および作成するように設計されています (上記のようにサポートが有効になっている場合)。エディタ内でのマルチプレイヤー を Null サブシステム でテストする際に作成されるローカル セッションで機能します。 このプラグインの初回リリースで他のオンライン バックエンドのサポートを完全に有効にするには、FOnlineSessionSearch などの内部セッション オブジェクトに渡されるオプションの一部の変更が必要な場合があります。