GameOs.xvd) 中。你的游戏在运行时可以使用的 GameInput API 版本取决于 GDK 版本、你编译时使用的 GameInput 头文件和库,以及你是否随游戏部署了 GameInput 运行时。
在 XBOX 上使用较新的 GameInput API 版本有两种方式:
- 更新 GDK。 每个 GDK 版本都包含一个支持特定 API 版本集的 GameInput 运行时。
- 旁加载 GameInput 运行时。 将 Microsoft.GameInput NuGet 包中的 GameInput 运行时随游戏一起部署,以使用比你的 GDK 所支持版本更新的 API 版本。
支持的 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 运行时:- 将 4.0 或更高版本的 Microsoft.GameInput NuGet 包添加到项目中,并使用其头文件和
GameInput.lib进行编译和链接。 - 将该包
native\bin\xbox\目录中的GameInputRedist.dll部署到游戏可执行文件所在的同一目录中。
GameInput.lib 链接是不够的。如果没有旁加载的运行时,你的游戏将使用 GDK 中的运行时,而在 2026 年 10 月 GDK 之前,该运行时不支持 API v4。在这种情况下,对 v4 API 的请求会失败并返回 E_NOINTERFACE,而 API 版本 v0 到 v3 仍可正常工作。
如何选择运行时
XBOX 主机和 PC 均支持旁加载 GameInput 运行时。在 XBOX 上,当你的游戏首次创建 GameInput 时,NuGet 包中的GameInput.lib 会将与游戏捆绑的 Game OS 中的 GameInput 运行时与旁加载的运行时(如果已部署)进行比较,并使用版本较高的运行时。因此:
- 比 GDK 运行时更新的旁加载运行时可以为你的游戏提供更新的 API 版本和修复。
- 当你的游戏迁移到所含运行时比旁加载运行时更新的 GDK 版本时,游戏会使用 GDK 运行时。你可以继续部署旁加载的运行时,也可以在它不再比 GDK 运行时更新时将其移除。
检查可用的 API 版本
如果你的游戏请求了运行时不支持的 API 版本,GameInput 会失败并返回E_NOINTERFACE。这同时适用于 GameInputCreate 和 QueryInterface。如果你的游戏可以在没有最新 API 版本的情况下运行,请检查此错误并回退到较早版本的功能。
另请参阅
通过 NuGet 在 PC 和主机上使用 GameInputGameInput 旁加载
GameInput API 版本管理
在一个应用程序中使用多个 GameInput API 版本
GameInputInitialize
