파티 빠른 시작
이 빠른 시작에서는 PlayFab 파티의 핵심 기능과 코드 조각에 대해 설명합니다. PlayFab 파티는 처음부터 여러 플랫폼용으로 설계되었습니다. 이러한 빠른 시작은 같은 방식으로 구성되었으므로, 대부분의 정보가 모든 플랫폼에 적용되며 플랫폼별 필수 조건 및 단계는 링크된 문서에서 설명합니다.
자세히 알아보려면 링크된 참고자료와 개념 설명서, 플랫폼별 응용 프로그램 예제를 참조하세요.
참고 항목
이 빠른 시작 가이드에서는 C++ 파티 SDK 사용에 대해 다룹니다.
- Unity 사용자의 경우 Unity 빠른 시작을 참조하세요.
- Unreal Engine용 PlayFab 온라인 하위 시스템을 사용하려는 Unreal Engine 사용자의 경우 Unreal 빠른 시작을 참조하세요.
필수 구성 요소
PlayFab 계정이 필요하며 파티를 사용하려면 파티 기능을 사용하도록 설정해야 합니다.
- PlayFab 계정을 만들거나 계정에 로그인합니다. 지침은 빠른 시작: 게임 관리자를 참조하세요.
- PlayFab 계정에서 게임 관리자를 통해 파티 기능을 사용하도록 설정합니다.
플랫폼 필수 조건
이 빠른 시작을 시작하기 전에 다음 항목에 지정된 대로 플랫폼별 필수 설정을 수행합니다.
플랫폼별 단계를 마치면 이 항목의 나머지 단계를 진행하여 PlayFab 파티를 설정합니다.
파티 SDK 다운로드 및 설정
다양한 플랫폼 및 게임 엔진에 대한 파티 SDK가 있습니다. 필요한 항목을 선택하고 다운로드합니다. 다운로드 링크는 파티 SDK를 참조하세요.
SDK를 설치한 후 코드를 작성하기 전에 샘플을 실행하여 파티의 작동 방식을 확인할 수 있습니다. 샘플을 다운로드하려면 파티 샘플로 이동합니다.
Xbox 및 PC 타이틀에서 파티를 사용할 경우 일관된 기능과 동작을 보장하기 위해 파티 Xbox Live 도우미 라이브러리를 사용하는 것이 좋습니다. 이 라이브러리를 사용하면 타이틀이 Xbox Live 요구 사항을 충족하는 데 도움이 됩니다. 자세한 내용은 Xbox 요구 사항을 참조하세요.
PlayFab 타이틀에 로그인하고 엔터티 토큰과 엔터티 ID를 가져옵니다.
파티를 초기화하고 사용하려면 PlayFab에 로그인해야 합니다. PlayFabClientAPI::LoginWithCustomID나 플랫폼별 로그인 방법을 사용할 수 있습니다.
로그인을 실행하면 PlayFab은 LoginResult의 일부로 엔터티 ID 및 엔터티 토큰을 반환합니다. 이러한 두 가지 주요 정보는 PlayFab 파티의 로컬 사용자 인스턴스를 초기화하는 데 사용됩니다.
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와 엔터티 토큰을 가져왔으면 파티를 사용하도록 설정하고 초기화할 수 있습니다.
참고 항목
Xbox Live를 사용하는 경우 파티 Xbox Live 도우미 라이브러리를 사용해 로그인할 수도 있습니다.
PlayFab 파티 초기화
개략적으로 파티 초기화에는 다음 단계가 포함됩니다.
PartyManager에 대한 싱글톤 참조를 가져오고 이를 초기화합니다.
파티 라이브러리와 상호 작용하기 위한 기본 관리 클래스입니다.
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;
}
}
- 채팅 제어를 만들고 파티가 데이터를 받거나 전달할 오디오 입력 및 출력 채널을 설정합니다.
채팅 컨트롤 개체는 특정 디바이스에서 사용자의 채팅 작업을 관리합니다.
// 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 파티가 초기화되었습니다.
완전한 예시는 데모 앱 NetworkManager.cpp의 NetworkManager::Initialize() 코드를 참조합니다.
다음 단계로 파티 네트워크를 만든 후 네트워크에 연결합니다.
파티 네트워크 만들기
파티 네트워크는 게임에서 채팅 또는 데이터 통신을 교환하기 위해 만드는 하나 이상의 디바이스와 그 인증된 사용자의 보안 컬렉션입니다. 파티 네트워크는 일반적으로 게임의 멀티 플레이어 세션 또는 채팅 “대기실” 개념과 부합합니다. 자체 네트워크 내의 플레이어에게만 메시지를 보낼 수 있습니다.
다음 코드 조각은 파티 네트워크를 만드는 방법을 보여 줍니다.
// 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 참조 설명서를 참조하세요.
파티 네트워크를 만든 후 초대 기능을 사용해 네트워크에 참가할 수 있는 사용자를 제어합니다. PlayFab 매치 메이킹, PlayFab 대기실, 플랫폼 초대 또는 사용자 지정 게임 서비스를 사용하여 다른 플레이어와 연결 세부 정보를 공유할 수 있습니다.
가장 간단한 초대 유형은 네트워크 설명자로 구성된 열린 초대입니다. 모든 초대 유형과 보안 모델에 대한 자세한 내용은 초대 및 보안 모델을 참조하세요.
공유 파티 네트워크 설명자
이 시점에서 파티 네트워크 설명자가 있으며 다른 플레이어와 공유할 준비가 된 것입니다. 이 정보를 공유하는 데 사용할 수 있는 많은 동기화 메커니즘이 있지만 빠른 테스트를 위해 파티 네트워크 설명자를 호스트 파티 세션에서 게스트 파티 세션으로 수동으로 복사하여 붙여넣을 수 있습니다. 멀티 플레이어 게임에서 네트워크 설명자를 공유하기 위해 PlayFab 로비를 사용하는 것이 좋지만, 게임의 요구 사항에 따라 사용자 고유의 로비 서비스, 초대 또는 기타 공유 메커니즘을 사용할 수도 있습니다.
파티 네트워크 설명자를 수동으로 공유
호스트 세션에서 PartyManager::SerializeNetworkDescriptor()를 사용하여 네트워크 설명자를 문자열로 직렬화하고 콘솔에 출력합니다.
네트워크 설명자 문자열을 복사하여 로컬 또는 원격으로 다른 게임에 붙여넣습니다.
게스트 세션에서 PartyManager::D eserializeNetworkDescriptor()를 사용하여 네트워크 설명자 문자열에서 네트워크 설명자를 역직렬화합니다.
파티 네트워크에 연결합니다.
PlayFab 로비를 사용하여 파티 네트워크 설명자 공유
PlayFab 로비는 플레이어가 매치 안팎으로 이동할 때 일시적으로 플레이어를 그룹화하는 데 사용할 수 있으며, 플레이어가 동일한 네트워크에 참가할 수 있도록 네트워크 설명자를 동기화하는 데 사용할 수 있습니다. PlayFab 로비는 지원되는 모든 플랫폼 및 여러 플랫폼에서 다양한 게임 플레이 요구를 지원하기 위해 고도로 사용자 지정할 수 있습니다. 실시간 알림과 함께 PlayFab 로비를 사용하는 방법에 대한 자세한 내용은 멀티 플레이어 SDK 빠른 시작을 참조하세요.
PlayFab 로비를 PlayFab 파티와 함께 사용하는 방법에 대한 자세한 내용은 PlayFab 멀티 플레이어 SDK를 사용하여 로비 만들기를 참조하세요.
파티 네트워크에 연결
파티 네트워크 설명자를 획득한 후 아래 단계에 따라 파티 네트워크에 가입합니다.
PartyManager::D eserializeNetworkDescriptor()를 사용하여 네트워크 설명자 문자열에서 네트워크 설명자를 역직렬화합니다.
파티 네트워크에 연결합니다.
네트워크에 로컬 사용자를 인증합니다.
VOIP를 사용할 수 있도록 로컬 채팅 컨트롤을 네트워크에 연결합니다.
게임 메시지 트래픽을 위한 파티 네트워크 엔드포인트를 설정합니다.
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;
}
다른 네트워크 디바이스 또는 엔드포인트로 메시지 보내기
파티 네트워크에 연결이 완료되면 로컬 엔드포인트 개체를 사용하여 메시지를 보낼 수 있습니다.
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
이전 단계 중 하나에서 채팅 컨트롤을 만들 때 파티가 오디오 데이터를 보내고 받고 렌더링하는 데 사용하는 오디오 입력 및 출력 디바이스를 이미 설정했습니다. 또한 오디오 메시지를 수신하려면 오디오가 흐를 수 있도록 각 채팅 제어 사이에 적절한 채팅 권한을 설정해야 합니다. 기본적으로 채팅 권한은 없음으로 설정됩니다. 자세한 내용은 채팅 권한 문서를 참조하세요.
파티 계층의 기타 메시지 처리는 전용 업데이트 스레드 또는 고주파 게임 루프에서 수행하는 것이 가장 좋습니다. 모든 프레임을 실행하고 StartProcessingStateChanges() 함수를 통해 파티 관리자의 메시지를 수신하도록 게임 루프를 설정해야 합니다.
모든 상태 변경에 대한 전체 설명은 파티 참조 설명서를 참조하세요. 아니면 NetworkManager.cpp에서 각 상태 변경 처리 방법에 대한 예시를 참조할 수도 있습니다.
타이틀 일시 중단 처리
일부 플랫폼에서는 iOS, Switch, GDK와 같은 타이틀 실행을 일시적으로 일시 중단할 수 있습니다. 타이틀이 일시 중단되면 네트워크 스택이 무효화되고 PlayFab 파티가 PlayFab 파티 네트워크 연결을 유지할 수 없게 됩니다. PlayFab 파티를 사용할 때 타이틀의 일시 중단 및 재개 실행을 처리하려면 특별한 고려 사항이 필요합니다.
iOS
iOS에서는 PlayFab 파티 네트워크에서 나가고 다시 연결해야 합니다.
파티 네트워크를 나가려면 LeaveNetwork()를 호출합니다. 네트워크가 다시 활성화되면 이전 파티 네트워크 설명자를 사용하여 ConnectToNetwork()를 호출합니다.
Switch 및 GDK
Nintendo Switch 및 Microsoft GDK에서는 PlayFab 파티를 정리하고 타이틀 실행이 다시 시작될 때까지 기다린 후 PlayFab 파티를 다시 초기화하고 네트워크에 다시 연결해야 합니다.
파티를 종료하려면 Cleanup()을 호출합니다.
Important
Cleanup()을 호출하여 모든 라이브러리 리소스를 회수하고 모든 라이브러리 개체를 삭제합니다. 파티를 다시 초기화한 후에는 로컬 사용자 및 채팅 컨트롤과 같은 라이브러리 개체를 다시 만들고, 로컬 사용자를 다시 인증하고, 채팅 컨트롤을 다시 연결하고, 엔드포인트를 다시 만들어 이전 네트워크 상태를 다시 설정해야 합니다.
네트워크가 다시 활성화되면 Initialize()를 호출합니다. 파티가 성공적으로 초기화되어 이전 PlayFab 파티 네트워크에 다시 참가하려면 다음 단계가 필요합니다.
이전 파티 네트워크 설명자를 사용하여 파티 네트워크에 연결합니다.
로컬 사용자 개체를 다시 만들고 해당 로컬 사용자를 네트워크에 다시 인증합니다.
로컬 채팅 컨트롤을 다시 만들고 해당 채팅 컨트롤을 네트워크에 다시 연결하여 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 파티 개체 및 그 관계에 대해 자세히 알아보고 게임에서 이러한 기능을 최대한 활용할 수 있도록 파티 API 참조 설명서를 참조하세요.
Xbox 관련 지침에 대한 자세한 내용은 Xbox 요구 사항을 조기에 자주 참조하세요.