Online Services Lobbies インターフェース は、ロビーを作成し、管理するための API を提供します。ロビー とは、クライアント アプリケーションのコンテキスト内で、すべてのプレイヤーが特定の共有状態を持っているプレイヤーのグループです。これは、全員が同一のオンライン対戦でプレイしているか、同一の対戦の開始を待機していることを意味します。ロビーとそのメンバーの両方に、この状態を共有するために使用される属性があります。ロビーの属性またはメンバーの属性の変更は、ロビーに参加しているメンバー全員にリアルタイムに表示されます。
ロビー リーダーはロビーの属性を変更できます。また、それぞれのメンバー (リーダーを含む) は いつでも自分の属性を変更できます。ロビー スキーマ では、このような属性を、その型と値の制約とともに定義します。定義されると、これらはロビーを作成するために使用されます。このロビー スキーマはアプリケーションのコンフィグ ファイルで定義され、アプリケーションの起動時に検証されます。ロビーを作成するためにすべての属性を定義する必要はありませんが、定義した属性がスキーマの検証に失敗すると、ロビーの作成が失敗します。
ロビーの一般的な用途は、対戦に進む前にプレイヤーをグループ化することです。1 つのロビーの存続期間内に、複数のゲーム対戦をプレイすることができます。以下は、ロビーのライフサイクルの例です。
- プレイヤーが希望のプライバシー設定と属性を使用して、新しいロビーを作成します。そのプレイヤーをロビー リーダーに任命されます。
- 他のプレイヤーが検索、招待、またはソーシャル プレゼンスを使用してロビーを見つけて、参加します。
- プレイヤーが属性の更新により、ロビー内で属性を共有します。
- ロビーが対戦でプレイすることを選択すると、ロビー リーダーが対戦セッション ID をロビー属性として記録します。
- 他のロビー メンバーがこのセッション ID を確認して、同じゲーム セッションに参加します。
- プレイヤーが複数のゲーム対戦の期間中、ロビーに参加したり、ロビーから退出したりします。
API の概要
関数
次の表に、ロビー インターフェースが提供する関数の概要を示します。
| 関数 | 説明 |
|---|---|
| 動作 | |
CreateLobby |
新しいロビーを作成して、参加します。 |
FindLobbies |
指定されたパラメータに適合するロビーを検索します。 |
RestoreLobbies |
以前に参加したロビーへの再参加を試行します。 |
JoinLobby |
指定されたロビー ID でロビーに参加します。 |
LeaveLobby |
参加したロビーから退出します。 |
InviteLobbyMember |
ロビーに参加するようプレイヤーを招待します。 |
DeclineLobbyInvitation |
ロビーへの招待を断ります。 |
KickLobbyMember |
ターゲット ロビーからメンバーを削除します。 |
PromoteLobbyMember |
他のロビー メンバーをリーダーに昇格させます。他のメンバーを昇格させるには、PromoteLobbyMember を呼び出したローカル プレイヤーが現在のロビー リーダーである必要があります。 |
| 変更 | |
ModifyLobbySchema |
ロビーとメンバーの属性に適用されるスキーマを変更します。ロビー リーダーのみがスキーマを変更することができます。新しいスキーマに存在しない既存の属性はクリアされます。 |
ModifyLobbyJoinPolicy |
ロビーに適用される参加ポリシーを変更します。ロビー リーダーのみが参加ポリシーを変更することができます。 |
ModifyLobbyAttributes |
ロビーに適用される属性を変更します。ロビー リーダーのみがロビーの属性を変更することができます。属性は、更新が成功する前にロビー スキーマに対して検証されます。 |
ModifyLobbyMemberAttributes |
ロビー メンバーに適用される属性を変更します。ロビー メンバーは自分の属性のみを変更することができます。属性は、更新が成功する前にロビー スキーマに対して検証されます。 |
| アクセサ | |
GetJoinedLobbies |
ターゲットのローカル プレイヤーが参加したロビーのリストを取得します。 |
GetReceivedInvitations |
ターゲットのローカル プレイヤーが受信した招待のリストを取得します。 |
| イベントのリッスン | |
OnLobbyJoined |
プレイヤーがロビーに参加したときにトリガーされるイベント。 |
OnLobbyLeft |
ローカル メンバーが全員ロビーから退出したときにトリガーされるイベント。 |
OnLobbyMemberJoined |
ローカル プレイヤーがロビーを作成または参加した結果として、ロビー メンバーが参加したとき、またはリモート プレイヤーが参加したときに、トリガーされるイベント。 |
OnLobbyMemberLeft |
参加したロビーからロビー メンバーが退出したときにトリガーされるイベント。 |
OnLobbyLeaderChanged |
ロビーのリーダーシップが変更されたときにトリガーされるイベント。 |
OnLobbySchemaChanged |
ロビーの属性スキーマが変更されたときにトリガーされるイベント。 |
OnLobbyAttributesChanged |
ロビーの属性が変更されたときにトリガーされるイベント。 |
OnLobbyMemberAttributesChanged |
ロビー メンバーの属性が変更されたときにトリガーされるイベント。 |
OnLobbyInvitationAdded |
ロビー メンバーが招待を受信したときにトリガーされるイベント。 |
OnLobbyInvitationRemoved |
ロビー メンバーが招待に対応したときか、招待の期限が切れたときにトリガーされるイベント。 |
OnUILobbyJoinRequested |
プレイヤーが外部メカニズムを通じてロビーへの参加を要求したときにトリガーされるイベント。 |
列挙型クラス
Lobbies インターフェースは、ロビー参加ポリシーとロビー メンバーの退出理由を反映する列挙型クラスを提供します。
ELobbyJoinPolicy
| 列挙子 | 説明 |
|---|---|
PublicAdvertised |
ユーザーは、属性マッチング、ロビー ID、または招待に基づいた検索によってロビーを検索できます。 |
PublicNotAdvertised |
ユーザーは、ロビー ID または招待によってロビーに参加できます。 |
InvitationOnly |
ユーザーは、招待によってのみロビーに参加できます。 |
ELobbyMemberLeaveReason
| 列挙子 | 説明 |
|---|---|
Left |
ロビー メンバーがロビーから退出することを選択します。 |
Kicked |
ロビー オーナーがロビーからロビー メンバーを削除しました。 |
Disconnected |
ロビー メンバーが予期せず退出しました。 |
Closed |
Online Services によりロビーが破棄され、すべてのメンバーが退出しました。 |
主な構造体
Lobby インターフェースの機能は、パラメータと戻り値を渡すための関数固有の構造体に加えて、主に 2 つの構造体 FLobbyMember および FLobby によって伝達されます。
FLobbyMember
| メンバー | 型 | 説明 |
|---|---|---|
AccountId |
FAccountId |
このロビー メンバーのアカウント ID。 |
PlatfromAccountId |
FAccountId |
このロビー メンバーのプラットフォーム アカウント ID。 |
PlatfromDisplayName |
FString |
このロビー メンバーのプラットフォーム表示名。 |
Attributes |
TMap<FSchemaAttributeId, FSchemaVariant> |
コンフィギュレーションで定義されたこのロビー メンバーの属性。 |
bIsLocalMember |
bool |
このロビー メンバーがこのクライアントのローカル プレイヤーであるかどうか。(デフォルト値は false)。 |
FLobby
| メンバー | 型 | 説明 |
|---|---|---|
LobbyId |
FLobbyId |
このロビーの ID。 |
OwnerAccountId |
FAccountId |
このロビーの現在のオーナーであるロビー メンバーのアカウント ID。 |
LocalName |
FName |
このロビーのローカル名。 |
SchemaId |
FSchemaId |
このロビーに適用されるスキーマの ID。 |
MaxMembers |
int32 |
このロビーに常時滞在できるメンバーの最大数。 |
JoinPolicy |
ELobbyJoinPolicy |
このロビーの参加ポリシーの設定。 |
Attributes |
TMap<FSchemaAttributeId, FSchemaVariant> |
コンフィギュレーションで定義されこのロビーの属性。 |
Members |
TMap<FAccountId, TSharedRef<const FLobbyMember>> |
ロビー メンバーの辞書。キーはアカウント ID で、値は対応するロビー メンバー構造体へのポインタです。 |
コンフィギュレーション
ロビーはスキーマ システムを使用して、ロビーの構造やプロパティ、ロビー メンバーの属性を定義します。1 つのゲームで複数の個別のスキーマ定義を宣言することで、さまざまなタイプのロビーをサポートすることができます。すべてのロビー スキーマは LobbyBase スキーマから派生している必要があります。
LobbyBase スキーマには、プレイヤーがロビーを検索するために使用できるすべての属性が含まれています。この継承構造により、Lobbies インターフェースは、ゲームで提供されたどのスキーマを検索結果に適用すべきかを把握できます。SchemaCompatibilityId は LobbyBase 内の特別な属性で、2 つのクライアント間でスキーマの互換性を保証します。
ゲームは、スキーマ定義に存在する各スキーマ属性の定義を宣言する必要があります。スキーマは、プロジェクトのコンフィギュレーション ファイル (*.ini) で定義されます。これらの定義には、属性のタイプ、最大サイズ、可視性のほか、その属性が検索パラメータとして使用可能かどうかなどの追加の動作が含まれます。
通常、スキーマには、属性定義を含むカテゴリがあります。Lobbies インターフェース スキーマには、2 つのカテゴリLobby と LobbyMember があります。これらのカテゴリには、ロビー オブジェクトとロビー メンバー オブジェクトにそれぞれ適用される属性定義が含まれています。
例
以下は、Lobbies インターフェースのコンフィギュレーションの例です。
DefaultEngine.ini
[OnlineServices.Lobbies]
+SchemaDescriptors=(Id="GameLobby", ParentId="LobbyBase")
!SchemaCategoryAttributeDescriptors=ClearArray
+SchemaCategoryAttributeDescriptors=(SchemaId="LobbyBase", CategoryId="Lobby", AttributeIds=("SchemaCompatibilityId", "ExampleSearchableLobbyAttribute"))
+SchemaCategoryAttributeDescriptors=(SchemaId="LobbyBase", CategoryId="LobbyMember")
+SchemaCategoryAttributeDescriptors=(SchemaId="GameLobby", CategoryId="Lobby", AttributeIds=("GameMode", "GameSessionId", "MapName", "MatchTimeout"))
+SchemaCategoryAttributeDescriptors=(SchemaId="GameLobby", CategoryId="LobbyMember", AttributeIds=("Appearance"))
+SchemaAttributeDescriptors=(Id="ExampleSearchableLobbyAttribute", Type="String", Flags=("Public", "Searchable"), MaxSize=64)
+SchemaAttributeDescriptors=(Id="GameMode", Type="String", Flags=("Public"), MaxSize=64)
+SchemaAttributeDescriptors=(Id="GameSessionId", Type="String", Flags=("Private"), MaxSize=64)
+SchemaAttributeDescriptors=(Id="MapName", Type="String", Flags=("Public"), MaxSize=64)
+SchemaAttributeDescriptors=(Id="MatchTimeout", Type="Double", Flags=("Public"))
+SchemaAttributeDescriptors=(Id="Appearance", Type="String", Flags=("Public"), MaxSize=64)
プロセス フロー
作成
プレイヤーがロビーの作成を開始します。ロビーが作成されるとそのプレイヤーがロビー リーダーに任命されます。ロビーを作成したプレイヤーは、ロビーの初期設定を決定します。設定には、以下が含まれる場合があります。
- 可視性
- 参加ポリシー
- スキーマ ID
- ロビーの属性
- ロビー メンバーの属性
他のプレイヤーは、ロビーを検索する際にこの公開属性を確認することができます。ロビー リーダーは、このページの リーダー アクション セクションで説明する追加権限を持ちます。リーダーを含むすべてのロビー メンバーは、自分の個人属性を変更したり、ロビーに参加するようプレイヤーを招待したりすることができます。これらのアクションの要約を、メンバー アクション セクションにまとめています。
ロビーを作成できたら、作成したプレイヤーは、OnLobbyJoined イベントの後に自分向けの OnLobbyMemberJoined イベントを受信します。これはロビーを作成したプレイヤーが、現在はロビー リーダーに任命されているためです。このプレイヤーは、ロビー リーダーに任命されている限り、プレイヤーのロビーへの参加および退出に伴う追加の OnLobbyMemberJoined イベントおよびOnLobbyMemberLeft イベントを受信します。
検索
ロビーに参加するには、まずそのロビーの ID を知る必要があります。プレイヤーは、以下の方法で ID を確認することができます。
- 検索
- 招待
検索と招待の両方で、クライアント アプリケーションにロビー データのスナップショットが提供されます。スナップショット内の属性は、プレイヤーがロビーに参加するまで更新されません。
検索
ロビー検索では、プレイヤーが属性を指定して、希望のコンフィギュレーションに一致するロビーを検索することができます。プレイヤーは、以下を使用してロビーを検索できます。
- 属性フィルタ
- ターゲット プレイヤー
- 特定のロビー ID
招待
ロビーのプライバシー設定によっては、ロビー メンバーが他のプレイヤーをロビーに招待できます。招待が送信されると、ターゲット プレイヤーは待機中の招待について通知する OnLobbyInvitationAdded イベントを受信します。OnLobbyInvitationRemoved イベントは、招待に対応したときか、期限が切れたときにトリガーされます。
ソーシャル プレゼンス
オンライン サービスの実装によっては、Online Services Presence インターフェース などの、ソーシャル ユーザー インターフェースを使用して、プレイヤーがフレンドのロビーに参加することができます。プレイヤーがこの方法で参加することを選択すると、OnUILobbyJoinRequested イベントがトリガーされ、アプリケーションにプレイヤーのロビーへの参加希望を示します。
参加
プレイヤーが参加を希望するロビーの ID を知ると、JoinLobby を呼び出すことによって、ローカル プレイヤーを追加するプロセスが開始されます。ローカル プレイヤーは、ロビーへの参加時に、初期の LobbyMember 属性を提供する必要があります。この属性は、他の既存のロビー メンバーと共有されます。
ロビーに参加できたら、プレイヤーは OnLobbyJoined イベントを受信します。ロビーの既存のメンバーは全員、新しいプレイヤーが参加したことを通知する OnLobbyMemberJoined イベントを受信します。プレイヤーがこのロビーに滞在している間、他のプレイヤーがロビーに参加するか、ロビーから退出すると、追加の OnLobbyMemberJoined イベントおよびOnLobbyMemberLeft イベントを受信します。
退出
プレイヤーがロビーへの滞在を希望しなくなった場合は、LeaveLobby が、提供されたロビー ID を使用して、そのプレイヤーをロビーから削除し、通知を停止します。プレイヤーがロビーから退出すると、ロビーにいる他のすべてのプレイヤーが OnLobbyMemberLeft 通知を受信します。これは、プレイヤーがロビーから退出したことを通知します。この通知の後、ロビーから退出したプレイヤーに OnLobbyLeft イベントが送信されます。
復元
RestoreLobbies は、呼び出したプレイヤーがこれまでに参加したすべてのロビーを復元します。これは、通常、アプリケーションの起動時にゲームによって実行され、アプリケーションが前回終了したときにローカル プレイヤーが参加していたロビーにプレイヤーが再び参加することができます。
リーダー アクション
ロビー リーダーには、ロビーを管理するためにロビー リーダーのみが使用できる追加の権限があります。
メンバーの昇格
ロビー リーダーは、PromoteLobbyMember の呼び出しを使用して、他のロビー メンバーをリーダーに昇格させることができます。このアクションでは、すべてのロビー メンバーに対して OnLobbyLeaderChanged イベントがトリガーされます。それまでリーダーだったプレイヤーは、通常のロビー メンバーになります。
メンバーの削除
ロビー リーダーは、KickLobbyMember の呼び出しを使用してターゲット メンバーをロビーから削除することができます。このアクションは、削除されたロビー メンバーに対して OnLobbyLeft イベントをトリガーし、他のロビー メンバーにも OnLobbyMemberLeft イベントをトリガーします。
ロビー属性の更新
ロビー リーダーは、ロビー オブジェクトの属性を変更できます。これは、ModifyLobbyAttributes の呼び出しによって処理されます。ロビー属性が変更されると、すべてのロビー メンバーは変更された属性を通知する OnLobbyAttributesChanged イベントを受信します。
ロビー参加ポリシーの変更
ロビーの参加ポリシーは、ロビーが検索結果に表示されるかどうか、招待のみで参加できるか、またはソーシャル プレゼンスで参加できるかを制御します。ロビー リーダーは、ModifyLobbyJoinPolicy の呼び出しでこの設定を変更することができます。
メンバー アクション
ロビー メンバーが実行できるアクションは、次の 2 つに制限されています。メンバーが実行できるのは、自分の属性を更新することと、他のメンバーをロビーに招待することです。
メンバー属性の変更
ロビー メンバーは、ModifyLobbyMemberAttributes の呼び出しを使用して、自分の属性を変更することができます。この変更は、OnLobbyMemberAttributesChanged イベントによって他のロビー メンバーに通知されます。
ロビーへのプレイヤーの招待
ロビーの参加ポリシーで現時点において招待が許可されている場合、ロビー メンバーは InviteLobbyMember の呼び出しにより、追加のプレイヤーを招待することができます。招待のターゲットは、保留中の招待について通知する OnLobbyInvitationAdded イベントを受信します。招待されたプレイヤーは、JoinLobby の呼び出しでロビーへの参加を選択するか、DeclineLobbyInvitation を使用して招待を拒否します。
Online Subsystem からコードを変換する
Lobbies は、Online Services の新しいインターフェースであり、Online Subsystem に直接相当するものはありません。
追加資料
ヘッダ ファイル
詳細については、必要に応じて、「Lobbies.h」ヘッダ ファイルで直接確認してください。Lobbies インターフェースのヘッダ ファイル「Lobbies.h」は次のディレクトリに格納されています。
UNREAL_ENGINE_ROOT\Engine\Plugins\Online\OnlineServices\Source\OnlineServicesInterface\Public\Online
UE のソース コードの入手方法については、「Unreal Engine のソース コードをダウンロードする」を参照してください。
関数パラメータおよび戻り型
関数のパラメータと戻り型、およびパラメータの渡し方や関数が戻ったときの結果の処理などについては、「Online Services の概要」ページの「関数」セクションを参照してください。
