Objetos de PlayFab Party y sus relaciones

Para usar correctamente la potencia y flexibilidad de la API de PlayFab Party, es fundamental comenzar por comprender los siguientes objetos cruciales definidos en su ámbito:

• Dispositivo: una instancia distinta del juego que se ejecuta en un dispositivo físico. Existe un dispositivo local siempre que se está usando la API.
• Usuario: un jugador individual que ha iniciado sesión o, más precisamente, una entidad title_player_account de PlayFab que el juego proporciona a PlayFab Party con fines de autenticación e identificación. Uno o varios usuarios están asociados a un dispositivo determinado.
• Red: una colección protegida de uno o varios dispositivos y sus usuarios autorizados que el juego crea para intercambiar comunicación de chat o de datos. Una red normalmente se alinea con el concepto de sesión multijugador o grupo de chat de un juego.
• Punto de conexión: una abstracción para enviar y recibir datos dentro de una red. Un punto de conexión puede representar un dispositivo, un usuario o cualquier concepto específico del juego que se desee.
• Control de chat: una representación de un usuario específicamente para configurar, originar y dirigir el chat de voz y texto en una o varias redes.

​

Relaciones entre objetos

Como jerarquía conceptual simplificada, las redes contienen dispositivos, que a su vez contienen usuarios, puntos de conexión opcionales y controles de chat opcionales. Por ejemplo: Aunque es lo suficientemente sencillo de entender, el diagrama de relaciones anterior es en realidad una representación incompleta de las capacidades de PlayFab Party y puede resultar engañoso si se toma por sí solo. En realidad, la API de Party admite que los dispositivos se conecten a varias redes a la vez. Por ejemplo, podría desearse mantener la comunicación con un grupo de amigos a lo largo del tiempo mientras ese mismo grupo también se une a sesiones de juego más grandes independientes con desconocidos y las abandona. Considerar este escenario más amplio nos permite comprender mejor las relaciones entre estos objetos. Puede parecer intuitivo conceptualizar que un dispositivo pertenece a las redes, pero no es así. Es más correcto entender que los dispositivos participan en las redes. Por ello, la biblioteca de Party solo crea un único objeto de API de dispositivo, ya sea remoto o local, cuando se encuentra una instancia concreta, independientemente del número de redes que comparta con su dispositivo local. Como ejemplo, el siguiente diagrama muestra dos redes y tres dispositivos con usuarios, controles de chat y puntos de conexión. El dispositivo A y sus dos controles de chat (con sus usuarios asociados) participan en la red 1, mientras que los dispositivos B y C se han conectado tanto a la red 1 como a la red 2 con un único control de chat (y un usuario asociado) cada uno. Todos los dispositivos han creado uno o dos puntos de conexión en cada red a la que están conectados: En el diagrama, cada dispositivo ve una única instancia de los tres dispositivos y sus controles de chat, ya que tienen al menos una red en común entre sí. El dispositivo A solo conoce los puntos de conexión 1-4 de la red 1, pero los dispositivos B y C también pueden ver los puntos de conexión 5-7 que crearon en la red 2. Si, en cambio, el dispositivo C solo participa en la red 2 y no en ambas redes, entonces:

• El dispositivo C obviamente no podría crear el punto de conexión 4 en la red 1, ni ver los puntos de conexión 1-3.
• El dispositivo C no conocería el dispositivo A ni sus dos controles de chat presentes solo en la red 1.
• Del mismo modo, el dispositivo A no vería el dispositivo C ni su control de chat presente solo en la red 2.

Sin embargo, el dispositivo B sí seguiría viendo todos los dispositivos y sus controles de chat, ya que sigue estando en ambas redes. Así pues, aunque los dispositivos y los controles de chat están “fuera” de una relación de árbol jerárquico estricta con las redes, es importante tener en cuenta que una instancia de juego nunca encontrará realmente un dispositivo o control de chat remoto sin el contexto de una red que lo acompañe. Si el dispositivo o control de chat local y el remoto tienen al menos una red en común, el objeto remoto puede ser visible. Pero si no hay redes en común, el objeto remoto nunca se creará.

​

Atributos comunes de los objetos

Todos los objetos tienen duraciones bien definidas. Una instancia de juego local crea y destruye cada objeto directamente o mediante mecanismos de notificación estandarizados que solo se señalan durante una ventana de tiempo elegida por el juego. El trabajo con notificaciones se describe con más detalle en un tema posterior. Todos los objetos de la API de PlayFab Party también admiten el concepto de contexto personalizado, que es simplemente una forma de almacenar con el objeto un puntero o valor de “acceso directo” opcional y de ámbito exclusivamente local. Los contextos personalizados facilitan pasar de los objetos de PlayFab Party a los objetos de juego privados correspondientes en memoria (si los hay) sin necesidad de realizar una búsqueda ineficiente. Estos valores no se transmiten de forma remota, ya que los valores de puntero solo tienen significado para la instancia de juego local. Por último, todos los objetos anteriores excepto la red tienen un subobjeto “Local” especializado que contiene métodos y propiedades que solo están disponibles para el dispositivo local propietario del objeto. Por ejemplo, hay un objeto base PartyEndpoint que se usa para representar cualquier punto de conexión local o remoto, y un objeto más específico PartyLocalEndpoint que se puede recuperar mediante PartyEndpoint::GetLocal() solo si ese punto de conexión fue creado realmente por el dispositivo local. Aquí es donde se expone el método PartyLocalEndpoint::SendMessage() para transmitir datos del juego, ya que no tendría sentido que un dispositivo pudiera transmitir de algún modo datos desde los puntos de conexión de origen de otro dispositivo remoto. Cuando se usa la interfaz de C++ de PlayFab Party (recomendada), los objetos se exponen como instancias de clase de C++. Cuando se usa la interfaz plana de C, los objetos se representan mediante valores de identificador.

​

Los roles de todos los objetos principales con más detalle

1. Administrador (PartyManager)
2. Red (PartyNetwork)
3. Dispositivo (PartyDevice y PartyLocalDevice)
4. Usuario (identificadores de entidad de usuario y PartyLocalUser)
5. Punto de conexión (PartyEndpoint y PartyLocalEndpoint)
6. Control de chat (PartyChatControl y PartyLocalChatControl)
7. Cambio de estado (PartyStateChange)

​

Administrador

Además de los objetos resumidos anteriormente, la API de PlayFab Party también expone un objeto singleton de nivel superior PartyManager. Este objeto de utilidad u organizativo se usa en gran medida como punto de partida para comenzar a trabajar con los demás objetos. El administrador es donde se crean inicialmente las nuevas redes y los usuarios locales, por ejemplo. Todas las finalizaciones de operaciones asincrónicas y las notificaciones también se centralizan aquí. En lo más fundamental, el administrador es donde la propia biblioteca de PlayFab Party se inicializa antes de su uso y se limpia cuando ya no se necesita.

​

Red

Un objeto PartyNetwork representa una colección protegida de dispositivos participantes, sus usuarios autorizados y cualquier punto de conexión o control de chat que los acompañe. Las redes se crean inicialmente vacías, pero los dispositivos se conectan a ellas y autentican al menos un usuario local en la red. Las redes que no tienen usuarios autenticados se destruyen automáticamente después de un tiempo de espera. Para conectarse a ellas, las redes se referencian mediante descriptores de red. Los descriptores de red son estructuras binarias en gran medida opacas que contienen la información que PlayFab Party necesita internamente para identificar y localizar la red. La API proporciona métodos para serializar las estructuras en cadenas compatibles con servicios web y viceversa, de modo que puedan intercambiarse con otros dispositivos mediante mecanismos comunes de invitación de plataformas sociales, PlayFab Matchmaking u otros mecanismos de encuentro externos fuera del ámbito de PlayFab Party. Incluso con un descriptor de red, el acceso a una red está restringido a los usuarios autorizados. Esta autorización de usuarios se realiza durante la creación de la red y mediante la creación y revocación posteriores de invitaciones, como se describe con más detalle en el tema Invitaciones y el modelo de seguridad. Los juegos pueden optar por usar invitaciones para restringir la entrada solo a los amigos de los usuarios, o para evitar que jugadores malintencionados se unan a la red. Los dispositivos pueden conectarse a más de una red a la vez. Puede obtener más información sobre si conviene usar varias redes y cómo hacerlo en un tema posterior. Los tipos de acciones que se pueden realizar en los objetos PartyNetwork incluyen autenticar usuarios locales en ella, conectar y enumerar controles de chat, crear y enumerar puntos de conexión, u obtener información de rendimiento de toda la red.

​

Dispositivo

El objeto PartyDevice representa una instancia distinta del juego y su código de biblioteca de PlayFab Party ejecutándose en un dispositivo físico. La mayoría de las operaciones no se realizan sobre los propios objetos PartyDevice; más bien son un mecanismo organizativo para definir qué puntos de conexión o controles de chat pertenecen a esa instancia de juego, en particular para las plataformas y juegos que admiten más de un usuario local simultáneamente. PlayFab Party usa este conocimiento de las relaciones para optimizar la transmisión de datos de juego y chat enviando una sola copia de un mensaje aunque varios destinos del dispositivo necesiten recibirlo, por ejemplo. Los objetos PartyDevice remotos son “subproductos” de conectarse a una red y autenticar a un usuario en esa red. Solo se crean cuando usuarios remotos válidos y autenticados asociados al dispositivo participan en una red a la que también está conectado el dispositivo local. En consecuencia, también se destruyen cuando eso deja de ser cierto. Por otro lado, el subobjeto especializado PartyLocalDevice siempre está disponible para que la instancia de juego local lo referencie mientras PlayFab Party esté inicializado. Nunca se crea ni se destruye explícitamente.

​

Usuario

Un usuario de PlayFab Party es un jugador humano único para quien el juego realiza un inicio de sesión de jugador de PlayFab para adquirir un identificador de entidad title_player_account y un token. Los usuarios remotos se identifican dentro de la API de PlayFab Party únicamente por su cadena de identificador de entidad asociada a los controles de chat y, opcionalmente, a los puntos de conexión. No se representan mediante un objeto dedicado. Esto se debe a que PlayFab Party no tiene funcionalidad que interactúe de forma significativa con usuarios arbitrarios, aparte de la identificación básica y como etiqueta asociada a esos otros objetos. Por el contrario, para los usuarios locales existen objetos PartyLocalUser explícitos, ya que los juegos son propietarios de la administración de sus duraciones dentro de PlayFab Party. Normalmente, el juego creará un PartyLocalUser cuando el juego haya iniciado sesión correctamente con ese jugador de PlayFab mediante el método de inicio de sesión aplicable, y destruirá el PartyLocalUser según corresponda cuando ese usuario cierre sesión. Para las plataformas y juegos que admiten varios jugadores locales con sesión iniciada, deben crearse objetos PartyLocalUser adicionales para cada jugador. Los objetos PartyLocalUser también son importantes porque son la base de toda la autenticación. Debe existir un usuario local válido para poder crear una nueva red o autenticarse en una. La autorización de usuarios se describe con más detalle en el tema que trata las invitaciones y el modelo de seguridad. Casi todas las operaciones requieren que se proporcione o esté presente un PartyLocalUser, aunque muy pocas operaciones se realizan sobre los propios objetos PartyLocalUser. Los objetos PartyLocalUser se crean mediante el objeto PartyManager. Solo pueden ser destruidos explícitamente por sus creadores. Aunque no tienen una representación directa como objeto en los dispositivos remotos, los controles de chat y los puntos de conexión asociados a ellos se destruirán si el dispositivo propietario quita el PartyLocalUser o se desconecta de la red, ya sea de forma correcta o no.

​

Punto de conexión

Los objetos PartyEndpoint son opcionales, pero son el núcleo de la comunicación de datos de PlayFab Party para los juegos que los aprovechan. Al igual que los sockets de red típicos, los puntos de conexión son un mecanismo de direccionamiento abstracto para originar o dirigir mensajes de datos dentro de una red. Podrían representar un dispositivo, un usuario individual o cualquier concepto arbitrario definido por el juego (por ejemplo, una unidad de tanque) que quiera identificar de forma única para enviar y recibir mensajes. El subobjeto especializado PartyLocalEndpoint es para los puntos de conexión creados en la red por la instancia de juego local. Aquí es donde reside la mayor parte de la funcionalidad de los puntos de conexión. Su método PartyLocalEndpoint::SendMessage() transmite cargas de datos del juego desde el PartyLocalEndpoint a uno o varios objetos PartyEndpoint de la misma red. Proporciona varias opciones para seleccionar la mejor forma de gestionar la pérdida de paquetes de Internet (por ejemplo, garantizar la entrega o el orden), para controlar el equilibrio entre una latencia baja y la fusión de varios mensajes del mismo punto de conexión local o de otros para reducir el uso de ancho de banda, y para reaccionar cuando la calidad de la conexión no es suficiente para soportar el ritmo al que el juego está enviando. Además de ser en sí mismo un origen o destino de mensajes de datos, a cada objeto PartyEndpoint PlayFab Party también le asigna un identificador único de punto de conexión de 16 bits que le permite referenciar el punto de conexión específico en las cargas de mensajes enviadas hacia o desde objetos PartyEndpoint independientes dentro de la red. Esto proporciona una forma cómoda de evitar la sobrecarga de enviar una cadena completa y más grande de identificador de entidad de usuario u otro identificador que pudiera representar, por ejemplo, sin tener que crear su propia negociación de acuerdo de identidad entre pares. Los objetos PartyLocalEndpoint se crean mediante el objeto PartyNetwork que los contiene. Al hacerlo, se crean los objetos PartyEndpoint correspondientes en los dispositivos remotos. Un punto de conexión puede ser destruido explícitamente por su creador, o se destruirá implícitamente cuando el dispositivo propietario se desconecte de la red o cuando el objeto PartyLocalUser asociado (si se había especificado uno) se quite de la red.

​

Control de chat

Los objetos PartyChatControl son el mecanismo para usar las características opcionales de comunicación de chat de PlayFab Party. Representan los dispositivos de entrada/salida de audio asociados, las preferencias y las directivas de comunicación de un usuario concreto. El subobjeto especializado PartyLocalChatControl también está disponible para los controles de chat creados por la instancia de juego local. Aquí es donde se configuran los permisos que permiten la comunicación de chat hacia o desde objetos PartyChatControl remotos, por ejemplo, para elegir entre chat de toda la red o solo de equipo, o para aplicar restricciones de directivas de plataforma. Los controles de chat locales se usan para enviar texto de chat, sintetizar texto a voz, solicitar transcripciones y traducciones de secuencias de voz, silenciar y más. Los objetos PartyLocalChatControl deben estar conectados a una red antes de que se creen como objetos PartyChatControl en los dispositivos remotos de esa misma red. Un dispositivo siempre verá creado un único objeto PartyChatControl representativo, incluso cuando ese dispositivo y el control de chat se hayan conectado a más de una red en común. Esto ayuda a evitar la duplicación o interrupción innecesarias de los mensajes de chat de audio y texto. Los objetos PartyLocalChatControl se crean mediante el objeto PartyLocalDevice que los contiene. Un control de chat puede ser destruido explícitamente por su creador, o se destruirá implícitamente cuando el dispositivo propietario se desconecte de la red o cuando el objeto PartyLocalUser asociado se quite de la red.

​

Cambio de estado

Las estructuras PartyStateChange se usan para informar al juego de todas las finalizaciones de operaciones asincrónicas, mensajes entrantes, notificaciones de actualización y otros eventos relacionados con la API. Para simplificar el trabajo con interacciones complejas entre varias máquinas a través de Internet con tiempos impredecibles, PlayFab Party garantiza que no modificará ningún estado que notifique desde la API salvo como resultado de una llamada explícita del juego. Pero como sigue necesitando una forma de conocer las operaciones iniciadas de forma remota o los sucesos no planificados que modifican el estado local, PlayFab Party y el juego cooperan mediante un par de métodos especiales, PartyManager::StartProcessingStateChanges() y PartyManager::FinishProcessingStateChanges(). Estos se llaman en un punto del bucle de trabajo del juego en el que resulte conveniente gestionar dichas actualizaciones. Los nuevos eventos se notifican desde PartyManager::StartProcessingStateChanges() como una matriz de cero o más estructuras PartyStateChange. Una vez que el juego ha gestionado los cambios de estado, la matriz se devuelve mediante PartyManager::FinishProcessingStateChanges(). La estructura PartyStateChange no es un objeto completo por sí misma. Es un encabezado base que debe convertirse a una estructura más detallada que contiene información sobre el tipo específico de finalización o notificación, punteros a los objetos relevantes y cualquier información de error. El trabajo con los cambios de estado se describe con todo detalle en un tema posterior.

​

Pasos siguientes

• Obtenga información sobre las invitaciones de PlayFab Party y el modelo de seguridad
• Aprenda cómo interactúa PlayFab Party con sus flujos de detección
• Obtenga más información sobre la comunicación de chat de PlayFab Party
• Vea cómo trabajar con operaciones asincrónicas y notificaciones en PlayFab Party