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

# Directional Pad

> Directional Pad

# Directional Pad

게임패드의 방향 패드를 항상 매핑하는 방향 패드 컨트롤입니다.

## Properties

`type` - *"directionalPad"*. 컨트롤 유형을 지정합니다.

`scale` - *number*, *optional*. 기본값은 1입니다. 크기 배율입니다. 방향 패드는 버튼처럼 배치되며 조이스틱처럼 자동으로 크기가 조정되지 않으므로 유용합니다.

`deadzone` - *number*, *optional*. 컨트롤에 대한 데드존의 크기를 백분율로 지정하는 0과 1 사이의 값입니다. 조이스틱의 [deadzone](https://devdocs.xbox.com/ko/reference/system/touchadaptationkit/types/game-streaming-touch-deadzone)과 달리, 방향 패드의 데드존은 항상 축 방향(정사각형)입니다.

`enabled` - *boolean*, *optional*. 기본값은 `true`입니다. 컨트롤의 시각적 상태를 활성/비활성으로 설정합니다. 비활성화된 컨트롤은 플레이어로부터 여전히 입력을 받지만, 입력에 따라 시각적 스타일이 변경되지는 않습니다.

`visible` - *boolean*, *optional*. 기본값은 `true`입니다. 플레이어가 상호 작용할 수 있도록 컨트롤을 표시할지 여부를 결정합니다. 게임 플레이 중에 변경하려면 [게임 상태를 사용하여 터치 레이아웃 변경](https://devdocs.xbox.com/ko/build/core-features/common/game-streaming/building-touch-layouts/game-streaming-touch-changing-layouts-game-state.md#change_state)을 참조하세요.

`styles` - *object*, *optional*. 컨트롤의 시각적 표현을 커스터마이즈합니다. 스타일은 스타일을 지정할 수 있는 상태별 오브젝트로 표현됩니다.

`interaction` - *object*, *optional*. 사용자가 컨트롤과 상호 작용하는 메커니즘을 변경할 수 있는 속성 정의입니다.

**Interaction**

`activationType` - *string*, *optional*. 방향 패드 상호 작용에서 특정 방향에 대해 허용되는 활성화 유형을 정의합니다. 기본값은 `allowNeighboring`입니다. `exclusive`로 설정하면 방향 패드에서 한 번에 하나의 방향만 활성화될 수 있습니다(즉, 'Up', 'Right', 'Down', 'Left' 중 하나만). `allowNeighboring`으로 설정하면 두 방향 사이를 탭하여 특정 방향과 그 이웃 방향 중 하나를 동시에 활성화할 수 있습니다(즉, 각 개별 방향을 활성화하는 기능 외에도, 사용자가 두 방향 사이를 탭하여 'Up+Right', 'Right+Down', 'Down+Left' 또는 'Left+Up'을 활성화할 수 있음).

**States and Styling properties**

방향 패드 컨트롤은 다음 상태에 대해 스타일을 지정할 수 있습니다.

* `default` - 기본 스타일입니다.
* `disabled` - 컨트롤이 비활성화되었을 때의 스타일입니다. 지정하지 않으면 컨트롤이 비활성화되었을 때 기본 스타일에 변환이 적용되어 비활성화된 것처럼 표시됩니다.
* `idle` - 플레이어가 컨트롤과 상호 작용하지 않을 때 적용됩니다.
* `activated` - 플레이어가 버튼을 터치하고 있을 때 적용됩니다.

방향 패드 컨트롤의 스타일을 지정하는 데 다음 속성을 사용할 수 있습니다.

`opacity` - *number*, *optional*. 컨트롤에 적용될 불투명도입니다. `disabled`를 제외한 모든 상태에서 기본값은 1.0입니다.

`fill` - *object*, *optional*. 방향 패드가 활성화되었을 때 사용할 그라디언트에 대해 정의된 색상을 가진 오브젝트입니다.

`gradient` - *object*, *optional*. 방향 패드가 활성화되었을 때 사용할 그라디언트에 대해 정의된 색상을 가진 오브젝트입니다.

`background` - *object*, *optional*. [color](https://devdocs.xbox.com/ko/reference/system/touchadaptationkit/types/game-streaming-touch-color) 또는 [image asset](https://devdocs.xbox.com/ko/reference/system/touchadaptationkit/types/game-streaming-touch-asset)일 수 있습니다.

`stroke` - *object*, *optional*. 방향 패드의 외곽선에 사용될 색상입니다. [stroke](https://devdocs.xbox.com/ko/reference/system/touchadaptationkit/types/game-streaming-touch-stroke) 오브젝트여야 합니다.

**Asset dimensions**

이미지 애셋을 허용하는 각 스타일 오브젝트에 대해, 주어진 애셋은 기본 해상도와 해당 기본 해상도의 1.5x, 2.0x, 3.0x, 4.0x 배율로 제공됩니다. 주어진 이미지의 해상도는 다음 최대 해상도보다 작거나 같아야 합니다.

| Object | @1.0x | @1.5x | @2.0x | @3.0x | @4.0x |
| :- | :- | :- | :- | :- | :- |
| background | 75x75 | 112x112 | 150x150 | 225x225 | 300x300 |

## Remarks

방향 패드는 실제 컨트롤러의 방향 패드와 유사한 경험을 제공하는 데 사용됩니다.

플레이어의 주요 이동 메커니즘으로 사용되는 경우(일반적으로 `left` `inner` 슬롯), 배율을 2로 설정하는 것이 좋습니다.

**Styling remarks**

`background`에 커스텀 이미지 애셋을 사용하는 경우, 참조된 최대 해상도는 scale=1.0에 대한 것입니다. 다른 배율을 사용하는 경우 최대 해상도는 해상도와 배율의 곱과 같습니다. 예를 들어, scale=1.5는 @1.0x DPI의 배경 이미지가 최대 90x90 해상도를 가질 수 있음을 의미합니다.

> [!WARNING]
>
> Windows 버전의 Content Test Application을 통해 스트리밍하는 경우, 모든 스타일이 올바르게 표시되지 않을 수 있습니다.

## Samples

#### Example 1: Default directional pad

**Figure 1. Directional Pad**

![방향 패드와 상호 작용하는 사용자](https://mintcdn.com/microsoft-4404708b/-_0FrcE2bDxzGxv-/images/gdk/reference/game-streaming-touch-control-images-directional-pad.gif?s=663feec658af51030d5c73cca7b8fc6e)

```
{
    "type": "directionalPad",
    "scale": 1.0
}
```

#### Example 2: Larger directional pad with customized colors.

**Figure 1. Customized Directional Pad**

![커스터마이즈된 방향 패드와 상호 작용하는 사용자](https://mintcdn.com/microsoft-4404708b/-_0FrcE2bDxzGxv-/images/gdk/reference/game-streaming-touch-control-images-directional-pad-2.gif?s=1ccee19714099eab37c0d825a9621856)

```
{
    "type": "directionalPad" ,
    "scale": 2.0,
    "styles" : {
        "default" : {
            "fill" : "#0e7a0d10",
            "gradient" : {
                "color": "#0e7a0d10"
            },
            "stroke" : {
                "type": "solid",
                "color" : "#0e7a0dff"
            }
        }
    }
}
```

## Requirements

**Layout Version:** 1.0+, (Styling support in 3.0+, Interaction support in 3.4+).


## Related topics

- [XGameStreamingGamepadPhysicality](https://devdocs.xbox.com/reference/system/xgamestreaming/enums/xgamestreaminggamepadphysicality.md)
- [Touch Adaptation Kit](https://devdocs.xbox.com/reference/system/touchadaptationkit/touchadaptationkit-reference.md)
- [Touch Adaptation Kit (TAK) Reference](https://devdocs.xbox.com/build/core-features/common/game-streaming/game-streaming-touch-touch-adaptation-kit-overview.md)
- [XINPUT_KEYSTROKE](https://devdocs.xbox.com/reference/input/xinputongameinput/structs/xinput_keystroke.md)
- [GameInputGamepadButtons](https://devdocs.xbox.com/reference/input/gameinput/enums/gameinputgamepadbuttons.md)