> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GameInput em consoles XBOX

> Descreve quais versões da API do GameInput estão disponíveis em consoles XBOX para cada versão do GDK e como usar versões mais recentes com o pacote NuGet e o sideload.

Em consoles XBOX, o runtime do GameInput faz parte do Microsoft Game Development Kit (GDK). Ele está incluído no arquivo do Game OS (`GameOs.xvd`) do GDK que acompanha o seu título. As versões da API do GameInput que o seu jogo pode usar em runtime dependem da versão do GDK, do cabeçalho e da biblioteca do GameInput com os quais você compila e de você implantar ou não um runtime do GameInput com o seu jogo.

Há duas formas de usar uma versão mais recente da API do GameInput no XBOX:

* **Atualizar o GDK.** Cada versão do GDK inclui um runtime do GameInput compatível com um conjunto específico de versões da API.
* **Fazer sideload do runtime do GameInput.** Implante o runtime do GameInput do pacote NuGet [Microsoft.GameInput](https://www.nuget.org/packages/Microsoft.GameInput) com o seu jogo para usar uma versão de API mais recente do que a compatível com o seu GDK.

Em ambos os casos, você deve compilar com os cabeçalhos e a biblioteca do pacote NuGet para usar a API v1 ou posterior.

## Versões de API compatíveis

A tabela a seguir mostra as versões de API disponíveis para cada versão do GDK.

| Versão do GDK | Cabeçalho e biblioteca do GDK | Cabeçalho e biblioteca do NuGet | Cabeçalho e biblioteca do NuGet e runtime com sideload |
| - | - | - | - |
| Anterior ao GDK de outubro de 2025 (2510) | v0 | Sem suporte | Sem suporte |
| GDK de outubro de 2025 (2510) e versões posteriores, antes do GDK de outubro de 2026 | v0 | v0 a v3 | v0 a v4 |
| GDK de outubro de 2026 (2610) e posteriores | v0 | v0 a v4 | v0 a v4 |

Os cabeçalhos e a biblioteca do GDK fornecem somente a API v0, independentemente da versão do GDK. O pacote NuGet não tem suporte com versões do GDK anteriores ao GDK de outubro de 2025.

## Usar a API v1 ou posterior

Para usar a API v1 ou posterior, adicione o pacote NuGet [Microsoft.GameInput](https://www.nuget.org/packages/Microsoft.GameInput) ao seu projeto e compile e vincule com os cabeçalhos e o `GameInput.lib` dele, em vez dos que estão no GDK. A versão principal do pacote NuGet corresponde à versão de API mais alta definida pelos cabeçalhos dele. Por exemplo, o pacote 4.x inclui a API v4. Para obter mais informações, confira [GameInput para PC e console com NuGet](https://docs.xbox.com/pt-BR/build/core-features/common/input/overviews/input-nuget.md).

Você não precisa instalar mais nada no console. Se você apenas vincular com `GameInput.lib` do pacote NuGet, seu jogo usará o runtime do GameInput incluído no GDK, e as versões de API compatíveis com o runtime serão limitadas pela versão do GDK, conforme mostrado na tabela [Versões de API compatíveis](#supported-api-versions).

## Usar a API v4 com um GDK anterior

Para usar a API v4 com uma versão do GDK a partir do GDK de outubro de 2025 até o GDK de outubro de 2026 (sem incluí-lo), faça o sideload do runtime do GameInput:

1. Adicione a versão 4.0 ou posterior do pacote NuGet [Microsoft.GameInput](https://www.nuget.org/packages/Microsoft.GameInput) ao seu projeto e compile e vincule com os cabeçalhos e o `GameInput.lib` dele.
2. Implante `GameInputRedist.dll` do diretório `native\bin\xbox\` do pacote no mesmo diretório que o executável do seu jogo.

Vincular com `GameInput.lib` do pacote NuGet não é suficiente por si só. Sem o runtime com sideload, seu jogo usa o runtime do GDK, que não é compatível com a API v4 antes do GDK de outubro de 2026. Nesse caso, as solicitações da API v4 falham com `E_NOINTERFACE`, e as versões de API v0 a v3 continuam funcionando.

> [!WARNING]
>
> O pacote NuGet contém cópias separadas de `GameInputRedist.dll` para PC e XBOX. Implante somente a cópia de `native\bin\xbox\` com o seu jogo para XBOX. Para obter mais informações, confira [Sideload do GameInput](https://docs.xbox.com/pt-BR/build/core-features/common/input/overviews/input-agility-redistributable.md).

## Como o runtime é escolhido

O sideload do runtime do GameInput é compatível com consoles XBOX, assim como com PC. No XBOX, quando o seu jogo cria o GameInput pela primeira vez, o `GameInput.lib` do pacote NuGet compara o runtime do GameInput no Game OS que acompanha o seu título com o runtime com sideload, se houver um implantado, e usa o runtime com a versão mais alta. Como resultado:

* Um runtime com sideload mais recente do que o runtime do GDK disponibiliza versões de API e correções mais recentes para o seu jogo.
* Quando o seu jogo passa para uma versão do GDK que inclui um runtime mais recente do que o runtime com sideload, seu jogo usa o runtime do GDK. Você pode continuar implantando o runtime com sideload ou removê-lo quando ele não for mais recente do que o runtime do GDK.

As limitações de sideload específicas do PC, como as relacionadas à entrada em segundo plano e ao foco de entrada, não se aplicam a consoles XBOX. Para obter mais informações sobre o sideload nas duas plataformas, confira [Sideload do GameInput](https://docs.xbox.com/pt-BR/build/core-features/common/input/overviews/input-agility-redistributable.md).

## Verificar qual versão de API está disponível

Se o seu jogo solicitar uma versão de API que o runtime não suporta, o GameInput falhará com `E_NOINTERFACE`. Isso se aplica tanto a [GameInputCreate](https://docs.xbox.com/pt-BR/reference/input/gameinput/functions/gameinputcreate.md) quanto a `QueryInterface`. Se o seu jogo puder ser executado sem a versão de API mais recente, verifique esse erro e recorra aos recursos de uma versão anterior.

```cpp theme={null}
#include <GameInput.h>

GameInput::v4::IGameInput* gameInput = nullptr;
HRESULT hr = GameInput::v4::GameInputCreate(&gameInput);
if (hr == E_NOINTERFACE)
{
    // The GameInput runtime doesn't support API v4. Deploy the sideloaded
    // runtime with your game, or use an earlier API version.
}
```

Para usar mais de uma versão de API no seu jogo, como código v0 junto com código v4, confira [Usando várias versões da API GameInput em um aplicativo](https://docs.xbox.com/pt-BR/build/core-features/common/input/overviews/input-version-interop.md).

## Confira também

[GameInput para PC e console com NuGet](https://docs.xbox.com/pt-BR/build/core-features/common/input/overviews/input-nuget.md)\
[Sideload do GameInput](https://docs.xbox.com/pt-BR/build/core-features/common/input/overviews/input-agility-redistributable.md)\
[Controle de versão da API do GameInput](https://docs.xbox.com/pt-BR/build/core-features/common/input/overviews/input-versioning.md)\
[Usando várias versões da API GameInput em um aplicativo](https://docs.xbox.com/pt-BR/build/core-features/common/input/overviews/input-version-interop.md)\
[GameInputInitialize](https://docs.xbox.com/pt-BR/reference/input/gameinput/functions/gameinputinitialize.md)


## Related topics

- [Sideload do GameInput](https://docs.xbox.com/pt-BR/build/core-features/common/input/overviews/input-agility-redistributable.md)
- [Perguntas frequentes sobre o GameInput](https://docs.xbox.com/pt-BR/build/core-features/common/input/overviews/input-faq.md)
- [GameInput para PC e console com NuGet](https://docs.xbox.com/pt-BR/build/core-features/common/input/overviews/input-nuget.md)
- [Controle de versão da API do GameInput](https://docs.xbox.com/pt-BR/build/core-features/common/input/overviews/input-versioning.md)
- [Usando várias versões da API GameInput em um aplicativo](https://docs.xbox.com/pt-BR/build/core-features/common/input/overviews/input-version-interop.md)