跳转到主要内容
在 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 NuGet 包中的 GameInput 运行时随游戏一起部署,以使用比你的 GDK 所支持版本更新的 API 版本。
无论哪种情况,若要使用 API v1 或更高版本,都必须使用 NuGet 包中的头文件和库进行编译。

支持的 API 版本

下表显示了每个 GDK 版本可用的 API 版本。 无论 GDK 版本如何,GDK 头文件和库仅提供 v0 API。早于 2025 年 10 月 GDK 的 GDK 版本不支持 NuGet 包。

使用 API v1 或更高版本

若要使用 API v1 或更高版本,请将 Microsoft.GameInput NuGet 包添加到项目中,并使用其头文件和 GameInput.lib(而不是 GDK 中的头文件和库)进行编译和链接。NuGet 包的主版本号与其头文件所定义的最高 API 版本一致。例如,4.x 包包含 v4 API。有关详细信息,请参阅通过 NuGet 在 PC 和主机上使用 GameInput。 无需在主机上安装任何其他内容。如果你只与 NuGet 包中的 GameInput.lib 链接,游戏将使用 GDK 附带的 GameInput 运行时,并且该运行时支持的 API 版本受 GDK 版本限制,如支持的 API 版本表中所示。

在较早的 GDK 中使用 API v4

若要在 2025 年 10 月 GDK 至 2026 年 10 月 GDK(不含)之间的 GDK 版本中使用 API v4,请旁加载 GameInput 运行时:
  1. 将 4.0 或更高版本的 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 仍可正常工作。
NuGet 包分别为 PC 和 XBOX 提供了 GameInputRedist.dll 的单独副本。请仅将 native\bin\xbox\ 中的副本随 XBOX 游戏一起部署。有关详细信息,请参阅 GameInput 旁加载。

如何选择运行时

XBOX 主机和 PC 均支持旁加载 GameInput 运行时。在 XBOX 上,当你的游戏首次创建 GameInput 时,NuGet 包中的 GameInput.lib 会将与游戏捆绑的 Game OS 中的 GameInput 运行时与旁加载的运行时(如果已部署)进行比较,并使用版本较高的运行时。因此:
  • 比 GDK 运行时更新的旁加载运行时可以为你的游戏提供更新的 API 版本和修复。
  • 当你的游戏迁移到所含运行时比旁加载运行时更新的 GDK 版本时,游戏会使用 GDK 运行时。你可以继续部署旁加载的运行时,也可以在它不再比 GDK 运行时更新时将其移除。
PC 特有的旁加载限制(例如有关后台输入和输入焦点的限制)不适用于 XBOX 主机。有关在两个平台上进行旁加载的详细信息,请参阅 GameInput 旁加载。

检查可用的 API 版本

如果你的游戏请求了运行时不支持的 API 版本,GameInput 会失败并返回 E_NOINTERFACE。这同时适用于 GameInputCreate 和 QueryInterface。如果你的游戏可以在没有最新 API 版本的情况下运行,请检查此错误并回退到较早版本的功能。
若要在游戏中使用多个 API 版本(例如将 v0 代码与 v4 代码一起使用),请参阅在一个应用程序中使用多个 GameInput API 版本。

另请参阅

通过 NuGet 在 PC 和主机上使用 GameInput
GameInput 旁加载
GameInput API 版本管理
在一个应用程序中使用多个 GameInput API 版本
GameInputInitialize
最后修改于 2026年11月6日