> ## 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만 제공합니다. NuGet 패키지는 2025년 10월 GDK 이전의 GDK 릴리스에서는 지원되지 않습니다.

## API v1 이상 사용

API v1 이상을 사용하려면 프로젝트에 [Microsoft.GameInput](https://www.nuget.org/packages/Microsoft.GameInput) NuGet 패키지를 추가하고, GDK의 헤더와 `GameInput.lib` 대신 이 패키지의 헤더와 `GameInput.lib`로 컴파일하고 링크하세요. NuGet 패키지의 주 버전은 해당 헤더가 정의하는 가장 높은 API 버전과 일치합니다. 예를 들어 4.x 패키지에는 v4 API가 포함되어 있습니다. 자세한 내용은 [NuGet으로 사용하는 PC와 콘솔용 GameInput](https://docs.xbox.com/ko/build/core-features/common/input/overviews/input-nuget.md)을 참조하세요.

콘솔에 다른 것을 설치할 필요는 없습니다. NuGet 패키지의 `GameInput.lib`와만 링크하면 게임은 GDK에 포함된 GameInput 런타임을 사용하며, [지원되는 API 버전](#supported-api-versions) 표에 나온 것처럼 런타임이 지원하는 API 버전은 GDK 릴리스에 따라 제한됩니다.

## 이전 GDK에서 API v4 사용

2025년 10월 GDK부터 2026년 10월 GDK 전까지(2026년 10월 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의 런타임을 사용하며, 이 런타임은 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/ko/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/ko/build/core-features/common/input/overviews/input-agility-redistributable.md)을 참조하세요.

## 사용 가능한 API 버전 확인

게임이 런타임에서 지원하지 않는 API 버전을 요청하면 GameInput은 `E_NOINTERFACE`와 함께 실패합니다. 이는 [GameInputCreate](https://docs.xbox.com/ko/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 버전을 사용하려면 [하나의 애플리케이션에서 여러 GameInput API 버전 사용](https://docs.xbox.com/ko/build/core-features/common/input/overviews/input-version-interop.md)을 참조하세요.

## 참고 항목

[NuGet으로 사용하는 PC와 콘솔용 GameInput](https://docs.xbox.com/ko/build/core-features/common/input/overviews/input-nuget.md)\
[GameInput 사이드로딩](https://docs.xbox.com/ko/build/core-features/common/input/overviews/input-agility-redistributable.md)\
[GameInput API 버전 관리](https://docs.xbox.com/ko/build/core-features/common/input/overviews/input-versioning.md)\
[하나의 애플리케이션에서 여러 GameInput API 버전 사용](https://docs.xbox.com/ko/build/core-features/common/input/overviews/input-version-interop.md)\
[GameInputInitialize](https://docs.xbox.com/ko/reference/input/gameinput/functions/gameinputinitialize.md)


## Related topics

- [GameInput 사이드로딩](https://docs.xbox.com/ko/build/core-features/common/input/overviews/input-agility-redistributable.md)
- [NuGet으로 사용하는 PC와 콘솔용 GameInput](https://docs.xbox.com/ko/build/core-features/common/input/overviews/input-nuget.md)
- [GameInput API 버전 관리](https://docs.xbox.com/ko/build/core-features/common/input/overviews/input-versioning.md)
- [GameInput 자주 묻는 질문](https://docs.xbox.com/ko/build/core-features/common/input/overviews/input-faq.md)
- [GameInputVersion](https://docs.xbox.com/ko/reference/input/gameinput/structs/gameinputversion.md)