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

# Sideload do GameInput

> Descreve como implantar o runtime do GameInput ao lado do seu jogo em vez de instalar o redistribuível do GameInput.

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](https://docs.xbox.com/pt-BR/build/core-features/common/input/overviews/input-xbox.md).

> [!NOTE]
>
> 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](https://www.nuget.org/packages/Microsoft.GameInput) contém o runtime para sideload nos locais a seguir.

| Caminho no pacote | Conteúdo |
| - | - |
| `native\bin\x64\` | `GameInputRedist.dll` e `GameInputRawInputProxy.exe` para jogos de PC de 64 bits |
| `native\bin\x86\` | `GameInputRedist.dll` e `GameInputRawInputProxy.exe` para jogos de PC de 32 bits |
| `native\bin\arm64\` | `GameInputRedist.dll` e `GameInputRawInputProxy.exe` para jogos de PC Arm64 |
| `native\bin\xbox\` | `GameInputRedist.dll` para consoles XBOX |

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.

> [!WARNING]
>
> 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](https://docs.xbox.com/pt-BR/reference/input/gameinput/functions/gameinputcreate.md) 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](https://docs.xbox.com/pt-BR/reference/input/gameinput/interfaces/igameinput/methods/igameinput_enablebackgroundinput.md) 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](https://docs.xbox.com/pt-BR/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_getsystembuttonstate.md).

## 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](https://docs.xbox.com/pt-BR/build/core-features/common/input/overviews/input-nuget.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)\
[GameInput em consoles XBOX](https://docs.xbox.com/pt-BR/build/core-features/common/input/overviews/input-xbox.md)\
[Controle de versão da API do GameInput](https://docs.xbox.com/pt-BR/build/core-features/common/input/overviews/input-versioning.md)\
[Fundamentos do GameInput](https://docs.xbox.com/pt-BR/build/core-features/common/input/overviews/input-fundamentals.md)\
[Referência da API do GameInput](https://docs.xbox.com/pt-BR/reference/input/gameinput/gameinput_members.md)


## Related topics

- [GameInput em consoles XBOX](https://docs.xbox.com/pt-BR/build/core-features/common/input/overviews/input-xbox.md)
- [Membros da API do GameInput](https://docs.xbox.com/pt-BR/reference/input/gameinput/gameinput_members.md)
- [Controle de versão da API do GameInput](https://docs.xbox.com/pt-BR/build/core-features/common/input/overviews/input-versioning.md)
- [IGameInput::EnableBackgroundInput](https://docs.xbox.com/pt-BR/reference/input/gameinput/interfaces/igameinput/methods/igameinput_enablebackgroundinput.md)
- [GameInput para PC e console com NuGet](https://docs.xbox.com/pt-BR/build/core-features/common/input/overviews/input-nuget.md)