Lobbies Interface

ロビーを操作するインターフェースです。

17 分で読めます

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

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

ロビーの作成と破棄

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

プロパティ
ApiVersionEOS_LOBBY_CREATELOBBY_API_LATEST
LocalUserIdロビーを作成するユーザー。このユーザーが所有者として自動でロビーに参加します。
MaxLobbyMembers同時にロビーに参加できるユーザーの最大数
PermissionLevelロビーがパブリックから見えるかどうかを設定します (詳細は「許可レベル」セクションを参照してください)。
BucketIdロビーに関連づけられるバケット ID。
bPresenceEnabledtrue の場合、このロビーはプレゼンス情報と関連づけられます。ユーザーのプレゼンスと関連づけられるロビーの数は 1 回につき 1 つのみです。
bAllowInvitesロビーのメンバーが他のメンバーを招待することができるかどうかを指定します。
bDisableHostMigrationホストが退出した場合、ホストの移行が許可されるか / ホストがオープンのままになるかを指定します。
bEnableRTCRoomこのロビーのすべてのメンバーに対してリアルタイム通信 (RTC) ルームを作成します。ロビーのすべてのメンバーは、ロビーに接続すると自動的に RTC に参加し、ロビーから退出または削除されると自動的に RTC ルームから去ります。RTC ルームへの参加と RTC ルームからの退出は自動ですが、ルームのその他すべての機能を処理するためには EOS RTC インターフェースが必要です。

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

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

プロパティ
ApiVersionEOS_LOBBY_DESTROYLOBBY_API_LATEST
LocalUserIdロビーの破棄をリクエストするユーザー。このユーザーは現在ロビーの所有者である必要があります。
LobbyId破棄するロビーの ID。

完了すると、破棄が成功したかどうかを示す 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 を呼び出します。

プロパティ
ApiVersionEOS_LOBBY_REJECTINVITE_API_LATEST
LobbyId招待に関連付けられたロビーの ID
LocalUserId招待を拒否するユーザーの ID

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

招待をすべて更新する

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

プロパティ
ApiVersionEOS_LOBBY_QUERYINVITES_API_LATEST
LocalUserId招待を取得する対象のユーザー ID

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

キャッシュから招待を取得する

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

プロパティ
ApiVersionEOS_LOBBY_GETINVITECOUNT_API_LATEST
LocalUserId招待をカウントする対象のローカル ユーザー

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

プロパティ
ApiVersionEOS_LOBBY_GETINVITEIDBYINDEX_API_LATEST
LocalUserId招待を所有するローカル ユーザー
Index取得する招待のインデックス

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

通知

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

メンバーをロビーから削除する