> 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/3d-nei-rong-ji-chu/move-entities.md).

# 移动实体

如何随时间逐步移动、旋转和缩放实体，并以增量方式变化。

若要让场景中的实体在一段时间内移动、旋转或缩放，请使用 `Tween` 组件。引擎会平滑地执行所需的变换，在指定时长结束前逐帧更新。此外，受影响实体的 `Transform` 组件值也会实时更新，以便在场景代码中进行距离检测等操作。

{% hint style="info" %}
**💡 提示**：在 [Creator Hub 中的场景编辑器](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-bian-ji-qi/ru-men/about-editor.md)中，你可以通过 **操作**以无代码方式移动实体，详见 [让任意物品变得智能](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-bian-ji-qi/jiao-hu-xing/make-any-item-smart.md).
{% endhint %}

Tween 组件包含以下函数：

* `setMove`：在两点之间移动
* `setRotate`：在两个方向之间旋转
* `setScale`：在两种尺寸之间缩放
* `setMoveRotateScale`：同时对移动、旋转和缩放这三个参数进行过渡
* `setMoveContinuous`：沿同一方向持续移动
* `setRotateContinuous`：沿同一方向持续旋转
* `setTextureMove`：在两个位置之间偏移材质纹理
* `setTextureMoveContinuous`：沿同一方向持续偏移材质纹理

## 在两点之间移动

若要让实体在两点之间移动，请创建一个 `Tween` 组件，并使用 `setMove` 函数。

```ts
const myEntity = engine.addEntity()
Transform.create(myEntity, {
	position: Vector3.create(4, 1, 4),
})
MeshRenderer.setBox(myEntity)

Tween.setMove(myEntity, 
	Vector3.create(1, 1, 1), 
	Vector3.create(8, 1, 8), 
	2000
)
```

移动补间需要以下信息：

* `entity`：要移动的实体
* `start`：表示起始位置的 Vector3
* `end`：表示结束位置的 Vector3
* `duration`：在两个位置之间移动所需的毫秒数

还可以使用以下另一个可选参数：

* `easingFunction`：要使用的缓动函数。请参阅 [非线性补间](#non-linear-tweens)

## 在两个方向之间旋转

要让实体在两个点之间旋转，请创建一个 `Tween` 组件，并使用 `setRotate` 函数。

```ts
const myEntity = engine.addEntity()
Transform.create(myEntity, {
	position: Vector3.create(4, 1, 4),
})
MeshRenderer.setBox(myEntity)

Tween.setRotate(myEntity, 
	Quaternion.fromEulerDegrees(0, 0, 0), 
	Quaternion.fromEulerDegrees(0, 170, 0), 
	700
)
```

旋转补间需要以下信息：

* `start`：表示起始旋转的四元数
* `end`：表示结束旋转的四元数
* `duration`：在两个位置之间移动所需的毫秒数

还可以使用以下另一个可选参数：

* `easingFunction`：要使用的缓动函数。请参阅 [非线性补间](#non-linear-tweens)

### 围绕支点旋转

旋转实体时，旋转始终以实体的中心坐标为参照。若要使用另一组坐标作为支点来旋转实体，请创建第二个（不可见的）实体，将支点设为其位置，并将其设为要旋转实体的父级。

旋转父实体时，其所有子实体都会以父实体的位置为支点一起旋转。请注意，子实体的 `position` 是相对于父实体的位置。

```ts
const pivotEntity = engine.addEntity()
Transform.create(pivotEntity, {
	position: Vector3.create(4, 1, 4),
})

const childEntity = engine.addEntity()
Transform.create(childEntity, {
	position: Vector3.create(1, 0, 0),
	parent: pivotEntity,
})
MeshRenderer.setBox(childEntity)

Tween.setRotate(pivotEntity, 
	Quaternion.fromEulerDegrees(0, 0, 0), 
	Quaternion.fromEulerDegrees(0, 170, 0), 
	700
)
```

请注意，在此示例中，系统旋转的是 `pivotEntity` 实体，它是 `childEntity` 实体的父级。

## 在两种尺寸之间缩放

要将实体的缩放比例从一种尺寸变为另一种尺寸，请创建一个 `Tween` 组件，并使用 `setScale` 函数。

```ts
const myEntity = engine.addEntity()
Transform.create(myEntity, {
	position: Vector3.create(4, 1, 4),
})
MeshRenderer.setBox(myEntity)

Tween.setScale(myEntity, 
	Vector3.create(1, 1, 1), 
	Vector3.create(4, 4, 4), 
	2000
)	

```

缩放补间需要以下信息：

* `start`：表示起始尺寸的 Vector3
* `end`：表示结束尺寸的 Vector3
* `duration`：在两个位置之间移动所需的毫秒数

还可以使用以下另一个可选参数：

* `easingFunction`：要使用的缓动函数。请参阅 [非线性补间](#non-linear-tweens)

## 从当前位置移动

补间运行期间，引擎会实时更新实体的 `Transform` 组件值。这意味着你可以随时从实体的 `Transform` 组件读取其当前位置，并将该值用作新补间的 `start` 值。这样，无论实体是如何到达当前位置的，它都会从当前位置移动到目标位置。

```ts
pointerEventsSystem.onPointerDown(
	{
		entity: myEntity,
		opts: { button: InputAction.IA_POINTER, hoverText: 'Move' },
	},
	() => {
		Tween.setMove(myEntity, 
			Transform.get(myEntity).position, 
			Vector3.create(8, 1, 8), 
			2000,
			EasingFunction.EF_EASEOUTQUAD
		)
	}
)
```

{% hint style="warning" %}
**📔 注意**：始终显式传入 `start` 值。如果 `start` 参数未设置，则会被视为 *(0, 0, 0)*，因此实体会先瞬移到场景原点，再开始移动。同样，如果传入的硬编码 `start` 值与实体当前位置不符，实体也会先明显地瞬移到该位置，再开始移动。需要从实体的 `Transform` 组件读取当前位置，就像本节示例中那样，确保移动从实体当前所在位置开始。
{% endhint %}

### 移动过程中重新指定目标

在已经有补间运行的实体上调用 `setMove` （或其他任何补间函数），会用新的补间替换正在运行的补间。由于 `start` 值取自实体的实时位置，因此实体会在移动过程中平滑地改变方向：从当时所在的位置转向新目标，不会发生跳跃。

下面的示例会将实体移动到玩家点击的垫子上。如果实体仍在移动时玩家又点击了另一个垫子，实体就会平滑地转向新目标。

```ts
function moveTo(target: Vector3) {
	Tween.setMove(shipEntity, 
		Transform.get(shipEntity).position, 
		target, 
		2000,
		EasingFunction.EF_EASEOUTQUAD
	)
}

pointerEventsSystem.onPointerDown(
	{
		entity: padA,
		opts: { button: InputAction.IA_POINTER, hoverText: 'Move here' },
	},
	() => moveTo(Vector3.create(2, 1, 2))
)

pointerEventsSystem.onPointerDown(
	{
		entity: padB,
		opts: { button: InputAction.IA_POINTER, hoverText: 'Move here' },
	},
	() => moveTo(Vector3.create(14, 1, 14))
)
```

若要在实体到达目的地时运行逻辑，请参阅 [补间结束时](#on-tween-finished).

{% hint style="warning" %}
**📔 注意**：仅在点击或到达航点等偶发事件发生时，才使用这种方式重新指定目标。如果目标持续变化（例如实体需要跟随玩家），不要每帧都创建新的补间，否则实体会明显卡顿。请参阅 [跟随移动目标](#follow-a-moving-target).
{% endhint %}

## 非线性补间

补间可以采用不同的 **缓动函数** ，从而影响变化速率随时间的变化方式。 **线性** 函数表示变化速度从开始到结束始终恒定。可选项很多，会生成不同形状的曲线，具体取决于开始和/或结束时减速的情况及程度。 **easeinexpo** 曲线开始缓慢、结束迅速，速度呈指数增长；与之相反的是 **easeoutexpo** 曲线开始时速度快，结束时速度慢。

{% hint style="info" %}
**💡 提示**：尝试使用不同的运动曲线。它们之间的差异通常很细微，但我们会下意识地从物体的运动方式中解读信息，例如重量、摩擦力，甚至个性。
{% endhint %}

```ts
Tween.setScale(myEntity, 
	Vector3.create(1, 1, 1), 
	Vector3.create(4, 4, 4), 
	2000,
	EasingFunction.EF_EASEOUTBOUNCE
)

```

可选的 `easingFunction` 参数的值取自 `EasingFunction` 枚举，该枚举提供以下选项：

* `EF_EASEBACK`
* `EF_EASEBOUNCE`
* `EF_EASECIRC`
* `EF_EASECUBIC`
* `EF_EASEELASTIC`
* `EF_EASEEXPO`
* `EF_EASEINBACK`
* `EF_EASEINBOUNCE`
* `EF_EASEINCIRC`
* `EF_EASEINCUBIC`
* `EF_EASEINELASTIC`
* `EF_EASEINEXPO`
* `EF_EASEINQUAD`
* `EF_EASEINQUART`
* `EF_EASEINQUINT`
* `EF_EASEINSINE`
* `EF_EASEOUTBACK`
* `EF_EASEOUTBOUNCE`
* `EF_EASEOUTCIRC`
* `EF_EASEOUTCUBIC`
* `EF_EASEOUTELASTIC`
* `EF_EASEOUTEXPO`
* `EF_EASEOUTQUAD`
* `EF_EASEOUTQUART`
* `EF_EASEOUTQUINT`
* `EF_EASEOUTSINE`
* `EF_EASEQUAD`
* `EF_EASEQUART`
* `EF_EASEQUINT`
* `EF_EASESINE`
* `EF_LINEAR`

## 恒定旋转

若要让实体持续旋转，请使用 `Tween` 组件及其 `setRotateContinuous` 函数。

```ts
Tween.setRotateContinuous(myEntity, 
	Quaternion.fromEulerDegrees(0, -1, 0), 
	45
)
```

持续旋转补间需要以下信息：

* `entity`：要旋转的实体
* `direction`：用于确定旋转轴的四元数。只有旋转轴会产生影响，角度大小会被忽略。例如， `Quaternion.fromEulerDegrees(0, -1, 0)` 和 `Quaternion.fromEulerDegrees(0, -90, 0)` 效果相同，都会绕 *y* 轴沿负方向旋转。
* `speed`：实体每秒旋转的度数。负值表示沿相反方向旋转。

还可以使用以下另一个可选参数：

* `duration`：旋转持续的毫秒数。时间到后，旋转将停止。

## 持续移动

若要让实体持续朝同一方向移动，请使用 `Tween` 组件及其 `setMoveContinuous` 函数。

```ts
Tween.setMoveContinuous(myEntity, 
	Vector3.create(0, 0, 1), 
	0.7
)
```

持续移动补间需要以下信息：

* `entity`：要移动的实体
* `direction`：表示移动方向的 Vector3
* `speed`：实体每秒移动的米数

还可以使用以下另一个可选参数：

* `duration`：移动持续的毫秒数。时间到后，移动将停止。

持续移动补间需要以下信息：

### 跟随移动目标

`setMoveContinuous` 在目标位置不断变化时也很适用，例如让实体跟随玩家。你可能会想改为每一帧都创建一个新的 `setMove` 补间，并将目标设为玩家的最新位置，但这样会产生明显的卡顿。

原因在于，你从补间实体的 `Transform` 组件读取到的位置，是引擎最近一次回传给场景的位置，因此会比实体的实际位置滞后几帧。当你将该值作为新补间的 `start` 传入时，引擎会立即应用它，导致实体跳回几帧前的位置。单次这样的校正不易察觉，但每秒重复多次就会很明显。

`setMoveContinuous` 可以彻底避免这个问题，因为你传入的是方向和速度，而不是起始位置。引擎会持续使用实体的实际位置，因此替换补间以改变方向时，实体不会跳动。

```ts
const CHASE_SPEED = 3
const STOP_DISTANCE = 1

engine.addSystem(() => {
	const playerPosition = Transform.get(engine.PlayerEntity).position
	const myPosition = Transform.get(myEntity).position

	if (Vector3.distance(myPosition, playerPosition) <= STOP_DISTANCE) {
		// 距离足够近：持续补间没有目标位置，因此需要手动停止
		if (Tween.has(myEntity)) {
			Tween.deleteFrom(myEntity)
		}
		返回
	}

	const direction = Vector3.subtract(playerPosition, myPosition)
	direction.y = 0 // 即使玩家跳跃，也保持在地面上

	Tween.setMoveContinuous(myEntity, Vector3.normalize(direction), CHASE_SPEED)
})
```

{% hint style="warning" %}
**📔 注意**：连续补间不会自行结束，因此实体会持续移动，直到你移除 `Tween` 组件，方法是调用 `Tween.deleteFrom()`，或者可选的 `duration` 耗尽。还请注意，每一帧都重新瞄准会导致每帧都向引擎发送更新。为避免这种情况，仅在方向发生足够大的变化时才再次调用 `setMoveContinuous` 。
{% endhint %}

## 补间序列

若要让实体按顺序播放一系列补间，请使用 `TweenSequence` 组件。此组件需要两个字段：

* `sequence`：包含多个补间定义的数组，这些定义将按顺序执行。数组可以为空，此时只播放当前补间。
* `loop` *（可选）*：如果未提供，则序列只播放一次。如果存在此字段，其值必须是 `TweenLoop` 枚举中的值。可接受的值包括：
  * `TL_RESTART`：序列结束时重新开始。如果最后一个状态与第一个状态不匹配，实体会立即从一个状态跳到另一个状态。
  * `TL_YOYO`：序列结束时，会反向播放，按相反顺序执行所有补间，直到回到起点。然后再次开始。

### 来回移动

若要让平台在两个位置之间持续来回移动，请将 `sequence` 数组留空，并将 `loop` 设为 `TweenLoop.TL_YOYO`

```ts
const myEntity = engine.addEntity()
Transform.create(myEntity, {
	position: Vector3.create(4, 1, 4),
})
MeshRenderer.setBox(myEntity)

Tween.setMove(myEntity, 
	Vector3.create(1, 1, 1), 
	Vector3.create(8, 1, 8), 
	2000
)

TweenSequence.create(myEntity, { sequence: [], loop: TweenLoop.TL_YOYO })
```

实体会在起点和终点之间来回移动，两个方向的持续时间和缓动函数都相同。

### 沿路径移动

若要让实体沿包含多个点的更复杂路径移动，请在 `sequence` 的 `TweenSequence` 组件中提供补间定义列表。

```ts
const myEntity = engine.addEntity()
Transform.create(myEntity, {
	position: Vector3.create(4, 1, 4),
})
MeshRenderer.setBox(myEntity)

Tween.setMove(myEntity, 
	Vector3.create(6.5, 7, 4), 
	Vector3.create(6.5, 7, 12), 
	4000
)

TweenSequence.create(myEntity, {
	sequence: [
		{
			duration: 2000,
			easingFunction: EasingFunction.EF_LINEAR,
			mode: Tween.Mode.Move({
				start: Vector3.create(6.5, 7, 12),
				end: Vector3.create(6.5, 10.5, 12),
			}),
		},
		{
			duration: 3000,
			easingFunction: EasingFunction.EF_LINEAR,
			mode: Tween.Mode.Move({
				start: Vector3.create(6.5, 10.5, 12),
				end: Vector3.create(6.5, 10.5, 4),
			}),
		},
		{
			duration: 3000,
			easingFunction: EasingFunction.EF_LINEAR,
			mode: Tween.Mode.Move({
				start: Vector3.create(6.5, 10.5, 4),
				end: Vector3.create(6.5, 7, 4),
			}),
		},
	],
	loop: TweenLoop.TL_RESTART,
})
```

请注意，在 TweenSequence 中定义补间动画时，需要使用更详细的格式 `Tween.Mode.Move`，或 `Tween.Mode.Rotate`，或 `Tween.Mode.Scale` 来定义补间动画。在这种更详细的格式中，需要指定：

* `duration`：在两个位置之间移动所需的毫秒数
* `easingFunction`：要使用的缓动函数。请参阅 [非线性补间动画](#non-linear-tweens)。在此格式中，此值为必填项。
* `mode`：补间动画的模式，可以是 `Tween.Mode.Move`, `Tween.Mode.Rotate`或 `Tween.Mode.Scale`.

并且在 `mode` 字段中，需要指定：

* `start`：补间动画的起始值
* `end`：补间动画的结束值

## 补间动画结束时

使用 `tweenSystem.tweenCompleted` 检测补间动画何时结束。这对于在补间动画结束时执行操作很有用，例如打开电梯门。

```ts
engine.addSystem(() => {
	const tweenCompleted = tweenSystem.tweenCompleted(myEntity)
	if (tweenCompleted) {
		//播放声音
	}
})
```

## 同时进行多个补间动画

若要在实体的初始状态和结束状态之间移动、旋转和缩放实体，请使用函数 `Tween` 组件，并调用 `setMoveRotateScale` 函数。此函数也可用于上述三个参数的任意组合。

```ts
const myEntity = engine.addEntity()
Transform.create(myEntity, {
	position: Vector3.create(14, 1, 2),
})
MeshRenderer.setBox(myEntity)

Tween.setMoveRotateScale(myEntity, {
	position: { start: Vector3.create(14, 1, 2), end: Vector3.create(14, 3, 2) },
	rotation: { start: Quaternion.fromEulerDegrees(0, 0, 0), end: Quaternion.fromEulerDegrees(0, 180, 90) },
	scale: { start: Vector3.One(), end: Vector3.create(2, 0.5, 2) },
	duration: 2000
})
```

移动补间需要以下信息：

* `entity`：要移动的实体
* `params`：包含以下参数的对象
  * `position`: *（可选）* 一个对象，包含 `start` 和 `end` 值，二者均为 `Vector3`.
  * `rotation`: *（可选）* 一个对象，包含 `start` 和 `end` 值，二者均为 `Quaternion`.
  * `scale`: *（可选）* 一个对象，包含 `start` 和 `end` 值，二者均为 `Vector3`。必须至少提供 `position`, `rotation` 或 `scale` 之一。
  * `duration`: *（必填）* 在两组值之间过渡所需的毫秒数
  * `easingFunction`: *（可选）* 要使用的缓动函数。请参阅 [非线性补间](#non-linear-tweens)

一个实体只能有一个 `Tween` 组件，每个补间组件一次只能执行一种变换。通过 `setMoveRotateScale` 补间类型，可以让实体在横向移动的同时旋转，但这两种运动会遵循同一时间线。如果需要彼此独立的过渡，可以将实体设为父子关系作为变通方案。例如，可以创建一个不可见的父实体使其横向移动，并让一个可见的子实体旋转。

在下面的代码片段中，父实体旋转的同时，子实体逐渐放大。

```ts
const parentEntity = engine.addEntity()
Transform.create(parentEntity, {
	position: Vector3.create(4, 1, 4),
})
MeshRenderer.setBox(parentEntity)
Tween.setRotate(parentEntity, 
	Quaternion.fromEulerDegrees(0, 0, 0), 
	Quaternion.fromEulerDegrees(0, 170, 0), 
	5000
)

const childEntity = engine.addEntity()
Transform.create(childEntity, {
	position: Vector3.create(0, 0, 0),
	parent: parentEntity,
})
MeshRenderer.setBox(childEntity)
Tween.setScale(childEntity, 
	Vector3.create(1, 1, 1), 
	Vector3.create(4, 4, 4), 
	2000
)
```

## 暂停补间动画

要暂停补间动画，请将 `playing` 属性设为 false。要恢复播放，请将其改回 true。

```ts
pointerEventsSystem.onPointerDown(
	{
		entity: button,
		opts: { button: InputAction.IA_POINTER, hoverText: 'pause' },
	},
	() => {
		let tweenData = Tween.getMutable(myEntity)
		tweenData.playing = !tweenData.playing
	}
)
```

要结束不再需要继续播放的补间动画，请从实体中删除 `Tween` 组件。如果实体还使用了 `TweenSequence` 组件，也请将其删除。

```ts
pointerEventsSystem.onPointerDown(
	{
		entity: button,
		opts: { button: InputAction.IA_POINTER, hoverText: 'pause' },
	},
	() => {
		if( Tween.has(myEntity)){
			Tween.deleteFrom(myEntity)
		}
		if( TweenSequence.has(myEntity)){
			TweenSequence.deleteFrom(myEntity)
		}
	}
)
```

## 基于系统的补间动画

除了使用 Tween 组件并由引擎处理变换外，你也可以在场景中通过 [系统](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/jia-gou/systems.md) 逐帧进行这项过渡：每次函数运行时，让实体移动一小段距离。

这种方式的优点是，你可以更灵活地在每一帧重新计算移动；但缺点是代码更复杂，而且性能较差的设备可能会让补间动画显得卡顿，逐步移动也会更加明显。

### 通过系统移动

移动实体最简单的方法是逐步修改存储在 *位置* 值（该值保存在 `Transform` 组件中）。

```ts
function SimpleMove() {
	let transform = Transform.getMutable(myEntity)
	transform.position = Vector3.add(
		transform.position,
		Vector3.scale(Vector3.Forward(), 0.05)
	)
}

engine.addSystem(SimpleMove)

const myEntity = engine.addEntity()
Transform.create(myEntity, {
	position: Vector3.create(4, 1, 4),
})
MeshRenderer.setBox(myEntity)
```

在这个示例中，我们让实体在游戏循环的每个 tick 中移动 0.05 米。

`Vector3.Forward()` 会返回一个朝向前方、长度为 1 米的向量。在此示例中，我们再使用 `Vector3.scale()`将该向量缩小到原长度的 1/20。最终速度取决于帧率：在每秒 60 帧的机器上，实体每秒移动 3 米；而在每秒 30 帧的机器上，实体每秒只移动 1.5 米。

![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-de7e8eb38ec395b56d54f34952ac73ba3db30f38%2Fmove.webp?alt=media)

### 通过系统旋转

旋转实体最简单的方法是逐步更改 Transform 组件中的值，并在系统函数中执行这些更改。

```ts
function SimpleRotate() {
	let transform = Transform.getMutable(myEntity)
	transform.rotation = Quaternion.multiply(
		transform.rotation,
		Quaternion.fromAngleAxis(1, Vector3.Up())
	)
}

engine.addSystem(SimpleRotate)

const myEntity = engine.addEntity()
Transform.create(myEntity, {
	position: Vector3.create(4, 1, 4),
})
MeshRenderer.setBox(myEntity)
```

请注意，为了将当前旋转与每次增量相结合，我们使用了 `Quaternion.multiply`。在四元数运算中，组合两个旋转要将它们相乘，而不是相加。一个四元数乘以另一个四元数所得到的旋转，等效于先执行一个旋转，再执行另一个旋转后的最终旋转。

在此示例中，我们会在游戏循环的每个 tick 中，将实体向上旋转 1 度。

{% hint style="info" %}
**💡 提示**：若要让实体始终旋转并面向玩家，可以添加一个 [`Billboard` 组件](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/3d-nei-rong-ji-chu/entity-positioning.md#face-the-player).
{% endhint %}

![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-10d76a54ac0c67a5501158d19b45d077174403cf%2Frotate.webp?alt=media)

### 通过系统围绕枢轴点旋转

旋转实体时，旋转始终以实体的中心坐标为参照。若要使用另一组坐标作为支点来旋转实体，请创建第二个（不可见的）实体，将支点设为其位置，并将其设为要旋转实体的父级。

旋转父实体时，其所有子实体都会以父实体的位置为支点一起旋转。请注意，子实体的 `position` 是相对于父实体的位置。

```ts
function SimpleRotate() {
	let transform = Transform.getMutable(pivotEntity)
	transform.rotation = Quaternion.multiply(
		transform.rotation,
		Quaternion.fromAngleAxis(1, Vector3.Up())
	)
}

engine.addSystem(SimpleRotate)

const pivotEntity = engine.addEntity()
Transform.create(pivotEntity, {
	position: Vector3.create(4, 1, 4),
})

const childEntity = engine.addEntity()
Transform.create(childEntity, {
	position: Vector3.create(1, 0, 0),
	parent: pivotEntity,
})
MeshRenderer.setBox(childEntity)
```

请注意，在此示例中，系统旋转的是 `pivotEntity` 实体，它是 `childEntity` 实体的父级。

![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-23bbd404133e9b16c55c8191c0df62e85ac20e77%2Fpivot-rotate.webp?alt=media)

### 根据时间调整移动

假设访问场景的玩家难以跟上帧率的节奏。这可能会导致移动看起来不连贯，因为各帧的间隔并不均匀，但每一帧都会让实体移动相同的距离。

你可以使用 `dt` 参数调整移动的缩放比例，以补偿这种不均匀的时间间隔。

```ts
function SimpleMove(dt: number) {
	let transform = Transform.getMutable(myEntity)
	transform.position = Vector3.add(
		transform.position,
		Vector3.scale(Vector3.Forward(), dt)
	)
}

engine.addSystem(SimpleMove)

const myEntity = engine.addEntity()
Transform.create(myEntity, {
	position: Vector3.create(4, 1, 4),
})
MeshRenderer.setBox(myEntity)
```

上面的示例会让实体以每秒 1 米的恒定速度移动，无论帧率如何。以每秒 60 帧运行时， `dt` 的值为 1/60；以每秒 30 帧运行时，则为 1/30。若要以不同速度移动，请将 `dt` 乘以以米每秒为单位的速度值。例如： `Vector3.scale(Vector3.Forward(), 3 * dt)` 以每秒 3 米的速度移动实体。

你也可以用同样的方法平滑旋转，只需将旋转量乘以 `dt`.

### 通过系统在两点之间移动

如果你想让实体在两点之间平滑移动，请使用 *线性插值（lerp）* 算法。这个算法在游戏开发中非常常见，因为它确实很实用。

这个 `lerp()` 函数接受三个参数：

* 原点位置的向量
* 目标位置的向量
* 插值比例，取值范围为 0 到 1，表示要完成的平移量占总平移量的比例。

```ts
const originVector = Vector3.Zero()
const targetVector = Vector3.Forward()

let newPos = Vector3.lerp(originVector, targetVector, 0.6)
```

线性插值算法会根据给定的比例，在两个向量之间的路径上找到一个中间点。

例如，如果原点向量是 *(0, 0, 0)* 而目标向量是 *(10, 0, 10)*:

* 使用 0 作为插值比例将返回 *(0, 0, 0)*
* 使用 0.3 作为数值将返回 *(3, 0, 3)*
* 使用 1 作为数值将返回 *(10, 0, 10)*

要实现这一点 `lerp()` 在场景中，我们建议创建一个 [自定义组件](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/jia-gou/custom-components.md) 来存储必要的信息。你还需要定义一个系统，以便在每一帧中实现渐进式移动。

```ts
// 定义自定义组件
const MoveTransportData = {
	start: Schemas.Vector3,
	end: Schemas.Vector3,
	fraction: Schemas.Float,
	speed: Schemas.Float,
}

export const LerpTransformComponent = engine.defineComponent(
	'LerpTransformComponent',
	MoveTransportData
)

// 定义系统
function LerpMove(dt: number) {
	let transform = Transform.getMutable(myEntity)
	let lerp = LerpTransformComponent.getMutable(myEntity)
	if (lerp.fraction < 1) {
		lerp.fraction += dt * lerp.speed
		transform.position = Vector3.lerp(lerp.start, lerp.end, lerp.fraction)
	}
}

engine.addSystem(LerpMove)

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

Transform.create(myEntity, {
	position: Vector3.create(4, 1, 4),
})

MeshRenderer.setBox(myEntity)

LerpTransformComponent.create(myEntity, {
	start: Vector3.create(4, 1, 4),
	end: Vector3.create(8, 1, 8),
	fraction: 0,
	speed: 1,
})
```

![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-a2059f7ebd97343d7176f5565a1b943c4af4af08%2Flerp-move.webp?alt=media)

### 通过系统平滑跟随移动目标

若要让实体逐渐靠近一个不断移动的目标（例如跟随玩家的宠物），请让它在每一帧移动剩余距离的一部分。不要每帧移动固定比例，例如 `Vector3.lerp(current, target, 0.1)`：这样会导致结果取决于帧率，因此实体在速度较快的电脑上会比在较慢的电脑上更快追上目标。应根据 `dt` 计算比例：

```ts
const follower = engine.addEntity()
Transform.create(follower, { position: Vector3.create(8, 1, 8) })
MeshRenderer.setBox(follower)

const RATE = 5 // 值越大，追上目标的速度越快

function FollowSystem(dt: number) {
	const transform = Transform.getMutable(follower)
	const target = Transform.get(engine.PlayerEntity).position
	// 在任何帧率下保持相同的平滑效果
	const t = 1 - Math.exp(-RATE * dt)
	transform.position = Vector3.lerp(transform.position, target, t)
}

engine.addSystem(FollowSystem)
```

同样的公式也适用于旋转，使用 `Quaternion.slerp()`.

### 通过系统在两个角度之间旋转

若要在两个角度之间平滑旋转，请使用 *球面* (*线性* 插值）算法。该算法与 *线性插值*非常相似，但专门用于处理四元数旋转。

slerp() `函数` 接受三个参数：

* 四元数 [ ](https://en.wikipedia.org/wiki/Quaternion) 原始旋转的角度
* 该 [四元数](https://en.wikipedia.org/wiki/Quaternion) 目标旋转的角度
* 插值比例，取值范围为 0 到 1，表示要完成的平移量占总平移量的比例。

{% hint style="info" %}
**💡 提示**：你可以使用 [欧拉角](https://en.wikipedia.org/wiki/Euler_angles) 度数（范围为 0 到 360）传递旋转值，方法是使用 `Quaternion.fromEulerDegrees()`.
{% endhint %}

```ts
const originRotation = Quaternion.fromEulerDegrees(0, 90, 0)
const targetRotation = Quaternion.fromEulerDegrees(0, 0, 0)

let newRotation = Quaternion.slerp(originRotation, targetRotation, 0.6)
```

要在场景中实现这一点，我们建议将传入 `Slerp()` 函数的数据存储在一个 [自定义组件](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/jia-gou/custom-components.md)中。你还需要定义一个系统，在每一帧中实现渐进旋转。

```ts
// 定义自定义组件
const RotateSlerpData = {
	start: Schemas.Quaternion,
	end: Schemas.Quaternion,
	fraction: Schemas.Float,
	speed: Schemas.Float,
}

export const SlerpData = engine.defineComponent('SlerpData', RotateSlerpData)

// 定义系统
function SlerpRotate(dt: number) {
	let transform = Transform.getMutable(myEntity)
	let slerpData = SlerpData.getMutable(myEntity)
	if (slerpData.fraction < 1) {
		slerpData.fraction += dt * slerpData.speed
		transform.rotation = Quaternion.slerp(
			slerpData.start,
			slerpData.end,
			slerpData.fraction
		)
	}
}

engine.addSystem(SlerpRotate)

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

Transform.create(myEntity, {
	position: Vector3.create(4, 1, 4),
})

MeshRenderer.setBox(myEntity)

SlerpData.create(myEntity, {
	start: Quaternion.fromEulerDegrees(0, 0, 0),
	end: Quaternion.fromEulerDegrees(0, 180, 0),
	fraction: 0,
	speed: 0.3,
})
```

{% hint style="warning" %}
**📔 注意**：你也可以改用欧拉角，将旋转表示为 `Vector3` 值，并使用 `Lerp()` 函数，但这意味着每一帧都要进行一次从 `Vector3` 到 `Quaternion` 的转换。旋转值在内部以四元数形式存储在 `Transform` 组件中，因此场景使用四元数会更高效。
{% endhint %}

![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-a3fddc2e8e2cf6cc5fa617cadd7fba6a65d0a802%2Flerp-rotate.webp?alt=media)

一种更简单但效率较低的方法是利用 `Quaternion.rotateTowards` 函数，无需使用任何自定义组件。

```ts
function SimpleRotate(dt: number) {
	let transform = Transform.getMutable(myEntity)
	transform.rotation = Quaternion.rotateTowards(
		transform.rotation,
		Quaternion.fromEulerDegrees(90, 0, 0),
		dt * 10
	)
	if (
		Quaternion.angle(transform.rotation, Quaternion.fromEulerDegrees(90, 0, 0)) < 0.01
	) {
		console.log('done')
		engine.removeSystem(SimpleRotate)
	}
}

engine.addSystem(SimpleRotate)

const myEntity = engine.addEntity()
Transform.create(myEntity, {
	position: Vector3.create(4, 1, 4),
	rotation: Quaternion.fromEulerDegrees(0, 0, 90),
})

MeshRenderer.setBox(myEntity)
```

在上面的示例中， `Quaternion.rotateTowards` 接受三个参数：初始旋转、期望的最终旋转，以及每帧允许的最大增量。在此例中，由于最大增量为 `dt * 10` 度，整个旋转过程将持续约 9 秒。

请注意，该系统还会检查旋转是否已完成；如果已完成，就会从引擎中移除该系统。否则，即使旋转已经完成，系统仍会在每一帧继续进行计算。

### 通过系统在两种尺寸之间更改缩放

如果你希望实体平滑地改变大小且不改变其比例，请使用 *线性插值* （linear interpolation）算法，即 `Scalar` 对象提供的算法。

如果你希望各轴按不同比例缩放，则使用 `Vector3` 表示初始缩放和目标缩放，然后使用 *线性插值* 函数，即 `Vector3`.

对象的 `lerp()` 函数，即 `Scalar` 对象接受三个参数：

* 初始缩放值
* 目标缩放值
* 插值量，即一个介于 0 到 1 之间的值，表示要完成的缩放比例。

```ts
const originScale = 1
const targetScale = 10

let newScale = Scalar.lerp(originScale, targetScale, 0.6)
```

要在场景中实现此插值，我们建议创建一个自定义组件来存储所需信息。你还需要定义一个系统，在每一帧逐步执行缩放。

```ts
// 定义自定义组件
const ScaleTransportData = {
	start: Schemas.Number,
	end: Schemas.Number,
	fraction: Schemas.Float,
	speed: Schemas.Float,
}

export const ScaleTransformComponent = engine.defineComponent(
	'ScaleTransformComponent',
	ScaleTransportData
)

// 定义系统
function LerpMove(dt: number) {
	let transform = Transform.getMutable(myEntity)
	let lerp = ScaleTransformComponent.getMutable(myEntity)
	if (lerp.fraction < 1) {
		lerp.fraction += dt * lerp.speed
		const newScale = Scalar.lerp(lerp.start, lerp.end, lerp.fraction)
		transform.scale = Vector3.create(newScale, newScale, newScale)
	}
}

engine.addSystem(LerpMove)

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

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

MeshRenderer.setBox(myEntity)

ScaleTransformComponent.create(myEntity, {
	start: 1,
	end: 2,
	fraction: 0,
	speed: 1,
})

Vector3.create(1, 1, 1)
```

![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-a430afcd10636fc6852e1b7b5e5157e0dcd9944f%2Flerp-scale.webp?alt=media)

### 通过 system 在两点之间以不规则速度移动

使用 lerp 方法时，你可以让移动速度呈非线性变化。在前面的示例中，我们每帧都按给定的数值增加 lerp 的比例，但也可以使用数学函数让数值呈指数增长，或通过其他方式改变移动节奏。

你也可以使用能产生循环结果的函数（例如正弦函数），来描述往复运动。

这种非线性过渡通常能让场景生动许多。沿曲线加速或逐渐减速的运动，可以充分体现物体或角色的特性。你甚至可以利用数学函数添加弹跳效果。

```ts
// 定义自定义组件
const MoveTransportData = {
	start: Schemas.Vector3,
	end: Schemas.Vector3,
	fraction: Schemas.Float,
	speed: Schemas.Float,
}

export const LerpTransformComponent = engine.defineComponent(
	'LerpTransformComponent',
	MoveTransportData
)

// 定义系统
function LerpMove(dt: number) {
	let transform = Transform.getMutable(myEntity)
	let lerp = LerpTransformComponent.getMutable(myEntity)
	if (lerp.fraction < 1) {
		lerp.fraction += dt * lerp.speed
		const interpolatedValue = interpolate(lerp.fraction)
		transform.position = Vector3.lerp(lerp.start, lerp.end, interpolatedValue)
	}
}

// 将 lerp 比例映射到指数曲线上
function interpolate(t: number) {
	return t * t
}

engine.addSystem(LerpMove)

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

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

MeshRenderer.setBox(myEntity)

LerpTransformComponent.create(myEntity, {
	start: Vector3.create(4, 1, 4),
	end: Vector3.create(8, 1, 8),
	fraction: 0,
	speed: 1,
})
```

上面的示例与之前展示的线性 lerp 示例类似，但 `fraction` 字段在每个时刻都会映射为一个非线性数值。这个非线性数值用于计算 `lerp` 函数，从而使运动沿指数曲线进行。

你也可以像上面那样，将线性过渡映射到曲线上，以相同的方式对旋转或缩放进行过渡映射。

![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-40e98a0199aaec74e734625a0ccf464a7a92f238%2Flerp-speed-up.webp?alt=media)

### 通过 system 沿路径移动

你可以让一个实体遍历由向量组成的数组，在每两个向量之间执行 lerp 移动，从而沿更复杂的路径移动。

```ts
// 定义自定义组件
const PathTransportData = {
	path: Schemas.Array(Schemas.Vector3),
	start: Schemas.Vector3,
	end: Schemas.Vector3,
	fraction: Schemas.Float,
	speed: Schemas.Float,
	pathTargetIndex: Schemas.Int,
}

export const LerpTransformComponent = engine.defineComponent(
	'LerpTransformComponent',
	PathTransportData
)

// 定义系统
function PathMove(dt: number) {
	let transform = Transform.getMutable(myEntity)
	let lerp = LerpTransformComponent.getMutable(myEntity)
	if (lerp.fraction < 1) {
		lerp.fraction += dt * lerp.speed
		transform.position = Vector3.lerp(lerp.start, lerp.end, lerp.fraction)
	} else {
		lerp.pathTargetIndex += 1
		if (lerp.pathTargetIndex >= lerp.path.length) {
			lerp.pathTargetIndex = 0
		}
		lerp.start = lerp.end
		lerp.end = lerp.path[lerp.pathTargetIndex]
		lerp.fraction = 0
	}
}

engine.addSystem(PathMove)

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

Transform.create(myEntity, {
	position: Vector3.create(1, 1, 1),
})

MeshRenderer.setBox(myEntity)

const point1 = Vector3.create(1, 1, 1)
const point2 = Vector3.create(8, 1, 3)
const point3 = Vector3.create(8, 4, 7)
const point4 = Vector3.create(1, 1, 7)

const myPath = [point1, point2, point3, point4]

LerpTransformComponent.create(myEntity, {
	path: myPath,
	start: Vector3.create(4, 1, 4),
	end: Vector3.create(8, 1, 8),
	fraction: 0,
	speed: 1,
	pathTargetIndex: 1,
})
```

上面的示例定义了一条由四个三维向量组成的三维路径。 `PathTransportData` 自定义组件存储的数据与上面 *lerp* 示例中的自定义组件相同，但增加了一个 `path` 数组，其中包含路径上的所有点；还增加了一个 `pathTargetIndex` 字段，用于记录当前正在使用路径中的哪一段。

这个 system 与 *lerp* 示例中的 system 非常相似，但当 lerp 操作完成时，它会设置 `target` 和 `origin` 字段设置为新值。如果到达路径末尾，则返回路径中的第一个值。

![](https://2460066822-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-9d92296f54da83a76e256668dda043ecf2b8be30%2Flerp-path.webp?alt=media)

## 纹理补间

要让纹理平滑滑动，请使用 `Tween` 组件以及 `setTextureMove` 函数。

```ts
Tween.setTextureMove(myEntity, 
	Vector2.create(0, 0), 
	Vector2.create(1, 0), 
	2000
)
```

纹理补间需要以下信息：

* `entity`: 要移动其纹理的实体
* `start`: 表示起始位置的 Vector2
* `end`: 表示结束位置的 Vector2
* `duration`：在两个位置之间移动所需的毫秒数

还可以使用以下另一个可选参数：

* `movementType`:（可选）定义移动作用于偏移量字段还是平铺字段。默认使用偏移量。
* `easingFunction`: 要使用的缓动函数。请参阅 [非线性补间](#non-linear-tweens).

## 纹理的持续移动

要让纹理持续滑动，请使用 `Tween` 组件以及 `setTextureMoveContinuous` 函数。

```ts
Tween.setTextureMoveContinuous(myEntity, 
	Vector2.create(0, 1), 
	0.7
)
```

纹理持续补间需要以下信息：

* `entity`: 要移动其纹理的实体
* `direction`: 表示移动方向的 Vector2
* `speed`: 实体每秒移动的单位数

还可以使用以下另一个可选参数：

* `movementType`: 定义移动作用于偏移量字段还是平铺字段。默认使用偏移量。
* `duration`：移动持续的毫秒数。时间到后，移动将停止。

在 [纹理补间](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/3d-nei-rong-ji-chu/materials.md#texture-tweens) 部分中了解有关纹理补间的更多信息。


---

# 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/3d-nei-rong-ji-chu/move-entities.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.
