> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Objetos de PlayFab Party y sus relaciones
> Conozca los objetos principales de PlayFab Party, como redes, dispositivos, puntos de conexión y controles de chat, y cómo se relacionan en la comunicación de chat y datos en tiempo real.
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**](#device): 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**](#user): un jugador individual que ha iniciado sesión o, más precisamente, una [entidad](/services/playfab/live-service-management/game-configuration/entities) `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**](#network): 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**](#endpoint): 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**](#chat-control): 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](#network) contienen [dispositivos](#device), que a su vez contienen [usuarios](#user), [puntos de conexión](#endpoint) opcionales y [controles de chat](#chat-control) 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á.
Los juegos no están obligados a conectarse a más de una red simultáneamente para usar PlayFab Party correctamente. Puede obtener más información sobre si conviene usar varias redes y cómo hacerlo en un [tema avanzado posterior](/services/playfab/multiplayer/networking/concepts-multiple-networks).
## 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](#network) tienen un subobjeto "Local" especializado que contiene métodos y propiedades que solo están disponibles para el [dispositivo](#device) local propietario del objeto.
Por ejemplo, hay un objeto base `PartyEndpoint` que se usa para representar cualquier [punto de conexión](#endpoint) 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](#manager) (`PartyManager`)
2. [Red](#network) (`PartyNetwork`)
3. [Dispositivo](#device) (`PartyDevice` y `PartyLocalDevice`)
4. [Usuario](#user) (identificadores de entidad de usuario y `PartyLocalUser`)
5. [Punto de conexión](#endpoint) (`PartyEndpoint` y `PartyLocalEndpoint`)
6. [Control de chat](#chat-control) (`PartyChatControl` y `PartyLocalChatControl`)
7. [Cambio de estado](#state-change) (`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](#network) y los [usuarios](#user) 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](#device) participantes, sus [usuarios](#user) autorizados y cualquier [punto de conexión](#endpoint) o [control de chat](#chat-control) 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](/services/playfab/multiplayer/matchmaking) u otros mecanismos de encuentro externos fuera del ámbito de PlayFab Party.
El *descriptor de red* de una *red* puede cambiar en circunstancias poco frecuentes. Los juegos deben estar preparados para recibir notificaciones de tales cambios y, a continuación, actualizar o volver a anunciar el nuevo *descriptor de red* de una *red* existente para evitar problemas con la conexión de dispositivos adicionales.
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](/services/playfab/multiplayer/networking/concepts-invitations-security-model).
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](/services/playfab/multiplayer/networking/concepts-multiple-networks).
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](#endpoint) o [controles de chat](#chat-control) pertenecen a esa instancia de juego, en particular para las plataformas y juegos que admiten más de un [usuario](#user) 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](#network) 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](/services/playfab/identity/player-identity/login) para adquirir un [identificador de entidad](/services/playfab/live-service-management/game-configuration/entities) `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](#chat-control) y, opcionalmente, a los [puntos de conexión](#endpoint). 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](/services/playfab/identity/player-identity/login) 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](#network) 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](/services/playfab/multiplayer/networking/concepts-invitations-security-model).
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](#device) 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](#network). Podrían representar un [dispositivo](#device), un [usuario](#user) 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](/services/playfab/live-service-management/game-configuration/entities) 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](#user) 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](#network) antes de que se creen como objetos `PartyChatControl` en los [dispositivos](#device) 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](/services/playfab/multiplayer/networking/concepts-invitations-security-model)
* [Aprenda cómo interactúa PlayFab Party con sus flujos de detección](/services/playfab/multiplayer/networking/concepts-discovery)
* [Obtenga más información sobre la comunicación de chat de PlayFab Party](/services/playfab/community/voice-communications/concepts-chat)
* Vea cómo trabajar con operaciones asincrónicas y notificaciones en PlayFab Party
## Related topics
- [Uso de varias redes de PlayFab Party](/es/services/playfab/multiplayer/networking/concepts-multiple-networks.md)
- [Características de PlayFab Party](/es/services/playfab/multiplayer/networking/party-features.md)
- [Biblioteca auxiliar de XBOX Live para PlayFab Party](/es/services/playfab/multiplayer/networking/party-xbox-live-guide.md)
- [Directrices de experiencia de usuario de texto a voz y entrada de texto de PlayFab Party](/es/services/playfab/community/voice-communications/party-text-to-speech-ux-guidelines.md)
- [Directrices de experiencia de usuario de conversión de voz en texto y visualización de texto de PlayFab Party](/es/services/playfab/community/voice-communications/party-speech-to-text-ux-guidelines.md)