> ## 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 旁加载

> 介绍如何将 GameInput 运行时部署在游戏旁边，而不是安装 GameInput 可再发行组件。

从 GameInput 4.0 开始，你可以将 GameInput 运行时 `GameInputRedist.dll` 部署在游戏可执行文件所在的同一目录中。这称为*旁加载*。借助旁加载的运行时，即使系统上未安装 GameInput 可再发行组件或安装的是较旧版本，你的游戏也能使用其构建和测试时所用的 GameInput 功能和修复。此模型与 DirectX Agility SDK 所用的模型类似。

PC 和 XBOX 主机均支持旁加载。在 XBOX 上，旁加载需要 2025 年 10 月 GDK (2510) 或更高版本，它让你的游戏能够使用比 GDK 运行时所支持版本更新的 API 版本，例如在 2026 年 10 月 GDK 之前使用 API v4。有关详细信息，请参阅 [XBOX 主机上的 GameInput](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-xbox.md)。

> [!NOTE]
>
> 在 PC 上，安装 GameInput 可再发行组件仍是部署 GameInput 的首选方式。已安装的运行时支持所有 GameInput 功能，由所有应用程序共享，并且独立于游戏进行更新。当安装可再发行组件不可行时，请使用旁加载，例如分发渠道不支持运行安装程序时，或在开发和测试计算机上。

## 获取可旁加载的运行时

[Microsoft.GameInput](https://www.nuget.org/packages/Microsoft.GameInput) NuGet 包在以下位置包含可旁加载的运行时。

| 包中的路径 | 内容 |
| - | - |
| `native\bin\x64\` | 适用于 64 位 PC 游戏的 `GameInputRedist.dll` 和 `GameInputRawInputProxy.exe` |
| `native\bin\x86\` | 适用于 32 位 PC 游戏的 `GameInputRedist.dll` 和 `GameInputRawInputProxy.exe` |
| `native\bin\arm64\` | 适用于 Arm64 PC 游戏的 `GameInputRedist.dll` 和 `GameInputRawInputProxy.exe` |
| `native\bin\xbox\` | 适用于 XBOX 主机的 `GameInputRedist.dll` |

NuGet 包不会将这些文件复制到你的生成输出中。请在生成或打包过程中添加一个步骤，将适用于目标平台和体系结构的文件复制到游戏可执行文件旁边。

在 PC 上，还需将 `GameInputRawInputProxy.exe` 部署到 `GameInputRedist.dll` 所在的同一目录中。旁加载的运行时使用此帮助程序进程接收键盘和鼠标输入。旁加载的运行时只使用与其位于同一位置的代理，绝不会使用已安装的可再发行组件中的代理。如果缺少该代理，运行时会回退为在游戏进程中接收键盘和鼠标输入。

> [!WARNING]
>
> PC 和 XBOX 运行时的文件名相同。请确保部署与目标平台匹配的副本。如果部署了错误的副本，`GameInputCreate` 会失败并返回 `HRESULT_FROM_WIN32(ERROR_EXE_MACHINE_TYPE_MISMATCH)` (0x800700D8)。

## 如何选择运行时

使用旁加载的运行时无需更改代码。与 NuGet 包中的 `gameinput.lib` 链接，并照常调用 [GameInputCreate](https://docs.xbox.com/zh-CN/reference/input/gameinput/functions/gameinputcreate.md)。首次调用 `GameInputCreate` 时，`gameinput.lib` 中的加载程序会在以下位置查找 GameInput 运行时：

1. 系统目录中的内置运行时 `GameInput.dll`。
2. 系统目录或 GameInput 可再发行组件安装目录中的已安装可再发行组件运行时 `GameInputRedist.dll`。
3. 游戏可执行文件所在目录中的旁加载运行时 `GameInputRedist.dll`。

加载程序会使用文件版本最高的运行时。如果两个运行时版本相同，则旁加载的运行时优先于已安装的可再发行组件，已安装的可再发行组件优先于内置运行时。

在 PC 上，当加载了旁加载的运行时且系统上安装了更新的 GameInput 运行时时，旁加载的运行时会将所有调用转发给更新的已安装运行时。因此，旁加载的运行时起到最低版本的作用：你的游戏始终使用你随附的版本或更新的已安装版本。游戏仍被视为旁加载，下一节中的限制仍然适用。

## 限制

在 PC 上，某些 GameInput 功能依赖于仅在安装了 GameInput 可再发行组件时才存在的组件，例如管理输入焦点的 GameInput 服务。当你的游戏在 PC 上使用旁加载的运行时时，存在以下限制。这些限制不适用于 XBOX 主机。

* 使用 `true` 调用 [IGameInput::EnableBackgroundInput](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinput/methods/igameinput_enablebackgroundinput.md) 不起作用，因为启用后台输入还会占用系统按钮，而旁加载的运行时无法占用这些按钮。
* 输入焦点不由 GameInput 服务管理，因此 GameInput 不会根据游戏是否处于焦点状态一致地筛选输入。根据设备不同，游戏在未处于焦点状态时可能会也可能不会收到输入。如果你的游戏依赖一致的焦点行为，请在处理输入之前检查游戏是否处于焦点状态，或安装 GameInput 可再发行组件。
* 在 API 版本 v1 到 v3 中，`IGameInput::SetFocusPolicy` 仅接受 `GameInputDefaultFocusPolicy` 和 `GameInputEnableBackgroundInput`。其他焦点策略（包括任何标志组合）都会被忽略。
* 在 API 版本 v1 到 v3 中，`IGameInput::RegisterSystemButtonCallback` 会失败并返回 `GAMEINPUT_E_FEATURE_REQUIRES_INSTALL` (0x838AD02B)。在 API 版本 v4 中，系统按钮在 `GameInputKindSystemButton` 类型的读取中报告，这适用于旁加载的运行时。有关详细信息，请参阅 [IGameInputReading::GetSystemButtonState](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_getsystembuttonstate.md)。

## 建议

* 对 GameInput 头文件、`gameinput.lib` 和旁加载的运行时使用同一版本的 NuGet 包。
* 在安装和未安装 GameInput 可再发行组件的情况下都测试你的游戏。
* 如果你的游戏在 PC 上需要后台输入或一致的焦点行为，请安装 GameInput 可再发行组件，以代替旁加载运行时或作为其补充。有关详细信息，请参阅[通过 NuGet 在 PC 和主机上使用 GameInput](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-nuget.md)。

## 另请参阅

[通过 NuGet 在 PC 和主机上使用 GameInput](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-nuget.md)\
[XBOX 主机上的 GameInput](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-xbox.md)\
[GameInput API 版本管理](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-versioning.md)\
[GameInput 基础](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-fundamentals.md)\
[GameInput API 参考](https://docs.xbox.com/zh-CN/reference/input/gameinput/gameinput_members.md)


## Related topics

- [XBOX 主机上的 GameInput](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-xbox.md)
- [IGameInput::EnableBackgroundInput](https://docs.xbox.com/zh-CN/reference/input/gameinput/interfaces/igameinput/methods/igameinput_enablebackgroundinput.md)
- [GameInput API 版本管理](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-versioning.md)
- [通过 NuGet 在 PC 和主机上使用 GameInput](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-nuget.md)
- [在一个应用程序中使用多个 GameInput API 版本](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-version-interop.md)