> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/avatars/locomotion.md).

# 이동 설정 및 제한

플레이어의 속도와 점프 높이를 변경하거나, 이동 방식을 제한합니다

씬 안에 있는 동안 플레이어의 아바타가 어떻게 움직이는지 바꿀 수 있습니다. 다음을 사용하세요 `AvatarLocomotionSettings` 컴포넌트로 속도와 점프 높이를 조정하고, `InputModifier` 컴포넌트로 플레이어를 고정하거나 특정 종류의 이동을 차단할 수 있습니다. 두 컴포넌트 모두 `engine.PlayerEntity`에 추가하며, 둘 다 플레이어가 씬의 경계 안에 있을 때만 적용됩니다.

## 이동 설정

플레이어의 달리기 속도, 점프 높이 등 이동 방식을 조정할 수 있습니다. 이는 동적으로 변경할 수 있으며, 예를 들어 아이템과 상호작용해 일시적인 속도 증가 효과를 얻도록 하거나, 짧은 시간 동안 플레이어의 점프 능력을 비활성화하는 데 사용할 수 있습니다.

{% hint style="info" %}
**💡 팁**: 코드를 작성하지 않고도 이 값들을 설정할 수 있습니다. 다음을 끌어다 놓으세요 **이동 설정** 스마트 아이템을 씬 안의 [Creator Hub의 Scene Editor](/creator/content-creator-ko/scene-editor/get-started/about-editor.md) 에 추가하고 슬라이더를 조정하세요. 참조 [이동 설정](/creator/content-creator-ko/scene-editor/interactivity/smart-items.md#locomotion-settings).
{% endhint %}

이렇게 하려면, 다음을 추가하세요 `AvatarLocomotionSettings` 컴포넌트를 `engine.PlayerEntity`.

```ts
import {AvatarLocomotionSettings, engine} from '@dcl/sdk/ecs'

AvatarLocomotionSettings.create(engine.PlayerEntity, {
	runSpeed: 10,
	jumpHeight: 2,
})
```

다음 속성을 사용할 수 있습니다:

* `walkSpeed`: 플레이어가 걷는 속도(초당 미터). 데스크톱 클라이언트에서는 Control 키를 눌러 걷습니다.
* `jogSpeed`: 플레이어가 조깅하는 속도(초당 미터). 이는 플레이어의 기본 이동 방식입니다.
* `runSpeed`: 플레이어가 달리는 속도(초당 미터). 데스크톱 클라이언트에서는 Shift 키를 눌러 달립니다.
* `jumpHeight`: 플레이어가 점프하는 높이(미터).
* `runJumpHeight`: 달린 후 플레이어가 점프하는 높이(미터).
* `doubleJumpHeight`: 더블 점프 시 두 번째 점프의 높이(미터).
* `glidingSpeed`: 플레이어가 활공 중 이동하는 수평 속도(초당 미터).
* `glidingFallingSpeed`: 플레이어가 활공 중 떨어지는 최대 속도(초당 미터). 이는 플레이어의 하강만 제한합니다. 씬의 지속 힘으로 인한 상승 같은 위쪽 이동은 제한되지 않습니다.
* `hardLandingCooldown`: 강한 착지 후 쿨다운(초). 높은 곳에서 떨어진 뒤 다시 움직일 수 있기까지 플레이어가 기다려야 하는 시간입니다.

참고로, 해당 속성의 기본값은 다음과 같습니다:

* `walkSpeed`: 1.5 m/s
* `jogSpeed`: 8 m/s
* `runSpeed`: 10 m/s
* `glidingSpeed`: 6 m/s
* `glidingFallingSpeed`: 1 m/s
* `jumpHeight`: 1 m
* `runJumpHeight`: 1.5 m
* `doubleJumpHeight`: 2 m
* `hardLandingCooldown`: 0.75 s

{% hint style="info" %}
**💡 팁**: 활공 중에는 씬에 의해 적용되는 지속 힘이 1.5배 더 강해지고, 위쪽 힘은 플레이어를 들어 올릴 수 있습니다. 참조 [글라이딩 중의 힘](/creator/content-creator-ko/sdk7/interactivity/player-physics.md#forces-while-gliding).
{% endhint %}

{% hint style="info" %}
**💡 팁**: 이러한 속성은 0보다 낮을 수 없습니다. 값 중 하나를 음수로 설정하면 0으로 고정됩니다. 이러한 값을 0으로 설정하면 `InputModifier` 를 사용해 특정 키의 사용을 차단하는 것과 같은 효과가 있습니다.

플레이어가 씬의 경계 안에 있을 때만 플레이어의 이동에 영향을 줄 수 있습니다. 다른 플레이어의 아바타에 영향을 주려면, 해당 플레이어의 자체 인스턴스에서 그들의 이동에 영향을 주는 코드를 실행해야 합니다.
{% endhint %}

다음을 만들 수 있습니다 [스마트 웨어러블](/creator/content-creator-ko/sdk7/kinds-of-projects/smart-wearables.md) 플레이어가 항상 더 빠르게 달리거나 더 높이 점프하게 만드는 것입니다. 씬과 스마트 웨어러블이 이 매개변수에 서로 다른 값을 정의한 경우, 항상 씬의 값이 사용됩니다.

파쿠르 씬에서 누구도 불공정한 이점을 얻지 않도록, 씬에 기본값을 명시적으로 추가하여 기본 매개변수를 강제할 수 있습니다:

```ts
import {AvatarLocomotionSettings, engine} from '@dcl/sdk/ecs'

AvatarLocomotionSettings.create(engine.PlayerEntity, {
	runSpeed: 10,
	walkSpeed: 1.5,
	jogSpeed: 8 ,
	jumpHeight: 1,
	runJumpHeight: 1.5,
	hardLandingCooldown: 0.75
})
```

## 이동 제한

플레이어가 씬에서 수행할 수 있는 행동을 제한할 수 있습니다. 플레이어를 고정하거나, 예를 들어 점프나 달리기를 막는 등 특정 이동 방식을 제한하는 데 사용하세요.

### 플레이어 고정

입력 키로는 아바타를 움직일 수 없도록 플레이어를 고정할 수 있습니다. 이는 다양한 게임 메커니즘에 유용할 수 있습니다. 이동으로 중단되면 안 되는 중요한 애니메이션을 수행할 때나, 또는 [가상 카메라](/creator/content-creator-ko/sdk7/3d/camera.md) 가 아바타에서 멀리 떨어져 있고 플레이어가 아무렇게나 움직이게 하고 싶지 않을 때 플레이어를 고정하는 것도 좋은 방법입니다.

다음을 사용하세요 `InputModifier` 컴포넌트를 다음에 `engine.PlayerEntity` 플레이어의 입력이 아바타의 이동에 영향을 주지 않도록 합니다. 아바타는 그대로 멈춰 있고, 플레이어는 카메라 회전만 할 수 있습니다.

```ts
import {InputModifier, engine} from '@dcl/sdk/ecs'

InputModifier.create(engine.PlayerEntity, {
	mode: InputModifier.Mode.Standard({
		disableAll: true,
	}),
})
```

다음 사항을 유의하세요:

* 플레이어의 상호작용이 비활성화되어 있어도, 아바타는 중력이나 움직이는 플랫폼 같은 외부 힘의 영향을 계속 받습니다.
* 이 `InputModifier` 컴포넌트는 `engine.PlayerEntity` 엔티티와 함께만 사용할 수 있습니다. 이 컴포넌트는 현재 플레이어에게만 영향을 줄 수 있으며, 다른 플레이어에게는 영향을 줄 수 없습니다.
* 이 컴포넌트는 아바타가 씬의 경계 안에 있을 때만 플레이어에게 영향을 줍니다. 플레이어가 씬을 떠나는 즉시 이동 제한이 해제됩니다.
* 플레이어의 상호작용이 비활성화되어 있어도, 플레이어는 감정 표현을 자유롭게 할 수는 없지만, 씬은 아바타에 애니메이션을 트리거할 수 있습니다.
* 플레이어 입력은 아바타에 영향을 주지 않지만, [전역 입력 이벤트](/creator/content-creator-ko/sdk7/interactivity/button-events/system-based-events.md#global-input-events) 는 여전히 씬에서 감지할 수 있습니다. 이를 사용해 차량을 제어하거나, [가상 카메라](/creator/content-creator-ko/sdk7/3d/camera.md) 를 사용해 다른 엔티티가 이동할 때 이를 따라가게 하여 대체 아바타처럼 취급할 수 있습니다.

### 특정 종류의 이동 제한

플레이어를 완전히 고정하는 대신, 플레이어의 특정 이동 방식을 제한할 수 있습니다. 이는 게임 플레이상의 이유로 사용할 수 있습니다. 예를 들어 더블 점프와 활공을 막아 플랫폼 게임의 난이도를 유지하는 데 쓰일 수 있습니다. 이러한 능력은 게임 메커니즘으로 동적으로 전환할 수도 있습니다. 예를 들어 플레이어에게 스태미나 바를 주고 그것이 소진되면 달리기를 못 하게 하는 식입니다. 또한 씬의 분위기를 정하는 데도 사용할 수 있습니다. 예를 들어 평온함을 의도한 장소에서 달리기나 점프를 막는 식입니다. 이 `InputModifier` 에는 다음 옵션이 포함됩니다:

* `disableWalk`: 플레이어는 천천히 걸을 수 없습니다(Control 키 누름). 플레이어가 걷기를 시도하면, 허용되는 경우 대신 조깅하거나 달립니다.
* `disableRun`: 플레이어는 달릴 수 없습니다(Shift 키 누름). 플레이어가 달리기를 시도하면, 허용되는 경우 대신 조깅합니다.
* `disableJog`: 플레이어는 조깅할 수 없습니다(이동의 기본 속도입니다). 플레이어가 조깅을 시도하면, 허용되는 경우 대신 달리거나 걷습니다.
* `disableJump`: 플레이어는 점프할 수 없습니다.
* `disableEmote`: 플레이어는 자발적으로 감정 표현을 할 수 없습니다. 씬은 플레이어의 아바타에 애니메이션을 트리거할 수 있습니다.
* `disableDoubleJump`: 플레이어는 더블 점프를 할 수 없습니다.
* `disableGliding`: 플레이어는 활공할 수 없습니다.

```ts
import {InputModifier, engine} from '@dcl/sdk/ecs'

InputModifier.create(engine.PlayerEntity, {
	mode: InputModifier.Mode.Standard({
		disableAll: false,
		disableWalk: false,
		disableRun: true,
		disableJog: true,
		disableJump: true,
		disableEmote: true,
		disableDoubleJump: true,
		disableGliding: true
	}),
})
```

### 고급 구문

도우미 없이 컴포넌트를 사용하려면 다음 구문을 사용할 수 있습니다:

```ts
import {InputModifier, engine} from '@dcl/sdk/ecs'

InputModifier.createOrReplace(engine.PlayerEntity, {
	mode: {
		$case: 'standard',
		standard: {
			disableAll: false,
			disableWalk: false,
			disableRun: true,
			disableJog: true,
			disableJump: true,
			disableEmote: true,
		},
	},
})
```

{% hint style="info" %}
**💡 팁**: 작동하는 예시는 다음을 참조하세요 [`0,1-input-modifier`](https://github.com/decentraland/sdk7-test-scenes/tree/main/scenes/0,1-input-modifier) 테스트 씬으로, 각각의 `InputModifier` 이동 플래그를 개별적으로 전환하고, 이동이 차단된 상태에서도 움직이는 플랫폼에 여전히 실려 가는 아바타를 보여줍니다.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-ko/sdk7/interactivity/avatars/locomotion.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.