パーティー クイック スタート
このクイックスタートでは、コード スニペットと共に PlayFab Party のコア機能について説明します。 PlayFab Party は、ゼロからクロスプラットフォームとして設計されました。 これらのクイックスタートは同じ方法で構成されており、ほとんどの情報はすべてのプラットフォームに適用され、プラットフォーム固有の前提条件と手順については、リンクされたドキュメントで説明されています。
理解を深めるには、リンク先のリファレンス、概念に関するドキュメント、およびプラットフォームごとのサンプル アプリケーションを参照してください。
注意
このクイックスタート ガイドでは、C++ Party SDK の使用について説明します
- Unity ユーザーの場合は、「Unity のクイック スタート」を参照してください。
- Unreal Engine 用 PlayFab オンライン サブシステムを使用する Unreal Engine ユーザーについては、「Unreal のクイック スタート」を参照してください。
前提条件
PlayFab アカウントが必要です。パーティーの使用を開始するには、パーティー機能を有効にしなければなりません。
- PlayFab アカウントを作成またはサインインします。 手順については、「クイック スタート: Game Manager」を参照してください。
- PlayFab アカウントから ゲーム マネージャーを使用してパーティー機能を有効にします。
プラットフォームの前提条件
このクイックスタートを開始する前に、次のトピックで指定されているように、必要なプラットフォーム固有のセットアップを実行します。
プラットフォーム固有の手順を完了したら、このトピックの残りの手順に進み、PlayFab Party を設定します。
パーティー SDK をダウンロードしてセットアップする
さまざまなプラットフォームとゲーム エンジン用の Party SDK があります。 必要なものを選択してダウンロードします。 ダウンロード リンクについては、「パーティー SDK」を参照してください。
SDK をインストールした後、コードの記述を開始する前に、サンプルを実行してパーティーのしくみを確認できます。 サンプルをダウンロードするには、 パーティーのサンプルに移動します。
Xbox および PC タイトルでパーティーを使用している場合は、パーティー Xbox Live ヘルパー ライブラリを使用して、一貫した機能と動作を確保することをお勧めします。 このライブラリは、タイトルが Xbox Live の要件を満たすのに役立ちます。 詳細については、「Xbox の要件」を参照してください。
PlayFab タイトルにログインし、エンティティ トークンとエンティティ ID を取得します。
Party を初期化して使用するには、PlayFab にログインする必要があります。 PlayFabClientAPI::LoginWithCustomID またはその他のログイン メソッドを使用できます。
ログインを実行すると、PlayFab は LoginResultの一部としてエンティティ ID とエンティティ トークンを返します。 これら 2 つの重要な情報は、後で PlayFab Party のローカル ユーザー インスタンスを初期化するために使用されます。
PlayFabManager.cpp で実装されているカスタム ID でログインする例を、次のコード スニペットに示します:
PlayFabClientAPI::LoginWithCustomID(
loginRequest,
[this, callback, userId](const LoginResult& loginResult, void*)
{
// Sign in was successful.
DEBUGLOG("PlayFab::signin -- Login with custom id callback\n");
// Save the PlayFab id and entity data for Party authentication.
m_playfabId = loginResult.PlayFabId;
if (loginResult.EntityToken.notNull() && loginResult.EntityToken->Entity.notNull())
{
m_entityKey = loginResult.EntityToken->Entity;
m_entityToken = loginResult.EntityToken->EntityToken;
}
PlayFab からエンティティ ID とエンティティ トークンを正常に取得したら、Party の有効化と初期化に進むことができます。
注意
Xbox Live を使用している場合は、Party Xbox Live ヘルパー ライブラリを取得してログインすることもできます。
PlayFab Party を初期化する
大まかには、パーティの初期化には次の手順が含まれます。
PartyManagerへのシングルトン参照を取得し、これを初期化します。
これは、Party ライブラリと対話するための主要な管理クラスです。
auto& partyManager = PartyManager::GetSingleton();
PartyError err;
//Only initialize the party manager once.
if (m_partyInitialized == false)
{
// Initialize PlayFab Party
err = partyManager.Initialize(titleId);
if (PARTY_FAILED(err))
{
DEBUGLOG("Initialize failed: %s\n", GetErrorMessage(err));
return;
}
m_partyInitialized = true;
}
- ローカル ユーザー オブジェクトを作成します。
ネットワーク操作とチャット操作を実行するときにデバイス (PC、コンソール、スマートフォンなど) 上のローカル ユーザーを表すために使用されるローカル ユーザー オブジェクト。 ローカル ユーザー オブジェクトは PlayFab エンティティ ID で初期化されます。
//Only create a local user object if it doesn't exist.
if (m_localUser == nullptr)
{
PartyString entityId = Managers::Get<PlayFabManager>()->EntityId().c_str();
PartyString entityToken = Managers::Get<PlayFabManager>()->EntityToken().c_str();
// Create a local user object
err = partyManager.CreateLocalUser(
entityId, // User id
entityToken, // User entity token
&m_localUser // OUT local user object
);
if (PARTY_FAILED(err))
{
DEBUGLOG("CreateLocalUser failed: %s\n", GetErrorMessage(err));
return;
}
}
- また、Party がデータを受信または転送するオーディオ入出力チャネルも設定します。
チャット コントロール オブジェクトは、特定のデバイス上のユーザーのチャット操作を管理します。
// Only create local chat controls if they don't exist.
if (m_localChatControl == nullptr)
{
PartyLocalDevice* localDevice = nullptr;
// Retrieve the local device
err = partyManager.GetLocalDevice(&localDevice);
if (PARTY_FAILED(err))
{
DEBUGLOG("GetLocalDevice failed: %s\n", GetErrorMessage(err));
return;
}
// Create a chat control for the local user on the local device
err = localDevice->CreateChatControl(
m_localUser, // Local user object
m_languageCode, // Language id
nullptr, // Async identifier
&m_localChatControl // OUT local chat control
);
if (PARTY_FAILED(err))
{
DEBUGLOG("CreateChatControl failed: %s\n", GetErrorMessage(err));
return;
}
// Use system default settings for the audio input device
err = m_localChatControl->SetAudioInput(
PartyAudioDeviceSelectionType::SystemDefault, // Selection type
nullptr, // Device id
nullptr // Async identifier
);
if (PARTY_FAILED(err))
{
DEBUGLOG("SetAudioInput failed: %s\n", GetErrorMessage(err));
return;
}
// Use system default settings for the audio output device
err = m_localChatControl->SetAudioOutput(
PartyAudioDeviceSelectionType::SystemDefault, // Selection type
nullptr, // Device id
nullptr // Async identifier
);
if (PARTY_FAILED(err))
{
DEBUGLOG("SetAudioOutput failed: %s\n", GetErrorMessage(err));
}
- 最後に、トランスクリプションと翻訳のオプションを設定します。
トランスクリプションと翻訳は、ゲームのアクセシビリティを大幅に向上させるオプションのチャット機能です。 これらの機能の詳細については、「Chat の概要」を参照してください。
// Get the available list of text to speech profiles
err = m_localChatControl->PopulateAvailableTextToSpeechProfiles(nullptr);
if (PARTY_FAILED(err))
{
DEBUGLOG("Populating available TextToSpeechProfiles failed: %s \n", GetErrorMessage(err));
}
// Set transcription options for transcribing other users regardless of language, and ourselves.
PartyVoiceChatTranscriptionOptions transcriptionOptions =
PartyVoiceChatTranscriptionOptions::TranscribeOtherChatControlsWithMatchingLanguages |
PartyVoiceChatTranscriptionOptions::TranscribeOtherChatControlsWithNonMatchingLanguages |
PartyVoiceChatTranscriptionOptions::TranslateToLocalLanguage |
PartyVoiceChatTranscriptionOptions::TranscribeSelf;
// Set the transcription options on our chat control.
err = m_localChatControl->SetTranscriptionOptions(
transcriptionOptions, // Transcription options
nullptr // Async identifier
);
if (PARTY_FAILED(err))
{
DEBUGLOG("SetTranscriptionOptions failed: %s\n", GetErrorMessage(err));
}
// Enable translation to local language in chat controls.
err = m_localChatControl->SetTextChatOptions(
PartyTextChatOptions::TranslateToLocalLanguage,
nullptr
);
この時点で、PlayFab Party はアプリケーションまたはゲームで初期化されています。
完全なサンプルについては、デモ アプリの NetworkManager.cpp の NetworkManager::Initialize() code を参照してください。
次の手順では、Party ネットワークを作成し、それに接続します。
パーティー ネットワークを作成する
Party ネットワークは、1 つ以上のデバイスとその承認されたユーザーのセキュリティで保護されたコレクションです。チャットやデータ通信のやりとりのためにゲームが作成します。 Party ネットワークは通常、ゲームのマルチプレイヤー セッションまたはチャットの "ロビー" の概念に合わせて調整されます。 自分のネットワーク内のプレイヤーにのみメッセージを送信できます。
次のコード スニペットは、パーティー ネットワークを作成する方法を示しています。
// Initialize an empty network descriptor to hold the result of the following call.
PartyNetworkDescriptor networkDescriptor = {};
// Create a new network descriptor
err = PartyManager::GetSingleton().CreateNewNetwork(
m_localUser, // Local User
&cfg, // Network Config
0, // Region List Count
nullptr, // Region List
&invitationConfiguration, // Invitation configuration
nullptr, // Async Identifier
&networkDescriptor, // OUT network descriptor
nullptr // applied initialinvitationidentifier.
);
CreateNewNetwork() の関数呼び出しが成功すると、ネットワーク記述子 PartyNetworkDescriptor オブジェクトが返されるか設定されます。 記述子には、他のプレイヤーがネットワークに接続するために必要とするデータが含まれています。
その他の関数パラメーターについては、「API リファレンス ドキュメント」を参照してください。
Party ネットワークが作成されると、招待を使用して、ネットワークに参加できるユーザーを制御します。 PlayFab マッチメイキング、PlayFab ロビー、プラットフォームへの招待、またはカスタム ゲーム サービスを使用して、接続の詳細を他のプレイヤーと共有できます。
最も単純な招待の種類は、ネットワーク記述子で構成されるオープン招待です。 すべての招待の種類とセキュリティ モデルの詳細については、「招待とセキュリティ モデル」を参照してください。
共有パーティ ネットワーク記述子
この時点で、パーティ ネットワーク記述子があり、他のプレイヤーと共有する準備ができました。 この情報を共有するために使用できる同期メカニズムは多数ありますが、迅速なテストのために、パーティ ネットワーク記述子をホスト パーティ セッションからゲスト パーティ セッションに手動でコピーして貼り付けることができます。 マルチプレイヤー ゲームでネットワーク記述子を共有するには PlayFab ロビーを使用することをお勧めしますが、ゲームのニーズに基づいて独自のロビー サービス、招待、またはその他の共有メカニズムを使用することもできます。
パーティ ネットワーク記述子を手動で共有する
ホスト セッションから、PartyManager::SerializeNetworkDescriptor() を使用してネットワーク記述子を文字列にシリアル化し、コンソールに出力します。
ネットワーク記述子文字列をコピーして、ローカルまたはリモートで別のゲームに貼り付けます。
ゲスト セッションで、PartyManager::DeserializeNetworkDescriptor() を使用して、ネットワーク記述子文字列からネットワーク記述子を逆シリアル化します。
パーティー ネットワークに接続します。
PlayFab ロビーを使用してパーティ ネットワーク記述子を共有する
PlayFab ロビーは、プレイヤーがマッチに出入りする間にプレイヤーを一時的にグループ化したり、プレイヤーが同じネットワークに参加できるようにネットワーク記述子を同期したりするために使用できます。 PlayFab ロビーは高度にカスタマイズ可能で、サポートされているすべてのプラットフォームおよびプラットフォーム間でのさまざまなゲームプレイのニーズをサポートします。 リアルタイム通知で PlayFab ロビーを使用する方法の詳細については、「Multiplayer SDK のクイックスタート」を参照してください。
PlayFab ロビーを PlayFab パーティと一緒に使用する方法の詳細については、「PlayFab マルチプレイヤー SDKを使用してロビーを作成する」を参照してください。
パーティー ネットワークに接続する
パーティ ネットワーク記述子を取得した後にパーティ ネットワークに参加するには、次の手順に従います。
PartyManager::DeserializeNetworkDescriptor() を使用して、ネットワーク記述子文字列からネットワーク記述子を逆シリアル化します。
パーティー ネットワークに接続します。
ネットワークのローカル ユーザーを認証します。
VOIP を使用できるように、ローカル チャット コントロールをネットワークに接続します。
ゲーム メッセージ トラフィックの Party Network エンドポイント を確立します。
PartyNetworkDescriptor networkDescriptor = {};
// Deserialize the remote network's descriptor
PartyError err = PartyManager::DeserializeNetworkDescriptor(descriptor, &networkDescriptor);
if (PARTY_FAILED(err))
{
DEBUGLOG("ConnectToNetwork failed to deserialize descriptor: %s\n", GetErrorMessage(err));
errorCallback(err);
return;
}
// This portion of connecting to the network is the same for
// both creating a new and joining an existing network.
PartyError err = PartyManager::GetSingleton().ConnectToNetwork(
&descriptor, // Network descriptor
nullptr, // Async identifier
&m_network // OUT network
);
if (PARTY_FAILED(err))
{
DEBUGLOG("ConnectToNetwork failed: %s\n", GetErrorMessage(err));
errorCallback(err);
return false;
}
// Authenticate the local user on the network so we can participate in it
err = m_network->AuthenticateLocalUser(
m_localUser, // Local user
networkId, // Invitation Id
nullptr // Async identifier
);
if (PARTY_FAILED(err))
{
DEBUGLOG("AuthenticateLocalUser failed: %s\n", GetErrorMessage(err));
errorCallback(err);
return false;
}
// Connect the local user chat control to the network so we can use VOIP
err = m_network->ConnectChatControl(
m_localChatControl, // Local chat control
nullptr // Async identifier
);
if (PARTY_FAILED(err))
{
DEBUGLOG("ConnectChatControl failed: %s\n", GetErrorMessage(err));
errorCallback(err);
return false;
}
// Establish a network endoint for game message traffic
err = m_network->CreateEndpoint(
m_localUser, // Local user
0, // Property Count
nullptr, // Property name keys
nullptr, // Property Values
nullptr, // Async identifier
&m_localEndpoint // OUT local endpoint
);
if (PARTY_FAILED(err))
{
DEBUGLOG("Failed to CreateEndpoint: %s\n", GetErrorMessage(err));
errorCallback(err);
return false;
}
別のネットワーク デバイスまたはエンドポイントにメッセージを送信する
Party ネットワーク に接続したら、ローカル エンドポイント オブジェクトを使用してメッセージを送信できます。
if (m_localEndpoint && m_state == NetworkManagerState::NetworkConnected)
{
auto packet = message.Serialize();
// Form the data packet into a data buffer structure
PartyDataBuffer data[] = {
{
static_cast<const void*>(packet.data()),
static_cast<uint32_t>(packet.size())
},
};
// Set delivery options for guaranteed and sequential delivery.
PartySendMessageOptions deliveryOptions =
PartySendMessageOptions::GuaranteedDelivery |
PartySendMessageOptions::SequentialDelivery;
// Send out the message to all other peers
PartyError err = m_localEndpoint->SendMessage(
0, // endpoint count; 0 = broadcast
nullptr, // endpoint list
deliveryOptions, // send message options
nullptr, // configuration
1, // buffer count
data, // buffer
nullptr // async identifier
);
if (PARTY_FAILED(err))
{
DEBUGLOG("Failed to SendMessage: %s\n", GetErrorMessage(err));
}
}
完全なコードは NetworkManager.cpp で入手できます。
メッセージを受信し、ローカル デバイスにレンダリングする
最後の手順では、リモート パーティー メンバーから送信されたメッセージを受信し、デバイス上でレンダリング (再生) します。
Important
前の手順でチャット コントロールを作成している間に、Party がオーディオ データの送受信、レンダリングに使用するオーディオ入出力デバイスは既に設定済みです。 オーディオ メッセージを受信するには、オーディオをフローさせる場合は、各チャット コントロール間で適切なチャット アクセス許可を設定する必要もあります。 既定では、チャットのアクセス許可は NONE に設定されます。 詳細については、チャット権限の記事を参照してください。
Party レイヤーからの他のメッセージの処理は、専用の更新スレッドまたは高頻度のゲーム ループで行うのが最適です。 ゲーム ループは、すべてのフレームを実行し、StartProcessingStateChanges() 関数を介してパーティー マネージャーからメッセージを受信するように設定する必要があります。
すべての状態変更の詳細については、パーティ リファレンス ドキュメントを参照してください。 または、各状態の変更を処理する方法の例については、「NetworkManager.cpp」を参照することもできます。
タイトルの一時停止の処理
一部のプラットフォームでは、iOS、Switch、GDK などのタイトルの実行を一時的に中断できます。 タイトルが中断されると、ネットワーク スタックが無効になり、PlayFab Party は PlayFab Party ネットワークへの接続を維持できなくなります。 PlayFab Party を使用する場合、タイトルの一時停止と再開の実行を処理するには、特別な考慮事項が必要です。
iOS
iOS では、PlayFab Party ネットワークから離れて再接続する必要があります
パーティー ネットワークを終了するには、LeaveNetwork() を呼び出します。 ネットワークが再アクティブ化されたら、ConnectToNetwork() を以前の Party ネットワーク記述子で呼び出します。
Switch と GDK
Nintendo Switch および Microsoft GDK では、PlayFab Party をクリーンアップし、タイトルの実行が再開されるまで待ってから、PlayFab Party を再初期化してネットワークに再接続する必要があります。
パーティをシャットダウンするには、Cleanup() を呼び出します。
Important
Cleanup() を呼び出すと、すべてのライブラリ リソースが解放され、すべてのライブラリ オブジェクトが破棄されます。 パーティーを再初期化した後、ローカル ユーザーやチャット コントロールなどのライブラリ オブジェクトを再作成するだけでなく、ローカル ユーザーの再認証、チャット コントロールの再接続、エンドポイントの再作成によって以前のネットワーク状態を再確立する必要があります。
ネットワークが再アクティブ化されたら、Initialize() を呼び出します。 パーティーが正常に初期化されたら、次の手順を実行して、以前の PlayFab Party Network に再度参加する必要があります。
以前のパーティ ネットワーク記述子を使用して Party Network に接続します。
ローカル ユーザー オブジェクトを再作成し、それらのローカル ユーザーをネットワークに対して再認証します。
ローカル チャット コントロールを再作成し、それらのチャット コントロールをネットワークに再接続して VOIP を有効にします。
ゲーム メッセージ トラフィック用のパーティ ネットワーク エンドポイントを再作成します。
PartyError err = PartyManager::GetSingleton().ConnectToNetwork(
&descriptor, // Network descriptor
nullptr, // Async identifier
&m_network // OUT network
);
if (PARTY_FAILED(err))
{
DEBUGLOG("ConnectToNetwork failed: %s\n", GetErrorMessage(err));
errorCallback(err);
return false;
}
// Authenticate the local user on the network so we can participate in it
err = m_network->AuthenticateLocalUser(
m_localUser, // Local user
networkId, // Invitation Id
nullptr // Async identifier
);
if (PARTY_FAILED(err))
{
DEBUGLOG("AuthenticateLocalUser failed: %s\n", GetErrorMessage(err));
errorCallback(err);
return false;
}
// Connect the local user chat control to the network so we can use VOIP
err = m_network->ConnectChatControl(
m_localChatControl, // Local chat control
nullptr // Async identifier
);
if (PARTY_FAILED(err))
{
DEBUGLOG("ConnectChatControl failed: %s\n", GetErrorMessage(err));
errorCallback(err);
return false;
}
// Establish a network endoint for game message traffic
err = m_network->CreateEndpoint(
m_localUser, // Local user
0, // Property Count
nullptr, // Property name keys
nullptr, // Property Values
nullptr, // Async identifier
&m_localEndpoint // OUT local endpoint
);
if (PARTY_FAILED(err))
{
DEBUGLOG("Failed to CreateEndpoint: %s\n", GetErrorMessage(err));
errorCallback(err);
return false;
}
Important
再接続が正常に完了すると、パーティーは他のピアと通信できるようになりますが、以前のネットワークが存在しない場合、再接続は失敗します。 この場合は、適切な接続エラーを処理する必要があります。
次の手順
「PlayFab Party オブジェクトとその関係」の詳細を読み、ゲームでこれらの機能を最大限に活用できるように、「Party API リファレンス ドキュメント」を参照してください。
Xbox 固有のガイダンスについては、「Xbox の要件」 を早い段階で頻繁に参照してください。