> ## 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 版本。

在這兩種情況下，您都必須使用 NuGet 套件中的標頭和程式庫進行編譯，才能使用 API v1 或更新版本。

## 支援的 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-TW/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` 複本。請只隨您的 XBOX 遊戲部署 `native\bin\xbox\` 中的複本。如需詳細資訊，請參閱 [GameInput 側載](https://docs.xbox.com/zh-TW/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-TW/build/core-features/common/input/overviews/input-agility-redistributable.md)。

## 檢查可用的 API 版本

如果您的遊戲要求執行階段不支援的 API 版本，GameInput 會失敗並傳回 `E_NOINTERFACE`。這同時適用於 [GameInputCreate](https://docs.xbox.com/zh-TW/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-TW/build/core-features/common/input/overviews/input-version-interop.md)。

## 另請參閱

[透過 NuGet 在 PC 和主機上使用 GameInput](https://docs.xbox.com/zh-TW/build/core-features/common/input/overviews/input-nuget.md)\
[GameInput 側載](https://docs.xbox.com/zh-TW/build/core-features/common/input/overviews/input-agility-redistributable.md)\
[GameInput API 版本控制](https://docs.xbox.com/zh-TW/build/core-features/common/input/overviews/input-versioning.md)\
[在單一應用程式中使用多個 GameInput API 版本](https://docs.xbox.com/zh-TW/build/core-features/common/input/overviews/input-version-interop.md)\
[GameInputInitialize](https://docs.xbox.com/zh-TW/reference/input/gameinput/functions/gameinputinitialize.md)


## Related topics

- [GameInput 側載](https://docs.xbox.com/zh-TW/build/core-features/common/input/overviews/input-agility-redistributable.md)
- [透過 NuGet 在 PC 和主機上使用 GameInput](https://docs.xbox.com/zh-TW/build/core-features/common/input/overviews/input-nuget.md)
- [GameInput API 版本控制](https://docs.xbox.com/zh-TW/build/core-features/common/input/overviews/input-versioning.md)
- [GameInput 常見問題集](https://docs.xbox.com/zh-TW/build/core-features/common/input/overviews/input-faq.md)
- [Microsoft Game Development Kit (GDK) 的新功能](https://docs.xbox.com/zh-TW/announcements/gdk/whats-new.md)