> ## 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 バージョンを使用するには、次の 2 つの方法があります。

* **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 のヘッダーとライブラリ、およびサイドロードされたランタイム |
| - | - | - | - |
| October 2025 GDK (2510) より前 | v0 | サポート対象外 | サポート対象外 |
| October 2025 GDK (2510) 以降のリリースで、October 2026 GDK より前 | v0 | v0 から v3 | v0 から v4 |
| October 2026 GDK (2610) 以降 | v0 | v0 から v4 | v0 から v4 |

GDK のヘッダーとライブラリは、GDK のリリースに関係なく、v0 API のみを提供します。NuGet パッケージは、October 2025 GDK より前の GDK リリースではサポートされていません。

## API v1 以降を使用する

API v1 以降を使用するには、[Microsoft.GameInput](https://www.nuget.org/packages/Microsoft.GameInput) NuGet パッケージをプロジェクトに追加し、GDK のものではなく、そのパッケージのヘッダーと `GameInput.lib` を使用してコンパイルおよびリンクします。NuGet パッケージのメジャー バージョンは、そのヘッダーが定義する最も高い API バージョンと一致します。たとえば、4.x パッケージには v4 API が含まれています。詳細については、[NuGet を使用した PC およびコンソール向け GameInput](https://docs.xbox.com/ja-jp/build/core-features/common/input/overviews/input-nuget.md) を参照してください。

本体にほかに何かをインストールする必要はありません。NuGet パッケージの `GameInput.lib` とリンクするだけの場合、ゲームは GDK に含まれている GameInput ランタイムを使用し、[サポートされている API バージョン](#supported-api-versions) の表に示すように、ランタイムがサポートする API バージョンは GDK のリリースによって制限されます。

## 以前の GDK で API v4 を使用する

October 2025 GDK 以降、October 2026 GDK より前の GDK リリースで API v4 を使用するには、GameInput ランタイムをサイドロードします。

1. [Microsoft.GameInput](https://www.nuget.org/packages/Microsoft.GameInput) NuGet パッケージのバージョン 4.0 以降をプロジェクトに追加し、そのヘッダーと `GameInput.lib` を使用してコンパイルおよびリンクします。
2. パッケージの `native\bin\xbox\` ディレクトリにある `GameInputRedist.dll` を、ゲームの実行可能ファイルと同じディレクトリに配置します。

NuGet パッケージの `GameInput.lib` とリンクするだけでは不十分です。サイドロードされたランタイムがない場合、ゲームは GDK のランタイムを使用しますが、October 2026 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/ja-jp/build/core-features/common/input/overviews/input-agility-redistributable.md) を参照してください。

## ランタイムの選択方法

GameInput ランタイムのサイドロードは、PC だけでなく XBOX 本体でもサポートされています。XBOX では、ゲームが初めて GameInput を作成するときに、NuGet パッケージの `GameInput.lib` が、タイトルにバンドルされている Game OS 内の GameInput ランタイムと、サイドロードされたランタイム (配置されている場合) を比較し、バージョンが高い方のランタイムを使用します。その結果、次のようになります。

* GDK ランタイムより新しいサイドロードされたランタイムにより、新しい API バージョンと修正をゲームで利用できるようになります。
* サイドロードされたランタイムより新しいランタイムを含む GDK リリースにゲームを移行すると、ゲームは GDK ランタイムを使用します。サイドロードされたランタイムを引き続き配置することも、GDK ランタイムより新しくなくなった時点で削除することもできます。

バックグラウンド入力や入力フォーカスに関するものなど、PC 固有のサイドロードの制限事項は、XBOX 本体には適用されません。両方のプラットフォームでのサイドロードの詳細については、[GameInput のサイドロード](https://docs.xbox.com/ja-jp/build/core-features/common/input/overviews/input-agility-redistributable.md) を参照してください。

## 利用可能な API バージョンを確認する

ランタイムがサポートしていない API バージョンをゲームが要求すると、GameInput は `E_NOINTERFACE` で失敗します。これは、[GameInputCreate](https://docs.xbox.com/ja-jp/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.
}
```

v0 のコードと v4 のコードを組み合わせるなど、ゲームで複数の API バージョンを使用するには、[1 つのアプリケーションで複数の GameInput API バージョンを使用する](https://docs.xbox.com/ja-jp/build/core-features/common/input/overviews/input-version-interop.md) を参照してください。

## 関連項目

[NuGet を使用した PC およびコンソール向け GameInput](https://docs.xbox.com/ja-jp/build/core-features/common/input/overviews/input-nuget.md)\
[GameInput のサイドロード](https://docs.xbox.com/ja-jp/build/core-features/common/input/overviews/input-agility-redistributable.md)\
[GameInput API のバージョン管理](https://docs.xbox.com/ja-jp/build/core-features/common/input/overviews/input-versioning.md)\
[1 つのアプリケーションで複数の GameInput API バージョンを使用する](https://docs.xbox.com/ja-jp/build/core-features/common/input/overviews/input-version-interop.md)\
[GameInputInitialize](https://docs.xbox.com/ja-jp/reference/input/gameinput/functions/gameinputinitialize.md)


## Related topics

- [GameInput のサイドロード](https://docs.xbox.com/ja-jp/build/core-features/common/input/overviews/input-agility-redistributable.md)
- [NuGet を使用した PC およびコンソール向け GameInput](https://docs.xbox.com/ja-jp/build/core-features/common/input/overviews/input-nuget.md)
- [GameInput API のバージョン管理](https://docs.xbox.com/ja-jp/build/core-features/common/input/overviews/input-versioning.md)
- [GameInput のよくある質問](https://docs.xbox.com/ja-jp/build/core-features/common/input/overviews/input-faq.md)
- [GameInputInitialize](https://docs.xbox.com/ja-jp/reference/input/gameinput/functions/gameinputinitialize.md)