Sessions インターフェース

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

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 型) を取得する必要があります。

プロパティ

ApiVersion

EOS_SESSIONS_COPYACTIVESESSIONHANDLE_API_LATEST

SessionName

セッション ハンドルを取得するセッションの名前です。

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

プロパティ

ApiVersion

EOS_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 を呼び出します。

プロパティ

ApiVersion

EOS_SESSIONDETAILS_COPYINFO_API_LATEST

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

セッションを作成する

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

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

プロパティ

ApiVersion

EOS_SESSIONS_CREATESESSIONMODIFICATION_API_LATEST

SessionName

セッション名。このユーザーによって作成されたセッションで一意です。

BucketId

セッション検索のための最上位のゲーム固有のフィルタ情報です。この条件は、ほとんど固定的かつ大まかな設定で設定する必要があります。多くの場合、「GameMode:Region:MapName」といった形式で指定します。

MaxPlayers

いつでもセッションで許可されるプレイヤーの最大数です。

LocalUserId

セッションに関連付けられているユーザー ID です。

bPresenceEnabled

このセッションがユーザーのプレゼンス情報に関連付けられたセッションであるかどうか (詳細については「Presence (プレゼンス) インターフェース」を参照)。

'SessionId'

(任意) 作成時にこのセッションに定期的に割り当てられる独自の ID をオーバーライドするために設定する値です。これを使って他のデベロッパー ID と関連する値を設定することも可能です。この方法によって、private sessions" を見つけるためにセッションに属性を追加したり、セッションをパブリックに公表する必要がなくなります。この値はアプリケーション エコシステムにおいてグローバルにユニークでなければなりません。そうしない場合、結果として 'EOS_Sessions_SessionAlreadyExists' エラーとなります。

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

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

プロパティ

ApiVersion

EOS_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 を呼び出します。

プロパティ

ApiVersion

EOS_SESSIONS_UPDATESESSIONMODIFICATION_API_LATEST

SessionName

変更するセッションの名前

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

関数

効果

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 を呼び出します。

プロパティ

ApiVersion

EOS_SESSIONS_UPDATESESSION_API_LATEST

SessionModificationHandle

サーバーに作成または更新させるセッションのハンドル (EOS_HSessionModification)

この操作は、完了時に、EOS_Sessions_UpdateSessionCallbackInfo データ構造体を指定して (EOS_Sessions_OnUpdateSessionCallback 型の) コールバック関数を呼び出します。

EOS ではプレイ中のセッションの変更をサポートしています。終了したものの、破棄されていないセッションでも、更新を受信して再開できます。このビヘイビアの一般的な使用例は、1 つのマップまたはレベルで対戦を実行し、リストを繰り返し処理して次のマップまたはレベルを見つけ、対戦の合間に (または対戦中でも) 他のプレイヤーが参加または退出して、新たな対戦を開始するゲームです。

カスタム属性

セッションには、属性 と呼ばれるユーザー定義データを含めることができます。各属性には、文字列キーとして機能する名前、値の型を識別する列挙型変数である値、および可視性設定があります。現在サポートされている変数の型は次のとおりです。

EOS_ESessionAttributeType

値の型

EOS_AT_BOOLEAN

EOS_Bool

EOS_AT_INT64

int64_t

EOS_AT_DOUBLE

double

EOS_AT_STRING

const char* (Null で終わる UTF8 文字列)

次の可視性タイプを使用できます。

EOS_ESessionAttributeAdvertisementType

可視性

EOS_SAAT_DontAdvertise

他のユーザーには表示されない

EOS_SAAT_Advertise

他のユーザーに表示される

属性にアクセスする

有効な EOS_HSessionDetails ハンドルと次の情報を含む EOS_SessionDetails_CopySessionAttributeByIndexOptions を使用して EOS_SessionDetails_GetSessionAttributeCount を呼び出すことにより、セッションが持つ属性の数を確認できます。

プロパティ

ApiVersion

EOS_SESSIONDETAILS_GETSESSIONATTRIBUTECOUNT_API_LATEST

属性のコピーを取得するには、有効な EOS_HSessionDetails ハンドルと次のように初期化された EOS_SessionDetails_CopySessionAttributeByIndexOptions を使用して、EOS_SessionDetails_CopySessionAttributeByIndex を呼び出します。

プロパティ

ApiVersion

EOS_SESSIONDETAILS_COPYSESSIONATTRIBUTEBYINDEX_API_LATEST

AttrIndex

コピーする属性のインデックス

成功時は、これは EOS_Success を返し、出力パラメータには、要求した属性インデックスに対応する EOS_SessionDetails_Attribute 構造体のコピーが含まれます。この構造体には、EOS_Sessions_AttributeData データ構造体の属性の値と型、および EOS_ESessionAttributeAdvertisementType 列挙値の可視性が格納されます。このデータが不要になったら、EOS_SessionDetails_Attribute_Release を使用してこれを解放します。

属性を追加する

EOS_Sessions_AttributeData データ構造体に次の情報を設定することで、追加または変更する属性を設定できます。

プロパティ

ApiVersion

EOS_SESSIONS_SESSIONATTRIBUTEDATA_API_LATEST

Key

属性の名前

Value

属性の値、または文字列の場合は文字列へのポインタ

ValueType

Value を説明する EOS_ESessionAttributeType

このデータの準備ができたら、EOS_SessionModification_AddAttribute を呼び出して属性を追加します。EOS_HSessionModification ハンドルと次のように初期化された EOS_SessionModification_AddAttributeOptions を提供する必要があります。

プロパティ

ApiVersion

EOS_SESSIONMODIFICATION_ADDATTRIBUTE_API_LATEST

SessionAttribute

実行する必要のある変更を含む EOS_Sessions_AttributeData への定数ポインタ

AdvertisementType

この属性を公開するかどうかを示す EOS_ESessionAttributeAdvertisementType

1 つのセッションには最大 EOS_SESSIONMODIFICATION_MAX_SESSION_ATTRIBUTES (現在 64) を格納でき、各属性の名前の長さは EOS_SESSIONMODIFICATION_MAX_SESSION_ATTRIBUTE_LENGTH (現在は 32) 文字にすることができます。

この関数では、追加または更新したい属性の設定のみを行います。この関数が、実際に属性を追加または更新したり、セッションを操作したりすることは一切ありません。この セクション の冒頭で説明したように、引き続き EOS_Sessions_UpdateSession を呼び出す必要があります。

属性を削除する

属性を削除するには、セッションの EOS_HSessionModification ハンドルと、次の情報を格納する EOS_SessionModification_RemoveAttributeOptions 構造体を使用して EOS_SessionModification_RemoveAttribute を呼び出します。

プロパティ

ApiVersion

EOS_SESSIONMODIFICATION_REMOVEATTRIBUTE_API_LATEST

Key

削除する属性の名前 (キー)

この関数は、特定の属性を削除する必要があるということのみを設定します。この関数が実際に属性を削除したり、セッションを操作したりすることは一切ありません。この セクション の冒頭で説明したように、引き続き EOS_Sessions_UpdateSession を呼び出す必要があります。

セッションにプレイヤーを招待する

アクティブ セッションに参加するよう他のプレイヤーを招待するために、セッションに 登録済みの メンバーが、次のデータを格納する EOS_Sessions_SendInviteOptions 構造体を指定して EOS_Sessions_SendInvite を呼び出すことができます。

プロパティ

ApiVersion

EOS_SESSIONS_SENDINVITE_API_LATEST

SessionName

プレイヤーが招待されるセッションの名前

LocalUserId

招待を送信するローカル ユーザー

TargetUserId

招待されるリモート ユーザー

サーバーが招待要求を処理すると、EOS_Sessions_OnSendInviteCallback 型のコールバックが、結果コードを含む EOS_Sessions_SendInviteCallbackInfo 構造体を指定して実行されます。この結果は、招待の送信プロセスでエラーが発生しなかった場合に成功を示します。成功は、リモート ユーザーが招待を承諾したり、招待を確認したことを意味するものではありません。

Epic Games Launcher の招待機能の場合は、デプロイメントを アーティファクト にもマッピングしてください。

リモート ユーザーは、招待が届くと通知を受け取り、ペイロードにより、招待されたユーザー ID と招待自体の ID が提供されます。受け取ったら、EOS_Sessions_CopySessionHandleByInviteId を使用して招待から EOS_HSessionDetails ハンドルを取得します。このハンドルを使用すると、関連付けられているセッションの セッションの詳細 データにアクセスしたり、その招待を承諾または拒否したりできます。ハンドルを使用した処理が完了したら、EOS_SessionDetails_Release を呼び出してハンドルを解放します。

この通知を受け取るには、EOS_Sessions_AddNotifySessionInviteReceived を使用してコールバックを登録する必要があります。通常、これは起動時に 1 回のみ実行する必要があります。それ以降は、招待を受け取るたびにコールバックが実行されます。通知が不要になったら、EOS_Sessions_RemoveNotifySessionInviteReceived を呼び出してコールバックを削除します。

招待を承認する

Sessions インターフェースには、招待を受け入れるための専用の関数はありません。招待から取得した EOS_HSessionDetails ハンドルを使用すると、標準的な方法で セッション に参加できます。すべての保留中の招待のリストを要求するには、次のように初期化された EOS_Sessions_QueryInvitesOptions データ構造体を指定して EOS_Sessions_QueryInvites を呼び出します。

プロパティ

ApiVersion

EOS_SESSIONS_QUERYINVITES_API_LATEST

LocalUserId

招待が要求されているローカル ユーザー

この操作は非同期です。完了すると、EOS_Sessions_QueryInvitesCallbackInfo データ構造体を指定して (EOS_Sessions_OnQueryInvitesCallback 型の) コールバック関数を呼び出します。成功すると、EOS はユーザーの保留中のすべての招待をローカルにキャッシュします。EOS_Sessions_GetInviteCount を使用すると、キャッシュ内の招待の数を特定できます。次の情報を格納する EOS_Sessions_GetInviteCountOptions 構造体を渡します。

プロパティ

ApiVersion

EOS_SESSIONS_GETINVITECOUNT_API_LATEST

LocalUserId

キャッシュされた招待を持つローカル ユーザー

この関数はローカルで実行され、現在キャッシュ内にある招待の数を表す uint32_t を返します。キャッシュされた招待の ID を取得するには、次の情報を格納する EOS_Sessions_GetInviteIdByIndexOptions を使用して EOS_Sessions_GetInviteIdByIndex を呼び出します。

プロパティ

ApiVersion

EOS_SESSIONS_GETINVITEIDBYINDEX_API_LATEST

LocalUserId

キャッシュされた招待を持つローカル ユーザー

Index

取得する ID の招待のキャッシュ インデックス

EOS_Sessions_GetInviteIdByIndexEOS_Success を返す場合、それに対して渡した出力パラメータには、招待の ID が null で終わる文字列とその文字列の長さが含まれています。

招待の ID 文字列の最大長は EOS_SESSIONS_INVITEID_MAX_LENGTH (現在は 64) です。

上記 のように、EOS_Sessions_CopySessionHandleByInviteId 関数は、EOS_HSession ハンドルを提供します。このハンドルでは、関連付けられているセッションの セッションの詳細 データへのアクセスを提供します。その後、セッションに 参加 して招待を受け入れるか、招待を無視するか、または招待を 拒否 するかを選択できます。EOS_HSession ハンドルを使用した処理が完了したら、EOS_SessionDetails_Release を呼び出してこのハンドルを解放します。

招待を拒否する

招待を拒否するには、次のように初期化された EOS_Sessions_RejectInviteOptions を使用して EOS_Sessions_RejectInvite を呼び出します。

プロパティ

ApiVersion

EOS_SESSIONS_REJECTINVITE

LocalUserId

招待を拒否するローカル ユーザー

InviteId

招待の ID

完了すると、成功/失敗を示す EOS_Sessions_RejectInviteCallbackInfo データ構造体を指定した EOS_Sessions_OnRejectInviteCallback コールバック関数への呼び出しを受け取ります。招待の拒否が成功すると、システムから招待が完全に削除されます。

リモート セッションを検出する

リモート セッションを検出するには、検索を構成し、その検索を実行して、結果を調べる必要があります。

検索を構成する

検索を開始するには、まず EOS_Sessions_CreateSessionSearch を呼び出して、検索ハンドルを作成します。次のように初期化された EOS_Sessions_CreateSessionSearchOptions 構造体を渡します。

プロパティ

ApiVersion

EOS_SESSIONS_CREATESESSIONSEARCH_API_LATEST

MaxSearchResults

返される検索結果の最大数

この関数はローカルで実行され、成功時には (EOS_HSessionSearch 型の) デフォルトの検索ハンドルを入力します。次のステップでは、必要な条件で特定の検索を実行するようにハンドルを構成します。EOS では、セッションを検索する次の 3 つの方法を提供しています。

  • セッション ID: 既知の ID を持つ単一のセッションを検索する

  • ユーザー ID: 既知のユーザーが関与するすべてのセッションを検索する — 現在は、ローカル ユーザーに限定されています。

  • 属性データ: いくつかのユーザー定義のフィルタ条件に一致するすべてのセッションを検索する

セッション ID を構成する

特定のセッションが必要で、そのサーバー側の ID が判明している場合は、検索ハンドルと次のように初期化された EOS_SessionSearch_SetSessionIdOptions を使用して EOS_SessionSearch_SetSessionId を呼び出します。

プロパティ

ApiVersion

EOS_SESSIONSEARCH_SETSESSIONID_API_LATEST

SessionId

検索するセッションの ID

これは、セッション ID 検索の構成に必要な唯一のステップです。他の検索方法とは異なり、この方法で複数の結果が返されることはありません。

EOS_OSPF_PublicAdvertised または EOS_OSPF_JoinViaPresence とマークされているセッションのみがこの方法で検索することができます。

この方法で設定するセッションは公開されるので、EOS エコシステム外のアプリケーションはそれらを見つけることができます。これらのアプリケーションはセッション データを使ってサーバーまたは P2P ホストの IP アドレスを取得し、障害を引き起こす可能性があります。

ユーザー ID を構成する

既知のユーザーが関与するすべてのセッションを検索するには、検索ハンドルと次の情報を含む EOS_SessionSearch_SetTargetUserIdOptions を使用して EOS_SessionSearch_SetTargetUserId を呼び出します。

プロパティ

ApiVersion

EOS_SESSIONSEARCH_SETTARGETUSERID_API_LATEST

TargetUserId

セッション内で検索するユーザー ID

これは、ユーザー ID 検索の構成に必要な設定する唯一のステップです。ローカルのログイン ユーザーである必要があります。

アプリケーションはローカルに認証されたユーザーまたはパブリック セッションに登録されたリモート ユーザーのみを検索できます。

パブリックに表示されるセッション (EOS_OSPF_PublicAdvertised または EOS_OSPF_JoinViaPresence で設定されたセッション) の登録ユーザーは、EOS エコシステム外のアプリケーションも含めて、ユーザー自体がパブリックに表示されます。これらのアプリケーションはセッション データを使ってサーバーまたは P2P ホストの IP アドレスを検出し、障害を引き起こす可能性があります。

属性データを構成する

セッションを検索する最も確実な方法は、フィルタとして機能する一連の検索パラメータに基づいて検索することです。特定のゲーム タイプまたはマップをユーザーが選択できるようにするためなど、一部のパラメータはユーザーに公開される場合がありますが、適切な対戦相手との対戦を見つけるためにプレイヤーの推定スキル レベルを使用する場合など、その他のパラメータは非表示である可能性があります。この検索方法では複数のパラメータを使用することができ、これらすべてのパラメータに一致するセッションのみを検索します。検索パラメータを設定するには、検索ハンドルと次の情報を格納する EOS_SessionSearch_SetParameterOptions を使用して EOS_SessionSearch_SetParameter を呼び出します。

プロパティ

ApiVersion

EOS_SESSIONSEARCH_SETPARAMETER_API_LATEST

Parameter

セッションに関連付けられている 属性 と比較するキー/値

ComparisonOp

実行する比較のタイプ

この関数を複数回呼び出すことで、複数のフィルタを設定できます。セッションを検索結果に表示するためには、これらすべてのフィルターを満たす必要があります。次の表に、使用できる比較のタイプ、それらが機能する値の型、および検索結果に表示されるために満たす必要がある条件を示します。

ComparisonOp

受け入れ可能な値の型

成功条件

EOS_CO_EQUAL

すべて

属性は検索値に等しい

EOS_CO_NOTEQUAL

すべて

属性は検索値に等しくない

EOS_CO_GREATERTHAN

数値型

属性は検索値より大きい

EOS_CO_GREATERTHANOREQUAL

数値型

属性は検索値以上

EOS_CO_LESSTHAN

数値型

属性は検索値未満

EOS_CO_LESSTHANOREQUAL

数値型

属性は検索値以下

EOS_CO_DISTANCE

数値型

フィルタではなく、属性は検索値、または Abs(AttributeValue - SearchValue)

どれだけ近いかに基づいてソートされる

EOS_CO_ANYOF

文字列

属性はセミコロン区切りのリストのいずれかのメンバーに一致する (例: "This;OrThis;MaybeThis")

EOS_CO_NOTANYOF

文字列

属性はセミコロン区切りのリストのいずれのメンバーにも一致しない (例: "NotThis;OrThisEither")

検索を実行する

検索を実行するには、検索ハンドルと次のように初期化された EOS_SessionSearch_FindOptions構造体を指定して EOS_SessionSearch_Find を呼び出します。

この操作は非同期に行われます。完了すると、EOS_SessionSearch_OnFindCallback 型のコールバック関数は、検索の成功/失敗を通知する EOS_SessionSearch_FindCallbackInfo 構造体を受け取ります。正常に完了すると、EOS キャッシュから検索結果のコピーを取得できます。

EOS では、複数の EOS_SessionSearch_Find 操作の並列実行をサポートしています。

検索結果を調べる

特定の EOS_HSessionSearch ハンドルの EOS_SessionSearch_GetSearchResultCount および EOS_SessionSearch_CopySearchResultByIndex は、個々の EOS_HSessionDetails ハンドルを使用してセッションの詳細を 1 件ずつ返します。

検索が正常に完了したら、EOS_SessionSearch_GetSearchResultCount を検索ハンドルとともに使用して、検索で返された結果の数を取得します。次に、EOS_SessionSearch_CopySearchResultByIndex を呼び出して、そのインデックスの アクティブ セッション に関連付けられている EOS_HSessionDetails ハンドルのコピーを取得できます。このハンドルでは、セッションの詳細 データへのアクセスを提供します。これを使用すると、ローカル ユーザーにセッションに関する情報を表示したり、独自のゲーム ロジックを使用してセッションに 参加 するかどうかを決定したりできます。EOS_HSessionDetails ハンドルは、不要になったら EOS_SessionDetails_Release を使用して解放する必要があります。

セッションに参加する

セッションに対する有効な EOS_HSessionDetails ハンドルがある場合、EOS_Sessions_JoinSession を呼び出して、次の情報を使用した EOS_Sessions_JoinSessionOptions 構造体を提供することにより、既存のセッションに参加できます。

プロパティ

ApiVersion

EOS_SESSIONS_JOINSESSION_API_LATEST

SessionName

ローカル システムがセッションを参照するために使用する一意の名前

SessionHandle

参加するセッションの EOS_HSessionDetails ハンドル

LocalUserId

セッションに参加するローカル ユーザー

bPresenceEnabled

このセッションがユーザーのプレゼンス情報に関連付けられたセッションであるかどうか (詳細については「Presence (プレゼンス) インターフェース」を参照)。

操作が完了すると、EOS_Sessions_OnJoinSessionCallback 型のコールバック関数は、成功/失敗を示す EOS_Sessions_JoinSessionCallbackInfo を受け取ります。操作が成功した場合、EOS は参加しているクライアントのシステムにアクティブ セッションを作成します。この新しいセッションはローカルで所有されているため、参加しているユーザーは、不要になったら、セッションを 破棄 する必要があります。

プレイヤーを登録する

プレイヤーがセッションに参加すると、セッション所有者はプレイヤーをセッションに登録する必要があります。これにより、バックエンド サービスがプレイヤー数を継続的に認識できるため、セッションが満杯になるとセッションのアドバタイズを停止できます。EOS では、EOS_Sessions_RegisterPlayers 関数を使用して一度に複数のプレイヤーを登録できます。次のデータを含む EOS_Sessions_RegisterPlayersOptions 構造体を使用して、所有しているクライアントからこの関数を呼び出します。

プロパティ

ApiVersion

EOS_SESSIONS_REGISTERPLAYERS_API_LATEST

SessionName

セッションのローカル名

PlayersToRegister

参加プレイヤーの ID の配列

PlayersToRegisterCount

PlayersToRegister の要素数

完了すると、EOS_Sessions_OnRegisterPlayersCallback 型のコールバックは、成功/失敗を示す EOS_Sessions_RegisterPlayersCallbackInfo パラメータを指定して実行されます。呼び出しが成功すると、新規登録されたプレイヤーは、他のプレイヤーをセッションに招待する機能など、セッション管理機能の一部にアクセスできるようになります。EOS ではプレイヤーがセッションに参加したことに関する通知を提供しません。そのため、自分が参加したときに所有者に通知するか、プレイヤーがセッションに参加できたら、そのことを検出できる方法を所有者に提供する必要があります。

ユーザーがパブリックに表示されるセッション (EOS_OSPF_PublicAdvertised または EOS_OSPF_JoinViaPresence で設定されたセッション) で登録すると、他のユーザーは EOS_SessionSearch_SetTargetUserId でそのセッションを見つけることができます。

この情報は EOS エコシステム外のアプリケーションを含み、パブリックに表示されます。これらのアプリケーションはセッション データを使ってサーバーまたは P2P ホストの IP アドレスを検出し、障害を引き起こす可能性があります。

セッションから退出する

セッション インターフェースには、セッションから退出するための専用の関数はありません。セッションから退出するには、ローカル名を使って、標準的な方法でローカル セッションを 破棄 します。

プレイヤーの登録を解除する

プレイヤーがセッションから退出すると、セッション所有者はプレイヤーの登録を解除する必要があります。登録を解除することで、サーバーによりプレイヤー スロットが解放されるため、それ以降プレイヤーが参加できるようになります。EOS では、EOS_Sessions_UnregisterPlayers 関数を使用して一度に複数のプレイヤーの登録を解除することができます。次のデータを含む EOS_Sessions_UnregisterPlayersOptions 構造体を使用して、所有しているクライアントからこの関数を呼び出します。

プロパティ

ApiVersion

EOS_SESSIONS_UNREGISTERPLAYERS_API_LATEST

SessionName

セッションのローカル名

PlayersToUnregister

退場するプレイヤーの ID の配列

PlayersToUnregisterCount

PlayersToUnregister の要素数

完了すると、EOS_Sessions_OnUnregisterPlayersCallback 型のコールバックは、成功/失敗を示す EOS_Sessions_UnregisterPlayersCallbackInfo パラメータを指定して実行されます。呼び出しが成功すると、バックエンド サービスにより、当該プレイヤーが最初に登録されたときに受け取ったセッション管理アクセスが取り消されます。たとえば、セッションに登録されていないプレイヤーは、他の人をセッションに招待することはできません。EOS ではプレイヤーがセッションから退出することに関する通知を提供しません。そのため、自分がセッションから退出するときに所有者に通知するか、プレイヤーがゲームから退場したり、接続を解除したことを検出する方法を所有者に提供する必要があります。

プレイを開始および終了する

プレイヤーは、ローカルのアクティブ セッションで対戦が開始または終了したことを宣言できます。そのセッションがローカル プレイヤーが所有するバックエンド サービスのセッションにマッピングされている場合、バックエンド バージョンでもプレイを開始または終了します。プレイ中に、セッションで [Join In Progress (進行中に参加)] が無効になっている場合、バックエンド サービスはセッションへの参加の試みを自動的に拒否します (詳細については「セッションを変更する」セクションを参照)。通常、セッションの開始は対戦の開始を意味しますが、この機能の具体的な使用法はゲームのデベロッパーに一任されます。

プレイを開始するには、次のように初期化された EOS_Sessions_StartSessionOptions を使用して EOS_Sessions_StartSession を呼び出します。

プロパティ

ApiVersion

EOS_SESSIONS_STARTSESSION_API_LATEST

SessionName

セッションのローカル名

操作が完了したら、成功/失敗を示す EOS_Sessions_StartSessionCallbackInfo データ構造体を指定して EOS_Sessions_OnStartSessionCallback 型のコールバックが実行されます。操作が成功した場合、次の情報を含む EOS_Sessions_EndSessionOptions を使用して EOS_Sessions_EndSession を呼び出すことでプレイが終了するまで、セッションは「進行中」と見なされます。

プロパティ

ApiVersion

EOS_SESSIONS_ENDSESSION_API_LATEST

SessionName

セッションのローカル名

完了すると、EOS_Sessions_OnEndSessionCallback 関数は成功/失敗を示す EOS_Sessions_EndSessionCallbackInfo データ構造体を指定した呼び出しを受け取ります。成功すると、セッションは「進行中」とは見なされなくなり、再びプレイヤーが参加できるようになります。セッションを終了しても、プレイヤーが削除されたり、セッションが破壊されたりすることはありません。つまり、セッションは実質的に開始前の状態に戻り、プレイの再開を含め、使用可能な状態になります。セッションを破棄する場合は、最初に EOS_Sessions_EndSession を呼び出す必要はありません。

セッションを破棄する

セッションが不要になったら EOS_Sessions_DestroySession を使用してセッションを破棄する必要があります。次の情報を含む EOS_Sessions_DestroySessionOptions データ構造体を指定してこの関数を呼び出します。

プロパティ

ApiVersion

EOS_SESSIONS_DESTROYSESSION_API_LATEST

SessionName

破棄するセッションの名前

破棄操作が完了すると、EOS_Sessions_DestroySessionCallbackInfo データ構造体を指定した EOS_Sessions_OnDestroySessionCallback 型のコールバックを受け取ります。この操作が成功すると、セッションは存在しなくなり、その名前を再利用できるようになります。ただし、このシステムの非同期の性質により、EOS_Sessions_DestroySession を呼び出した後であるものの、バックエンド サービスがセッションを破棄する前には、プレイヤーが要求を行うことができます。この場合、破棄操作の開始後に、セッションへの参加要求を受け取ることがあります。このようなプレイヤーを拒否したり、ネットワークをシャットダウンしたりすることで、非アクティブ セッションに参加できないようにする必要があります。

リモート クライアントでセッション管理を反映する

Sessions インターフェースを使用して、セッション所有者 (セッションを作成したユーザー) は、セッションがバックエンド サービスに存在するときは、セッションの状態を管理できます。セッションのライフサイクルは、作成で始まり、破棄で終わります。これら 2 つのイベントの間に、Sessions インターフェースではセッションの変更、プライバシー設定の変更、招待の送信、プレイヤーの参加および退出、そして対戦の開始、プレイ、終了に伴うプレイヤーの登録と登録解除を行うことができます。セッションのライフサイクルは厳密ではありません。たとえば、セッションはいつでもデータを変更でき、複数の対戦を開始および終了できます。

バックエンド サービスのセッション データを変更できるのは、通常、セッション所有者のみです。セッションに 参加 するリモート クライアントには、セッションの独自のローカル ビューがありますが、このビューでは、バックエンド バージョンに関するデータ更新を自動的に受信しません。必須ではありませんが、次の関数呼び出しを反映することで、リモート クライアントがローカル ビューとバックエンド セッションの同期を維持するのに役立ちます。

  • EOS_Sessions_StartSession

  • EOS_Sessions_EndSession

  • EOS_Sessions_RegisterPlayers

  • EOS_Sessions_UnregisterPlayers

これらの関数は、バックエンド サービスのバージョンに影響を与えることなく、リモート (所有者以外) クライアントのセッションのローカル状態を変更します。

使用上の制限事項

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

スロットリング、使用クォータ、ベストプラクティスの一般情報については、「

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

セッションには次の一般的な制限事項が適用されます。

機能

制限事項

同時プレイヤー数

1000 / セッション

セッション属性

100 / セッション

属性名の長さ

1000 文字

Sessions インターフェースとのユーザー インタラクションは以下の制限事項を順守しなければなりません。

機能

制限事項

デプロイメントごとの制限

セッションの作成

30 リクエスト / 分

30 リクエスト / 1 CCU / 分

セッションの削除

30 リクエスト / 分

30 リクエスト / 1 CCU / 分

セッションの更新

30 リクエスト / 分

30 リクエスト / 1 CCU / 分

プレイヤーの追加または削除

100 リクエスト / 分

30 リクエスト / 1 CCU / 分

セッションの開始または停止

30 リクエスト / 分

30 リクエスト / 1 CCU / 分

ユーザーの招待

100 リクエスト / 分

30 リクエスト / 1 CCU / 分

セッションのフィルタ

30 リクエスト / 分

30 リクエスト / 1 CCU / 分

マッチメイキング セキュリティに関する留意事項

マッチメイキング 機能は、プレイヤー ID やサーバー IP アドレスなどの情報を取得することを要求し、そのデータを他の潜在的なプレイヤーに配信します。通常、セッション データは以下の内容で構成されます。

  1. EOS_SessionModification_SetHostAddress を使用して設定した、または EOS サーバーによって自動検知された ホスト IP アドレス。ゲームへの参加を希望する場合、このアドレスが必須となります。

  2. セッションに登録しているすべてのプレイヤーの EOS Product User ID

  3. EOS_SessionModification_AddAttribute を使ってセッションに追加されたカスタム属性。デベロッパーによって設定されたものはすべてこれになります。

マッチメイキングはゲームデータを受け取り検索可能なインデックスを作成するので、セッションを作成する時に公開対象のデータをどれにするのか常に気にする必要があります。専用サーバーを使用するゲームの場合、サーバーの IP アドレスを公開します。ピアツーピア (P2P) セッションの場合、エンドユーザーの IP アドレスを公開することができます。

セッションを作成するときに、EOS_SessionModification_SetPermissionLevel を使ってセッションに 権限レベル を指定することができます。セッションには 3 つのレベルのセキュリティがあります。

セキュリティ レベル

説明

EOS_OSPF_PublicAdvertised

セッションが開始されていない、あるいはセッションによる参加許可が進行中である限り、どのクライアントも、セッション ID を知る必要なしに検索結果のセッションを取得し、セッション情報を読み込むことができます。固有のセッション ID へのアクセスが可能なクライアント / プレイヤーは、セッションが参加可能でない場合でも、セッション情報を見ることができます。

EOS_OSPF_JoinViaPresence

一意のセッション ID にアクセスできるクライアント / プレイヤーはすべてセッション情報を見ることができます (通常この情報はプレゼンス データ経由で共有されますが、他の方法でも共有可能です)。

EOS_OSPF_InviteOnly

既存のセッション メンバーによりセッションへ明示的に招待されているプレイヤーのみがセッション情報を見ることができます。

ベスト プラクティス

  • セッションの公開対象は必要とされる最低量になるようにしてください。

  • セッションを見ているすべての人に公開すべきではない情報をセッションに追加しないでください。

  • JoinViaPresence を使用している場合は、プレイヤー / UI でセッション ID が見えないようにしてください。公開されると、セッション データへのアクセスが可能になります。

  • ゲームが JoinInProgress をサポートしていない場合は、ゲームが進行中の間は今後の検索からセッションを取り除くために、ゲーム サーバーが EOS_Sessions_StartSession でセッションを開始することを確認してください。