PlayFab Party 개체 및 해당 관계
PlayFab Party API의 강력한 기능과 유연성을 사용하려면 해당 범위에 정의된 다음과 같은 중요한 개체를 이해해야 합니다.
- 장치 - 물리적 장치에서 실행되는 게임의 고유한 인스턴스입니다. 로컬 장치는 API를 사용할 때마다 존재합니다.
- 사용자 - 로그인한 개별 플레이어 또는 더 정확히 말하면 게임에서 인증 및 식별을 위해 PlayFab Party에 적극적으로 제공한 PlayFab
title_player_account엔터티입니다. 한 명 이상의 사용자가 지정된 장치와 연결되어 있습니다. - 네트워크 - 채팅 또는 데이터 통신을 교환하기 위해 게임에서 만드는 하나 이상의 장치와 해당 인증된 사용자의 보안 컬렉션입니다. 이는 일반적으로 게임의 멀티 플레이어 세션 또는 채팅 파티 개념과 일치합니다.
- 엔드포인트 - 네트워크 내에서 데이터를 보내고 받는 작업의 추상적 개념입니다. 엔드포인트는 장치, 사용자 또는 원하는 게임별 개념을 나타낼 수 있습니다.
- 채팅 컨트롤 - 특별히 하나 이상의 네트워크에서 음성 및 텍스트 채팅을 구성하고 시작 및 대상으로 지정하기 위한 사용자의 표현입니다.
개체 관계
간단한 개념적 계층 구조의 경우, 네트워크에 장치가 포함되고, 이는 사용자, 선택적 엔드포인트 및 선택적 채팅 컨트롤을 차례로 포함합니다. 예:
이해하기는 쉽지만, 위의 관계 다이어그램은 실제로는 PlayFab Party의 기능을 불완전하게 보여 주는 것으로, 자의적으로 간주하면 오해의 소지가 있을 수 있습니다. 실제로, Party API는 여러 네트워크에 한 번에 연결하는 장치를 지원합니다. 예를 들어, 친구 그룹이 별도의 더 큰 게임 세션에 참여하고 해당 세션을 떠날 때 시간이 지남에 따라 동일한 그룹과의 통신을 유지하려고 할 수 있습니다. 이 포괄적인 시나리오를 고려하면 해당 개체 간의 관계를 더 잘 이해할 수 있습니다.
네트워크에 속하는 장치를 개념화하는 것은 직관적일 수 있지만, 이는 그렇지 않습니다. 장치가 네트워크에 참여함을 인식하는 것이 더 정확합니다. 따라서 로컬 장치와 공유하는 네트워크 수에 관계없이 특정 인스턴스가 발견되면 원격 또는 로컬에 관계없이 Party 라이브러리에서 단일 장치 API 개체만 만듭니다.
예를 들어, 다음 다이어그램에서는 사용자, 채팅 컨트롤 및 엔드포인트가 있는 두 개의 네트워크와 세 개의 장치를 보여 줍니다. 장치 A 및 두 개의 채팅 컨트롤(연결된 사용자 포함)이 네트워크 1에 참여하는 반면에, 장치 B 및 C는 해당 네트워크에 연결하고 각각 단일 채팅 컨트롤(및 연결된 사용자)을 사용하여 네트워크 2에 연결했습니다. 모든 장치에서 연결된 각 네트워크에 하나 또는 두 개의 엔드포인트를 만들었습니다.
위의 다이어그램에서, 모든 장치는 서로 공통된 네트워크가 하나 이상 있으므로 모든 장치에서 세 장치와 해당 장치의 채팅 컨트롤에 대한 단일 인스턴스를 볼 수 있습니다. 장치 A는 네트워크 1의 엔드포인트 1~4에 대해서만 알고 있지만, 장치 B 및 C는 네트워크 2에서 만든 엔드포인트 5~7도 볼 수 있습니다.
위의 다이어그램에서 장치 C가 대신 네트워크 2에 참여했으며 두 네트워크 모두에 참여하지 않은 경우, 다음을 수행합니다.
- 장치 C는 네트워크 1에서 엔드포인트 4를 만들 수도 없었고 다른 장치가 그 안에 만든 엔드포인트 1~3도 볼 수 없었을 것입니다.
- 장치 C는 네트워크 1에만 있는 장치 A 또는 해당하는 두 채팅 컨트롤에 대해서 모를 것입니다.
- 마찬가지로 장치 A에 네트워크 2에만 있는 장치 C 또는 해당하는 채팅 컨트롤이 표시되지 않을 것입니다.
그러나 모든 장치와 해당하는 채팅 컨트롤이 여전히 두 네트워크에 있으므로 장치 B에서 계속 표시됩니다.
따라서 장치와 채팅 컨트롤이 네트워크와의 엄격한 계층적 트리 관계 "외부"에 있는 경우에도, 게임 인스턴스는 함께 제공되는 네트워크의 컨텍스트 없이는 실제로 원격 장치 또는 채팅 컨트롤을 만나지 않는다는 점에 유의해야 합니다. 로컬 및 원격 장치 또는 채팅 컨트롤에 공통된 네트워크가 하나 이상 있는 경우, 원격 개체가 표시될 수 있습니다. 그러나 공통 네트워크가 없으면 원격 개체가 만들어지지 않습니다.
참고 항목
PlayFab Party를 사용하기 위해 게임은 둘 이상의 네트워크에 동시에 연결할 필요가 없습니다. 차후의 고급 항목에서 여러 네트워크의 사용 여부와 사용 방법에 대해 자세히 알아볼 수 있습니다.
공통 개체 특성
위의 모든 개체에는 잘 정의된 수명이 있습니다. 각각은 로컬 게임 인스턴스에서 직접 생성되고 제거되거나, 게임 선택 기간 동안에만 신호를 받는 표준화된 알림 메커니즘을 사용하여 생성되고 제거됩니다. 알림 작업에 대한 자세한 내용은 이후 항목에 설명되어 있습니다.
모든 PlayFab Party API 개체는 사용자 지정 컨텍스트 개념도 지원하며, 이는 단순히 선택적 로컬 전용 "바로 가기" 포인터 또는 값을 개체와 함께 저장하는 방법입니다. 이렇게 하면 비효율적인 조회를 수행할 필요 없이 PlayFab Party 개체에서 메모리의 해당 개인 게임 개체(있는 경우)로 간편하게 이동할 수 있습니다. 포인터 값은 로컬 게임 인스턴스에만 의미가 있으므로 이 값은 원격으로 전송되지 않습니다.
마지막으로, 네트워크를 제외한 위의 모든 개체에는 해당 개체를 소유하는 로컬 장치에서만 사용할 수 있는 메서드와 속성을 포함하는 특수화된 "로컬" 하위 개체가 있습니다.
예를 들어, 로컬 또는 원격 엔드포인트를 나타내는 데 사용되는 기본 PartyEndpoint 개체와 해당 엔드포인트가 실제로 로컬 장치에서 만들어진 경우에만 PartyEndpoint::GetLocal()을(를) 통해 검색할 수 있는 보다 구체적인 PartyLocalEndpoint 개체가 있습니다. 여기서 한 장치가 완전히 다른 원격 장치의 원본 엔드포인트에서 데이터를 전송할 수 없으므로 게임 데이터를 전송하는 PartyLocalEndpoint::SendMessage() 메서드는 노출됩니다.
C++PlayFab Party 인터페이스(권장)를 사용하는 경우, 개체가 C++ 클래스 인스턴스로 노출됩니다. 플랫 C 인터페이스를 사용하는 경우 개체는 핸들 값으로 표시됩니다.
모든 주요 개체의 역할에 대해 자세히 설명합니다.
- 관리자(
PartyManager) - 네트워크(
PartyNetwork) - 장치(
PartyDevice및PartyLocalDevice) - 사용자(사용자 엔터티 ID 및
PartyLocalUser) - 엔드포인트(
PartyEndpoint및PartyLocalEndpoint) - 채팅 컨트롤(
PartyChatControl및PartyLocalChatControl) - 상태 변경(
PartyStateChange)
관리자
이전에 요약된 개체 외에도 PlayFab Party API는 최상위 PartyManager 싱글톤 개체를 노출합니다.
이 유틸리티/조직 개체는 주로 다른 개체로 작업을 시작하기 위한 시작점으로 사용됩니다. 예를 들어, 여기서 새 네트워크 로컬 사용자가 처음 만들어집니다. 모든 비동기 작업 완료 및 알림도 여기에서 중앙 집중화됩니다. 가장 기본적으로, 여기서 PlayFab Party 라이브러리 자체가 사용 전에 초기화되고 더 이상 필요하지 않을 때 정리됩니다.
네트워크
PartyNetwork 개체는 참여하는 장치, 인증된 사용자 및 함께 제공되는 엔드포인트 또는 채팅 컨트롤의 보안 컬렉션을 나타냅니다.
네트워크는 처음에 게임에서 비어 있는 것으로 만들어지지만, 장치가 네트워크에 연결되면 하나 이상의 로컬 사용자를 네트워크에 인증합니다.
인증된 사용자가 없는 네트워크는 시간 제한 초과 후에 자동으로 제거됩니다.
네트워크에 연결하기 위해 네트워크 설명자를 사용하여 네트워크를 참조합니다. 이러한 구조는 PlayFab Party에서 내부적으로 네트워크를 식별하고 찾는 데 필요한 정보를 포함하는 불투명 이진 구조입니다. API는 일반적인 소셜 플랫폼 초대 메커니즘, PlayFab 매치 메이킹 또는 PlayFab Party 자체의 범위를 벗어나는 다른 외부 랑데부 메커니즘을 사용하여 다른 장치와 교환할 수 있도록 구조를 웹 서비스 친화적 문자열로 직렬화하고 다시 직렬화하는 메서드를 제공합니다.
참고 항목
네트워크에 대한 네트워크 설명자가 드물게 변경될 수 있습니다. 게임은 이러한 변경에 대한 알림을 준비한 다음, 추가 장치 연결 문제를 방지하기 위해 기존 네트워크의 새 네트워크 설명자를 업데이트하거나 다시 광고해야 합니다.
네트워크 설명자를 사용할 수 있더라도, 네트워크 대한 액세스 권한은 게임에서 특정 네트워크에 사전에(또는 사용자가 외부에서 관리되는 해당 게임 플레이 세션에 추가된 경우 "적시에") 참여할 수 있는 권한을 부여한 사용자로 제한됩니다. 초대 및 보안 모델 항목에 자세히 설명된 대로, 이 사용자 권한 부여는 네트워크 생성 중에 수행되며 초대의 후속 생성 및 해지 작업을 통해 수행됩니다.
게임은 초대를 사용하여 사용자의 친구로만 가입을 제한하거나 악의적인 플레이어가 네트워크에 참여하지 못하도록 할 수 있습니다.
장치는 한 번에 둘 이상의 네트워크 연결할 수 있습니다. 이후 항목에서 여러 네트워크의 사용 여부와 사용 방법에 대해 자세히 알아볼 수 있습니다.
PartyNetwork 개체에 대해 수행할 수 있는 작업 종류에는 로컬 사용자 인증, 채팅 컨트롤 연결 및 열거, 엔드포인트 생성 및 열거, 네트워크 전체 성능 정보 가져오기 등이 있습니다.
장치
PartyDevice 개체는 게임의 고유한 인스턴스와 물리적 장치에서 실행되는 PlayFab Party 라이브러리 코드를 나타냅니다.
대부분의 작업은 PartyDevice 개체 자체에서 수행되지 않으며, 오히려 특히 둘 이상의 로컬 사용자를 동시에 지원하는 플랫폼과 게임의 경우 해당 게임 인스턴스에 속하는 엔드포인트 또는 채팅 컨트롤을 정의하기 위한 조직 메커니즘입니다.
예를 들어, PlayFab Party는 이 관계 지식을 사용하여 장치의 여러 대상이 수신해야 하는 경우에도 메시지 복사본을 하나만 전송하여 게임 데이터 및 채팅 전송을 최적화합니다.
원격 PartyDevice 개체는 네트워크에 연결하고 해당 네트워크에 사용자를 인증하는 "부산물"입니다.
이는 해당 장치와 연결된 유효하고 인증된 원격 사용자가 로컬 장치가 연결된 네트워크에 참여하는 경우에만 생성됩니다. 따라서, 더 이상 true가 아니면 이는 제거됩니다.
반면에 PartyLocalDevice 특수 하위 개체는 PlayFab Party가 초기화되는 한, 로컬 게임 인스턴스에서 항상 참조할 수 있습니다.
명시적으로 생성되거나 제거되지 않습니다.
사용자
PlayFab 파티 사용자는 게임에서 title_player_account엔터티 ID 및 토큰을 얻기 위해 PlayFab 플레이어 로그인을 수행한 고유한 인간 플레이어입니다.
원격 사용자는 채팅 컨트롤과 연결된 엔터티 ID 문자열로만 PlayFab Party API 내에서 식별되며 필요에 따라 엔드포인트를 사용합니다. 전용 개체를 사용하여 표시되지 않습니다. PlayFab Party에는 원시 식별 및 다른 개체와 연결된 레이블이 아닌, 임의의 사용자와 의미 있게 상호 작용하는 기능이 없기 때문입니다.
반대로, 로컬 사용자의 경우 게임은 PlayFab Party 내에서 수명 관리를 소유하므로 명시적 PartyLocalUser 개체가 있습니다.
게임은 일반적으로 해당 로그인 메서드를 사용하여 PlayFab 플레이어가 로그온한 경우 PartyLocalUser을(를) 만들고, 해당 사용자가 로그오프할 때 적절하게 PartyLocalUser을(를) 삭제합니다.
로그인한 여러 로컬 플레이어를 지원하는 플랫폼 및 게임의 경우, 각 플레이어에 대해 추가 PartyLocalUser 개체를 만들어야 합니다.
PartyLocalUser 개체는 모든 인증의 기반이 되기 때문에 중요합니다. 새 네트워크 만들거나 인증하려면 유효한 로컬 사용자가 있어야 합니다.
사용자 권한 부여는 초대 및 보안 모델을 다루는 항목에 자세히 설명되어 있습니다.
PartyLocalUser 개체 자체에서 거의 작업이 수행되지 않더라도 거의 모든 작업을 수행하려면 PartyLocalUser을(를) 제공하거나 갖추어야 합니다.
PartyLocalUser 개체는 PartyManager 개체를 사용하여 생성됩니다.
작성자만 명시적으로 이를 제거할 수 있습니다.
원격 장치에는 직접 개체 표현이 없지만, 소유 장치가 정상적으로 또는 다른 방법으로 PartyLocalUser을(를) 제거하거나 네트워크에서 연결을 끊으면 여기에 연결된 채팅 컨트롤과 엔드포인트가 제거됩니다.
엔드포인트
PartyEndpoint 개체는 선택 사항이지만 이를 활용하는 게임에 대한 PlayFab 파티 데이터 통신의 핵심입니다.
일반적인 네트워킹 소켓과 마찬가지로, 엔드포인트는 네트워크내에서 데이터 메시지를 시작하거나 대상으로 지정하기 위한 추상화된 주소 지정 메커니즘입니다.
장치, 개별 사용자 또는 메시지를 보내고 받기 위해 고유하게 식별하는 임의의 게임 정의 개념(예: 탱크 유닛)을 나타낼 수 있습니다.
특수 PartyLocalEndpoint 하위 개체는 로컬 게임 인스턴스에서 네트워크에 만든 엔드포인트에 사용됩니다.
대부분의 엔드포인트 기능이 상주하는 곳입니다.
PartyLocalEndpoint::SendMessage()에서 PartyLocalEndpoint에 있는 게임 데이터 페이로드를 동일한 네트워크에 있는 하나 이상의 다른 PartyEndpoint 개체로 전송합니다.
인터넷 패킷 손실을 처리(예: 배달 및/또는 주문 보장)하고, 낮은 대역폭 사용을 위해 동일하거나 다른 로컬 엔드포인트에서 여러 메시지를 병합하는 것과 짧은 대기 시간 간의 균형을 제어하고, 연결 품질이 게임 전송 속도를 지원하기에 충분하지 않을 때 대응하는 가장 좋은 방법을 선택하도록 다양한 옵션을 제공합니다.
이후 항목에서 엔드포인트를 사용하여 게임 데이터를 전송하는 방법에 대해 자세히 알아볼 수 있습니다.
각 PartyEndpoint 개체는 데이터 메시지 자체의 원본 또는 대상일 뿐 아니라, PlayFab Party에서 16비트 엔드포인트 고유 식별자도 할당하며, 이를 통해 네트워크 내의 별도 PartyEndpoint 개체로 보내거나 여기에서 받는 메시지 페이로드에서 특정 엔드포인트를 참조할 수 있습니다.
예를 들어, 이렇게 하면 사용자 고유의 피어 투 피어 ID 규약 협상을 빌드하지 않고도 더 큰 전체 사용자 엔터티 ID 문자열 또는 기타 식별자를 보내는 오버헤드를 간편하게 방지할 수 있습니다.
PartyLocalEndpoint 개체는 포함하는 PartyNetwork 개체를 사용하여 생성됩니다.
이렇게 하면 해당 PartyEndpoint 개체가 원격 장치에서 만들어집니다.
엔드포인트를 작성자가 명시적으로 제거하거나, 소유 장치가 네트워크에서 연결이 끊기거나 연결된 PartyLocalUser 개체(지정된 경우)가 네트워크에서 제거될 때 암시적으로 제거됩니다.
채팅 컨트롤
PartyChatControl 개체는 PlayFab Party의 선택적 채팅 통신 기능을 사용하기 위한 메커니즘입니다.
특정 사용자의 연결된 오디오 입력/출력 장치, 기본 설정 및 통신 정책을 나타냅니다.
특수 PartyLocalChatControl 하위 개체는 로컬 게임 인스턴스에서 만든 채팅 컨트롤에도 사용할 수 있습니다.
여기에서 원격 PartyChatControl 개체 간 채팅 통신을 허용하는 권한(예: 네트워크 전체 채팅과 팀 전용 채팅을 선택하거나 플랫폼 정책 제한을 적용)을 구성합니다.
로컬 채팅 컨트롤을 사용하여 채팅 텍스트를 보내고, 텍스트를 음성으로 합성하고, 음성 스트림의 전사 및 번역 요청, 음소거 등을 할 수 있습니다.
PartyLocalChatControl 개체는 동일한 네트워크의 원격 장치에서 PartyChatControl 개체로 생성되기 전에 네트워크에 연결되어야 합니다.
장치와 채팅 컨트롤이 공통적으로 둘 이상의 네트워크에 연결되어 경우에도 장치는 항상 단일 대표 PartyChatControl 개체만 생성됩니다.
이렇게 하면 오디오 및 문자 채팅 메시지가 불필요하게 중복되거나 중단되는 것을 방지할 수 있습니다.
PartyLocalChatControl 개체는 포함하는 PartyLocalDevice 개체를 사용하여 생성됩니다.
채팅 컨트롤을 작성자가 명시적으로 제거하거나, 소유 장치가 네트워크에서 연결이 끊기거나 연결된 PartyLocalUser 개체가 네트워크에서 제거될 때 암시적으로 제거됩니다.
상태 변경
PartyStateChange 구조는 모든 비동기 작업 완료, 수신 메시지, 업데이트 알림 및 기타 API 관련 이벤트를 게임에 알리는 데 사용됩니다.
예측할 수 없는 타이밍으로 인터넷을 통해 복잡한 다중 머신 상호 작용을 사용하는 방법을 간소화하기 위해 PlayFab Party는 게임에서 명시적 호출의 결과를 제외하고 API에서 보고하는 상태를 수정하지 않도록 보장합니다.
하지만 로컬 상태를 수정하는 원격으로 시작된 작업 또는 계획되지 않은 발생에 대해 알아보는 방법이 여전히 필요하므로, PlayFab Party와 게임은 특수한 한 쌍의 메서드(PartyManager::StartProcessingStateChanges() 및 PartyManager::FinishProcessingStateChanges())를 통해 협력합니다.
이는 이와 같은 업데이트를 처리하는 것이 편리한 게임 작업 루프의 지점에서 호출됩니다.
새 이벤트는 0개 이상의 PartyStateChange 구조 배열로 PartyManager::StartProcessingStateChanges()에서 보고됩니다.
게임이 상태 변경을 처리하면 PartyManager::FinishProcessingStateChanges()을(를) 사용하여 배열이 반환됩니다.
PartyStateChange 구조 자체는 전체 개체가 아닙니다. 특정 유형의 완료 또는 알림, 관련 개체에 대한 포인터 및 오류 정보를 포함하는 보다 자세한 구조로 캐스팅되는 기본 헤더입니다.
상태 변경에 대한 자세한 내용은 이후 항목에 설명되어 있습니다.