Objetos do PlayFab Party e suas relações

Aproveitar com sucesso o poder e a flexibilidade da API do PlayFab Party começa com a compreensão dos seguintes objetos essenciais definidos em seu escopo:

• Dispositivo - Uma instância distinta do jogo em execução em um dispositivo físico. Um dispositivo local existe sempre que a API está sendo usada.
• Usuário - Um jogador individual conectado ou, mais precisamente, uma entidade title_player_account do PlayFab que o jogo fornece ao PlayFab Party para fins de autenticação e identificação. Um ou mais usuários são associados a um determinado dispositivo.
• Rede - Um conjunto protegido de um ou mais dispositivos e seus usuários autorizados que o jogo cria para trocar comunicação de chat ou de dados. Uma rede normalmente corresponde ao conceito de sessão multijogador ou de grupo de chat de um jogo.
• Ponto de extremidade - Uma abstração para enviar e receber dados dentro de uma rede. Um ponto de extremidade pode representar um dispositivo, um usuário ou qualquer conceito específico do jogo desejado.
• Controle de chat - Uma representação de um usuário especificamente para configurar, originar e direcionar o chat de voz e de texto em uma ou mais redes.

​

Relações entre objetos

Como uma hierarquia conceitual simplificada, as redes contêm dispositivos, que, por sua vez, contêm usuários, pontos de extremidade opcionais e controles de chat opcionais. Por exemplo: Embora seja simples de entender, o diagrama de relações anterior é, na verdade, uma representação incompleta dos recursos do PlayFab Party e pode ser enganoso se considerado isoladamente. Na realidade, a API do Party dá suporte a dispositivos que se conectam a várias redes ao mesmo tempo. Por exemplo, pode-se desejar manter a comunicação com um grupo de amigos ao longo do tempo enquanto esse mesmo grupo também entra e sai de sessões de jogo maiores e separadas com desconhecidos. Considerar esse cenário mais amplo nos permite compreender melhor as relações entre esses objetos. Pode parecer intuitivo conceituar um dispositivo como pertencente a redes, mas esse não é o caso. É mais correto entender que os dispositivos participam das redes. Dessa forma, a biblioteca do Party só cria um único objeto de API de dispositivo, seja remoto ou local, quando uma determinada instância é encontrada, independentemente do número de redes que ele compartilha com o seu dispositivo local. Como exemplo, o diagrama a seguir mostra duas redes e três dispositivos com usuários, controles de chat e pontos de extremidade. O Dispositivo A e seus dois controles de chat (com os usuários associados) participam da Rede 1, enquanto os Dispositivos B e C se conectaram tanto à Rede 1 quanto à Rede 2 com um único controle de chat (e usuário associado) cada. Todos os dispositivos criaram um ou dois pontos de extremidade em cada rede à qual estão conectados: No diagrama, cada dispositivo vê uma única instância de todos os três dispositivos e de seus controles de chat, pois eles têm pelo menos uma rede em comum entre si. O Dispositivo A só conhece os Pontos de extremidade 1 a 4 na Rede 1, mas os Dispositivos B e C também podem ver os Pontos de extremidade 5 a 7 que criaram na Rede 2. Se, em vez disso, o Dispositivo C participar apenas da Rede 2 e não de ambas as redes:

• Obviamente, o Dispositivo C não poderia criar o Ponto de extremidade 4 na Rede 1, nem ver os Pontos de extremidade 1 a 3.
• O Dispositivo C não saberia da existência do Dispositivo A nem de seus dois controles de chat que estão apenas na Rede 1.
• Da mesma forma, o Dispositivo A não veria o Dispositivo C nem seu controle de chat que está apenas na Rede 2.

O Dispositivo B, no entanto, ainda veria todos os dispositivos e seus controles de chat, pois ainda está em ambas as redes. Portanto, apesar de os dispositivos e os controles de chat estarem “fora” de uma relação de árvore hierárquica estrita com as redes, é importante observar que uma instância de jogo nunca encontrará de fato um dispositivo ou controle de chat remoto sem o contexto de uma rede correspondente. Se o dispositivo ou controle de chat local e o remoto tiverem pelo menos uma rede em comum, o objeto remoto poderá ficar visível. Mas, se não houver redes em comum, o objeto remoto nunca será criado.

​

Atributos comuns dos objetos

Todos os objetos têm tempos de vida bem definidos. Uma instância de jogo local cria e destrói cada objeto diretamente ou por meio de mecanismos de notificação padronizados que só são sinalizados durante uma janela de tempo escolhida pelo jogo. O trabalho com notificações é descrito com mais detalhes em um tópico posterior. Todos os objetos da API do PlayFab Party também dão suporte ao conceito de contexto personalizado, que é simplesmente uma forma de armazenar um ponteiro ou valor de “atalho” opcional, somente local, com o objeto. Os contextos personalizados facilitam ir dos objetos do PlayFab Party de volta aos objetos privados correspondentes do seu jogo na memória (se houver), sem precisar realizar uma pesquisa ineficiente. Esses valores não são transmitidos remotamente, pois os valores de ponteiro só têm significado para a instância de jogo local. Por fim, todos os objetos acima, exceto a rede, têm um subobjeto “Local” especializado que contém métodos e propriedades disponíveis apenas para o dispositivo local que é dono do objeto. Por exemplo, há um objeto base PartyEndpoint usado para representar qualquer ponto de extremidade local ou remoto, e um objeto mais específico PartyLocalEndpoint que pode ser recuperado por meio de PartyEndpoint::GetLocal() somente se esse ponto de extremidade tiver sido de fato criado pelo dispositivo local. É aqui que o método PartyLocalEndpoint::SendMessage() para transmitir dados de jogo é exposto, pois não faria sentido um dispositivo poder, de alguma forma, transmitir dados a partir dos pontos de extremidade de origem de outro dispositivo remoto. Ao usar a interface C++ do PlayFab Party (recomendada), os objetos são expostos como instâncias de classes C++. Ao usar a interface C simples, os objetos são representados por valores de identificador.

​

As funções de todos os principais objetos em mais detalhes

1. Gerenciador (PartyManager)
2. Rede (PartyNetwork)
3. Dispositivo (PartyDevice e PartyLocalDevice)
4. Usuário (IDs de entidade de usuário e PartyLocalUser)
5. Ponto de extremidade (PartyEndpoint e PartyLocalEndpoint)
6. Controle de chat (PartyChatControl e PartyLocalChatControl)
7. Alteração de estado (PartyStateChange)

​

Gerenciador

Além dos objetos resumidos anteriormente, a API do PlayFab Party também expõe um objeto singleton de nível superior, PartyManager. Esse objeto utilitário/organizacional é usado principalmente como ponto de partida para começar a trabalhar com os outros objetos. É no Gerenciador que novas redes e usuários locais são criados inicialmente, por exemplo. Todas as conclusões de operações assíncronas e notificações também são centralizadas aqui. Fundamentalmente, é no gerenciador que a própria biblioteca do PlayFab Party é inicializada antes do uso e limpa quando não é mais necessária.

​

Rede

Um objeto PartyNetwork representa um conjunto protegido de dispositivos participantes, seus usuários autorizados e quaisquer pontos de extremidade ou controles de chat correspondentes. As redes são criadas inicialmente vazias, mas os dispositivos se conectam a elas e autenticam pelo menos um usuário local na rede. As redes que não têm nenhum usuário autenticado são destruídas automaticamente após um tempo limite. Para que seja possível se conectar a elas, as redes são referenciadas usando descritores de rede. Os descritores de rede são estruturas binárias em grande parte opacas que contêm as informações de que o PlayFab Party precisa internamente para identificar e localizar a rede. A API fornece métodos para serializar as estruturas em cadeias de caracteres adequadas para serviços Web e vice-versa, para que possam ser trocadas com outros dispositivos usando mecanismos comuns de convite de plataformas sociais, o PlayFab Matchmaking ou outros mecanismos externos de encontro fora do escopo do próprio PlayFab Party. Mesmo com um descritor de rede, o acesso a uma rede é restrito a usuários autorizados. Essa autorização de usuários é feita durante a criação da rede e por meio da criação e revogação subsequentes de convites, conforme descrito com mais detalhes no tópico Convites e o modelo de segurança. Os jogos podem optar por usar convites para restringir a entrada apenas aos amigos dos usuários ou para impedir que jogadores mal-intencionados ingressem na rede. Os dispositivos podem se conectar a mais de uma rede ao mesmo tempo. Você pode saber mais sobre se e como usar várias redes em um tópico posterior. Os tipos de ações que podem ser realizadas em objetos PartyNetwork incluem autenticar usuários locais na rede, conectar e enumerar controles de chat, criar e enumerar pontos de extremidade ou obter informações de desempenho de toda a rede.

​

Dispositivo

O objeto PartyDevice representa uma instância distinta do jogo e do código da biblioteca do PlayFab Party em execução em um dispositivo físico. A maioria das operações não é realizada nos próprios objetos PartyDevice; em vez disso, eles são um mecanismo organizacional para definir quais pontos de extremidade ou controles de chat pertencem a essa instância do jogo, especialmente em plataformas e jogos que dão suporte a mais de um usuário local simultaneamente. O PlayFab Party usa esse conhecimento das relações para otimizar a transmissão de dados de jogo e de chat, enviando, por exemplo, apenas uma cópia de uma mensagem mesmo que vários destinos no dispositivo precisem recebê-la. Os objetos PartyDevice remotos são “subprodutos” da conexão a uma rede e da autenticação de um usuário nessa rede. Eles só são criados quando usuários remotos válidos e autenticados associados ao dispositivo estão participando de uma rede à qual o dispositivo local também está conectado. Da mesma forma, eles são destruídos quando isso deixa de ser verdade. Por outro lado, o subobjeto especializado PartyLocalDevice está sempre disponível para ser referenciado pela instância de jogo local enquanto o PlayFab Party estiver inicializado. Ele nunca é criado ou destruído explicitamente.

​

Usuário

Um usuário do PlayFab Party é um jogador humano exclusivo para o qual o jogo realiza um Login de jogador do PlayFab para obter uma ID de entidade title_player_account e um token. Os usuários remotos são identificados na API do PlayFab Party apenas pela cadeia de caracteres da ID de entidade associada aos controles de chat e, opcionalmente, aos pontos de extremidade. Eles não são representados por um objeto dedicado. Isso ocorre porque o PlayFab Party não tem funcionalidades que interajam de forma significativa com usuários arbitrários, exceto para identificação bruta e como um rótulo associado a esses outros objetos. Por outro lado, para os usuários locais, há objetos PartyLocalUser explícitos, pois os jogos são responsáveis pelo gerenciamento do tempo de vida deles no PlayFab Party. O jogo normalmente criará um PartyLocalUser quando tiver conectado com êxito esse jogador do PlayFab usando o método de login aplicável e destruirá o PartyLocalUser conforme apropriado quando esse usuário se desconectar. Em plataformas e jogos que dão suporte a vários jogadores locais conectados, objetos PartyLocalUser adicionais devem ser criados para cada jogador. Os objetos PartyLocalUser também são importantes porque são a base de toda a autenticação. Um usuário local válido deve existir para criar uma nova rede ou para se autenticar em uma. A autorização de usuários é descrita com mais detalhes no tópico sobre Convites e o modelo de segurança. Quase todas as operações exigem que um PartyLocalUser seja fornecido ou esteja presente, embora pouquíssimas operações sejam realizadas nos próprios objetos PartyLocalUser. Os objetos PartyLocalUser são criados usando o objeto PartyManager. Eles só podem ser destruídos explicitamente por seus criadores. Embora não tenham representação direta como objeto nos dispositivos remotos, os controles de chat e os pontos de extremidade associados a eles serão destruídos se o dispositivo proprietário remover o PartyLocalUser ou se desconectar da rede, de forma normal ou não.

​

Ponto de extremidade

Os objetos PartyEndpoint são opcionais, mas são o núcleo da comunicação de dados do PlayFab Party para os jogos que os utilizam. Assim como os soquetes de rede típicos, os pontos de extremidade são um mecanismo de endereçamento abstrato para originar ou direcionar mensagens de dados dentro de uma rede. Eles podem representar um dispositivo, um usuário individual ou qualquer conceito arbitrário definido pelo jogo (por exemplo, uma unidade de tanque) que você queira identificar de forma exclusiva para enviar e receber mensagens. O subobjeto especializado PartyLocalEndpoint destina-se aos pontos de extremidade criados na rede pela instância de jogo local. É nele que reside a maior parte da funcionalidade dos pontos de extremidade. Seu método PartyLocalEndpoint::SendMessage() transmite cargas de dados de jogo do PartyLocalEndpoint para um ou mais outros objetos PartyEndpoint na mesma rede. Ele fornece várias opções para selecionar a melhor forma de lidar com a perda de pacotes na Internet (por exemplo, garantir a entrega e/ou a ordenação), para controlar o equilíbrio entre baixa latência e a combinação de várias mensagens do mesmo ponto de extremidade local ou de outros para reduzir o uso de largura de banda, e para reagir quando a qualidade da conexão não for suficiente para suportar a taxa em que o jogo está enviando. Além de ser uma origem ou um destino de mensagens de dados, cada objeto PartyEndpoint também recebe do PlayFab Party um identificador exclusivo de ponto de extremidade de 16 bits, que permite referenciar o ponto de extremidade específico em cargas de mensagens enviadas para ou de objetos PartyEndpoint separados na rede. Isso oferece uma forma conveniente de evitar a sobrecarga de enviar uma cadeia de caracteres completa e maior de ID de entidade de usuário ou outro identificador que ele possa representar, por exemplo, sem precisar criar sua própria negociação de acordo de identidade ponto a ponto. Os objetos PartyLocalEndpoint são criados usando o objeto PartyNetwork que os contém. Isso faz com que objetos PartyEndpoint correspondentes sejam criados nos dispositivos remotos. Um ponto de extremidade pode ser destruído explicitamente por seu criador ou será destruído implicitamente quando o dispositivo proprietário se desconectar da rede ou quando o objeto PartyLocalUser associado (se algum tiver sido especificado) for removido da rede.

​

Controle de chat

Os objetos PartyChatControl são o mecanismo para usar os recursos opcionais de comunicação por chat do PlayFab Party. Eles representam os dispositivos de entrada/saída de áudio, as preferências e as políticas de comunicação associados a um determinado usuário. O subobjeto especializado PartyLocalChatControl também está disponível para os controles de chat criados pela instância de jogo local. É nele que você configura as permissões que permitem a comunicação por chat de ou para objetos PartyChatControl remotos, por exemplo, para escolher entre chat de toda a rede ou apenas da equipe, ou para aplicar restrições de política da plataforma. Os controles de chat locais são usados para enviar texto de chat, sintetizar texto em fala, solicitar transcrições e traduções de fluxos de voz, silenciar e muito mais. Os objetos PartyLocalChatControl precisam estar conectados a uma rede antes de serem criados como objetos PartyChatControl nos dispositivos remotos dessa mesma rede. Um dispositivo sempre verá apenas um único objeto PartyChatControl representativo criado, mesmo quando esse dispositivo e o controle de chat estiverem conectados a mais de uma rede em comum. Isso ajuda a evitar duplicação ou interrupção desnecessária das mensagens de chat de áudio e de texto. Os objetos PartyLocalChatControl são criados usando o objeto PartyLocalDevice que os contém. Um controle de chat pode ser destruído explicitamente por seu criador ou será destruído implicitamente quando o dispositivo proprietário se desconectar da rede ou quando o objeto PartyLocalUser associado for removido da rede.

​

Alteração de estado

As estruturas PartyStateChange são usadas para informar o jogo sobre todas as conclusões de operações assíncronas, mensagens recebidas, notificações de atualização e outros eventos relacionados à API. Para simplificar o trabalho com interações complexas entre várias máquinas pela Internet com tempos imprevisíveis, o PlayFab Party garante que não modificará nenhum estado relatado pela API, exceto como resultado de uma chamada explícita do jogo. Mas, como você ainda precisa de uma forma de saber sobre operações iniciadas remotamente ou ocorrências não planejadas que modificam o estado local, o PlayFab Party e o jogo cooperam por meio de um par especial de métodos, PartyManager::StartProcessingStateChanges() e PartyManager::FinishProcessingStateChanges(). Eles são chamados em um ponto do loop de trabalho do jogo em que seja conveniente lidar com essas atualizações. Os novos eventos são relatados por PartyManager::StartProcessingStateChanges() como uma matriz de zero ou mais estruturas PartyStateChange. Depois que o jogo tiver tratado as alterações de estado, a matriz é devolvida usando PartyManager::FinishProcessingStateChanges(). A estrutura PartyStateChange não é um objeto completo por si só. É um cabeçalho base que deve ser convertido em uma estrutura mais detalhada que contém informações sobre o tipo específico de conclusão ou notificação, ponteiros para os objetos relevantes e quaisquer informações de erro. O trabalho com alterações de estado é descrito em detalhes em um tópico posterior.

​

Próximas etapas

• Saiba mais sobre os convites do PlayFab Party e o modelo de segurança
• Saiba como o PlayFab Party interage com seus fluxos de descoberta
• Saiba mais sobre a comunicação por chat do PlayFab Party
• Veja como trabalhar com operações assíncronas e notificações no PlayFab Party