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

# XBOX 主机上的 GameInput

> 介绍每个 GDK 版本在 XBOX 主机上可用的 GameInput API 版本，以及如何通过 NuGet 包和旁加载使用更新的版本。

在 XBOX 主机上，GameInput 运行时是 Microsoft Game Development Kit (GDK) 的一部分。它包含在与你的游戏捆绑的 GDK 的 Game OS 文件 (`GameOs.xvd`) 中。你的游戏在运行时可以使用的 GameInput API 版本取决于 GDK 版本、你编译时使用的 GameInput 头文件和库，以及你是否随游戏部署了 GameInput 运行时。

在 XBOX 上使用较新的 GameInput API 版本有两种方式：

* **更新 GDK。** 每个 GDK 版本都包含一个支持特定 API 版本集的 GameInput 运行时。
* **旁加载 GameInput 运行时。** 将 [Microsoft.GameInput](https://www.nuget.org/packages/Microsoft.GameInput) NuGet 包中的 GameInput 运行时随游戏一起部署，以使用比你的 GDK 所支持版本更新的 API 版本。

无论哪种情况，若要使用 API v1 或更高版本，都必须使用 NuGet 包中的头文件和库进行编译。

## 支持的 API 版本

下表显示了每个 GDK 版本可用的 API 版本。

| GDK 版本 | GDK 头文件和库 | NuGet 头文件和库 | NuGet 头文件和库，以及旁加载的运行时 |
| - | - | - | - |
| 早于 2025 年 10 月 GDK (2510) | v0 | 不支持 | 不支持 |
| 2025 年 10 月 GDK (2510) 及更高版本，早于 2026 年 10 月 GDK | v0 | v0 到 v3 | v0 到 v4 |
| 2026 年 10 月 GDK (2610) 及更高版本 | v0 | v0 到 v4 | v0 到 v4 |

无论 GDK 版本如何，GDK 头文件和库仅提供 v0 API。早于 2025 年 10 月 GDK 的 GDK 版本不支持 NuGet 包。

## 使用 API v1 或更高版本

若要使用 API v1 或更高版本，请将 [Microsoft.GameInput](https://www.nuget.org/packages/Microsoft.GameInput) NuGet 包添加到项目中，并使用其头文件和 `GameInput.lib`（而不是 GDK 中的头文件和库）进行编译和链接。NuGet 包的主版本号与其头文件所定义的最高 API 版本一致。例如，4.x 包包含 v4 API。有关详细信息，请参阅[通过 NuGet 在 PC 和主机上使用 GameInput](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-nuget.md)。

无需在主机上安装任何其他内容。如果你只与 NuGet 包中的 `GameInput.lib` 链接，游戏将使用 GDK 附带的 GameInput 运行时，并且该运行时支持的 API 版本受 GDK 版本限制，如[支持的 API 版本](#supported-api-versions)表中所示。

## 在较早的 GDK 中使用 API v4

若要在 2025 年 10 月 GDK 至 2026 年 10 月 GDK（不含）之间的 GDK 版本中使用 API v4，请旁加载 GameInput 运行时：

1. 将 4.0 或更高版本的 [Microsoft.GameInput](https://www.nuget.org/packages/Microsoft.GameInput) NuGet 包添加到项目中，并使用其头文件和 `GameInput.lib` 进行编译和链接。
2. 将该包 `native\bin\xbox\` 目录中的 `GameInputRedist.dll` 部署到游戏可执行文件所在的同一目录中。

仅与 NuGet 包中的 `GameInput.lib` 链接是不够的。如果没有旁加载的运行时，你的游戏将使用 GDK 中的运行时，而在 2026 年 10 月 GDK 之前，该运行时不支持 API v4。在这种情况下，对 v4 API 的请求会失败并返回 `E_NOINTERFACE`，而 API 版本 v0 到 v3 仍可正常工作。

> [!WARNING]
>
> NuGet 包分别为 PC 和 XBOX 提供了 `GameInputRedist.dll` 的单独副本。请仅将 `native\bin\xbox\` 中的副本随 XBOX 游戏一起部署。有关详细信息，请参阅 [GameInput 旁加载](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-agility-redistributable.md)。

## 如何选择运行时

XBOX 主机和 PC 均支持旁加载 GameInput 运行时。在 XBOX 上，当你的游戏首次创建 GameInput 时，NuGet 包中的 `GameInput.lib` 会将与游戏捆绑的 Game OS 中的 GameInput 运行时与旁加载的运行时（如果已部署）进行比较，并使用版本较高的运行时。因此：

* 比 GDK 运行时更新的旁加载运行时可以为你的游戏提供更新的 API 版本和修复。
* 当你的游戏迁移到所含运行时比旁加载运行时更新的 GDK 版本时，游戏会使用 GDK 运行时。你可以继续部署旁加载的运行时，也可以在它不再比 GDK 运行时更新时将其移除。

PC 特有的旁加载限制（例如有关后台输入和输入焦点的限制）不适用于 XBOX 主机。有关在两个平台上进行旁加载的详细信息，请参阅 [GameInput 旁加载](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-agility-redistributable.md)。

## 检查可用的 API 版本

如果你的游戏请求了运行时不支持的 API 版本，GameInput 会失败并返回 `E_NOINTERFACE`。这同时适用于 [GameInputCreate](https://docs.xbox.com/zh-CN/reference/input/gameinput/functions/gameinputcreate.md) 和 `QueryInterface`。如果你的游戏可以在没有最新 API 版本的情况下运行，请检查此错误并回退到较早版本的功能。

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

若要在游戏中使用多个 API 版本（例如将 v0 代码与 v4 代码一起使用），请参阅[在一个应用程序中使用多个 GameInput API 版本](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-version-interop.md)。

## 另请参阅

[通过 NuGet 在 PC 和主机上使用 GameInput](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-nuget.md)\
[GameInput 旁加载](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-agility-redistributable.md)\
[GameInput API 版本管理](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-versioning.md)\
[在一个应用程序中使用多个 GameInput API 版本](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-version-interop.md)\
[GameInputInitialize](https://docs.xbox.com/zh-CN/reference/input/gameinput/functions/gameinputinitialize.md)


## Related topics

- [GameInput 旁加载](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-agility-redistributable.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-versioning.md)
- [GameInput 常见问题](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-faq.md)
- [在一个应用程序中使用多个 GameInput API 版本](https://docs.xbox.com/zh-CN/build/core-features/common/input/overviews/input-version-interop.md)