Party クイックスタート

このクイックスタートでは、PlayFab Party のコア機能をコードスニペットと共に説明します。PlayFab Party は、最初からクロスプラットフォームであるように設計されています。これらのクイックスタートも同様に構造化されており、ほとんどの情報はすべてのプラットフォームに適用され、プラットフォーム固有の前提条件と手順はリンクされたドキュメントに記載されています。より深く理解するには、リンクされたリファレンスおよび概念ドキュメント、およびプラットフォームごとのサンプルアプリケーションを参照してください。

このクイックスタートガイドでは、C++ Party SDK の使用について説明します。* Unity ユーザーの場合は、Unity のクイックスタートを参照してください。* Unreal Engine 用の PlayFab Online Subsystem を使用したい Unreal Engine ユーザーの場合は、Unreal のクイックスタートを参照してください。

前提条件

PlayFab アカウントが必要で、Party の使用を開始するには Party 機能を有効にする必要があります。

PlayFab アカウントを作成またはサインインします。手順については、クイックスタート: Game Manager を参照してください。
PlayFab アカウントから Game Manager 経由で Party 機能を有効にするを実行します。

プラットフォームの前提条件

このクイックスタートを開始する前に、次のトピックで指定されているプラットフォーム固有のセットアップを実行してください:

Linux の前提条件

プラットフォーム固有の手順を完了したら、このトピックの残りの手順に進んで PlayFab Party をセットアップします。

Party SDK のダウンロードとセットアップ

Party SDK は、さまざまなプラットフォームとゲームエンジン用に用意されています。必要なものを選択してダウンロードしてください。ダウンロードリンクについては、Party SDK を参照してください。 SDK をインストールした後、コードの記述を開始する前に、Party がどのように動作するかを確認するためにサンプルを実行することができます。サンプルをダウンロードするには、Party サンプルにアクセスしてください。 XBOX および PC タイトルで Party を使用している場合は、一貫した機能と動作を保証するために Party XBOX Live Helper ライブラリの使用を推奨します。このライブラリは、タイトルが 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 Helper ライブラリを使用してログインすることもできます。

PlayFab Party の初期化

大まかに言うと、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 Entity 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));
        }

文字起こしと翻訳のオプションを設定します。文字起こしと翻訳は、ゲームのアクセシビリティを大幅に向上させることができるオプションのチャット機能です。これらの機能の詳細については、チャットの概要を参照してください。

        // 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() コードを参照してください。次のステップは、Party ネットワークを作成してそれに接続することです。

Party ネットワークの作成

Party ネットワークは、チャットまたはデータ通信を交換するためにゲームが作成する、1 つ以上のデバイスとそれらの認可されたユーザーのセキュアなコレクションです。Party ネットワークは通常、ゲームのマルチプレイヤーセッションまたはチャットの「ロビー」の概念と一致します。メッセージは自分のネットワーク内のプレイヤーにのみ送信できます。次のコードスニペットは、Party ネットワークを作成する方法を示しています。

    // Set the maximum number of devices allowed in a network to 16 devices
    constexpr uint8_t c_maxSampleNetworkDeviceCount = 16;
    static_assert(c_maxSampleNetworkDeviceCount <= c_maxNetworkConfigurationMaxDeviceCount, "Must be less than or equal to c_maxNetworkConfigurationMaxDeviceCount.");

    // Initialize network configuration for Party Network.
    PartyNetworkConfiguration cfg = {};
    cfg.maxDeviceCount = c_maxSampleNetworkDeviceCount;
    cfg.maxUserCount = c_maxSampleNetworkDeviceCount;
    ...
    
    // 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 Matchmaking、PlayFab Lobby、プラットフォームの招待、またはカスタムゲームサービスを使用して、他のプレイヤーと接続の詳細を共有できます。最も単純な招待の種類は、ネットワーク記述子で構成されるオープン招待です。すべての招待の種類とセキュリティモデルの詳細については、招待とセキュリティモデルを参照してください。

Party ネットワーク記述子の共有

この時点で、Party ネットワーク記述子があり、他のプレイヤーと共有する準備ができています。この情報を共有するために使用できる同期メカニズムは多数ありますが、簡単なテスト目的では、ホストの Party セッションからゲストの Party セッションに Party ネットワーク記述子を手動でコピー & ペーストできます。マルチプレイヤーゲームでネットワーク記述子を共有するには PlayFab Lobby の使用を推奨しますが、ゲームのニーズに基づいて独自のロビーサービス、招待、またはその他の共有メカニズムを使用することもできます。

Party ネットワーク記述子を手動で共有する

ホストセッションから、PartyManager::SerializeNetworkDescriptor() を使用してネットワーク記述子を文字列にシリアル化し、コンソールに出力します。
ネットワーク記述子文字列をローカルまたはリモートの別のゲームにコピー & ペーストします。
ゲストセッションで、PartyManager::DeserializeNetworkDescriptor() を使用して、ネットワーク記述子文字列からネットワーク記述子を逆シリアル化します。
Party ネットワークに接続します。

PlayFab Lobby を使用して Party ネットワーク記述子を共有する

PlayFab Lobby を使用すると、プレイヤーがマッチの出入りをするときにプレイヤーを一時的にグループ化でき、ネットワーク記述子を同期して同じネットワークに参加できるようにすることができます。 PlayFab Lobby は、すべてのサポート対象プラットフォームとプラットフォーム間で幅広いゲームプレイのニーズをサポートするために高度にカスタマイズ可能です。リアルタイムメッセージで PlayFab Lobby を使用する詳細については、Multiplayer SDK のクイックスタートを参照してください。 PlayFab Lobby を PlayFab Party と一緒に使用する詳細については、PlayFab Multiplayer SDK でロビーを作成するを参照してください。

スケーラブルネットワークの有効化

PlayFab Party ネットワークは、2 から 128 のデバイスの範囲でサポートするようにスケーリングできます。サービスはシナリオに最適化されたリレー構成を選択するため、PartyNetworkConfiguration の maxDeviceCount をネットワーク内で予想されるデバイスの最大数に一致するように構成することが重要です。スケーラブルネットワークの説明については、スケーラブルネットワークを参照してください。

Party ネットワークへの接続

Party ネットワーク記述子を取得した後、以下の手順に従って Party ネットワークに参加します:

PartyManager::DeserializeNetworkDescriptor() を使用して、ネットワーク記述子文字列からネットワーク記述子を逆シリアル化します。
Party ネットワークに接続します。
ネットワークのローカルユーザーを認証します。
VOIP を使用できるように、ローカルチャットコントロールをネットワークに接続します。
ゲームメッセージトラフィック用の Party ネットワークエンドポイントを確立します。

    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 で入手できます。

メッセージを受信してローカルデバイスでレンダリングする

最後のステップは、リモート Party メンバーから送信されたメッセージを受信し、デバイスでそれらをレンダリング (再生) することです。

前のステップの 1 つでチャットコントロールを作成する際、Party がオーディオデータの送受信およびレンダリングに使用するオーディオ入力および出力デバイスを既にセットアップしています。オーディオメッセージを受信するには、オーディオを流したい場合、各チャットコントロール間で適切なチャットアクセス許可も設定する必要があります。既定では、チャットアクセス許可は NONE に設定されています。詳細については、チャットのアクセス許可の記事を参照してください。

Party レイヤーからの他のメッセージの処理は、専用の更新スレッドまたは高頻度のゲームループで最適に実行できます。ゲームループは、フレームごとに実行し、StartProcessingStateChanges() 関数を介して Party Manager からメッセージを受信するようにセットアップされる必要があります。すべての状態変更の完全な説明については、Party リファレンスドキュメントを参照してください。または、各状態変更を処理する方法の例については、NetworkManager.cpp を参照してください。

タイトル中断の処理

一部のプラットフォームでは、タイトルの実行を一時的に中断することがサポートされています: iOS、Switch、および GDK。タイトルが中断されると、ネットワークスタックが無効になり、PlayFab Party は PlayFab Party ネットワークへの接続を維持できなくなります。 PlayFab Party を使用しているときにタイトルの実行を中断および再開する処理には、特別な考慮が必要です。

iOS

iOS では、PlayFab Party ネットワークから退出して再接続する必要があります。 Party ネットワークから退出するには、LeaveNetwork() を呼び出します。ネットワークが再アクティブ化されたら、以前の Party ネットワーク記述子で ConnectToNetwork() を呼び出します。

Switch および GDK

Nintendo Switch および Microsoft GDK では、PlayFab Party をクリーンアップし、タイトルの実行が再開されるのを待ってから PlayFab Party を再初期化してネットワークに再接続する必要があります。 Party をシャットダウンするには、Cleanup() を呼び出します。

Cleanup() を呼び出すと、すべてのライブラリリソースが再利用され、すべてのライブラリオブジェクトが破棄されます。Party を再初期化した後、ローカルユーザーの再認証、チャットコントロールの再接続、およびエンドポイントの再作成により、ローカルユーザーやチャットコントロールなどのライブラリオブジェクトを再作成し、以前のネットワーク状態を再確立する必要があります。

ネットワークが再アクティブ化されたら、Initialize() を呼び出します。Party が正常に初期化されたら、以前の PlayFab Party ネットワークに再参加するために以下の手順が必要です:

以前の Party ネットワーク記述子で Party ネットワークに接続します。
ローカルユーザーオブジェクトを再作成し、それらのローカルユーザーをネットワークに再認証します。
ローカルチャットコントロールを再作成し、それらのチャットコントロールをネットワークに再接続して VOIP を有効にします。
ゲームメッセージトラフィック用の Party ネットワークエンドポイントを再作成します。

    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 は他のピアと通信できるようになりますが、以前のネットワークがもう存在しない場合、再接続は失敗します。この場合、適切な接続エラーを処理する必要があります。

次のステップ

PlayFab Party オブジェクトとその関係の詳細について読み、ゲームがこれらの機能を最大限に活用できるように、Party API リファレンスドキュメントを参照してください。より XBOX 固有のガイダンスについては、早めに、そして頻繁に XBOX 要件を参照してください。

XBOX Services

PlayFab

前提条件

プラットフォームの前提条件

Party SDK のダウンロードとセットアップ

PlayFab タイトルにログインしてエンティティトークンとエンティティ ID を取得する

PlayFab Party の初期化

Party ネットワークの作成

Party ネットワーク記述子の共有

Party ネットワーク記述子を手動で共有する

PlayFab Lobby を使用して Party ネットワーク記述子を共有する

スケーラブルネットワークの有効化

Party ネットワークへの接続

別のネットワークデバイスまたはエンドポイントへのメッセージの送信

メッセージを受信してローカルデバイスでレンダリングする

タイトル中断の処理

iOS

Switch および GDK

次のステップ

関連項目

​前提条件

​プラットフォームの前提条件

​Party SDK のダウンロードとセットアップ

​PlayFab タイトルにログインしてエンティティ トークンとエンティティ ID を取得する

​PlayFab Party の初期化

​Party ネットワークの作成

​Party ネットワーク記述子の共有

​Party ネットワーク記述子を手動で共有する

​PlayFab Lobby を使用して Party ネットワーク記述子を共有する

​スケーラブル ネットワークの有効化

​Party ネットワークへの接続

​別のネットワーク デバイスまたはエンドポイントへのメッセージの送信

​メッセージを受信してローカル デバイスでレンダリングする

​タイトル中断の処理

​iOS

​Switch および GDK

​次のステップ

​関連項目

前提条件

プラットフォームの前提条件

Party SDK のダウンロードとセットアップ

PlayFab タイトルにログインしてエンティティトークンとエンティティ ID を取得する

PlayFab Party の初期化

Party ネットワークの作成

Party ネットワーク記述子の共有

Party ネットワーク記述子を手動で共有する

PlayFab Lobby を使用して Party ネットワーク記述子を共有する

スケーラブルネットワークの有効化

Party ネットワークへの接続

別のネットワークデバイスまたはエンドポイントへのメッセージの送信

メッセージを受信してローカルデバイスでレンダリングする

タイトル中断の処理

iOS

Switch および GDK

次のステップ

関連項目