Sessions Interface

インターフェースセッションベースのマッチメイキングを処理するインターフェース

28 分で読めます

Epic Online Services (EOS) では Sessions インターフェース を使用して、プレイヤーはオンライン ゲーム セッションをホスト、検索、および操作することができます。ゲーム開始前に特定数のプレイヤー スロットを埋めて、ゲーム終了後に解散するなどの場合は、セッションは短くなる可能性があります。また、複数のマップやレベルにわたって対戦を繰り返すゲームの経過を追跡するなどの場合は、セッションが長くなる可能性があります。また、Sessions インターフェースでは、バックエンド サービスの検索およびマッチメイキング機能をサポートするゲーム固有のデータも管理します。

Sessions インターフェースを利用するには、Platform インターフェース 関数 EOS_Platform_GetSessionsInterface を使用して EOS_HSessions ハンドルを取得する必要があります。すべての Sessions インターフェースの関数が 1 つ目のパラメータとしてこのハンドルを使用する必要があります。リクエストの完了時にトリガーする、コールバックの EOS_HPlatform ハンドルが確実にティックするようにしてください。

このインターフェースを使用する場合のさまざまな考慮事項について、「セキュリティに関するドキュメント」を参照してください。

アクティブセッション

アクティブ セッションは、Sessions インターフェースが実行するあらゆる処理の中核をなします。アプリケーションは同時に複数のアクティブ セッションを持つことができ、それぞれが一意のローカル名で識別されます。たとえば、ローカル プレイヤーのフレンドで構成される「パーティー」というセッションがあり、そのセッションでは他のチームとの対戦時にそれらのフレンド全員をまとめて保持します。また、それらのフレンドの一部または全員、および現在進行中の対戦の他のプレイヤーを含む「ゲーム」という別のセッションもあるといった状況が考えられます。各セッションには、参加している各プレイヤーのシステムごとに独自の EOS_HActiveSession ハンドルがあります。アクティブ セッションは、プレイヤーがセッションを作成するか、オンライン検索または招待から見つかったセッションに参加するたびに、プレイヤーのマシンで形成されます。アクティブ セッションはローカルに存在するため、ローカル アプリケーションでは、不要になったらアクティブ セッションを破棄する必要があります。ホストがこれを実行できない場合、バックエンド サービス サーバーによるセッションの破棄が遅れ、他のプレイヤーがオンライン検索で意図せずセッションを検出することにつながる可能性があります。

作成または参加したローカル ユーザーの名前、ID、現在の状態、セッションの詳細への参照 (EOS_SessionDetails_Info への定数ポインタ) やユーザー定義のデータ属性といったアクティブ セッションの高レベルの情報 (EOS_ActiveSession_Info 型) のコピーを取得するには、まず次のように初期化された EOS_Sessions_CopyActiveSessionHandleOptions を指定したローカル関数 EOS_Sessions_CopyActiveSessionHandle を呼び出して、アクティブ セッション ハンドル (EOS_HActiveSession 型) を取得する必要があります。

プロパティ
ApiVersionEOS_SESSIONS_COPYACTIVESESSIONHANDLE_API_LATEST
SessionNameセッション ハンドルを取得するセッションの名前です。

このハンドルを使用すると、EOS_ActiveSession_CopyInfo を呼び出すことができます。また、次のように EOS_ActiveSession_CopyInfoOptions を初期化して渡す必要があります。

プロパティ
ApiVersionEOS_ACTIVESESSION_COPYINFO_API_LATEST

この関数もローカルで実行され、成功時には、セッションの EOS_ActiveSession_Info データのコピーが作成されます。コピーは、不要になったら、EOS_ActiveSession_Info_Release を使用して解放する必要があります。

セッションの詳細

ローカルで作成するか、検索、招待、または他のユーザーの プレゼンス データを使用して検出するアクティブ セッションでは、EOS_SessionDetails_Info という内部データ構造体を格納します。この構造体はセッションに関する次の基本的な詳細を格納します。

  • セッション ID

  • ホスト アドレス

  • セッションの空きスロットの数

この構造体には、別の構造体 EOS_SessionDetails_Settings へのポインタも格納されています。この構造体では、次を含む、セッションの状態に関する詳細を提供します。

バケット ID と呼ばれる最上位のフィルタ条件。これは、ゲームに固有であり、多くの場合、「GameMode:Region:MapName」などの形式になります。

  • セッションで許可されている接続の総数

  • 進行中に参加の設定

  • プライバシー設定

セッションの詳細にアクセスする

EOS_ActiveSession_Info データ構造体がある場合、その SessionDetails 変数により、当該セッションの EOS_SessionDetails_Info にアクセスできます。このデータ構造体がない場合は、EOS_HSessionDetails ハンドルを使用して EOS_SessionDetails_CopyInfo を呼び出すことで、EOS_SessionDetails_Info データのコピーを取得できます。次の情報が格納されている EOS_SessionDetails_CopyInfoOptions 構造体を指定して EOS_SessionDetails_CopyInfo を呼び出します。

プロパティ
ApiVersionEOS_SESSIONDETAILS_COPYINFO_API_LATEST

成功時、これは、セッションの EOS_SessionDetails_Info のコピーを返します。このコピーには、セッションの ID、ホストのアドレス、セッションの空きスロットの数が格納されています。この情報が不要になったら、EOS_SessionDetails_Info_Release を呼び出して解放します。

セッションを作成する

セッションの作成は次の 2 つのステップで実行されます。

まず、EOS_Sessions_CreateSessionModification 関数を使用して、セッションの初期状態と設定をローカルで設定します。次の情報を含む EOS_Sessions_CreateSessionModificationOptions 構造体を渡す必要があります。

プロパティ
ApiVersionEOS_SESSIONS_CREATESESSIONMODIFICATION_API_LATEST
SessionNameセッション名。このユーザーによって作成されたセッションで一意です。
BucketIdセッション検索のための最上位のゲーム固有のフィルタ情報です。この条件は、ほとんど固定的かつ大まかな設定で設定する必要があります。多くの場合、「GameMode:Region:MapName」といった形式で指定します。
MaxPlayersいつでもセッションで許可されるプレイヤーの最大数です。
LocalUserIdセッションに関連付けられているユーザー ID です。
bPresenceEnabledこのセッションがローカル ユーザーのプレゼンス情報に関連付けられたセッションであるかどうか (詳細については「Presence (プレゼンス) インターフェース」を参照)。
SessionId(任意) 作成時にこのセッションに定期的に割り当てられる独自の ID をオーバーライドするために設定する値です。これを使って他のデベロッパー ID と関連する値を設定することも可能です。この方法によって、private sessions” を見つけるためにセッションに属性を追加したり、セッションをパブリックに公表する必要がなくなります。この値はアプリケーション エコシステムにおいてグローバルにユニークでなければなりません。そうしない場合、結果として 'EOS_Sessions_SessionAlreadyExists' エラーとなります。
bSanctionsEnabledこのセッションで、処罰対象のユーザーがこのセッションに参加できないようにする必要があるかどうかを設定します。これにより、これらのユーザー Join および RegisterPlayers への呼び出しに成功しないようにします。詳細は「Sanctions インターフェース」を参照してください。

EOS_Sessions_CreateSessionModification 呼び出しが成功すると、EOS_Success を返し、指定したデフォルトの EOS_HSessionModification に有効なハンドルが格納されます。

次に、必要なすべての変更が完了するまで、セッションの初期設定を変更し続けます (「[セッションを変更する]」セクションを参照)。次のように初期化された EOS_Sessions_UpdateSessionOptions 構造体を指定して EOS_Sessions_UpdateSession を呼び出すことで、作成プロセスを完了できます。

プロパティ
ApiVersionEOS_SESSIONS_UPDATESESSION_API_LATEST
SessionModificationHandle作成または更新するセッションのハンドル (EOS_HSessionModification)

EOS_Sessions_UpdateSession は非同期であり、完了時に EOS_Sessions_UpdateSessionCallbackInfo データ構造体を指定して (EOS_Sessions_OnUpdateSessionCallback 型の) デリゲートを呼び出します。成功時は、指定したローカル名が、サーバーの検索可能な一意の ID 文字列とペアになります。

セッションを変更する

既存のセッションを変更するには、まず、デフォルトの EOS_HSessionModification オブジェクトへのポインターと次のように初期化された EOS_Sessions_UpdateSessionModificationOptions 構造体を指定して EOS_Sessions_UpdateSessionModification を呼び出します。

プロパティ
ApiVersionEOS_SESSIONS_UPDATESESSIONMODIFICATION_API_LATEST
SessionName変更するセッションの名前

この呼び出しが成功すると、EOS_Success を返し、変更がローカル セッションに適用され、指定した EOS_HSessionModification オブジェクトが有効なハンドルになります。セッション所有者である場合は、そのハンドルを使用すると、EOS_Sessions_UpdateSession を呼び出すことで、セッションのバックエンド サービスのバージョンに行ったローカルの変更を適用できます。この関数は、新しいセッション (サーバーでまだ作成されていないセッション) と既存のセッションの両方で機能します。次の関数は、セッションのさまざまな要素を変更します。

Function Effect
EOS_SessionModification_SetHostAddress サーバーに到達するために必要なデータを含む文字列を変更します。ホスト アドレスは IP アドレスである必要はありません。ソケット ID、URL、またはその他の属性でも機能します。
EOS_SessionModification_SetBucketId バケット ID は主要な検索条件であり、すべての検索で必要なゲーム固有の情報が格納されています。たとえば、「GameMode:Region:MapName」といった形式を使用してバケット ID を形成できます。
EOS_SessionModification_SetMaxPlayers これを使用して、セッションで許可されるプレイヤーの最大数を設定します。
EOS_SessionModification_SetJoinInProgressAllowed この関数を使用すると、既に開始されているゲームへの参加をプレイヤーに許可または禁止することができます (詳細については「プレイを開始および終了する」セクションを参照)。
EOS_SessionModification_SetPermissionLevel この関数は、セッションのプライバシー設定を次のいずれかに変更できます。
  • EOS_OSPF_PublicAdvertised:セッションがすべてのプレイヤーに表示され、検索で表示されます。
  • EOS_OSPF_JoinViaPresence:セッション ID を含む、作成中のユーザーのプレゼンス情報にアクセスできるプレイヤーだけに、このセッションが表示されます。
  • EOS_OSPF_InviteOnly:セッションは招待されたプレイヤーのみが利用できます。
EOS_SessionModification_AddAttribute セッションにカスタム属性 (EOS_SessionDetails_AttributeData 型) を追加します。詳細については、「[キャッシュ ストレージ](キャッシュ ストレージ)」セクションを参照してください。
EOS_SessionModification_RemoveAttribute セッションからカスタム属性を削除します。詳細については、「[キャッシュ ストレージ](キャッシュ ストレージ)」セクションを参照してください。

セッションをローカルで変更した後、セッション所有者であれば、バックエンド サービスのセッションを更新できます。これを実行するには、次の情報を格納する EOS_Sessions_UpdateSessionOptions を使用して EOS_Sessions_UpdateSession を呼び出します。