Lobbies インターフェース

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

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

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

ロビーの作成と破棄

ロビーは EOS_Lobby_CreateLobby 関数で作成します。この関数の EOS_Lobby_CreateLobbyOptions を以下のように初期化します。

プロパティ

ApiVersion

EOS_LOBBY_CREATELOBBY_API_LATEST

LocalUserId

ロビーを作成するユーザー。このユーザーが所有者として自動でロビーに参加します。

MaxLobbyMembers

同時にロビーに参加できるユーザーの最大数

Visibility

ロビーがパブリックから見えるかどうかを設定します (詳細は「許可レベル セクションを参照してください)。

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

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

プロパティ

ApiVersion

EOS_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 ボタン、ソーシャル オーバーレイ、ロビー間のインタラクションの詳細については、「

[ソーシャル オーバーレイ インテグレーション: ロビーを使用する](EpicAccountServices/SocialOverlayIntegration)
」を参照してください。

招待を拒否する

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

プロパティ

ApiVersion

EOS_LOBBY_REJECTINVITE_API_LATEST

LobbyId

招待に関連付けられたロビーの ID

LocalUserId

招待を拒否するユーザーの ID

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

招待をすべて更新する

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

プロパティ

ApiVersion

EOS_LOBBY_QUERYINVITES_API_LATEST

LocalUserId

招待を取得する対象のユーザー ID

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

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

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

プロパティ

ApiVersion

EOS_LOBBY_GETINVITECOUNT_API_LATEST

LocalUserId

招待をカウントする対象のローカル ユーザー

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

プロパティ

ApiVersion

EOS_LOBBY_GETINVITEIDBYINDEX_API_LATEST

LocalUserId

招待を所有するローカル ユーザー

Index

取得する招待のインデックス

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

通知

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

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

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

プロパティ

ApiVersion

EOS_LOBBY_KICKMEMBER_API_LATEST

LobbyId

メンバーの削除を行うロビーの ID。

LocalUserId

削除をリクエストするロビー メンバーの ID。これには必ずロビーの所有者を指定します。

EOS_ProductUserId TargetUserId

削除される対象のロビー メンバーの ID。

操作の完了後に 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 で検索する

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

ユーザー ID で検索する

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

属性で検索する

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

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

比較演算子

演算子

説明

すべての属性型で機能する比較

EOS_CO_EQUAL

属性と完全に一致する値の検索。

EOS_CO_NOTEQUAL

属性と完全に一致しない値の検索。

数値型で機能する比較

EOS_CO_GREATERTHAN

属性は検索値より大きい。

EOS_CO_GREATERTHANOREQUAL

属性は検索値以上。

EOS_CO_LESSTHAN

属性は検索値未満。

EOS_CO_LESSTHANOREQUAL

属性は検索値以下。

EOS_CO_DISTANCE

属性は次の式に基づいた検索値に近い:abs(attribute - searchvalue) = 0

文字列型で機能する比較

EOS_CO_ANYOF

属性は、セミコロンで区切られた文字列値リストのいずれかと等しい。例:"This;OrThis;MaybeThis"

EOS_CO_NOTANYOF

属性は、文字列値リストのどれとも一致しない。例:"NotThis;OrThisEither"

検索結果の制限

取得できる検索結果の最大数を制限するには 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:それぞれのユーザーに関連するキーと値のペア

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

許可レベル

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

許可レベル (マクロ)

ロビーのビヘイビア

EOS_LPL_PUBLICADVERTISED

公共のロビー。定員に達しない限り、任意のユーザーがいつでも検索して参加できます。

EOS_LPL_JOINVIAPRESENCE

フレンド専用のロビー。このロビーは全体の検索結果に表示されず、所有者のフレンドだけが参加できます。ただし、このロビーは private ではなく、ロビー ID が分かる場合は見つけることができます。

EOS_LPL_INVITEONLY

この種類のロビーはプライベートで検索結果に表示されません。既存のメンバーから招待されたユーザーのみが、このロビーに参加できます。

ロビーやユーザーの情報を変更する

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

所有者を変更する

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

ロビーとそのメンバーのプロパティ

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

フィールド

コンテンツ

Key

属性を特定する文字列。属性を検索したときに、この文字列がシステムによって比較されます。

Value

Key に関連付けられた数値、文字列、またはブール値のデータ。

ValueType

Value が含むデータの型を示します。

Visibility

アドバタイズされるか、セッション EOS_ELobbyAttributeVisibility でローカルにただ格納される属性。

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

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

関数

効果

EOS_LobbyModification_SetPermissionLevel

ロビーの許可レベルの設定に使用します。

EOS_LobbyModification_SetMaxMembers

この関数は同時にロビーに参加できるユーザーの最大数を変更します。この値に設定できる範囲は、現在ロビーにいるユーザー数から EOS_LOBBY_MAX_LOBBY_MEMBERS までです。

EOS_LobbyModification_AddAttribute

ロビーのデータに新しいキーと値のペアを追加します。

EOS_LobbyModification_RemoveAttribute

ロビーのデータからキーと値のペアを削除します。

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

関数

効果

EOS_LobbyModification_AddMemberAttribute

ロビーにいる特定のメンバーに、新しいキーと値のペアを追加します。

EOS_LobbyModification_RemoveMemberAttribute

ロビーにいる特定のメンバーから、キーと値のペアを削除します。

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

イベントを通知する

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

ロビーのデータを更新する

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

ユーザー データを更新する

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

ロビー メンバーの状態

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

イベントの種類

意味

EOS_LMS_JOINED

ロビーに新しいユーザーが参加し、すぐ後にロビーのメンバーの更新が予想される。

EOS_LMS_LEFT

既存のユーザーがロビーから退場して関連するデータが削除された。

EOS_LMS_DISCONNECTED

既存のユーザーが予期せずロビーから退場した。

EOS_LMS_KICKED

所有者が特定のユーザーをロビーから削除した。

EOS_LSM_PROMOTED

前の所有者によって明示的に、または前の所有者がロビーを退場したことで暗黙的に、既存のユーザーがロビーの所有者に昇格した。

EOS_LMS_CLOSED

所有者が破棄したか、もしくはエラーが発生したため、ロビーが終了した。

使用上の制限事項

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

[](Overview#ServiceUsageLimitations)
」を参照してください。

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

機能

サービスの制限事項

ロビーでの最大プレイヤー数

64

最大セッション属性数

100

最大メンバー属性数

100

文字列属性の長さ

1000 文字

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

機能

ユーザー制限

接続

30 リクエスト / 分

ロビーを作成

30 リクエスト / 分

ロビーを削除

30 リクエスト / 分

ロビーに参加

30 リクエスト / 分

1 度に 1 人のユーザーが参加できるロビー数

16

ロビーデータの読み取り

100 リクエスト / 分

ロビー属性の更新

100 リクエスト / 分

メンバー属性の更新

100 リクエスト / 分

ロビー設定の変更

30 リクエスト / 分

ユーザーの招待

30 リクエスト / 分

招待の削除

30 リクエスト / 分

プレイヤーのキックアウト

30 リクエスト / 分

メンバーのロビー オーナーへの昇格

30 リクエスト / 分

ロビーの検索

30 リクエスト / 分

ID によるロビーの取得

100 リクエスト / 分

ユーザーによるロビーの検索

30 リクエスト / 分

ユーザーによる招待の検索

30 リクエスト / 分

招待によるロビーの検索

30 リクエスト / 分

1 クエリでの検索結果の最大数

256