> 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/move-player.md).

# 移动玩家

将玩家传送到场景中的新位置，或引导其步行到新位置

要更改场景中玩家的位置，请使用 `movePlayerTo()` 函数。可用它来重生玩家、设置检查点，或让玩家走到某个位置，作为过场动画的一部分。

{% 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/make-any-item-smart.md).
{% endhint %}

此函数接受一个具有以下属性的对象：

* `newRelativePosition`：玩家要放置的位置，以 Vector3 表示。
* `cameraTarget`：（可选）让摄像机朝向的方向，以 Vector3 表示，即要注视的空间中某个点的坐标。如果未提供值，摄像机将保持与移动前相同的旋转。
* `avatarTarget`：（可选）让虚拟形象朝向的方向，以 Vector3 表示，即要注视的空间中某个点的坐标。如果未提供值，虚拟形象将保持与移动前相同的旋转。如果玩家处于第一人称摄像机模式，摄像机和虚拟形象的旋转将相同。
* `持续时间`：（可选）过渡应持续的时间，以秒为单位。如果未提供值，过渡将立即发生。如果提供了持续时间，虚拟形象将走或跑到这个新位置。

{% hint style="warning" %}
**📔 注意**：在过渡期间，虚拟形象不受碰撞体影响，因此可以穿过物体。
{% endhint %}

```ts
import { movePlayerTo } from '~system/RestrictedActions'

// 创建实体
const myEntity = engine.addEntity()
MeshRenderer.setBox(myEntity)
MeshCollider.setBox(myEntity)

Transform.create(myEntity, {
	position: { x: 4, y: 1, z: 4 },
})

// 给实体添加行为
pointerEventsSystem.onPointerDown(
	{
		entity: myEntity,
		opts: { button: InputAction.IA_POINTER, hoverText: '点击' },
	},
	function () {
		// 重生玩家
		movePlayerTo({
			newRelativePosition: Vector3.create(1, 0, 1),
			cameraTarget: Vector3.create(8, 1, 8),
			avatarTarget: Vector3.create(8, 1, 8),
		})
	}
)
```

玩家的移动会立即发生，不会出现任何确认界面或摄像机过渡。

{% hint style="warning" %}
**📔 注意**：只有当玩家已经站在场景边界内时，才能移动他们，而且只能移动到场景边界范围内的位置。你不能使用 `movePlayerTo()` 来将玩家传送到另一个场景。要将玩家移动到另一个场景，请参见 [传送](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/external-links.md#teleports).
{% endhint %}

该 `movePlayerTo()` 函数是可等待的，因此如果移动有持续时间，你可以使用 `await` 来等待玩家到达目的地。

```ts
import { movePlayerTo } from '~system/RestrictedActions'

pointerEventsSystem.onPointerDown(
	{
		entity: myEntity,
		opts: { button: InputAction.IA_POINTER, hoverText: '点击' },
	},
	async function () {
		await movePlayerTo({
			newRelativePosition: Vector3.create(1, 0, 1),
			cameraTarget: Vector3.create(8, 1, 8),
			avatarTarget: Vector3.create(8, 1, 8),
			duration: 2,
		})
	}
)
```

如果玩家在过渡持续期间尝试移动，则过渡将被中断，并且 `movePlayerTo` 函数将永远不会完成解析。你可以在过渡进行期间使用 `InputModifier` 组件来禁用所有输入，参见 [限制移动](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/tou-xiang/locomotion.md#restrict-locomotion).

```ts
import { movePlayerTo } from '~system/RestrictedActions'
import {InputModifier, engine} from '@dcl/sdk/ecs'

pointerEventsSystem.onPointerDown(
	{
		entity: myEntity,
		opts: { button: InputAction.IA_POINTER, hoverText: '点击' },
	},
	async function () {

		// 禁用所有输入
		InputModifier.create(engine.PlayerEntity, {
			mode: InputModifier.Mode.Standard({
				disableAll: true,
			}),
		})

		// 移动玩家
		await movePlayerTo({
			newRelativePosition: Vector3.create(1, 0, 1),
			cameraTarget: Vector3.create(8, 1, 8),
			avatarTarget: Vector3.create(8, 1, 8),
			duration: 2,
		})

		// 启用所有输入
		InputModifier.deleteFrom(engine.PlayerEntity)
	}
)
```

{% hint style="warning" %}
**📔 注意**：此外，await 的结果可以被存储，以评估其 `成功` 属性，以判断移动是被中断了（例如被输入移动打断）还是成功完成。
{% endhint %}

{% hint style="info" %}
**💡 提示**：要将玩家移动到不同的场景，或 Genesis City 地图中的不同坐标，请参见 [传送](/creator/content-creator-zh/chang-jing-sdk7/jiao-hu-xing/external-links.md#teleports).
{% 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/move-player.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.