Pular para o conteúdo principal
A partir do GameInput 4.0, você pode implantar o runtime do GameInput, GameInputRedist.dll, no mesmo diretório que o executável do seu jogo. Isso é chamado de sideload. Um runtime com sideload permite que seu jogo use os recursos e as correções do GameInput com os quais ele foi compilado e testado, mesmo em um sistema em que o redistribuível do GameInput não está instalado ou em que uma versão mais antiga está instalada. Esse modelo é semelhante ao usado pelo DirectX Agility SDK. O sideload é compatível com PC e com consoles XBOX. No XBOX, o sideload requer o GDK de outubro de 2025 (2510) ou posterior e permite que seu jogo use uma versão de API mais recente do que a compatível com o runtime do GDK, como a API v4 antes do GDK de outubro de 2026. Para obter mais informações, confira GameInput em consoles XBOX.
Instalar o redistribuível do GameInput ainda é a forma preferencial de implantar o GameInput no PC. Um runtime instalado é compatível com todos os recursos do GameInput, é compartilhado por todos os aplicativos e é atualizado independentemente do seu jogo. Use o sideload quando a instalação do redistribuível não for prática, por exemplo, quando o seu canal de distribuição não permitir a execução de instaladores, ou em computadores de desenvolvimento e teste.

​
Obter o runtime para sideload

O pacote NuGet Microsoft.GameInput contém o runtime para sideload nos locais a seguir. O pacote NuGet não copia esses arquivos para a saída do build. Adicione uma etapa ao seu processo de build ou empacotamento que copie os arquivos da plataforma e da arquitetura de destino para junto do executável do seu jogo. No PC, implante também GameInputRawInputProxy.exe no mesmo diretório que GameInputRedist.dll. O runtime com sideload usa esse processo auxiliar para receber a entrada de teclado e mouse. Um runtime com sideload usa somente o proxy que está ao lado dele, nunca o de um redistribuível instalado. Se o proxy estiver ausente, o runtime passará a receber a entrada de teclado e mouse no processo do seu jogo.
Os runtimes de PC e XBOX têm o mesmo nome de arquivo. Certifique-se de implantar a cópia que corresponde à sua plataforma de destino. Se a cópia errada for implantada, GameInputCreate falhará com HRESULT_FROM_WIN32(ERROR_EXE_MACHINE_TYPE_MISMATCH) (0x800700D8).

​
Como o runtime é selecionado

Você não precisa alterar seu código para usar um runtime com sideload. Vincule com gameinput.lib do pacote NuGet e chame GameInputCreate normalmente. Na primeira vez que GameInputCreate é chamada, o carregador em gameinput.lib procura o runtime do GameInput nos seguintes locais:
  1. O runtime nativo da caixa de entrada, GameInput.dll, no diretório do sistema.
  2. O runtime do redistribuível instalado, GameInputRedist.dll, no diretório do sistema ou no diretório em que o redistribuível do GameInput está instalado.
  3. O runtime com sideload, GameInputRedist.dll, no diretório do executável do jogo.
O carregador usa o runtime com a versão de arquivo mais alta. Se dois runtimes tiverem a mesma versão, o runtime com sideload terá preferência sobre o redistribuível instalado, e o redistribuível instalado terá preferência sobre o runtime nativo da caixa de entrada. No PC, quando um runtime com sideload é carregado e um runtime do GameInput mais recente está instalado no sistema, o runtime com sideload encaminha todas as chamadas para o runtime instalado mais recente. Como resultado, o runtime com sideload funciona como uma versão mínima: seu jogo sempre usa a versão que você distribuiu ou uma versão instalada mais recente. O jogo ainda é tratado como usando sideload, e as limitações da seção a seguir continuam se aplicando.

​
Limitações

No PC, alguns recursos do GameInput dependem de componentes que só estão presentes quando o redistribuível do GameInput está instalado, como o serviço GameInput que gerencia o foco de entrada. Quando o seu jogo usa um runtime com sideload no PC, as limitações a seguir se aplicam. Essas limitações não se aplicam a consoles XBOX.
  • As chamadas para IGameInput::EnableBackgroundInput com true não têm efeito, porque habilitar a entrada em segundo plano também reivindica os botões do sistema, que um runtime com sideload não pode reivindicar.
  • O foco de entrada não é gerenciado pelo serviço GameInput, portanto o GameInput não filtra de forma consistente a entrada com base em o seu jogo estar ou não em foco. Dependendo do dispositivo, seu jogo pode ou não receber entrada enquanto não está em foco. Se o seu jogo depende de um comportamento de foco consistente, verifique se ele está em foco antes de agir com base na entrada ou instale o redistribuível do GameInput.
  • Nas versões de API v1 a v3, IGameInput::SetFocusPolicy aceita somente GameInputDefaultFocusPolicy e GameInputEnableBackgroundInput. Outras políticas de foco, incluindo qualquer combinação de sinalizadores, são ignoradas.
  • Nas versões de API v1 a v3, IGameInput::RegisterSystemButtonCallback falha com GAMEINPUT_E_FEATURE_REQUIRES_INSTALL (0x838AD02B). Na versão de API v4, os botões do sistema são relatados em leituras do tipo GameInputKindSystemButton, que funcionam com um runtime com sideload. Para obter mais informações, confira IGameInputReading::GetSystemButtonState.

​
Recomendações

  • Use a mesma versão do pacote NuGet para o cabeçalho do GameInput, gameinput.lib e o runtime com sideload.
  • Teste seu jogo com e sem o redistribuível do GameInput instalado.
  • Se o seu jogo exigir entrada em segundo plano ou um comportamento de foco consistente no PC, instale o redistribuível do GameInput em vez de fazer o sideload do runtime ou além disso. Para obter mais informações, confira GameInput para PC e console com NuGet.

​
Confira também

GameInput para PC e console com NuGet
GameInput em consoles XBOX
Controle de versão da API do GameInput
Fundamentos do GameInput
Referência da API do GameInput
Última modificação em 6 de novembro de 2026