Pular para o conteúdo principal
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 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. 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 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. 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.

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

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.

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

Confira também

GameInput para PC e console com NuGet
Sideload do GameInput
Controle de versão da API do GameInput
Usando várias versões da API GameInput em um aplicativo
GameInputInitialize
Última modificação em 6 de novembro de 2026