Xbox 요건
게임이 Xbox 콘솔을 타겟팅하는 경우, Xbox Live와 상호 작용할 때 일관된 기능과 동작을 보장하기 위해 일련의 요구 사항을 준수해야 합니다. 이 요구 사항 집합은 Xbox 요구 사항(줄여서 XR)에 나열되어 있습니다. XR은 PC 및 기타 플랫폼의 게임에서 Xbox Live를 사용하도록 요구되는 정책과 상호 작용하고 중첩됩니다. 여기에서는 이러한 요구 사항을 준수하는 데 도움이 될 PlayFab 파티의 모범 사례를 설명합니다.
빠른 참조를 위해, PlayFab 파티 시나리오 및 해당 시나리오에서 다루는 XR과 일치하는 다음 표를 참조합니다.
PlayFab 파티 Xbox Live 도우미 라이브러리
핵심 PlayFab 파티 라이브러리와 함께, Xbox Live 정책 및 확장별 XR을 준수하도록 설계된 Xbox Live 도우미 라이브러리를 제공합니다. 이 도우미 라이브러리의 사용은 필수는 아니지만 매우 권장되며 모범 사례로 간주됩니다. 여기에 제시된 예제에서는 Xbox Live 도우미 라이브러리를 사용하는 것으로 가정합니다.
PlayFab 파티를 Xbox Live 사용자의 채팅 설정 및 권한에 맞추기
PlayFab 파티는 채팅 통신의 옵트인 모델을 사용하며 기본적으로 두 채팅 컨트롤 간의 모든 통신을 두 참가자 모두가 사용하도록 설정한 통신 집합으로 제한합니다. 자세한 내용은 채팅 권한 및 음소거에 대한 설명서를 참조하세요.
PlayFab 파티의 Xbox Live 도우미 라이브러리는 현재 파티 세션에서 통신하는 Xbox Live 사용자의 기본 설정 및 권한에 맞게 설정해야 하는 채팅 권한 집합을 나타냅니다. 자세한 내용은 Xbox Live 사용자의 개인 정보 설정 및 사용 권한 준수에 대한 설명서를 참조하세요.
PlayFab 파티 및 Xbox Live 도우미 라이브러리를 적절히 사용함으로써 게임은 XR-015에서 지정한 요구 사항을 전적으로 충족할 수 있으며 XR-045에서 지정한 관련 통신 요구 사항을 충족할 수 있습니다. PlayFab 파티의 범위를 벗어나는 추가 요구 사항은 XR-045 기술 설명서를 참조하세요.
멀티 플레이어 세션 문서 유지 관리
PlayFab 파티는 어떤 종류의 Xbox 사용자 명단도 제공하지 않습니다. MPSD(멀티 플레이어 세션 디렉터리 서비스)를 이용해 게임을 의존하여 명단을 유지하고 파티 네트워크 활동을 게임 세션의 사용자와 연결합니다. PlayFab 파티는 파티 네트워크에서 오고 가는 원격 엔드포인트와 채팅 컨트롤을 광고합니다. 이러한 개체와 연결된 PlayFab 엔터티 ID는 MPSD 문서의 Xbox 사용자와 일치하여 게임 세션에서 어떤 PlayFab 파티 개체가 Xbox 사용자를 나타내는지를 인식해야 합니다. 교차 플레이 시나리오의 경우 Xbox 사용자와 연관되지 않은 PlayFab 엔터티는 다른 멀티 플레이어 에코시스템의 사용자를 나타낼 수 있습니다.
Xbox 사용자를 인식하려면 PlayFab 엔터티 ID와 Xbox Live 사용자 간에 매핑을 빌드해야 합니다. 이를 위해 세션의 Xbox Live 사용자 목록을 MPSD 문서에 저장하고 Xbox Live 도우미 라이브러리를 사용하여 해당 Xbox Live 사용자를 PlayFab 엔터티 ID로 변환하는 것이 좋습니다. 예를 들어, Xbox Live 사용자 ID와 PlayFab 엔터티 ID 간의 매핑을 참조합니다.
MPSD 문서는 파티 네트워크의 명단을 제공하는 것 외에도 매치 메이킹, 플랫폼 초대, 최근 플레이어 목록 및 진행 중인 참가와 같은 Xbox 멀티 플레이어 에코시스템에서 많은 멀티 플레이어 환경을 추진합니다. 이러한 MPSD 흐름에 파티 네트워크를 통합하는 방법에 대한 자세한 내용은 MPSD와 함께 PlayFab 파티 사용을 참조하세요.
자세한 내용은 MPSD 개요를 참조하세요.
Important
이 섹션에서는 MPSD와 함께 PlayFab 파티를 사용할 때 모범 사례를 제공하지만 PlayFab 파티 자체는 XR-067 MPSD 요구 사항을 묵시적으로 충족하지 않습니다. 이러한 요구 사항을 충족하는 방법에 대한 자세한 내용은 XR-067 기술 설명서를 참조하세요.
교차 플레이 파티 네트워크에서 Xbox 클라이언트 사용
교차 플레이 시나리오의 경우 Xbox Live 에코시스템과 상호 작용할 때 다음 모범 사례를 염두에 두세요.
Important
이 섹션은 Xbox Live와 교차 플레이 시나리오에서 PlayFab 파티를 사용하기 위한 모범 사례를 제공하지만, PlayFab 파티의 사용은 XR-007의 교차 플레이 요구 사항을 묵시적으로 충족시키지는 않습니다. 이러한 요구 사항을 충족하는 방법에 대한 자세한 내용은 XR-007 기술 설명서를 참조하세요.
네트워크 간 게임 세션에서 플레이어 식별하기
고유한 플레이어는 멀티 플레이어 에코시스템에서 식별 가능하고 구별할 수 있어야 합니다. 이를 위해 PlayFab 파티는 세션의 사용자와 연결할 수 있는 다양한 개체(PartyLocalUser, PartyEndpoint, PartyChatControl)에 PlayFab 엔터티 ID를 제공합니다.
네트워크 간 표시 이름은 PlayFab 파티 API에서 제공되지 않습니다. Xbox 사용자를 UI에 표시할 때는 해당 게이머태그를 사용해야 하며, 게이머태그는 MPSD 문서의 Xbox 사용자 ID에서 확인해야 합니다. Xbox 이외 사용자는 XR-007 지침에 따라 UI로 표시되어야 합니다. 플랫폼 제공 표시 이름이 없는 경우 PlayFab은 GetPlayerProfile을 통해 표시 이름을 지원합니다. 네트워크에 가입할 때 플레이어는 다른 플레이어가 볼 수 있도록 공유 세션 문서에 표시 이름을 게시해야 합니다.
PlayFab 파티 라이브러리는 일부 개체를 PlayFab 사용자와 연결하지만(PlayFab 엔터티 ID를 통해) 라이브러리는 PlayFab 사용자가 연결할 수 있는 멀티 플레이어 에코시스템을 식별하는 기능을 제공하지 않습니다. Xbox Live PlayFab 사용자를 다른 멀티플레이어 에코시스템의 사용자와 구별하려면 MPSD와 함께 파티 네트워크에서 PlayFab 엔터티 ID를 상호 참조하는 것이 좋습니다. MPSD를 통해 Xbox Live 플레이어를 비 Xbox Live 플레이어와 구별하는 방법에 대한 자세한 내용은 멀티 플레이어 세션 문서 유지 관리의 섹션을 참조하세요.
Xbox Live와의 교차 플레이 네트워크에서 사용자를 식별하는 방법의 요구 사항에 대한 자세한 내용은 XR-007을 참조하세요.
Xbox Live 사용자에 대한 네트워크 간 통신 권한 준수하기
PlayFab 파티는 Xbox Live 네트워크 간 통신 제한을 묵시적으로 준수하지 않습니다. 따라서 PlayFab 파티 Xbox Live 도우미 라이브러리는 Xbox Live 사용자의 네트워크 간 통신 권한을 쿼리하는 기능을 제공합니다. XR-007에 명시된 네트워크 간 통신 요구 사항을 준수하려면 이 정보를 사용해야 합니다.
자세한 내용은 네트워크 간 통신 준수를 참조하세요.
교차 플레이가 허용되지 않는 경우 PlayFab 파티 초대장을 사용하여 네트워크에 대한 액세스를 제한합니다.
Xbox Live 사용자는 네트워크 간 게임 세션에서 비 Xbox Live 사용자와 상호 작용하기 위해 네트워크 간 권한이 필요합니다. PlayFab 파티는 이러한 네트워크 간 제한(XR-007에 설명됨)을 묵시적으로 준수하지 않으므로 PlayFab 파티 라이브러리 외부에서 이 권한을 쿼리해야 합니다. 이러한 권한이 부여되지 않으면 파티 네트워크가 게임 세션의 MPSD 문서에 알려진 Xbox Live 사용자만 허용하도록 제한해야 합니다. 알려진 Xbox 사용자만 네트워크에 참가할 수 있도록 파티 초대를 사용하도록 샘플 진행 중인 참가 흐름을 보강하여 이 작업을 수행할 수 있습니다.
먼저 제한된 초대를 사용하여 파티 네트워크가 생성되었는지 확인합니다.
PartyString networkCreatorEntityId;
RETURN_VOID_IF_FAILED(m_localPartyUser->GetEntityId(&networkCreatorEntityId));
PartyInvitationConfiguration newNetworkInitialInvite{};
newNetworkInitialInvite.identifier = nullptr; // let Party select the invitation identifier for simplicity
newNetworkInitialInvite.revocability = PartyInvitationRevocability::Anyone; // the initial invitation must be revocable by anyone
// this initial invitation only allows the original xbl user creating the network
newNetworkInitialInvite.entityIdCount = 1;
newNetworkInitialInvite.entityIds = &networkCreatorEntityId;
PartyError error = PartyManager::GetSingleton().CreateNewNetwork(
m_localPartyUser,
&networkConfiguration,
0,
nullptr,
&newNetworkInitialInvite,
nullptr,
nullptr,
nullptr);
진행 중인 참가 흐름과 마찬가지로, 새 Xbox 사용자가 네트워크에 참가하려고 할 때 먼저 세션 문서에 해당 사용자를 추가합니다. 네트워크에 허용하려는 플레이어가 업데이트를 확인하면 세션 문서를 반영하도록 초대 집합을 업데이트합니다. 이렇게 하면 세션 문서의 사용자(Xbox Live 사용자에게 보장됨)만 네트워크에 참가할 수 있습니다.
void
OnSessionDocumentUpdated(
PartyNetwork* network,
uint32_t usersInDocumentCount,
const uint64_t* usersInDocument
)
{
PartyInvitationConfiguration newInvite{};
newInvite.identifier = nullptr; // let Party select the invitation identifier for simplicity
newInvite.revocability = PartyInvitationRevocability::Creator; // must be revocable by the creator only
// the updated invite should contain all users currently in the document
std::vector<PartyString> entityIdsInDocument;
for (uint32_t i = 0; i < usersInDocumentCount; ++i)
{
uint64_t xboxUserId = usersInDocument[i];
// Call title-defined xuid->entityid mapping helper
PartyString xboxUserEntityId = GetEntityIdFromXboxUserId(xboxUserId);
if (xboxUserEntityId != nullptr)
{
entityIdsInDocument.push_back(xboxUserEntityId);
}
else
{
DEBUGLOG("User %llu did not have a matching entity ID.", xboxUserId);
}
}
newInvite.entityIdCount = entityIdsInDocument.size();
newInvite.entityIds = entityIdsInDocument.data();
// Create a new invitation which includes all of the users currently in the document
PartyInvitation* newInvitation;
PartyError error = network->CreateInvitation(
m_localUser,
&newInvite,
nullptr,
&newInvitation);
if (PARTY_FAILED(error))
{
DEBUGLOG("PartyNetwork(0x%p)::CreateInvitation failed! (error=0x%x)", network, error);
return;
}
// Post the invitation's id somewhere that it can be seen by anyone trying to join/rejoin
PostInvitationToMPSD(newInvite);
// Cleanup previous invitations. This isn't strictly necessary, but is a good practice.
uint32_t invitationCount;
PartyInvitationArray invitations;
error = network->GetInvitations(&invitationCount, &invitations);
if (PARTY_FAILED(error))
{
DEBUGLOG("PartyNetwork(0x%p)::GetInvitations failed! (error=0x%x)", network, error);
return;
}
for (uint32_t i = 0; i < invitationCount; ++i)
{
if (invitations[i] == newInvite)
{
continue; // don't prune the old invitation
}
PartyInvitation* oldInvitation = invitations[i];
error = network->RevokeInvitation(m_localUser, oldInvitation, nullptr);
if (PARTY_FAILED(error))
{
DEBUGLOG("PartyNetwork(0x%p)::RevokeInvitation failed! (err=0x%x)", network, error);
}
}
}
참고 항목
Xbox Live 사용자 ID와 PlayFab 엔터티 ID 간에 변환해야 하므로 둘 사이의 매핑을 빌드하는 것이 좋습니다. 이 작업을 수행하는 방법은 Xbox Live 사용자 ID와 PlayFab 엔터티 ID 간의 매핑을 참조합니다.
Xbox Live 프로필 설정과 동기화 유지하기
PlayFab 파티는 기본적으로 XR-048 프로필 설정 요구 사항을 준수합니다. 라이브러리는 Xbox Live 프로필 설정의 영구 캐시를 유지하지 않습니다. PlayFab 파티 사용에 프로필 설정이 필요한 경우 설정은 Xbox Live로부터 쿼리되고 설정과 관련된 PlayFab 파티 API 개체의 수명 동안 유효하게 유지되지만 개체의 여러 인스턴스에서 유지되지 않습니다.
PlayFab 파티 외부에서 Xbox Live 프로필 설정 데이터를 사용하는 방법에 대한 자세한 내용은 XR-048 기술 설명서를 참조하세요.
플랫폼 멀티 플레이어 참가 흐름 지원하기
Xbox에서 플레이어는 진행 중인 참가 및 플랫폼 초대 기능을 통해 멀티 플레이어 게임에 참가할 수 있습니다. PlayFab 파티는 이러한 플랫폼 기능과 직접 통합되지 않지만 PartyNetworkDescriptor 및 PartyInvitation 개체를 통한 사용을 지원합니다.
PartyNetworkDescriptor 개체는 원격 사용자가 파티 네트워크를 찾아서 연결하는 데 필요한 연결 정보를 제공하며 PartyManager::SerializeNetworkDescriptor을(를) 통해 직렬화할 수 있습니다..
PartyInvitation 개체는 파티 네트워크에 인증하고 가입하는 데 사용되는 ID를 원격 사용자에게 제공합니다. 원격 사용자가 진행 중인 참가 및 플랫폼 초대를 통해 멀티 플레이어 게임에 참가할 수 있도록 하려면 직렬화된 네트워크 설명자 및 파티 초대 식별자를 기존 흐름에 통합합니다. 예제 흐름은 MPSD와 함께 PlayFab 파티 사용 문서에서도 찾을 수 있습니다.
플랫폼 멀티 플레이어 참가 흐름 요구 사항에 대한 자세한 내용은 XR-064 및 XR-124 기술 설명서를 참조하세요.
친구 목록
PlayFab 파티는 플랫폼의 친구 목록과 기본적으로 상호 작용하지 않지만, 멀티 플레이어 게임은 다른 시나리오에 대해 친구 목록을 고려해야 할 수 있습니다. Xbox Live 및 네트워크 간 친구 목록과 상호 작용할 때의 요구 사항 및 지침에 대한 자세한 내용은 다음 설명서를 참조하세요.
Xbox Live 서비스 재시도 정책 및 서비스 액세스 제한 준수
PlayFab 파티는 Xbox Live 도우미 라이브러리 외부에서 Xbox Live 서비스와 직접 상호 작용하지 않습니다. Xbox Live 도우미 라이브러리는 내부적으로 XR-074 및 XR-132에 명시된 관련 Xbox Live 서비스에 대한 재시도 정책 및 액세스 제한을 준수합니다. 또한 Xbox Live 도우미 라이브러리에서 보고한 다음 오류 코드를 통해 이러한 서비스 정책을 준수함으로써 API 장애를 인식할 수 있습니다. PartyXblChatPermissionMaskReason::XboxLiveServiceError and PartyXblStateChangeResult::PartyServiceError.
Xbox Live 도우미 라이브러리 외부에서 이러한 서비스 정책을 준수하는 방법에 대한 자세한 내용은 XR-074 및 XR-132 기술 설명서를 참조하세요.