- デバイス - 物理デバイス上で実行されているゲームの明確なインスタンス。API が使用されているとき、ローカル デバイスが常に存在します。
- ユーザー - ログオンしている個々のプレイヤー。より正確には、ゲームが認証と識別の目的で PlayFab Party に提供する PlayFab の
title_player_accountエンティティ。1 つ以上のユーザーが指定されたデバイスに関連付けられます。 - ネットワーク - チャットまたはデータ通信を交換するためにゲームが作成する、1 つ以上のデバイスとそれらの認可されたユーザーのセキュアなコレクション。ネットワークは通常、ゲームのマルチプレイヤー セッションまたはチャット パーティのコンセプトと一致します。
- エンドポイント - ネットワーク内でデータを送受信するための抽象化。エンドポイントはデバイス、ユーザー、または任意のゲーム固有のコンセプトを表す場合があります。
- チャット コントロール - 1 つ以上のネットワークで音声とテキスト チャットの構成、発信元、およびターゲットを設定するためのユーザーの表現。
オブジェクトの関係
簡略化された概念階層として、ネットワーク には デバイス が含まれ、それらには ユーザー、任意の エンドポイント、および任意の チャット コントロール が含まれます。例: 上記の関係図は理解しやすいものですが、実際には PlayFab Party の機能の不完全な描写であり、それだけで解釈すると誤解を招く可能性があります。実際には、Party API はデバイスが 複数の ネットワークに同時に接続することをサポートしています。たとえば、同じフレンド グループが見知らぬ人との別の大きなゲーム セッションに参加および退出しながらも、そのフレンド グループとの通信を長期間維持したい場合があります。このより広範なシナリオを考慮することで、これらのオブジェクト間の関係をよりよく理解できます。 デバイスがネットワークに 属している と概念化するのは直感的に感じられるかもしれませんが、これは正しくありません。デバイスはネットワークに 参加している と考えるほうがより正確です。したがって、Party ライブラリは、特定のインスタンスに遭遇したとき、それが共有するローカル デバイスとのネットワーク数に関係なく、リモートまたはローカルのいずれかに関係なく、単一のデバイス API オブジェクトを常に作成します。 例として、以下の図は 2 つのネットワークと 3 つのデバイス、ユーザー、チャット コントロール、エンドポイントを示しています。デバイス A とその 2 つのチャット コントロール (関連ユーザー付き) は ネットワーク 1 に参加しており、デバイス B と C は単一のチャット コントロール (関連ユーザー付き) で ネットワーク 1 と ネットワーク 2 の両方に接続しています。すべてのデバイスは、接続している各ネットワーク内で 1 つまたは 2 つのエンドポイントを作成しています。 図では、すべてのデバイスが 3 つのデバイスすべてとそれらのチャット コントロールの単一のインスタンスを見ることができます。少なくとも 1 つのネットワークを互いに共有しているためです。デバイス A は ネットワーク 1 の エンドポイント 1-4 のみを知っていますが、デバイス B と C は ネットワーク 2 で作成した エンドポイント 5-7 も見ることができます。 デバイス C が代わりに ネットワーク 2 のみに参加し、両方のネットワークに参加していない場合、以下のようになります。- デバイス C は明らかに ネットワーク 1 で エンドポイント 4 を作成できず、エンドポイント 1-3 も見ることができません。
- デバイス C は ネットワーク 1 内のみの デバイス A またはその 2 つのチャット コントロールについて知りません。
- 同様に、デバイス A は ネットワーク 2 内のみの デバイス C またはそのチャット コントロールを見ません。
PlayFab Party を正常に使用するために、ゲームが複数のネットワークに同時に接続する必要はありません。複数のネットワークを使用するかどうか、および使用方法について詳しくは、後続の高度なトピック を参照してください。
共通のオブジェクト属性
すべてのオブジェクトには明確に定義された有効期間があります。ローカル ゲーム インスタンスは、各オブジェクトを直接、またはゲームの選択したタイム ウィンドウ中にのみシグナルされる標準化された通知メカニズムを使用して作成および破棄します。通知の操作については、後のトピックで詳しく説明します。 すべての PlayFab Party API オブジェクトは、カスタム コンテキスト の概念もサポートしています。これは、オブジェクトに任意のローカルのみの「ショートカット」ポインターまたは値を保存する単なる方法です。カスタム コンテキストにより、PlayFab Party オブジェクトから、メモリ内の対応するプライベート ゲーム オブジェクト (存在する場合) に戻ることが、非効率的なルックアップを実行することなく簡単にできます。これらの値はリモート送信されません。ポインター値はローカル ゲーム インスタンスにのみ意味があるためです。 最後に、ネットワーク を除く上記のすべてのオブジェクトには、オブジェクトを所有するローカル デバイス のみが利用できるメソッドとプロパティを含む専用の「Local」サブオブジェクトがあります。 たとえば、任意のローカルまたはリモート エンドポイント を表すために使用される基本のPartyEndpoint オブジェクトと、そのエンドポイントが実際にローカル デバイスによって作成された場合にのみ PartyEndpoint::GetLocal() を介して取得できる、より具体的な PartyLocalEndpoint オブジェクトがあります。ここでは、ゲーム データを送信するための PartyLocalEndpoint::SendMessage() メソッドが公開されています。1 つのデバイスが別のリモート デバイスのソース エンドポイントから何らかの方法でデータを送信できるようにするのは意味がないためです。
C++ PlayFab Party インターフェース (推奨) を使用する場合、オブジェクトは C++ クラス インスタンスとして公開されます。フラット C インターフェースを使用する場合、オブジェクトはハンドル値で表されます。
すべての主要なオブジェクトの役割の詳細
- Manager (
PartyManager) - Network (
PartyNetwork) - Device (
PartyDeviceとPartyLocalDevice) - User (ユーザー エンティティ ID と
PartyLocalUser) - Endpoint (
PartyEndpointとPartyLocalEndpoint) - Chat Control (
PartyChatControlとPartyLocalChatControl) - State Change (
PartyStateChange)
Manager
前述のオブジェクトに加えて、PlayFab Party API はトップレベルのPartyManager シングルトン オブジェクトも公開します。
このユーティリティ/組織オブジェクトは、他のオブジェクトを扱い始めるための出発点として大部分使用されます。たとえば、Manager は新しい ネットワーク やローカル ユーザー が最初に作成される場所です。すべての非同期操作の完了と通知もここに集中されます。最も基本的には、Manager は使用前に PlayFab Party ライブラリ自体を初期化し、不要になったときにクリーンアップする場所です。
Network
PartyNetwork オブジェクトは、参加している デバイス、それらの認可された ユーザー、および付随する エンドポイント または チャット コントロール のセキュアなコレクションを表します。ネットワーク は最初は空で作成されますが、デバイスがそれらに接続し、少なくとも 1 つのローカル ユーザーを ネットワーク に認証します。認証されたユーザーがいない ネットワーク は、タイムアウト後に自動的に破棄されます。
ネットワーク に接続するには、ネットワーク記述子 を使用して ネットワーク を参照します。ネットワーク記述子 は、PlayFab Party が内部的に ネットワーク を識別および特定するのに必要な情報を含む、ほぼ不透明なバイナリ構造です。API は、構造体を Web サービスに適した文字列にシリアル化したり戻したりするメソッドを提供します。これにより、一般的なソーシャル プラットフォームの招待メカニズム、PlayFab マッチメイキング、または PlayFab Party 自体の範囲外のその他の外部ランデブー メカニズムを使用して、他のデバイスと交換できます。
ネットワーク の ネットワーク記述子 は、まれな状況で変更される可能性があります。ゲームは、そのような変更の通知に備え、追加のデバイスの接続の問題を回避するために、既存の ネットワーク の新しい ネットワーク記述子 を更新または再アドバタイズする必要があります。
PartyNetwork オブジェクトで実行できるアクションの種類には、ローカル ユーザーを認証すること、チャット コントロールの接続と列挙、エンドポイントの作成と列挙、または ネットワーク 全体のパフォーマンス情報の取得が含まれます。
Device
PartyDevice オブジェクトは、物理デバイス上で実行されているゲームとその PlayFab Party ライブラリ コードの明確なインスタンスを表します。ほとんどの操作は PartyDevice オブジェクト自体で実行されるわけではありません。むしろ、特に複数のローカル ユーザー を同時にサポートするプラットフォームとゲームの場合、どの エンドポイント や チャット コントロール がそのゲーム インスタンスに属するかを定義するための組織メカニズムです。PlayFab Party はこの関係の知識を利用して、たとえばデバイス上の複数のターゲットがメッセージを受信する必要がある場合でも、メッセージのコピーを 1 つだけ送信することで、ゲーム データとチャットの送信を最適化します。
リモート PartyDevice オブジェクトは、ネットワーク への接続とそのネットワークへのユーザー認証の「副産物」です。それらは、デバイス に関連付けられた有効な認証済みリモート ユーザーが、ローカル デバイス も接続しているネットワークに参加している場合にのみ作成されます。同様に、それが真実でなくなったときにも破棄されます。
一方、PartyLocalDevice 特殊サブオブジェクトは、PlayFab Party が初期化されている限り、ローカル ゲーム インスタンスが参照できるように常に利用可能です。これは明示的に作成または破棄されることはありません。
User
PlayFab Party の ユーザー は、ゲームが PlayFab プレイヤー ログイン を実行してtitle_player_account エンティティ ID とトークンを取得する、一意の人間プレイヤーです。
リモート ユーザーは、チャット コントロール および任意で エンドポイント に関連付けられたエンティティ ID 文字列のみで PlayFab Party API 内で識別されます。専用のオブジェクトを使用して表されるわけではありません。これは、PlayFab Party に、生の識別と他のオブジェクトに関連付けられたラベルとして以外に、任意のユーザーと有意義に相互作用する機能がないためです。
逆に、ローカル ユーザー には明示的な PartyLocalUser オブジェクトがあります。ゲームが PlayFab Party 内でその有効期間の管理を所有するためです。ゲームは通常、該当の ログイン メソッドを使用してその PlayFab プレイヤーを正常にログインさせたときに PartyLocalUser を作成し、そのユーザーがログオフしたときに適切に PartyLocalUser を破棄します。複数のローカル プレイヤーがログインすることをサポートするプラットフォームとゲームの場合、各プレイヤーに対して追加の PartyLocalUser オブジェクトを作成する必要があります。
PartyLocalUser オブジェクトは、すべての認証の基盤であるため重要です。新しい ネットワーク を作成するか、そのネットワークに認証するには、有効なローカル ユーザー が存在する必要があります。
ユーザーの認可については、招待とセキュリティ モデル を扱うトピックで詳しく説明されています。
PartyLocalUser オブジェクト自体で実行される操作はごくわずかですが、ほぼすべての操作で PartyLocalUser を提供または存在させる必要があります。
PartyLocalUser オブジェクトは PartyManager オブジェクトを使用して作成されます。それらは、その作成者によってのみ明示的に破棄できます。それらはリモート デバイス 上に直接オブジェクトの表現を持ちませんが、それらに関連付けられたチャット コントロールとエンドポイントは、所有デバイスが PartyLocalUser を削除するか、ネットワークから正常またはそれ以外の方法で切断された場合に破棄されます。
Endpoint
PartyEndpoint オブジェクトはオプションですが、それらを活用するゲームの PlayFab Party データ通信のコアです。典型的なネットワーキング ソケットと同様に、エンドポイント は ネットワーク 内でデータ メッセージの発信または対象を指定する抽象化されたアドレッシング メカニズムです。それらは デバイス、個々の ユーザー、またはメッセージの送受信のために一意に識別したい任意のゲーム定義のコンセプト (例: 戦車ユニット) を表現できます。
特殊化された PartyLocalEndpoint サブオブジェクトは、ローカル ゲーム インスタンスによってネットワーク内で作成された エンドポイント 用です。ここに、ほとんどの エンドポイント 機能があります。その PartyLocalEndpoint::SendMessage() は、同じネットワーク内の 1 つ以上の他の PartyEndpoint オブジェクトに PartyLocalEndpoint からゲーム データ ペイロードを送信します。インターネット パケット損失に最適に対応する方法を選択するためのさまざまなオプション (例: 配信および/または順序の保証)、低レイテンシと、同じまたは他のローカル エンドポイントからの複数のメッセージを結合してより低い帯域幅使用を実現することとの間のトレードオフを制御するオプション、および接続品質がゲームの送信率をサポートするのに十分でない場合の対応オプションを提供します。
データ メッセージ自体のソースまたは宛先であることに加えて、各 PartyEndpoint オブジェクトには PlayFab Party によって 16 ビットの エンドポイント固有識別子 も割り当てられ、ネットワーク内の別の PartyEndpoint オブジェクトに送信または受信されるメッセージ ペイロードで、特定の エンドポイント を参照できます。これにより、独自のピアツーピア ID 合意ネゴシエーションを構築することなく、たとえば、それが表す可能性のある完全でより大きなユーザー エンティティ ID 文字列またはその他の識別子を送信するオーバーヘッドを回避する便利な方法が提供されます。
PartyLocalEndpoint オブジェクトは、それを含む PartyNetwork オブジェクトを使用して作成されます。そうすると、対応する PartyEndpoint オブジェクトがリモート デバイスに作成されます。エンドポイント は、その作成者によって明示的に破棄することも、所有デバイスがネットワークから切断したとき、または関連する PartyLocalUser オブジェクト (指定されている場合) がネットワークから削除されたときに暗黙的に破棄されます。
Chat control
PartyChatControl オブジェクトは、PlayFab Party のオプションのチャット通信機能を使用するためのメカニズムです。それらは特定の ユーザー の関連付けられたオーディオ入力/出力デバイス、設定、および通信ポリシーを表します。
特殊化された PartyLocalChatControl サブオブジェクトは、ローカル ゲーム インスタンスによって作成された チャット コントロール に対しても利用可能です。ここでは、たとえば、ネットワーク全体対チーム限定のチャットを選択するため、またはプラットフォーム ポリシー制限を適用するために、リモート PartyChatControl オブジェクトへのまたはそこからのチャット通信を許可する権限を構成します。ローカル チャット コントロール は、チャット テキストの送信、テキストの音声合成、音声ストリームの文字起こしと翻訳の要求、ミュートなどに使用されます。
PartyLocalChatControl オブジェクトは、リモート デバイス 上の同じネットワーク内で PartyChatControl オブジェクトとして作成される前に、ネットワーク に接続する必要があります。そのデバイスと チャット コントロール が複数のネットワークに共通で接続されている場合でも、デバイスは常に単一の代表的な PartyChatControl オブジェクトのみを見ます。これは、オーディオおよびテキスト チャット メッセージの不要な重複や中断を回避するのに役立ちます。
PartyLocalChatControl オブジェクトは、それを含む PartyLocalDevice オブジェクトを使用して作成されます。チャット コントロール は、その作成者によって明示的に破棄することも、所有デバイスがネットワークから切断したとき、または関連する PartyLocalUser オブジェクトがネットワークから削除されたときに暗黙的に破棄されます。
State Change
PartyStateChange 構造体は、すべての非同期操作の完了、受信メッセージ、更新通知、およびその他の API 関連イベントをゲームに通知するために使用されます。
予測不可能なタイミングでのインターネット上の複雑なマルチマシン相互作用の処理を簡素化するため、PlayFab Party は、ゲームによる明示的な呼び出しの結果である場合を除いて、API から報告する状態を変更しないことを保証します。ただし、リモート開始操作またはローカル状態を変更する予期しない発生について学ぶ方法は依然として必要なため、PlayFab Party とゲームは特別なペアのメソッド PartyManager::StartProcessingStateChanges() と PartyManager::FinishProcessingStateChanges() を通じて協力します。これらは、そのような更新を処理するのに便利なゲームの作業ループの時点で呼び出されます。新しいイベントは、0 個以上の PartyStateChange 構造体の配列として PartyManager::StartProcessingStateChanges() から報告されます。ゲームが 状態変更 を処理し終わったら、その配列は PartyManager::FinishProcessingStateChanges() を使用して返されます。
PartyStateChange 構造体はそれ自体では完全なオブジェクトではありません。特定の完了または通知の種類、関連するオブジェクトへのポインター、およびエラー情報を含むより詳細な構造体にキャストされる基本ヘッダーです。
状態変更 の操作については、後のトピックで詳しく説明します。
次のステップ
- PlayFab Party の招待とセキュリティ モデルについて学ぶ
- PlayFab Party が検出フローとどのように相互作用するかを学ぶ
- PlayFab Party のチャット通信について詳しく知る
- PlayFab Party で非同期操作と通知を扱う方法を確認する