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