Lobby Interface

ロビーは、ユーザー間の永続的な接続を提供し、ゲームとユーザーの状態をリアルタイムで更新して共有できるようにします。通常、ユーザーがロビーを作成したりこれに参加したりすると、チームの編成、ゲーム前のオプション選択、他のプレイヤーの参加を待って一緒にプレイすることができます。ユーザーは Lobbyインターフェース を使用して、ロビーの作成、参加、離脱、管理を行えます。

Lobby インターフェースを利用するには、Platform Interface 関数の EOS_Platform_GetLobbyInterface で EOS_HLobby ハンドルを取得する必要があります。すべてのロビー インターフェースの関数が 1 つ目のパラメータとしてこのハンドルを使用する必要があります。必ず EOS_HPlatform ハンドルがティックしており、操作の完了時に適切なコールバックをトリガーするようにします。

ロビーは EOS_Lobby_CreateLobby 関数で作成します。プロパティと詳細については、「EOS_Lobby_CreateLobbyOptions」を参照してください。 EOS_Lobby_CreateLobbyOptions を以下のように初期化します。

操作の完了後に EOS_Lobby_OnCreateLobbyCallback を EOS_Lobby_CreateLobbyCallbackInfo データ構造とともに実行します。このデータ構造の ResultCode フィールドに成功と表示された場合は、LobbyId フィールドに新しいロビーの ID 値が含まれます。この値は今後ロビーで操作を行う際に必要となります。

ロビーの所有者がロビーを破棄する場合、次の情報で初期化した EOS_Lobby_DestroyLobbyOptions 構造体とともに EOS_Lobby_DestroyLobby を呼び出す必要があります。

完了すると、破棄が成功したかどうかを示す EOS_Lobby_DestroyLobbyCallbackInfo データ構造とともに EOS_Lobby_OnDestroyLobbyCallback コールバック関数を、実行します。ロビーを閉じると残っているメンバーを全員自動で削除して、ステー EOS_LMS_CLOSED でメンバー状態の更新をトリガーします。

通常、ロビーのライフサイクルは以下の順序です。

• ユーザーがロビーを作成します。このユーザーが自動でロビーに参加して、最初のメンバーかつ所有者になります。
• この所有者がロビーの初期状態を設定して、他のユーザーを招待して参加させます。
• 他のユーザーがロビーに参加したり退出したりします。接続中のメンバーは、自分自身の状態に関する情報を更新したり、他のユーザーを招待できます。
• ロビーの所有者は、ゲームのステート専用のデータを更新することができます。
• 所有者はロビーからメンバーを削除したり、所有者の状態を他のメンバーに譲渡したりできます。
• ロビーから退出したりロビーを破棄せずに、ユーザーは複数ラウンドのゲームをプレイできます。ゲーム ロジックがロビーのライフタイムを決定します。
• 最後に所有者がロビーを破棄します。

有効な EOS_HLobbyDetails ハンドルで EOS_Lobby_JoinLobby を呼び出すと、そのユーザーはハンドルが参照する先のロビーに参加を試みます。ユーザーは同時に複数のロビーに参加できます。ユーザーがあるロビーに参加しても、参加している他のロビーから退出する必要はありません。新しいロビーに参加しても、既存のロビーの退出にはなりません。ロビーの退出または破棄は明示的でなければなりません。

ロビーから退出するには EOS_Lobby_LeaveLobby を呼び出します。ロビーから退出するユーザーが現在の所有者の場合、EOS は残りのユーザーから新しい所有者を選びます。ユーザーが退出したときや、所有者が変わったときは、すべてのメンバーが通知を受け取ります。

ロビーに参加しているユーザーは EOS_Lobby_SendInvite 関数で他のユーザーを招待できます。招待を正常に送信すると、EOS_Lobby_OnSendInviteCallback 型のコールバックがローカルでトリガーされます。招待が到着すると、対象ユーザーは [通知] を受け取ります。ゲームはプレイヤーがいつオーバーレイで [Accept (承諾)] ボタンをクリックしたかを確認するために EOS_Sessions_AddNotifySessionInviteAccepted を使用します。Invite ボタン、ソーシャル オーバーレイ、ロビー間のインタラクションの詳細については、「ソーシャル オーバーレイ インテグレーション: ロビーを使用する」を参照してください。Epic Games Launcher の招待機能の場合は、デプロイメントを アーティファクト にもマッピングしてください。

招待を拒否するには、以下の情報を含む EOS_Lobby_RejectInviteOptions 構造体とともに EOS_Lobby_RejectInvite を呼び出します。

完了すると EOS_Lobby_OnRejectInviteCallback 関数が EOS_Lobby_RejectInviteCallbackInfo データ構造とともにローカルでトリガーされます。成功すると、その招待がシステムから完全に削除されます。

ローカル キャッシュに保留した招待がすべて存在することを確認するには、以下のデータを含む EOS_Lobby_QueryInvitesOptions 構造体とともに EOS_Lobby_QueryInvites を呼び出します。

操作の完了後に、EOS_Lobby_OnQueryInvitesCallback を EOS_Lobby_QueryInvitesCallbackInfo データ構造とともに実行します。成功すると、指定したユーザーの保留した招待がローカル キャッシュにすべて含まれます。この招待は検索できます。これはユーザーがオフラインだったときに受け取った招待を、起動時に確認するのに役立ちます。プレイ中は登録した通知があるので、この関数をユーザーが呼び出す必要はほとんどありません。

キャッシュされた招待を確認するには、まず以下のように初期化した EOS_Lobby_GetInviteCountOptions 構造体とともに EOS_Lobby_GetInviteCount を呼び出します。

この関数をローカル キャッシュに対して実行すると、キャッシュにある保留した招待の数を示す uint32_t をすぐに返します。その後、以下のデータを含む EOS_Lobby_GetInviteIdByIndexOptions 構造体とともに EOS_Lobby_GetInviteIdByIndex を呼び出します。

EOS_Lobby_GetInviteIdByIndex はローカル キャッシュに対しても実行され、呼び出しが成功すると EOS_Success をすぐに返します。成功すると、指定した出力パラメータに招待のデータとサイズのコピーが追加されます。このバッファは不要になったときに解放する必要があります。

ユーザーが EOS_Lobby_AddNotifyLobbyInviteReceived でコールバックを登録している場合、リアルタイムで招待を受け取ります。このコールバック データは招待に関連する情報をすべて含みます。この時点では、ユーザーは EOS_Lobby_CopyLobbyDetailsHandleByInviteId を使用して招待を EOS_HLobbyDetails の形式で取得できます。これはロビーに参加するために必須となります。アプリケーションを終了する場合、またはオフラインにする場合は、EOS_Lobby_RemoveNotifyLobbyInviteReceived を使用してコールバックを通知リストから削除します。

ロビーの所有者はロビーのメンバーをいつでも削除できます。実行するには、以下のように初期化した EOS_Lobby_KickMemberOptions データ構造で EOS_Lobby_KickMember を呼び出します。

操作の完了後に EOS_Lobby_KickMemberCallbackInfo データ構造で EOS_Lobby_OnKickMemberCallback 関数の呼び出しを受けます。さらに、残っているロビー メンバー全員が EOS_LMSC_KICKED イベントの通知を受け取ります。

EOS_Lobby_CreateLobbySearch はハンドル (EOS_HLobbySearch 型) を作成して、これを使用して検出できるように設定されたロビーを検索できます。詳細は「許可レベル」を参照してください。このハンドルを以下の関数を使用して構成し、EOS_LobbySearch_Find を呼び出して実行します。正常に完了するとアプリケーションは検索結果を参照できます。複数の検索操作を異なるハンドルで同時に実行できます。

検索の完了後に EOS_LobbySearch_GetSearchResultCount を使用して、特定の EOS_HLobbySearch ハンドルについて結果の数を取得します。その後、EOS_LobbySearch_CopySearchResultByIndex でそれぞれの結果のコピーをリクエストできます。このコピーが完了したら EOS_LobbyDetails_Release でデータを破棄し、使用したメモリを解放します。

ユーザーが必要なロビー ID を把握している場合は、EOS_LobbySearch_SetLobbyId で直接検索できます。ロビー ID を他のユーザーと共有することは、この API では想定していません。

EOS_LobbySearch_SetTargetUserId は既知のユーザー ID から、その対象ユーザーがメンバーになっているロビーを表す検索結果を返します。

ロビーを探す最も強力な方法は、目的の設定サブセットを検索することです。これは、ユーザー インターフェースでユーザーが選択したフィルターのコレクションに対応して実現でき、ユーザーのスキルやその他の要因に基づき自動でバックグラウンド実行することも、両方の方法を組み合わせて実行することもできます。

EOS_LobbySearch_SetParameter で、ユーザーによる EOS_Lobby_AttributeData の設定と、属性をサービスとともに保存されているすべての既存のロビーと比較する方法を示す EOS_EComparisonOp の提供が可能になります。これらの呼び出しの 1 つ以上で暗黙のブール値 AND を使用して、検索パラメータを設定します。

取得できる検索結果の最大数を制限するには EOS_LobbySearch_SetMaxResults 関数を使用します。

ロビーに関する情報を取得するには、ユーザーは EOS_HLobbyDetails ハンドルをリクエストします。ローカル ユーザーとロビーの接続に基づいて、この情報を提供する関数が 3 つあります。

• EOS_Lobby_CopyLobbyDetailsHandle は、現在そのロビーに接続しているユーザーが使用できます。
• EOS_Lobby_CopyLobbyDetailsHandleByInviteId はロビーへの招待が必要となります。
• EOS_LobbySearch_CopySearchResultByIndex は、ローカル ユーザーが検索から見つけたロビーで機能します。

上記いずれかの操作が正常に完了すると EOS_HLobbyDetails ハンドルを受け取り、これで以下の情報にアクセスできます。

• Lobby ID:そのロビーに固有の識別子
• Lobby Owner:そのロビーの現在の所有者
• Permission level:ロビーの検索や参加ができるユーザーに関する制限。以下の「許可レベル」を参照してください。
• Space Available:現在利用できる空きスロットの数
• Max Members:同時にロビーに参加できるユーザーの最大数
• Lobby Attributes:そのロビーに関連するキーと値のペア
• Lobby Member Attributes:それぞれのユーザーに関連するキーと値のペア
• Lobby Member Platform:個々のユーザーのハードウェア プラットフォームはサーバーによって特定されます。この値はコンソール プラットフォームのロビー メンバーのみに提供され、それ以外はプレースホルダー値を返すことに注意してください。このプレースホルダー値は、特定のユーザーのハードウェア プラットフォームを確実に特定できないことを示します。

そのロビーの所有者の ID は EOS_LobbyDetails_GetLobbyOwner を呼び出して見つけます。ロビーに関する詳細は EOS_LobbyDetails_CopyInfo 関数を使用して EOS_LobbyDetails_Info データ構造の形式で取得できます。この取得する EOS_LobbyDetails_Info は、EOS SDK でキャッシュした情報のコピーです。メモリ リークを防ぐために、EOS_LobbyDetails_Info_Release 関数で所有するデータのメモリを解放する必要があります。このデータはスナップショットなので、受け取った後でそのロビーに関連する情報が変更されても更新は行われません。

ロビーの許可レベルは、ロビーを検索して参加できるユーザーに関する条件を制御します。所有者は EOS_LobbyModification_SetPermissionLevel を呼び出して、これをいつでも変更できます。以下の設定を使用できます。

ロビーの所有者は、最初に EOS_Lobby_UpdateLobbyModification を呼び出してロビー変更ハンドル (EOS_HLobbyModification 型) を取得することによって、ロビーを変更したり、メンバーはユーザー情報を変更したりできます。

EOS_Lobby_PromoteMember を呼び出すことで、所有者はロビーの他のメンバーを新しい所有者に昇格できます。1 つのロビーの所有者は 1 人だけなので、これを呼び出したユーザーはその時点で所有者の地位を失います。そして、メンバー全員がこのイベントの通知を受け取ります。

ロビーと各メンバーは、アプリケーションに固有のキーと値の属性を持つことができます。これらの属性は、数値、文字列、またはブール値のデータとして表すことができる限り、EOS_Lobby_Attribute データ型でサポートされます。これらの属性は、数値、文字列、ブールデータで表現されなければなりません。EOS_Lobby_Attribute データ構造は以下の情報を含みます。

Lobby and lobby member attributes have public and private visibilities. In public visibility, data is visible to all members outside of the lobby for lobby attributes, and data is visible inside the lobby for lobby member attributes. Conversely, for private visibility, data is visible inside the lobby for lobby attributes, and data is visible to the member only for lobby member attributes.

単一のロビーの単一のユーザー、またはロビー自体は、最大で EOS_LOBBYMODIFICATION_MAX_ATTRIBUTES 属性を持てます。Key の属性名フィールドは最大で EOS_LOBBYMODIFICATION_MAX_ATTRIBUTE_LENGTH 文字です。

ロビーの現在の所有者は、次の関数でロビーに変更を加えることができます。

既に接続しているユーザーは、次の関数で自分のデータを変更できます。

必要な属性をすべて変更したら、その変更をロビーにコミットして有効化する必要があります。これは EOS_Lobby_UpdateLobby の呼び出しで行います。この操作が完了すると、変更が反映されて他のロビー メンバーが通知を受け取ります。また、変更したユーザー自身はコールバック関数の呼び出しも受け取ります。

ユーザーはロビーに永続的に接続でき、ロビーの存続中に発生したイベントについて通知を受け取ります。通知の登録は開始時に行うことができ、各コールバックで完全な情報が提供されるため、影響するロビーについて知ることができます。

所有者がロビーのプロパティを変更すると、ロビーのメンバー全員が通知を受け取ります。この通知は何らかの変更があったことのみを知らせます。ゲームはロビーで利用できるデータをすべて評価して、これをゲームに再適用する必要があります。

ロビーのメンバーが自分のデータについてプロパティを変更すると、ロビーのメンバー全員が毎回通知を受け取ります。この通知は何らかの変更があったことのみを知らせます。ゲームはロビー メンバーの利用できるデータをすべて評価して、これをゲームに再適用する必要があります。

ロビーに参加するユーザーが以下に示すアクティビティを行うと、他のロビー メンバー全員に発生と同時に通知が送信されます。

EOS の Lobby を使って Epic のサーバー上、または独自のバックエンド サービス上に EOS Voice チャットルームをホストすることができます。このインターフェースを使用して、対戦中や製品のロビーで、複数のプラットフォーム間で一対一またはグループでコミュニケーションを取ることができます。詳細は「Lobby を使用した Voice のフロー」と「Voice インターフェース」を参照してください。

EOS Lobbies RTC ルーム機能を使用するアプリケーションはロビー システムによって内部で自動的に処理されるため、ボイス ルームに手動で参加または退出する必要はありません。RTC Room を有効にしてロビーが正常に作成されると、ローカル ユーザーがロビーに存在する限り、ロビー システムは RTC ルームへ参加と接続を自動的に管理します。

アプリケーションは、必要に応じて、情報提供の目的で、オプションの EOS_Lobby_IsRTCRoomConnected、EOS_Lobby_AddNotifyRTCRoomConnectionChanged、および EOS_Lobby_RemoveNotifyRTCRoomConnectionChanged 関数を使用できます。適用例としては、マルチプレイヤー ロビー内で Lobby RTC サービスから切断されると切断のアイコンを表示することです。

EOS_RTC_* 関数または EOS_RTCAudio_* 関数のスイートと対話するためには、アプリケーションはまず EOS_Lobby_GetRTCRoomName 関数を使ってロビーに関連付けられているルーム名を取得します。Result パラメーターが EOS_Success の場合、EOS_Lobby_GetRTCRoomName を正常に呼び出すことができる最も早いものは EOS_Lobby_OnJoinLobbyCallback または EOS_Lobby_OnCreateLobbyCallback の内部にあります。また、この時点で、アプリケーションはロビーの RTC ルームに固有のすべての RTC 通知に登録して、ルームの既存のメンバーなどのこれらの通知の直後に発生する可能性のある通知を見逃さないようにする必要があります。

RTC ルーム名を使用する例：

• 通話状況やルームメンバーシップなどの通知を登録する場合
• ルームのローカルユーザーのオーディオ出力をミュートまたはミュート解除する場合
• 部屋の参加者をブロックまたはブロック解除する場合
• ローカル オーディオ デバイス設定を行う場合。

次の関数は、通常使用される EOS_RTC_* 関数の置き換えに使用されますが、機能が内部で処理されているか、データがアプリケーションで提供されていないか、機能が EOS_RTCAdmin_*` 関数であるため、互換性のないロビーです。

ロビーのオーナーは EOS_Lobby_HardMuteMemberOptions データ構造体で EOS_Lobby_HardMuteMember を呼び出すことで既存のロビー メンバーをハードミュートすることができます。この構造体は、特定のメンバーをミュートすべきか否かに関する情報を含んでいます。ハードミュートにすることで、ローカルのミュート ステータスに関係なく、ロビー メンバーの可聴性がすべての人に対して変更されます。

操作の完了後に、EOS_Lobby_OnHardMuteMemberCallback を EOS_Lobby_HardMuteMemberCallbackInfo データ構造とともに実行します。このデータ構造の ResultCode フィールドに成功と表示された場合は、LobbyId フィールドに新しいロビーの ID 値、そして TargetUserId にはハード ミュート ステータスが更新されたメンバーが含まれています。

ロビーは、ユーザー間の永続的な接続を提供し、ゲームとユーザーの状態をリアルタイムで更新して共有できるようにします。通常、ユーザーがロビーを作成したりこれに参加したりすると、他のユーザーとのチャット、チームの編成、ゲーム前のオプション選択、他のユーザーの参加を待って一緒にプレイすることができます。スロットリング、使用クォータ、ベストプラクティスの一般情報については、「」を参照してください。

ロビー サービスに対する一般的な制限事項は以下の通りです。

ユーザーごとのレート制限もあります。スロットリングを避けるために、以下の制限事項を考慮してください。