> 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-zh/chang-jing-sdk7/jiao-hu-xing/tou-xiang/locomotion.md).

# 移动设置与限制

更改玩家的速度和跳跃高度，或限制他们的移动方式

你可以更改玩家的头像在你的场景内的移动方式。使用 `AvatarLocomotionSettings` 组件来调整速度和跳跃高度，以及 `InputModifier` 组件来冻结玩家或阻止特定类型的移动。这两个组件都放在 `engine.PlayerEntity`上，并且都只会在玩家位于你的场景边界内时生效。

## 移动设置

你可以影响玩家的移动能力，例如他们的奔跑速度、跳跃高度等等。这个值可以动态更改，例如让玩家通过与某个物品互动来获得临时速度加成，或者在一段时间内禁用玩家的跳跃能力。

{% hint style="info" %}
**💡 提示**：你无需编写代码即可设置这些值。将 **移动设置** 智能物品拖入你的场景中的 [Creator Hub 中的场景编辑器](/creator/content-creator-zh/chang-jing-bian-ji-qi/ru-men/about-editor.md) 并移动它的滑块。参见 [移动设置](/creator/content-creator-zh/chang-jing-bian-ji-qi/jiao-hu-xing/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-zh/chang-jing-sdk7/jiao-hu-xing/player-physics.md#forces-while-gliding).
{% endhint %}

{% hint style="info" %}
**💡 提示**：这些属性都不能低于 0。如果你将其中之一设为负值，它会被钳制为 0。将这些值设为 0 的效果与使用 `InputModifier` 来阻止某些按键的使用的效果相同。

只有当玩家位于场景边界内时，你才能影响其移动。如果要影响其他玩家的头像，你必须在他们自己的实例上运行影响其移动的代码。
{% endhint %}

你可以创建一个 [智能穿戴](/creator/content-creator-zh/chang-jing-sdk7/xiang-mu-lei-xing/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-zh/chang-jing-sdk7/3d-nei-rong-ji-chu/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-zh/chang-jing-sdk7/jiao-hu-xing/an-niu-shi-jian/system-based-events.md#global-input-events) 仍可被场景监听。你可以用它们来控制一辆载具，或者使用一个 [虚拟摄像机](/creator/content-creator-zh/chang-jing-sdk7/3d-nei-rong-ji-chu/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-zh/chang-jing-sdk7/jiao-hu-xing/tou-xiang/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.