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

# 게임 상태에 따라 터치 컨트롤 레이아웃 변경

> 게임 상태에 따라 터치 컨트롤 레이아웃 변경

게임은 플레이어에게 표시되는 터치 레이아웃을 변경하거나 현재 표시된 레이아웃이 사용하는 상태를 수정할 수 있습니다. 두 가지 방법을 함께 사용하여 플레이어를 위한 가장 자연스러운 경험을 만들 수 있습니다.

**[레이아웃 변경](#change_layout)**

레이아웃 변경은 다음과 같은 경우에 사용해야 합니다.

* 서로 다른 컨트롤 방식 간 전환(예: 차량 운전 및 1인칭 슈터)
* 터치 레이아웃을 일시적으로 숨김(전체 터치 경험을 하려면, 시네마틱 경험을 활성화하려면 등)

**[상태 변경](#change_state)**

터치 적응 번들의 컨텍스트 부분에 포함된 게임 상태를 변경하는 것은 다음과 같은 경우에 사용해야 합니다.

* 플레이어의 현재 게임 상태에 따라 컨트롤의 이미지/아이콘 수정. 몇 가지 예:
  * 플레이어가 선택한 무기에 따라 사격 버튼의 이미지를 변경합니다.
  * 플레이어가 현재 인벤토리에 가지고 있는 아이템에 따라 능력 이미지를 변경합니다.
* 플레이어의 현재 게임 상태에 따라 컨트롤의 시각적 상태(가시성 및 활성화됨) 수정. 몇 가지 예:
  * 플레이어에게 추가 탄약이 없을 때 재장전 버튼을 비활성화합니다.
  * 플레이어가 상호 작용할 수 있는 아이템에 접근할 때 상호 작용 버튼을 표시하고(멀어지면 보이지 않게).

<a id="change_layout" />

## 런타임에 레이아웃 변경

**지정된 레이아웃 표시**
게임은 새 레이아웃을 표시하기 위해 [`XGameStreamingShowTouchControlLayout`](/reference/system/xgamestreaming/functions/xgamestreamingshowtouchcontrollayout) API를 사용해야 합니다.

**현재 레이아웃 숨기기**
게임은 현재 표시된 레이아웃을 숨기기 위해 [`XGameStreamingHideTouchControls`](/reference/system/xgamestreaming/functions/xgamestreaminghidetouchcontrols) API를 사용해야 합니다.

게임의 현재 상태에 따라 게임이 레이아웃을 설정하는 방법의 예:

```C++ theme={null}
void OnGameStateChanged(GameState newState)
{
    // Toggle to the set of touch overlay controls which best match the new state of the game
    switch (newState)
    {
    case GameState::FirstPersonAction:
        XGameStreamingShowTouchControlLayout("FirstPersonAction");
        break;
    case GameState::Driving:
        XGameStreamingShowTouchControlLayout("Driving");
        break;
    case GameState::CutScene:
        // Don't show any touch overlay controls while the cut scene is rendering
        XGameStreamingHideTouchControls();
        break;
    }
}
```

<a id="change_state" />

## 런타임에 상태 변경

게임 실행 시 초기 상태는 터치 적응 번들에 포함된 [기본 상태](/build/core-features/common/game-streaming/game-streaming-touch-touch-adaptation-bundle#context)로 정의됩니다. 터치 컨트롤 레이아웃에서 컨트롤은 런타임에 변경될 수 있는 속성에 대한 상태를 참조해야 합니다.

게임은 런타임 중에 상태를 업데이트하기 위해 `XGameStreamingUpdateTouchControlsState` API를 활용할 수 있습니다.

예를 들어, 다음은 비활성화 상태로 시작하지만 해당 기능을 가져야 할 때 활성화되는 "재장전" 컨트롤을 갖도록 사용됩니다.

```JSON theme={null}
//Example context file
{
  "$schema": "https://raw.githubusercontent.com/microsoft/xbox-game-streaming-tools/main/touch-adaptation-kit/schemas/context/v3.0/context.json",

  "state": {
    "enableReload": false
  }
}

//Example control in the layout:
{
    "type": "button",
    "action": "leftBumper",
    "enabled": {
        "$ref": "../../context.json#/state/enableReload"
    }
    ...
}
```

게임은 상태를 업데이트하기 위해 API 호출을 수행합니다.

```C++ theme={null}

// In this example, after the player has switched their active weapon - the game updates the
// enabled state of reload based on whether the player has extra magazines.
//
// Assumes passing in game structure that includes the active weapon with appropriate state.
//

void GameStreamingClientManager::UpdateStateAfterItemsChange(const playerWeapon& playerWeapon)
{
    // create an update for whether the reload button should be enabled
    XGameStreamingTouchControlsStateOperation reloadEnabled;
    reloadEnabled.operationKind = XGameStreamingTouchControlsStateOperationKind::Replace;
    reloadEnabled.path = "/enableReload";
    reloadEnabled.valueKind = XGameStreamingTouchControlsStateValueKind::Bool;
    reloadEnabled.booleanValue = playerWeapon.activeWeapon.reloadClips > 0;

    // combine all the updates into the update state call and make the call
    XGameStreamingTouchControlsStateOperation[1] updateOperations = {reloadEnabled};

    XGameStreamingUpdateTouchControlsState(updateOperations, _countof(updateOperations));
}
```


## Related topics

- [XBOX 게임 스트리밍용 터치 컨트롤 레이아웃 구축](/ko/build/core-features/common/game-streaming/building-touch-layouts/index.md)
- [터치 컨트롤 레이아웃 구축](/ko/build/core-features/common/game-streaming/building-touch-layouts/game-streaming-touch-building-touch-layout.md)
- [표준 XBOX 컨트롤러 터치 컨트롤 레이아웃](/ko/build/core-features/common/game-streaming/building-touch-layouts/samples/game-streaming-touch-tak-sample-full-layout.md)
- [격투 터치 컨트롤 레이아웃](/ko/build/core-features/common/game-streaming/building-touch-layouts/samples/game-streaming-touch-tak-sample-fighter.md)
- [2D 플랫포머 터치 컨트롤 레이아웃](/ko/build/core-features/common/game-streaming/building-touch-layouts/samples/game-streaming-touch-tak-sample-platformer.md)