메인 콘텐츠로 건너뛰기
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만 제공합니다. NuGet 패키지는 2025년 10월 GDK 이전의 GDK 릴리스에서는 지원되지 않습니다.

API v1 이상 사용

API v1 이상을 사용하려면 프로젝트에 Microsoft.GameInput NuGet 패키지를 추가하고, GDK의 헤더와 GameInput.lib 대신 이 패키지의 헤더와 GameInput.lib로 컴파일하고 링크하세요. NuGet 패키지의 주 버전은 해당 헤더가 정의하는 가장 높은 API 버전과 일치합니다. 예를 들어 4.x 패키지에는 v4 API가 포함되어 있습니다. 자세한 내용은 NuGet으로 사용하는 PC와 콘솔용 GameInput을 참조하세요. 콘솔에 다른 것을 설치할 필요는 없습니다. NuGet 패키지의 GameInput.lib와만 링크하면 게임은 GDK에 포함된 GameInput 런타임을 사용하며, 지원되는 API 버전 표에 나온 것처럼 런타임이 지원하는 API 버전은 GDK 릴리스에 따라 제한됩니다.

이전 GDK에서 API v4 사용

2025년 10월 GDK부터 2026년 10월 GDK 전까지(2026년 10월 GDK는 제외)의 GDK 릴리스에서 API v4를 사용하려면 GameInput 런타임을 사이드로드하세요.
  1. 프로젝트에 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은 계속 작동합니다.
NuGet 패키지에는 PC용과 XBOX용 GameInputRedist.dll의 별도 사본이 포함되어 있습니다. XBOX 게임에는 native\bin\xbox\의 사본만 배포하세요. 자세한 내용은 GameInput 사이드로딩을 참조하세요.

런타임 선택 방식

GameInput 런타임 사이드로딩은 PC뿐 아니라 XBOX 콘솔에서도 지원됩니다. XBOX에서 게임이 처음으로 GameInput을 만들 때, NuGet 패키지의 GameInput.lib는 타이틀과 함께 번들로 제공되는 Game OS의 GameInput 런타임과 사이드로드된 런타임(배포된 경우)을 비교하여 버전이 더 높은 런타임을 사용합니다. 그 결과는 다음과 같습니다.
  • GDK 런타임보다 최신인 사이드로드된 런타임을 사용하면 게임에서 최신 API 버전과 수정 사항을 사용할 수 있습니다.
  • 게임이 사이드로드된 런타임보다 최신 런타임이 포함된 GDK 릴리스로 이동하면 게임은 GDK 런타임을 사용합니다. 사이드로드된 런타임을 계속 배포하거나, 더 이상 GDK 런타임보다 최신이 아니면 제거할 수 있습니다.
백그라운드 입력 및 입력 포커스 관련 제한 사항과 같은 PC 전용 사이드로딩 제한 사항은 XBOX 콘솔에는 적용되지 않습니다. 두 플랫폼에서의 사이드로딩에 대한 자세한 내용은 GameInput 사이드로딩을 참조하세요.

사용 가능한 API 버전 확인

게임이 런타임에서 지원하지 않는 API 버전을 요청하면 GameInput은 E_NOINTERFACE와 함께 실패합니다. 이는 GameInputCreate와 QueryInterface 모두에 적용됩니다. 게임이 최신 API 버전 없이도 실행될 수 있다면 이 오류를 확인하고 이전 버전의 기능으로 대체하세요.
v0 코드와 v4 코드를 함께 사용하는 경우처럼 게임에서 둘 이상의 API 버전을 사용하려면 하나의 애플리케이션에서 여러 GameInput API 버전 사용을 참조하세요.

참고 항목

NuGet으로 사용하는 PC와 콘솔용 GameInput
GameInput 사이드로딩
GameInput API 버전 관리
하나의 애플리케이션에서 여러 GameInput API 버전 사용
GameInputInitialize
마지막 수정일 2026년 11월 6일