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

# 터치 적응 레이아웃용 사용자 지정 자산

> 터치 적응 레이아웃용 사용자 지정 자산

터치 적응 레이아웃의 컨트롤에 의미 아이콘을 제공하는 것은 각 컨트롤이 무엇을 하도록 되어 있는지 게임 플레이어에게 전달하는 효과적인 방법입니다. XBOX 컨트롤러에 익숙한 플레이어는 일반적인 A, B, X, Y 버튼을 빠르게 이해하지만, 다른 플레이어는 컨트롤이 트리거할 동작을 표시하는 경우 터치 컨트롤을 더 쉽게 이해할 수 있습니다. 예를 들어, XBOX A가 있는 버튼 대신 사람이 점프하는 이미지가 있는 버튼은 플레이어가 각 컨트롤이 수행할 동작을 이해하는 데 도움이 될 수 있습니다.

컨트롤에 대해 기본 제공 [아이콘](/ko/reference/system/touchadaptationkit/types/game-streaming-touch-icon) 세트에서 선택할 수도 있지만, 게임의 시각적 미학에 맞는 아트워크로 사용자 지정할 수도 있습니다. 이렇게 하면 게임의 터치 컨트롤이 게임의 훨씬 더 필수적인 부분처럼 느껴져 게임 플레이 경험이 모바일에 더 네이티브하게 느껴집니다.

예를 들어, 다음은 표준 아이콘을 사용하여 만든 레이아웃입니다.

![의미 아이콘을 사용한 터치 레이아웃](https://mintcdn.com/microsoft-4404708b/UZTRJSf0emX1fheE/images/gdk/features/common/game-streaming-tak-custom-assets-icons.png?fit=max\&auto=format\&n=UZTRJSf0emX1fheE\&q=85\&s=6a1f17581b93194ad962f94c2bd59ac1)

그리고 다음은 사용자 지정 아트워크를 사용한 동일한 레이아웃입니다.

![사용자 지정 아트가 있는 터치 레이아웃](https://mintcdn.com/microsoft-4404708b/UZTRJSf0emX1fheE/images/gdk/features/common/game-streaming-tak-custom-assets-assets.png?fit=max\&auto=format\&n=UZTRJSf0emX1fheE\&q=85\&s=cdc5edd016dd0f9e47bd810b6af17c1a)

이 레이아웃이 게임 위에 로드되면 사용자 지정 아트워크가 터치 컨트롤의 시각적 스타일을 게임의 시각적 스타일과 연결하는 데 도움이 됩니다.

![게임 내 사용자 지정 아트가 있는 터치 레이아웃](https://mintcdn.com/microsoft-4404708b/UZTRJSf0emX1fheE/images/gdk/features/common/game-streaming-tak-custom-assets-game.png?fit=max\&auto=format\&n=UZTRJSf0emX1fheE\&q=85\&s=9e48c7c63b3a45b1759c8497f0cea0b5)

## 자산 파일

자산은 PNG 파일이며, 기본 해상도와 해당 기본 해상도의 1.5배, 2.0배, 3.0배, 4.0배 크기로 제공되어야 합니다. 이를 통해 스트리밍 클라이언트가 게임이 스트리밍되는 디바이스의 DPI에 따라 표시할 자산의 최상의 버전을 선택할 수 있습니다. 각 자산 유형의 기본 해상도는 [아래](#custom-asset-sizes)에 나열되어 있습니다.

Touch Adaptation Kit는 [자산 지역화](/ko/build/core-features/common/game-streaming/game-streaming-tak-localization.md)를 지원하므로 게임이 스트리밍되는 디바이스의 언어에 따라 다른 자산을 제공할 수 있습니다. 자산의 지역화된 각 버전에는 필요한 모든 해상도가 포함되어야 합니다.

디스크에 자산을 배치할 때 파일 구조는 먼저 [언어](/ko/build/core-features/common/game-streaming/game-streaming-tak-localization.md)별로, 그다음 자산 크기별로 구성됩니다. 예를 들어, 파일 구조는 다음과 같이 보일 수 있습니다.

```
assets/
    neutral/
        @1.0x/
            JoystickBackground.png
            JoystickKnobBackground.png
            JoystickKnobForeground.png
        @1.5x/
            JoystickBackground.png
            JoystickKnobBackground.png
            JoystickKnobForeground.png
        @2.0x/
            JoystickBackground.png
            JoystickKnobBackground.png
            JoystickKnobForeground.png
        @3.0x/
            JoystickBackground.png
            JoystickKnobBackground.png
            JoystickKnobForeground.png
        @4.0x/
            JoystickBackground.png
            JoystickKnobBackground.png
            JoystickKnobForeground.png
    fr/
        fr-CA/
            @1.0x/
                JoystickKnobForeground.png
            @1.5x/
                JoystickKnobForeground.png
            @2.0x/
                JoystickKnobForeground.png
            @3.0x/
                JoystickKnobForeground.png
            @4.0x/
                JoystickKnobForeground.png
        @1.0x/
            JoystickKnobBackground.png
        @1.5x/
            JoystickKnobBackground.png
        @2.0x/
            JoystickKnobBackground.png
        @3.0x/
            JoystickKnobBackground.png
        @4.0x/
            JoystickKnobBackground.png
```

이 설정에서 캐나다 프랑스어는 `fr-CA` `JoystickKnobForeground` 자산, `fr` `JoystickKnobBackground` 자산, `neutral` `JoystickBackground` 자산을 사용합니다. 프랑스어(프랑스)는 `JoystickKnobForeground` 및 `JoystickKnobBackground` 모두에 `fr` 자산을 사용하고 `JoystickBackground`에는 `neutral` 자산을 사용합니다. 다른 모든 언어는 모든 것에 `neutral` 자산을 사용합니다.

## 레이아웃에서 자산 참조

자산은 자산이 적용되는 컨트롤의 styles 섹션 내에서 참조됩니다. 자산을 참조하려면 스타일이 지정되는 항목의 유형이 "asset"이어야 하고 값은 PNG 확장자가 없는 자산 파일 이름이어야 합니다. 예를 들어, 위의 자산으로 스타일이 지정된 조이스틱은 다음과 같이 구성될 수 있습니다.

```json theme={null}
{
  "type": "joystick",
  "styles": {
    "default": {
      "background": {
        "type": "asset",
        "value": "JoystickBackground"
      },
      "knob": {
        "faceImage": {
          "type": "asset",
          "value": "JoystickKnobForeground"
        },
        "background": {
          "type": "asset",
          "value": "JoystickKnobBackground"
        }
      }
    }
  }
}
```

이 스타일을 감안할 때, 조이스틱에 사용되는 세 가지 자산 각각에 대해 Touch Adaptation Kit는 플레이어의 디바이스 언어와 DPI를 사용하여 레이아웃이 사용할 가장 잘 일치하는 자산을 찾습니다. 따라서 레이아웃은 사용할 언어나 자산 크기를 지정하지 않으며, Touch Adaptation Kit가 자동으로 가장 잘 일치하는 자산을 찾습니다.

### 변수 대체와 함께 자산 사용

[XGameStreamingUpdateTouchControlsStateOnClient](/ko/reference/system/xgamestreaming/functions/xgamestreamingupdatetouchcontrolsstateonclient.md) API를 사용하여 런타임에 레이아웃에서 사용하는 자산을 변경할 수도 있습니다. 이를 수행하려면 컨트롤에 대한 잠재적 자산 목록이 터치 적응 번들의 `context.json` 파일에 정의되어야 합니다.

context.json:

```json theme={null}
{
    "$schema": "https://raw.githubusercontent.com/microsoft/xbox-game-streaming-tools/main/touch-adaptation-kit/schemas/context/v3.3/context.json",
    "definitions": {
      "potionButtonImages": [
        "Empty",
        "Healing",
        "Invisibility",
        "Mana"
      ]
    },
    "state": {
      "potionButtonFaceImage": "Empty"
    },
    "allowedStateValues": {
      "potionButtonFaceImage": {
        "$ref": "#/definitions/potionButtonImages"
      }
    }
  }
}
```

이는 레이아웃의 물약 버튼 이미지에 `Empty.png`, `Healing.png`, `Invisibility.png` 또는 `Mana.png` 중 어느 것도 사용할 수 있도록 번들의 컨텍스트를 설정합니다. 현재 선택된 이미지는 상태 변수 `potionButtonFaceImage`에 저장됩니다. 버튼 자체는 이 컨텍스트에 대한 참조로 구성됩니다.

layout.json:

```json theme={null}
{
  "type": "button",
  "styles": {
    "default": {
      "faceImage": {
        "type": "asset",
        "value": {
          "$ref": "../../context.json#/state/potionButtonFaceImage"
        }
      }
    }
  }
}
```

이는 버튼에 현재 컨텍스트의 potionButtonFaceImage 상태 변수에 저장된 자산을 얼굴 이미지로 사용하도록 지시합니다.

마지막으로, 게임이 이 버튼에 현재 표시되는 이미지를 변경하려는 경우 다음과 같은 코드를 사용합니다.

```c++ theme={null}
HRESULT ChangePotion(XGameStreamingClientId client, const char* potionName)
{
    XGameStreamingTouchControlsStateOperation updateOperations[1] = {};
    updateOperations[0].operationKind = XGameStreamingTouchControlsStateOperationKind::Replace;
    updateOperations[0].path = "/potionButtonFaceImage";
    updateOperations[0].value.valueKind = XGameStreamingTouchControlsStateValueKind::String;

    // potionName is one of "Empty", "Healing", "Invisibility", "Mana"
    updateOperations[0].value.stringValue = potionName;

    return XGameStreamingUpdateTouchControlsStateOnClient(client, _countof(updateOperations), updateOperations);
}
```

이 코드는 potionButtonFaceImage 상태 변수에 저장된 자산 이름을 변경하며, 이로 인해 이 상태를 스타일에서 참조하는 모든 레이아웃에 새로 선택된 자산이 나타납니다.

## 사용자 지정 자산 크기

다음 표는 사용자 지정 자산을 적용할 수 있는 각 컨트롤의 요소와 각 자산의 1.0배 크기에 대한 최대 픽셀 크기를 요약합니다.

| **컨트롤** | **스타일 지정 가능 요소** | **@1.0x 픽셀 크기** |
| - | - | - |
| ArcadeButton | background | 60 x 60 |
| | faceImage | 60 x 60 |
| Button | background | 60 x 60 |
| | faceImage | 60 x 60 |
| DirectionalPad | background | 60 x 60 |
| Joystick | background | 120 x 120 |
| | knob/background | 60 x 60 |
| | knob/faceImage | 60 x 60 |
| Throttle | knob/background | 60 x 60 |
| | knob/faceImage | 60 x 60 |
| Touchpad | background (renderAsButton = true) | 60 x 60 |
| | background (renderAsButton = false) | 120 x 120 |
| | faceImage | 60 x 60 |

ArcadeButton faceImage, Button faceImage, Joystick knob faceImage, Throttle knob faceImage 및 Touchpad faceImage 자산의 픽셀 크기는 다음과 같습니다.

| **크기 배율** | **픽셀 크기** |
| - | - |
| @1.0x | 60 x 60 |
| @1.5x | 90 x 90 |
| @2.0x | 120 x 120 |
| @3.0x | 180 x 180 |
| @4.0x | 240 x 240 |

ArcadeButton background, Button background, DirectonalPad background, Joystick knob background, Throttle knob background 및 Touchpad(renderAsButton=true 포함) background 자산의 픽셀 크기는 다음과 같습니다.

| **크기 배율** | **픽셀 크기** |
| - | - |
| @1.0x | 60 x 60 |
| @1.5x | 90 x 90 |
| @2.0x | 120 x 120 |
| @3.0x | 180 x 180 |
| @4.0x | 240 x 240 |

Joystick background 및 Touchpad(renderAsButton=false 포함) background 자산의 픽셀 크기는 다음과 같습니다.

| **크기 배율** | **픽셀 크기** |
| - | - |
| @1.0x | 120 x 120 |
| @1.5x | 180 x 180 |
| @2.0x | 240 x 240 |
| @3.0x | 360 x 360 |
| @4.0x | 480 x 480 |

## 이미지 양자화

터치 적응 번들을 빌드할 때 [TAK CLI](/ko/build/core-features/common/game-streaming/tak-command-line-tool/game-streaming-tak-command-line.md)는 생성되는 .takx 파일의 크기를 줄이기 위해 제공된 PNG에서 양자화를 수행합니다. 양자화가 자산의 모양에 영향을 미치지 않아야 하지만, 이미지를 만들 때 예상했던 것과 자산이 터치 레이아웃에 표시되는 것이 일치하는지 확인하는 것이 좋습니다.

양자화 프로세스가 이미지 렌더링 방식에 영향을 미치는 경우 번들을 빌드할 때 TAK CLI에 `--no-asset-optimization` 옵션을 전달하여 비활성화할 수 있습니다.


## Related topics

- [터치 적응 레이아웃용 고대비 모드](/ko/build/core-features/common/game-streaming/building-touch-layouts/game-streaming-tak-high-contrast-mode.md)
- [터치 컨트롤 레이아웃 구축](/ko/build/core-features/common/game-streaming/building-touch-layouts/game-streaming-touch-building-touch-layout.md)
- [터치 시작하기](/ko/build/core-features/common/game-streaming/game-streaming-getting-started-with-touch.md)
- [XBOX 게임 스트리밍용 터치 컨트롤 레이아웃 구축](/ko/build/core-features/common/game-streaming/building-touch-layouts/index.md)
- [Pack 명령](/ko/build/core-features/common/game-streaming/tak-command-line-tool/game-streaming-tak-command-line-pack-command.md)