> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 게임 런처와 핸드헬드

> Windows에서 Full Screen Experience 감지, 리소스 제한, 웹 기술, 가이드 버튼 처리, 포그라운드 관리를 갖춘 핸드헬드 게임 런처를 만드세요.

게임 런처는 여러 형태를 가질 수 있습니다. 플레이어가 게임을 시작할 때 일부 게임은 곧바로 시작되지 않고 런처가 먼저 시작됩니다. 많은 게임과 퍼블리셔는 플레이어의 참여를 유지하는 방법으로 런처에 의존합니다. 런처는 게임이 실제로 시작되기 전에 옵션을 설정하거나 게임 웹사이트를 방문하거나 다른 게임 기능과 상호작용하는 데 사용될 수도 있습니다. 이러한 런처들은 게이밍 핸드헬드 기기에서 잘 동작해야 합니다. 런처도 게임과 마찬가지로 다음 문서의 안내를 따라야 합니다.

* [XBOX가 설계한 Handheld Compatibility 프로그램 가이드라인](/build/gdk-and-engines/handheld/handheld-guidance)
* [핸드헬드 기기 추가 고려 사항](/build/gdk-and-engines/handheld/handheld-considerations)

핸드헬드 기기에서 게임이 동작하도록 하기 위해 제공되는 안내는 런처에도 동일하게 적용되지만, 개발자가 유의해야 할 몇 가지 추가 고려 사항이 있습니다.

## Full Screen Experience

게이밍 핸드헬드가 시작될 때 OEM은 전용 게이밍 앱이 전체 화면으로 실행되도록 구성할 수 있습니다. 예를 들어 ASUS ROG XBOX Ally X에서는 기기가 XBOX 앱의 전체 화면 버전으로 시작됩니다. 플레이어는 자신의 게임 카탈로그에 쉽게 접근할 수 있고 새로운 게임을 탐색하고 구매할 기회를 얻습니다.

OEM은 기본 전체 화면 앱을 구성할 수 있습니다. 이 구성이 설정되면 다음과 같이 됩니다.

* 작업 표시줄, 일부 시작 앱, 기타 서비스와 같은 많은 표준 Windows 경험이 억제됩니다. 이로 인해 게임에 사용할 수 있는 메모리가 늘어납니다.
* 기본 앱이 한 번에 게임 하나만 실행되도록 정책을 시행할 수 있습니다.
* 절전 또는 최대 절전 상태에서 다시 시작할 때 플레이어는 게임 또는 앱으로 돌아갑니다. 절전 또는 최대 절전 이전에 게임과 앱이 닫혔다면 플레이어는 기본 게이밍 앱으로 돌아갑니다.
* 종료 상태에서 기기가 켜지면 기본 앱이 자동으로 실행됩니다.
* 게임과 애플리케이션이 자동으로 전체 화면 모드로 실행됩니다.

전반적으로 Windows는 이를 *full screen experience*(FSE)라고 부릅니다.

게이밍 핸드헬드에서 FSE가 활성 상태인지 확인하려면 게임이 `IsGamingFullScreenExperienceActive` 함수를 호출하도록 하세요. 다음 코드 예시는 이 함수를 사용하는 방법을 보여줍니다.

```cpp theme={null}
#include <gamingexperience.h>
#pragma comment(lib, "windowsapp.lib")

if (IsApiSetImplemented("api-ms-win-gaming-experience-l1-1-0"))
{
   if (IsGamingFullScreenExperienceActive())
   {
      // Full Screen Experiences (FSE) 활성
   }
}
```

기기의 플레이어는 FSE를 켜고 끌 수 있습니다. 앱과 게임은 **RegisterGamingFullScreenExperienceChangeNotification** 함수로 변경 알림을 등록해 이러한 변경에 대해 통지받을 수 있습니다. 변경 알림 등록을 해제하려면 **UnregisterGamingFullScreenExperienceChangeNotification** 함수를 사용하세요. 다음 코드 예시는 변경 알림을 등록하는 방법을 보여줍니다. 알림에 응답할 때 반드시 FSE의 현재 상태를 조회하세요.

```cpp theme={null}
static GAMING_FULL_SCREEN_EXPERIENCE_REGISTRATION g_fseHandle = nullptr;

// ...

if (IsApiSetImplemented("api-ms-win-gaming-experience-l1-1-0"))
{
  RegisterGamingFullScreenExperienceChangeNotification([](PVOID)
  {
    // Full Screen Experience (FSE) 변경, 활성 여부 조회
    if (IsGamingFullScreenExperienceActive())
    {
      // FSE가 활성으로 변경됨
    }
    else
    {
      // FSE가 비활성으로 변경됨
    }
  }, nullptr, &g_fseHandle);
}

// ...

if (IsApiSetImplemented("api-ms-win-gaming-experience-l1-1-0"))
{
   UnregisterGamingFullScreenExperienceChangeNotification(g_fseHandle);
}
```

전체 화면 경험에 대한 정보를 얻으려면 Windows SDK 버전 10.0.26100.3916 이상을 사용하세요. 이 버전은 2025년 4월에 출시되었습니다.

## 리소스

게임 런처는 종종 백그라운드에서 실행되며 메모리와 같은 자원을 소비합니다. 게이밍 핸드헬드는 일반 PC에 비해 메모리와 리소스가 제한적입니다. 따라서 게임 런처는 플레이어에게 최상의 경험을 제공하기 위해 모범 사례를 따라야 합니다.

* 런처가 포그라운드에 있지 않을 때 리소스 사용을 최소화하세요.
* 런처가 게임을 성공적으로 실행한 후에는 런처를 종료(또는 최소한 리소스 사용을 축소)해 게임에 더 많은 리소스를 제공하는 것을 고려하세요.
* FSE에서는 플레이어가 사용할 수 없으므로 작업 트레이에 설치하지 마세요.
* 플레이어가 런처를 손쉽게 닫을 수 있도록 하세요.
* 게임과 마찬가지로 런처가 [전력 사용](/build/gdk-and-engines/handheld/handheld-considerations#power)과 배터리 수명에 미치는 영향을 어떻게 최소화할지 고려하세요.

## 웹 기술

런처는 종종 HTML에 의존해 콘텐츠를 제공합니다. 런처의 다른 모든 부분과 게이밍 핸드헬드에서 잘 동작하기 위한 개발자 안내와 마찬가지로 다음 요구 사항을 준수하세요.

* HTML 콘텐츠는 얼굴로부터 30.5 cm 떨어져 있고 7인치(17.8 cm) 화면에서 기본적으로 잘 동작하고 판독 가능한 방식으로 기능해야 합니다.
* 모든 아이코노그래피가 기기에 정확해야 합니다.
* 텍스트 입력은 가상 키보드를 사용하고 물리 키보드를 요구하지 않아야 합니다.

가장 중요한 것은, 사용자가 게임패드로 모든 HTML 콘텐츠를 탐색할 수 있어야 한다는 점입니다. HTML Gamepad API를 사용해 웹으로 전달되는 모든 콘텐츠가 게임패드를 염두에 두고 설계되도록 하세요. 자세한 내용은 [Using the Gamepad API - Web APIs | MDN](https://developer.mozilla.org/en-US/docs/Web/API/Gamepad_API/Using_the_Gamepad_API)을 참조하세요.

## 게임 오버레이와 가이드 버튼

FSE가 활성화되어 있을 때 Windows는 컨트롤러의 **Guide** 버튼에 대한 배타적 액세스 권한을 가집니다. Full Screen Experience에서 플레이어가 **Guide** 버튼을 짧게 누르면 XBOX Game Bar가 표시됩니다. 플레이어는 시스템 유틸리티와 OEM 위젯에 빠르게 액세스할 수 있습니다. XBOX Game Bar는 Game Bar Widget SDK를 통해 확장 가능합니다. 자세한 내용은 [XBOX Game Bar SDK](https://learn.microsoft.com/gaming/game-bar/)를 참조하세요.

**Guide** 버튼을 사용하는 기존 경험과의 호환성을 보장하기 위해 플레이어는 **View+Menu**를 눌러 포커스된 애플리케이션에 **Guide** 버튼을 보낼 수 있습니다. 컨트롤러 드라이버는 입력 페이로드의 일부로 **View**, **Menu**, **Guide** 버튼 입력을 모두 전송합니다. **Guide** 버튼을 길게 누르면 최적화된 **Task Switcher**가 열리며, 선택된 앱에 **View**를 눌러 **Guide** 버튼 입력을 보낼 수 있습니다.

## 포그라운드와 백그라운드 관리

게임과 런처는 FSE에서 Windows 포그라운드 관리를 위해 특별한 작업을 할 필요가 없습니다. FSE 활성 여부와 관계없이 Windows에서 포그라운드 창 관리가 올바르게 동작하도록 하세요.

Windows는 플레이어가 상호작용하는 창을 계속 제어할 수 있도록 설계되었습니다. 포그라운드 창은 다른 앱을 포그라운드로 가져올 수 있지만, 백그라운드 앱은 포그라운드를 가져갈 수 없습니다. Windows는 포그라운드 제어를 운영 체제 수준의 권한으로 강제합니다.

게임과 런처에 흔한 일부 시나리오에서는 앱이 포그라운드 관리를 더 명시적으로 제어해야 합니다. 예를 들어 어떤 게임은 단일 인스턴스만 유지하며, 새 프로세스의 활성화를 이미 백그라운드에서 실행 중인 프로세스로 리다이렉트할 수 있습니다. 새 프로세스는 포그라운드 권한을 이미 실행 중인 프로세스로 명시적으로 전송해야 합니다. 게임은 [AllowSetForegroundWindow](https://learn.microsoft.com/windows/win32/api/winuser/nf-winuser-allowsetforegroundwindow), [CoAllowSetForegroundWindow](https://learn.microsoft.com/windows/win32/api/objbase/nf-objbase-coallowsetforegroundwindow), [SetForegroundWindow](https://learn.microsoft.com/windows/win32/api/winuser/nf-winuser-setforegroundwindow)를 사용해 이러한 전송을 처리합니다.

Windows의 게임 기본 상태인 FSE 비활성일 때, 잘못된 포그라운드 동작은 플레이어에게 미치는 영향이 거의 없습니다. 앱의 아이콘이 작업 표시줄에서 깜박여 주의를 끌고, 플레이어가 아이콘을 선택하면 앱이 포그라운드로 이동합니다.

FSE가 활성 상태일 때는 작업 표시줄이 숨겨져 있습니다. 그 결과 플레이어가 백그라운드 창을 알아차리기 어렵고 이를 보정할 수 없습니다.


## Related topics

- [PC 핸드헬드 개요](/ko/build/gdk-and-engines/handheld/overview.md)
- [XBOX PC Remote Tools FAQ 및 문제 해결 가이드](/ko/tools/tools-pc/xbox-pc-remote-tools/faq.md)
- [핸드헬드 기기 추가 고려 사항](/ko/build/gdk-and-engines/handheld/handheld-considerations.md)
- [Handheld Compatibility 가이드라인 및 테스트 케이스](/ko/build/gdk-and-engines/handheld/handheld-guidelines-and-testcases.md)
- [성능과 전력 효율의 균형](/ko/build/gdk-and-engines/handheld/handheld-performance.md)