移动玩家

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

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

💡 提示：移动玩家最简单的方法是使用 Creator Hub 中的场景编辑器。请使用无代码 移动玩家 或者 将玩家移动到此处 操作，请参见 让任意项目变为智能项目.

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

• newRelativePosition：玩家要放置的位置，以 Vector3 表示。

• cameraTarget：（可选）让摄像机朝向的方向，以 Vector3 表示，即要注视的空间中某个点的坐标。如果未提供值，摄像机将保持与移动前相同的旋转。

• avatarTarget：（可选）让虚拟形象朝向的方向，以 Vector3 表示，即要注视的空间中某个点的坐标。如果未提供值，虚拟形象将保持与移动前相同的旋转。如果玩家处于第一人称摄像机模式，摄像机和虚拟形象的旋转将相同。

• 持续时间：（可选）过渡应持续的时间，以秒为单位。如果未提供值，过渡将立即发生。如果提供了持续时间，虚拟形象将走或跑到这个新位置。

📔 注意：在过渡期间，虚拟形象不受碰撞体影响，因此可以穿过物体。

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),
		})
	}
)

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

📔 注意：只有当玩家已经站在场景边界内时，才能移动他们，而且只能移动到场景边界范围内的位置。你不能使用 movePlayerTo() 来将玩家传送到另一个场景。要将玩家移动到另一个场景，请参见 传送.

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

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 组件来禁用所有输入，参见 限制移动.

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)
	}
)

📔 注意：此外，await 的结果可以被存储，以评估其 成功 属性，以判断移动是被中断了（例如被输入移动打断）还是成功完成。

💡 提示：要将玩家移动到不同的场景，或 Genesis City 地图中的不同坐标，请参见 传送.