> ## 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.

# GameInput 사이드로딩

> GameInput 재배포 가능 패키지를 설치하는 대신 게임과 함께 GameInput 런타임을 배포하는 방법을 설명합니다.

GameInput 4.0부터는 GameInput 런타임인 `GameInputRedist.dll`을 게임 실행 파일과 같은 디렉터리에 배포할 수 있습니다. 이를 *사이드로딩*이라고 합니다. 사이드로드된 런타임을 사용하면 GameInput 재배포 가능 패키지가 설치되어 있지 않거나 이전 버전이 설치된 시스템에서도 게임이 빌드 및 테스트에 사용한 GameInput 기능과 수정 사항을 사용할 수 있습니다. 이 모델은 DirectX Agility SDK에서 사용하는 모델과 유사합니다.

사이드로딩은 PC와 XBOX 콘솔에서 지원됩니다. XBOX에서 사이드로딩을 사용하려면 2025년 10월 GDK(2510) 이상이 필요하며, 이를 통해 게임은 2026년 10월 GDK 이전의 API v4처럼 GDK 런타임이 지원하는 것보다 최신 API 버전을 사용할 수 있습니다. 자세한 내용은 [XBOX 콘솔의 GameInput](https://docs.xbox.com/ko/build/core-features/common/input/overviews/input-xbox.md)을 참조하세요.

> [!NOTE]
>
> PC에서 GameInput을 배포하는 데는 여전히 GameInput 재배포 가능 패키지를 설치하는 방법이 권장됩니다. 설치된 런타임은 모든 GameInput 기능을 지원하고, 모든 애플리케이션에서 공유되며, 게임과 독립적으로 업데이트됩니다. 배포 채널에서 설치 프로그램 실행을 지원하지 않는 경우나 개발 및 테스트 컴퓨터처럼 재배포 가능 패키지를 설치하는 것이 현실적이지 않을 때 사이드로딩을 사용하세요.

## 사이드로드 가능한 런타임 가져오기

[Microsoft.GameInput](https://www.nuget.org/packages/Microsoft.GameInput) NuGet 패키지에는 다음 위치에 사이드로드 가능한 런타임이 포함되어 있습니다.

| 패키지 내 경로 | 내용 |
| - | - |
| `native\bin\x64\` | 64비트 PC 게임용 `GameInputRedist.dll` 및 `GameInputRawInputProxy.exe` |
| `native\bin\x86\` | 32비트 PC 게임용 `GameInputRedist.dll` 및 `GameInputRawInputProxy.exe` |
| `native\bin\arm64\` | Arm64 PC 게임용 `GameInputRedist.dll` 및 `GameInputRawInputProxy.exe` |
| `native\bin\xbox\` | XBOX 콘솔용 `GameInputRedist.dll` |

NuGet 패키지는 이러한 파일을 빌드 출력에 복사하지 않습니다. 대상 플랫폼과 아키텍처에 맞는 파일을 게임 실행 파일 옆에 복사하는 단계를 빌드 또는 패키징 프로세스에 추가하세요.

PC에서는 `GameInputRawInputProxy.exe`도 `GameInputRedist.dll`과 같은 디렉터리에 배포하세요. 사이드로드된 런타임은 이 도우미 프로세스를 사용하여 키보드 및 마우스 입력을 받습니다. 사이드로드된 런타임은 바로 옆에 있는 프록시만 사용하며, 설치된 재배포 가능 패키지의 프록시는 사용하지 않습니다. 프록시가 없으면 런타임은 게임 프로세스에서 키보드 및 마우스 입력을 받는 방식으로 대체됩니다.

> [!WARNING]
>
> PC 런타임과 XBOX 런타임은 파일 이름이 같습니다. 대상 플랫폼에 맞는 사본을 배포해야 합니다. 잘못된 사본을 배포하면 `GameInputCreate`가 `HRESULT_FROM_WIN32(ERROR_EXE_MACHINE_TYPE_MISMATCH)`(0x800700D8)와 함께 실패합니다.

## 런타임 선택 방식

사이드로드된 런타임을 사용하기 위해 코드를 변경할 필요는 없습니다. NuGet 패키지의 `gameinput.lib`와 링크하고 평소처럼 [GameInputCreate](https://docs.xbox.com/ko/reference/input/gameinput/functions/gameinputcreate.md)를 호출하세요. `GameInputCreate`가 처음 호출되면 `gameinput.lib`의 로더가 다음 위치에서 GameInput 런타임을 찾습니다.

1. 시스템 디렉터리에 있는 기본 제공 런타임인 `GameInput.dll`
2. 시스템 디렉터리 또는 GameInput 재배포 가능 패키지가 설치된 디렉터리에 있는, 설치된 재배포 가능 패키지 런타임인 `GameInputRedist.dll`
3. 게임 실행 파일 디렉터리에 있는 사이드로드된 런타임인 `GameInputRedist.dll`

로더는 파일 버전이 가장 높은 런타임을 사용합니다. 두 런타임의 버전이 같으면 설치된 재배포 가능 패키지보다 사이드로드된 런타임이 우선하고, 기본 제공 런타임보다 설치된 재배포 가능 패키지가 우선합니다.

PC에서 사이드로드된 런타임이 로드되었고 시스템에 더 최신 GameInput 런타임이 설치되어 있으면, 사이드로드된 런타임은 모든 호출을 더 최신의 설치된 런타임으로 전달합니다. 따라서 사이드로드된 런타임은 최소 버전 역할을 합니다. 즉, 게임은 항상 함께 제공한 버전 또는 더 최신의 설치된 버전을 사용합니다. 이 경우에도 게임은 여전히 사이드로드된 것으로 취급되며, 다음 섹션의 제한 사항이 계속 적용됩니다.

## 제한 사항

PC에서 일부 GameInput 기능은 입력 포커스를 관리하는 GameInput 서비스처럼 GameInput 재배포 가능 패키지가 설치된 경우에만 존재하는 구성 요소에 의존합니다. PC에서 게임이 사이드로드된 런타임을 사용하는 경우 다음 제한 사항이 적용됩니다. 이러한 제한 사항은 XBOX 콘솔에는 적용되지 않습니다.

* [IGameInput::EnableBackgroundInput](https://docs.xbox.com/ko/reference/input/gameinput/interfaces/igameinput/methods/igameinput_enablebackgroundinput.md)을 `true`로 호출해도 아무 효과가 없습니다. 백그라운드 입력을 사용하도록 설정하면 시스템 버튼도 점유하게 되는데, 사이드로드된 런타임은 시스템 버튼을 점유할 수 없기 때문입니다.
* 입력 포커스가 GameInput 서비스에서 관리되지 않으므로 GameInput은 게임에 포커스가 있는지 여부에 따라 입력을 일관되게 필터링하지 않습니다. 장치에 따라 게임에 포커스가 없는 동안에도 입력을 받을 수도 있고 받지 않을 수도 있습니다. 게임이 일관된 포커스 동작에 의존하는 경우 입력에 따라 작업하기 전에 게임에 포커스가 있는지 확인하거나, GameInput 재배포 가능 패키지를 설치하세요.
* API 버전 v1부터 v3까지에서 `IGameInput::SetFocusPolicy`는 `GameInputDefaultFocusPolicy`와 `GameInputEnableBackgroundInput`만 허용합니다. 플래그 조합을 포함한 다른 포커스 정책은 무시됩니다.
* API 버전 v1부터 v3까지에서 `IGameInput::RegisterSystemButtonCallback`은 `GAMEINPUT_E_FEATURE_REQUIRES_INSTALL`(0x838AD02B)과 함께 실패합니다. API 버전 v4에서는 시스템 버튼이 `GameInputKindSystemButton` 종류의 판독값으로 보고되며, 이는 사이드로드된 런타임에서도 작동합니다. 자세한 내용은 [IGameInputReading::GetSystemButtonState](https://docs.xbox.com/ko/reference/input/gameinput/interfaces/igameinputreading/methods/igameinputreading_getsystembuttonstate.md)를 참조하세요.

## 권장 사항

* GameInput 헤더, `gameinput.lib`, 사이드로드된 런타임에 동일한 버전의 NuGet 패키지를 사용하세요.
* GameInput 재배포 가능 패키지가 설치된 경우와 설치되지 않은 경우 모두에서 게임을 테스트하세요.
* PC에서 게임에 백그라운드 입력이나 일관된 포커스 동작이 필요한 경우 런타임을 사이드로드하는 대신, 또는 사이드로드와 함께 GameInput 재배포 가능 패키지를 설치하세요. 자세한 내용은 [NuGet으로 사용하는 PC와 콘솔용 GameInput](https://docs.xbox.com/ko/build/core-features/common/input/overviews/input-nuget.md)을 참조하세요.

## 참고 항목

[NuGet으로 사용하는 PC와 콘솔용 GameInput](https://docs.xbox.com/ko/build/core-features/common/input/overviews/input-nuget.md)\
[XBOX 콘솔의 GameInput](https://docs.xbox.com/ko/build/core-features/common/input/overviews/input-xbox.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-fundamentals.md)\
[GameInput API 참조](https://docs.xbox.com/ko/reference/input/gameinput/gameinput_members.md)


## Related topics

- [XBOX 콘솔의 GameInput](https://docs.xbox.com/ko/build/core-features/common/input/overviews/input-xbox.md)
- [GameInput API 버전 관리](https://docs.xbox.com/ko/build/core-features/common/input/overviews/input-versioning.md)
- [IGameInput::EnableBackgroundInput](https://docs.xbox.com/ko/reference/input/gameinput/interfaces/igameinput/methods/igameinput_enablebackgroundinput.md)
- [하나의 애플리케이션에서 여러 GameInput API 버전 사용](https://docs.xbox.com/ko/build/core-features/common/input/overviews/input-version-interop.md)
- [IGameInput::SetFocusPolicy (사용되지 않음)](https://docs.xbox.com/ko/reference/input/gameinput/deprecated/interfaces/igameinput/methods/igameinput_setfocuspolicy.md)