> ## 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.

# Usuários e dispositivos de entrada

> Usuários e dispositivos de entrada

Os jogos precisam saber quais dispositivos de entrada estão associados a um usuário especificado.
Isso é fundamental para responder às seguintes perguntas:

* Quem realizou uma ação no jogo?

* Quem recebe a conquista?

* Quem está fazendo a compra?

Este tópico aborda alguns conceitos importantes que ajudam você a lidar com essas associações e a responder
a esses tipos de perguntas.

## Diferenças no modelo de usuário entre a ERA do XBOX One e o Microsoft Game Development Kit (GDK)

Seja desenvolvendo um novo título do Microsoft Game Development Kit (GDK) ou portando um título anterior da ERA do XBOX One, implementar o gerenciamento de usuários e dispositivos de entrada pode ser confuso para quem está acostumado ao modelo de usuário da ERA do XBOX One.

* Os títulos que precisam de usuários, por exemplo quando são necessários salvamentos de jogo ou conquistas, devem estabelecer um
  usuário principal. Esse usuário principal é uma construção exclusiva do título e não é fornecido pelo sistema.

* O título só conhece os usuários adicionados por meio de uma chamada a [XUserAddAsync](/pt-BR/reference/system/xuser/functions/xuseraddasync). O título
  não é informado sobre nenhuma ação realizada pelo sistema para usuários que ele não adicionou.

* Quando um dispositivo que estava associado anteriormente a um usuário do título é associado a um usuário que o título
  desconhece, o título é informado apenas de um evento de associação de dispositivo, sem um novo usuário.

* Se um dispositivo que não estava associado a um usuário do título for associado a outro usuário que também não foi
  adicionado com [XUserAddAsync](/pt-BR/reference/system/xuser/functions/xuseraddasync), o título não será informado do evento de associação.

* O Seletor de Contas se comporta de forma diferente dependendo de como foi aberto (Guia do Sistema ou
  [XUserAddAsync](/pt-BR/reference/system/xuser/functions/xuseraddasync)).

<Note>O exemplo UserManagement aborda o gerenciamento de usuários e o comportamento de emparelhamento de dispositivos de entrada
em uma ampla variedade de situações de jogo. Ele também lida com os requisitos XR relacionados a usuários
e dispositivos de entrada. Para obter mais informações sobre exemplos, confira
[Exemplos do Microsoft Game Development Kit](/pt-BR/home/setup-install/samples).</Note>

## Como identificar um usuário especificado

Os jogos usam a *ID local* para interagir com dispositivos de entrada. A ID local é um
identificador que permanece com o usuário durante todo o tempo de vida dele na sessão de jogo. A ID local pode ser usada em
todos os processos que um jogo gerar ou se o jogo
chamar [XLaunchNewGame](/pt-BR/reference/system/xgame/functions/xlaunchnewgame). Não use a ID local para identificar um usuário
entre sessões de jogo.

Para obter a ID local de um usuário, use a função [XUserGetLocalId](/pt-BR/reference/system/xuser/functions/xusergetlocalid).

## Como identificar um dispositivo de entrada específico

Os dispositivos de jogo, como gamepads, arcade sticks e volantes, têm uma
*ID de dispositivo* exclusiva, representada por uma estrutura [APP\_LOCAL\_DEVICE\_ID](/pt-BR/reference/system/xuser/structs/app_local_device_id).
Essa ID de dispositivo persiste entre várias inicializações do jogo ou
reinicializações do sistema. A ID de dispositivo é diferente entre dois
jogos diferentes em execução no mesmo sistema.

Se você estiver usando o `XInput` no console, poderá obter a ID de dispositivo usando
[XInputGetDeviceId](/pt-BR/reference/input/xinputongameinput/functions/xinputgetdeviceid).

Se você estiver usando o [GameInput](/pt-BR/build/core-features/common/input/overviews/input-overview), poderá obter a ID de dispositivo do
membro `deviceId` do objeto [GameInputDeviceInfo](/pt-BR/reference/input/gameinput/structs/gameinputdeviceinfo) retornado por
uma chamada a [IGameInputDevice::GetDeviceInfo](/pt-BR/reference/input/gameinput/interfaces/igameinputdevice/methods/igameinputdevice_getdeviceinfo).

## Modelo de usuário

Quando um título precisa ter usuários, por exemplo quando são necessários salvamentos de jogo ou conquistas, o título é
totalmente responsável por estabelecer um usuário principal. Esse usuário principal deve ser mantido mesmo ao
permitir que vários usuários entrem. O título também deve permitir que o usuário principal seja alterado conforme
necessário. Uma forma de fazer isso seria ter um prompt *Trocar de usuário* que abra um Seletor de Contas
com [XUserAddAsync](/pt-BR/reference/system/xuser/functions/xuseraddasync).

O Seletor de Contas lista todos os usuários que já entraram no
console, tem um botão **Adicionar nova** para entrar em novas contas e permite conectar usuários
convidados temporários. Qualquer uma dessas contas de usuário pode ser selecionada, independentemente da verdadeira
identidade do usuário. O sistema oferece suporte a usuários que optam por jogar como outras pessoas dessa
forma.

Os títulos do Microsoft Game Development Kit (GDK) não têm conhecimento completo dos usuários no sistema. Em vez disso, os usuários só podem
ser adicionados a um título por meio de uma chamada a [XUserAddAsync](/pt-BR/reference/system/xuser/functions/xuseraddasync). Os usuários adicionados dessa forma são os
únicos usuários com os quais o título pode interagir. O sistema não informará o título sobre ações realizadas para
usuários que o título não adicionou. Como resultado, o título deve manter sua própria lista de usuários.

O Seletor de Contas pode ser aberto de duas maneiras diferentes: pelo Guia do Sistema e por meio de
[XUserAddAsync](/pt-BR/reference/system/xuser/functions/xuseraddasync). Esse seletor se comporta de forma diferente nessas duas circunstâncias:

| Caso | Seletor de Contas de [XUserAddAsync](/pt-BR/reference/system/xuser/functions/xuseraddasync) | Seletor de Contas do Guia |
| - | - | - |
| Selecionar um usuário que não entrou no título | O usuário passa a estar conectado tanto ao sistema quanto ao título. | O usuário é conectado apenas ao sistema. O título não é informado da entrada. |
| Selecionar um usuário que já entrou no título | O usuário já está conectado ao título, portanto não ocorrem outras alterações de estado do usuário. | O usuário já está conectado ao título, portanto não ocorrem outras alterações de estado do usuário. |

<Note>O conjunto de usuários conectados a um título é sempre um subconjunto dos usuários
conectados ao sistema. Um título não pode ter usuários conectados que o sistema não tenha conectados.
No entanto, o sistema pode ter usuários que o título não conhece.</Note>

Os eventos de usuário podem ser tratados por meio de um [XUserChangeEventCallback](/pt-BR/reference/system/xuser/functions/xuserchangeeventcallback) registrado
com [XUserRegisterForChangeEvent](/pt-BR/reference/system/xuser/functions/xuserregisterforchangeevent). Os eventos só serão chamados para
usuários que foram conectados com [XUserAddAsync](/pt-BR/reference/system/xuser/functions/xuseraddasync). Quando um usuário sai do
sistema, o título deve reagir de acordo e remover o usuário do título ou permitir que o jogador
tente conectar o usuário novamente.

## Associações de dispositivos de entrada

O Microsoft Game Development Kit (GDK) permite que os usuários tenham qualquer número de dispositivos de entrada associados a eles. Isso pode
ser desafiador ao portar títulos mais antigos que podem pressupor um mapeamento 1:1 entre usuários e dispositivos.

As associações de dispositivos geralmente são feitas por meio do Seletor de Contas. O dispositivo de entrada que seleciona o usuário na
interface do usuário passa a ser associado a esse usuário. As associações também podem mudar em outros casos, como quando um
usuário sai ou quando [XUserAddAsync](/pt-BR/reference/system/xuser/functions/xuseraddasync) é usado sem interface do usuário por meio das
opções [AddDefaultUserSilently](/pt-BR/reference/system/xuser/enums/xuseraddoptions) e [AddDefaultUserAllowingUI](/pt-BR/reference/system/xuser/enums/xuseraddoptions).

O Seletor de Contas também se comporta de forma diferente em relação às associações, dependendo de como o seletor foi aberto:

| Caso | Seletor de Contas de [XUserAddAsync](/pt-BR/reference/system/xuser/functions/xuseraddasync) | Seletor de Contas do Guia |
| - | - | - |
| Selecionar um usuário que não entrou no título | Depois que o usuário entra no título, o dispositivo que concluiu o prompt passa a ser associado ao usuário. | O usuário é conectado ao sistema (se ainda não estiver conectado) e o dispositivo que concluiu o prompt é associado a esse usuário. Como o título não conhece esse usuário, ele será informado de que o dispositivo está desassociado. |
| Selecionar um usuário que já entrou no título | O dispositivo que concluiu o prompt passa a ser associado ao usuário do sistema e do título. | O dispositivo que concluiu o prompt passa a ser associado ao usuário do sistema e do título. |

Se o usuário tiver sido conectado automaticamente ao título sem um Seletor de Contas por uma chamada a
[XUserAddAsync](/pt-BR/reference/system/xuser/functions/xuseraddasync) usando uma das opções [AddDefaultUserSilently](/pt-BR/reference/system/xuser/enums/xuseraddoptions) ou
[AddDefaultUserAllowingUI](/pt-BR/reference/system/xuser/enums/xuseraddoptions), os emparelhamentos de dispositivos de entrada que o sistema tinha
serão comunicados ao título.

Para ser notificado sobre alterações na associação de dispositivos de usuário, você pode registrar um
retorno de chamada [XUserDeviceAssociationChangedCallback](/pt-BR/reference/system/xuser/functions/xuserdeviceassociationchangedcallback) com o
método [XUserRegisterForDeviceAssociationChanged](/pt-BR/reference/system/xuser/functions/xuserregisterfordeviceassociationchanged). Você também
pode chamar [XUserFindForDevice](/pt-BR/reference/system/xuser/functions/xuserfindfordevice) para procurar uma associação de um dispositivo específico.

<Note>Como o título só pode conhecer usuários que foram adicionados com
[XUserAddAsync](/pt-BR/reference/system/xuser/functions/xuseraddasync), os retornos de chamada e métodos de associação de dispositivos de usuário só podem retornar usuários
que o título adicionou anteriormente.</Note>

## Correspondência do usuário com um ponto de extremidade de áudio padrão

Headsets ou microfones são frequentemente fornecidos com os jogos. Veja a seguir algumas perguntas
importantes a fazer.

* O usuário tem um headset? Em caso afirmativo, qual headset ele provavelmente está usando?
  Qual é o ponto de extremidade de áudio padrão de renderização de comunicação?

* O usuário tem um microfone associado a ele? Qual é o
  ponto de extremidade padrão de captura de comunicação?

Para responder a essas perguntas para um usuário específico, os jogos podem chamar
[XUserGetDefaultAudioEndpointUtf16](/pt-BR/reference/system/xuser/functions/xusergetdefaultaudioendpointutf16). Assim como as associações de usuário a
dispositivo podem mudar, os pontos de extremidade de áudio padrão associados a um
usuário específico também podem mudar. Para detectar essas alterações de associação, os jogos
devem chamar [XUserRegisterForDefaultAudioEndpointUtf16Changed](/pt-BR/reference/system/xuser/functions/xuserregisterfordefaultaudioendpointutf16changed) e prestar atenção
ao retorno de chamada resultante.


## Related topics

- [Usuarios y dispositivos de entrada](/es/build/core-features/common/user/users-input-devices.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)
- [Usuarios](/es/build/core-features/common/user/user-toc.md)
- [Entrada](/es/build/core-features/common/input/gc-input-toc.md)
- [XR-064 Sessões de jogo com entrada permitida e jogo online](/pt-BR/publishing/certification/xr/xr-064.md)