> 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-pt/scenes-sdk7/fundamentos-de-conteudo-3d/move-entities.md).

# Mover Entities

Como mover, girar e dimensionar uma entity gradualmente ao longo do tempo, com mudanças incrementais.

Para mover, rodar ou redimensionar uma Entity na sua Scene ao longo de um período de tempo, use o `Tween` Component. O Engine executa a transformação pretendida suavemente, apresentando atualizações em cada frame até terminar o período especificado. Além disso, os valores do `Transform` Component da Entity afetada são atualizados em tempo real, caso seja necessário fazer verificações de proximidade no código da Scene.

{% hint style="info" %}
**💡 Dica**: No [Scene Editor no Creator Hub](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/primeiros-passos/about-editor.md), pode mover Entities sem código através de **Actions**, consulte [Tornar qualquer item inteligente](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/interatividade/make-any-item-smart.md).
{% endhint %}

O Component Tween tem as seguintes funções:

* `setMove`: Mover entre dois pontos
* `setRotate`: Rodar entre duas direções
* `setScale`: Ajustar a escala entre dois tamanhos
* `setMoveRotateScale`: Fazer a transição simultânea nos três parâmetros
* `setMoveContinuous`: Mover continuamente na mesma direção
* `setRotateContinuous`: Rodar continuamente na mesma direção
* `setTextureMove`: Deslocar a Texture de um Material entre duas posições
* `setTextureMoveContinuous`: Deslocar continuamente a Texture de um Material na mesma direção

## Mover entre dois pontos

Para mover uma Entity entre dois pontos, crie um `Tween` Component com a função `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
)
```

O Tween de movimento recebe as seguintes informações:

* `entity`: A Entity a mover
* `start`: Um Vector3 para a posição inicial
* `end`: Um Vector3 para a posição final
* `duration`: Quantos milissegundos demora a deslocação entre as duas posições

Este outro parâmetro opcional também está disponível:

* `easingFunction`: A função de easing a utilizar. Consulte [Tweens não lineares](#non-linear-tweens)

## Rodar entre duas direções

Para rodar uma entidade entre dois pontos, crie um `Tween` Component com a função `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
)
```

O tween de rotação utiliza as seguintes informações:

* `start`: Um Quaternion para a rotação inicial
* `end`: Um Quaternion para a rotação final
* `duration`: Quantos milissegundos demora a deslocação entre as duas posições

Este outro parâmetro opcional também está disponível:

* `easingFunction`: A função de easing a utilizar. Consulte [Tweens não lineares](#non-linear-tweens)

### Rodar em torno de um ponto de pivot

Ao rodar uma entidade, a rotação é sempre relativa às coordenadas do centro da entidade. Para rodar uma entidade usando outro conjunto de coordenadas como ponto de pivot, crie uma segunda entidade (invisível) com o ponto de pivot como posição e defina-a como parent da entidade que pretende rodar.

Ao rodar a entidade parent, todas as entidades child também serão rodadas usando a posição da parent como ponto de pivot. Tenha em atenção que a `position` da entidade child é relativa à da entidade parent.

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

Tenha em atenção que, neste exemplo, o sistema está a rodar a entidade `pivotEntity` , que é parent da entidade `childEntity` .

## Alterar a escala entre dois tamanhos

Para alterar a escala de uma entidade entre dois tamanhos, crie um `Tween` Component com a função `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
)	

```

O tween de escala utiliza as seguintes informações:

* `start`: Um Vector3 para o tamanho inicial
* `end`: Um Vector3 para o tamanho final
* `duration`: Quantos milissegundos demora a deslocação entre as duas posições

Este outro parâmetro opcional também está disponível:

* `easingFunction`: A função de easing a utilizar. Consulte [Tweens não lineares](#non-linear-tweens)

## Mover-se a partir da posição atual

Enquanto um tween está ativo, o engine atualiza os valores do componente `Transform` da entidade em tempo real. Isso significa que pode ler a posição atual da entidade a partir do seu componente `Transform` a qualquer momento e usar esse valor como `start` de um novo tween. A entidade passa então a mover-se de onde quer que esteja até ao destino, independentemente de como chegou lá.

```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" %}
**📔 Nota**: Passe sempre um valor explícito para `start` . Se o parâmetro `start` não for definido, será tratado como *(0, 0, 0)*, fazendo com que a entidade se teletransporte para a origem da cena antes de se mover. Da mesma forma, se passar um valor `start` codificado diretamente que não corresponda à posição atual da entidade, esta teletransporta-se visivelmente para essa posição antes de se mover. Leia a posição atual a partir do componente `Transform` da entidade, como nos exemplos desta secção, sempre que quiser que o movimento comece a partir de onde a entidade está nesse momento.
{% endhint %}

### Redirecionar durante o percurso

Chamar `setMove` (ou qualquer outra função de tween) numa entidade que já tenha um tween em execução substitui o tween atual pelo novo. Como o valor de `start` é lido da posição atual da entidade, isso redireciona-a suavemente a meio do percurso: ela muda de direção a partir de onde estiver nesse momento, sem saltos.

O exemplo abaixo move uma entidade para a plataforma em que o jogador clicar. Se o jogador clicar noutra plataforma enquanto a entidade ainda estiver em movimento, ela muda suavemente de direção para o novo destino.

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

Para executar lógica quando a entidade chegar ao destino, consulte [Quando o tween terminar](#on-tween-finished).

{% hint style="warning" %}
**📔 Nota**: Redirecione desta forma apenas em resposta a eventos ocasionais, como um clique ou a chegada a um ponto de passagem. Se o destino mudar constantemente, por exemplo, no caso de uma entidade que segue o jogador, não crie um novo tween em cada frame: a entidade ficará visivelmente aos solavancos. Consulte [Seguir um destino em movimento](#follow-a-moving-target).
{% endhint %}

## Tweens não lineares

Os tweens podem usar diferentes **funções de easing** que afetam a taxa de mudança ao longo do tempo. Uma função **linear** , significa que a velocidade da mudança é constante do início ao fim. Há muitas opções para escolher, que desenham curvas com formas diferentes, consoante o início e/ou o fim sejam lentos e em que medida. Uma curva **easeinexpo** começa lentamente e termina rapidamente, aumentando a velocidade de forma exponencial; por outro lado, uma **easeoutexpo** a curva começa rapidamente e termina devagar.

{% hint style="info" %}
**💡 Dica**: Experimente diferentes curvas de movimento. As diferenças costumam ser subtis, mas interpretamos subconscientemente informações sobre a forma como as coisas se movem, como o peso, a fricção ou até a personalidade.
{% endhint %}

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

```

O parâmetro opcional `easingFunction` obtém o seu valor do enum `EasingFunction` , que oferece as seguintes opções:

* `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`

## Rotação constante

Para fazer uma Entity rodar continuamente, use o componente `Tween` com a função `setRotateContinuous` .

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

O Tween de rotação contínua recebe as seguintes informações:

* `entity`: A entidade a rodar
* `direction`: Um Quaternion que determina o eixo em torno do qual rodar. Só importa o eixo desta rotação; a amplitude do ângulo é ignorada. Por exemplo, `Quaternion.fromEulerDegrees(0, -1, 0)` e `Quaternion.fromEulerDegrees(0, -90, 0)` comportam-se da mesma forma, rodando ambos em torno do eixo *y* no sentido negativo.
* `speed`: Quantos graus por segundo a entidade irá rodar. Um valor negativo faz com que rode no sentido oposto.

Este outro parâmetro opcional também está disponível:

* `duration`: Durante quantos milissegundos manter a rotação. Após esse período, a rotação para.

## Movimento constante

Para fazer uma entidade mover-se constantemente na mesma direção, use o componente `Tween` com a função `setMoveContinuous` .

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

O tween de movimento contínuo recebe as seguintes informações:

* `entity`: A Entity a mover
* `direction`: Um Vector3 para o movimento
* `speed`: Quantos metros por segundo a entidade irá mover-se

Este outro parâmetro opcional também está disponível:

* `duration`: Durante quantos milissegundos manter o movimento. Após esse período, o movimento para.

O tween de movimento contínuo recebe as seguintes informações:

### Seguir um alvo em movimento

`setMoveContinuous` também é a ferramenta certa quando o destino está sempre a mudar, por exemplo, para uma entidade que segue o jogador. Pode parecer tentador criar um novo tween `setMove` a cada frame, apontado para a posição mais recente do jogador, mas isso provoca uma trepidação visível.

A razão é que a posição que lê do componente `Transform` de uma entidade animada por um tween é a posição que o Engine comunicou pela última vez à Scene, pelo que fica alguns frames atrás da posição real da entidade. Quando passa esse valor como `start` de um novo tween, o Engine aplica-o imediatamente e a entidade salta para a posição em que estava alguns frames antes. Uma dessas correções é impercetível, mas repeti-las muitas vezes por segundo não é.

`setMoveContinuous` evita completamente este problema, porque recebe uma direção e uma velocidade em vez de um ponto de partida. O Engine continua a usar a posição real da entidade, por isso, substituir o tween para mudar de direção nunca faz a entidade saltar.

```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) {
		// Perto o suficiente: um tween contínuo não tem destino, por isso tem de o parar manualmente
		if (Tween.has(myEntity)) {
			Tween.deleteFrom(myEntity)
		}
		return
	}

	const direction = Vector3.subtract(playerPosition, myPosition)
	direction.y = 0 // permanecer no chão, mesmo que o jogador salte

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

{% hint style="warning" %}
**📔 Nota**: Um tween contínuo nunca termina por si só, por isso a entidade continua a mover-se até remover o componente `Tween` com `Tween.deleteFrom()`, ou até que a `duration` opcional termine. Tenha também em atenção que voltar a apontar em cada frame envia uma atualização ao motor a cada frame. Para evitar isso, só volte a chamar `setMoveContinuous` quando a direção mudar o suficiente para fazer diferença.
{% endhint %}

## Sequências de Tween

Para fazer uma entidade executar uma série de tweens em sequência, use o componente `TweenSequence` . Este componente requer dois campos:

* `sequence`: Uma matriz com várias definições de tween, que serão executadas sequencialmente. A matriz pode estar vazia, caso em que apenas executa o tween atual.
* `loop` *(opcional)*: Se não for fornecido, a sequência será executada apenas uma vez. Se o campo estiver presente, o valor tem de ser um valor do enum `TweenLoop` . Os valores aceites são:
  * `TL_RESTART`: Quando a sequência termina, recomeça. Se o último estado não corresponder ao primeiro, a entidade salta instantaneamente de um para o outro.
  * `TL_YOYO`: Quando a sequência termina, ela é executada ao contrário, percorrendo todos os tweens em ordem inversa até voltar ao início. Depois, recomeça.

### Mover-se para a frente e para trás

Para fazer uma plataforma mover-se continuamente para a frente e para trás entre duas posições, deixe a matriz `sequence` vazia e defina `loop` como `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 })
```

A entidade mover-se-á para a frente e para trás entre o ponto inicial e o ponto final, com a mesma duração e a mesma função de easing em ambas as direções.

### Seguir um percurso

Para fazer uma entidade seguir um percurso mais complexo com vários pontos, forneça uma lista de definições de tween em `sequence` de um componente `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,
})
```

Tenha em atenção que, ao definir um tween dentro de um TweenSequence, tem de usar o formato mais detalhado de `Tween.Mode.Move`, ou `Tween.Mode.Rotate`, ou `Tween.Mode.Scale` para definir o tween. Neste formato mais detalhado, tem de especificar:

* `duration`: Quantos milissegundos demora a deslocação entre as duas posições
* `easingFunction`: A função de easing a utilizar. Consulte [Tweens não lineares](#non-linear-tweens). Neste formato, o valor é obrigatório.
* `mode`: O modo do tween, que pode ser `Tween.Mode.Move`, `Tween.Mode.Rotate`, ou `Tween.Mode.Scale`.

E, dentro do campo `mode` , tem de especificar:

* `start`: O valor inicial do tween
* `end`: O valor final do tween

## Quando o tween terminar

Use `tweenSystem.tweenCompleted` para detetar quando um tween terminou. Isto pode ser útil para executar ações quando um tween termina, por exemplo, para abrir a porta de um elevador.

```ts
engine.addSystem(() => {
	const tweenCompleted = tweenSystem.tweenCompleted(myEntity)
	if (tweenCompleted) {
		//play sound
	}
})
```

## Tweens simultâneos

Para mover, rodar e alterar a escala de uma Entity entre um estado inicial e um estado final, crie um componente `Tween` com a função `setMoveRotateScale` . Esta função também pode ser usada com qualquer combinação destes três parâmetros.

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

O Tween de movimento recebe as seguintes informações:

* `entity`: A Entity a mover
* `params`: Um objeto com os seguintes parâmetros
  * `position`: *(opcional)* Um objeto com um `start` e `end` valor, ambos como `Vector3`.
  * `rotation`: *(opcional)* Um objeto com um `start` e `end` valor, ambos como `Quaternion`.
  * `scale`: *(opcional)* Um objeto com um `start` e `end` valor, ambos como `Vector3`. Pelo menos um de `position`, `rotation` ou `scale` tem de ser fornecido.
  * `duration`: *(obrigatório)* Quantos milissegundos são necessários para fazer a transição entre os dois conjuntos de valores
  * `easingFunction`: *(opcional)* Que função de easing utilizar. Consulte [Tweens não lineares](#non-linear-tweens)

Uma Entity só pode ter um componente `Tween` e cada componente Tween só pode executar uma transformação de cada vez. Com o tipo de tween `setMoveRotateScale` pode fazer uma Entity mover-se lateralmente e rodar ao mesmo tempo, mas ambos os movimentos seguirão a mesma linha temporal. Se precisar que as transições sejam independentes, pode recorrer a Entities parentais. Por exemplo, pode ter uma Entity parental invisível que se move lateralmente e uma Entity filha visível que roda.

No seguinte excerto, uma Entity parental roda enquanto uma Entity filha aumenta de escala.

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

## Pausar um tween

Para pausar um tween, altere a propriedade `playing` para false. Para o retomar, volte a alterá-la para true.

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

Para terminar um tween que não precisa de continuar, elimine o componente `Tween` da entidade. Se a entidade também estiver a utilizar um componente `TweenSequence` elimine-o também.

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

## Tweens baseados num sistema

Em vez de utilizar o componente Tween e deixar que o engine trate da transformação, pode preferir fazer esta transição gradualmente, frame a frame, através de um [sistema](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/systems.md) na sua scene, movendo a entidade uma pequena quantidade de cada vez que a função é executada.

Por um lado, isto dá-lhe mais controlo para recalcular os movimentos em cada frame. Por outro lado, o código é mais complicado e os jogadores com máquinas menos potentes poderão sentir o tween como lento, notando cada incremento.

### Mover através de um sistema

A forma mais simples de mover uma entidade é modificar gradualmente o valor de *posição* armazenado no componente `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)
```

Neste exemplo, movemos uma entidade 0,05 metros por tick do ciclo do jogo.

`Vector3.Forward()` devolve um vector orientado para a frente com 1 metro de comprimento. Neste exemplo, reduzimos depois este vector para 1/20 do seu comprimento com `Vector3.scale()`. A velocidade resultante depende da frequência de frames: a 60 frames por segundo, a entidade move-se a 3 metros por segundo, mas numa máquina que execute a 30 frames por segundo, move-se apenas a 1,5 metros por segundo.

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

### Rodar através de um sistema

A forma mais simples de rodar uma entidade é alterar gradualmente os valores no componente Transform e executar esta operação como parte da função de um sistema.

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

Note que, para combinar a rotação atual com cada incremento, estamos a utilizar `Quaternion.multiply`. Na matemática dos quaternions, combinam-se duas rotações multiplicando-as, NÃO somando-as. A rotação resultante da multiplicação de um quaternion por outro é equivalente à rotação final obtida ao executar primeiro uma rotação e depois a outra.

Neste exemplo, estamos a rodar a entity 1 grau para cima em cada tick do loop do jogo.

{% hint style="info" %}
**💡 Dica**: Para fazer com que uma entity rode sempre na direção do jogador, pode adicionar um [`Billboard` component](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/entity-positioning.md#face-the-player).
{% endhint %}

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

### Rodar em torno de um ponto de pivô através de um system

Ao rodar uma entidade, a rotação é sempre relativa às coordenadas do centro da entidade. Para rodar uma entidade usando outro conjunto de coordenadas como ponto de pivot, crie uma segunda entidade (invisível) com o ponto de pivot como posição e defina-a como parent da entidade que pretende rodar.

Ao rodar a entidade parent, todas as entidades child também serão rodadas usando a posição da parent como ponto de pivot. Tenha em atenção que a `position` da entidade child é relativa à da entidade parent.

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

Tenha em atenção que, neste exemplo, o sistema está a rodar a entidade `pivotEntity` , que é parent da entidade `childEntity` .

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

### Ajustar o movimento ao tempo de atraso

Suponha que o jogador que visita a sua scene tem dificuldade em acompanhar a taxa de frames. Isso pode fazer com que o movimento pareça irregular, pois os frames não estão todos espaçados de forma uniforme, mas cada um move a entity na mesma medida.

Pode compensar esta irregularidade utilizando o `dt` como parâmetro para ajustar a escala do movimento.

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

O exemplo acima move a entity a uma velocidade constante de 1 metro por segundo, independentemente da taxa de frames. Ao executar a 60 frames por segundo, o valor de `dt` é 1/60; a 30 frames por segundo, é 1/30. Para mover a uma velocidade diferente, multiplique `dt` por essa velocidade em metros por segundo: por exemplo, `Vector3.scale(Vector3.Forward(), 3 * dt)` move a entity a 3 metros por segundo.

Também pode suavizar as rotações da mesma forma, multiplicando o valor da rotação por `dt`.

### Mover entre dois pontos através de um system

Se quiser que uma entity se mova suavemente entre dois pontos, utilize o algoritmo *lerp* (interpolação linear). Este algoritmo é muito conhecido no desenvolvimento de jogos, pois é bastante útil.

A `lerp()` recebe três parâmetros:

* O vetor da posição de origem
* O vetor da posição de destino
* A quantidade, um valor entre 0 e 1 que representa a fração da translação a efetuar.

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

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

O algoritmo de interpolação linear encontra um ponto intermédio no percurso entre os dois vetores que corresponde à quantidade fornecida.

Por exemplo, se o vetor de origem for *(0, 0, 0)* e o vetor de destino for *(10, 0, 10)*:

* Utilizar uma quantidade de 0 devolveria *(0, 0, 0)*
* Utilizar uma quantidade de 0,3 devolveria *(3, 0, 3)*
* Utilizar uma quantidade de 1 devolveria *(10, 0, 10)*

Para implementar esta `lerp()` na sua scene, recomendamos que crie um [component personalizado](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/custom-components.md) para guardar as informações necessárias. Também precisa de definir um system que implemente o movimento gradual em cada frame.

```ts
// definir component personalizado
const MoveTransportData = {
	start: Schemas.Vector3,
	end: Schemas.Vector3,
	fraction: Schemas.Float,
	speed: Schemas.Float,
}

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

// define system
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)

// create entity
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://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-a2059f7ebd97343d7176f5565a1b943c4af4af08%2Flerp-move.webp?alt=media)

### Seguir suavemente um alvo em movimento através de um sistema

Para fazer uma Entity aproximar-se suavemente de um alvo que continua em movimento, como um animal de estimação que segue o jogador, mova-a uma parte da distância restante a cada frame. Não use uma parte fixa por frame, como `Vector3.lerp(current, target, 0.1)`: o resultado passa então a depender da taxa de frames, pelo que a Entity alcança o alvo mais depressa num computador rápido do que num lento. Calcule a proporção a partir de `dt` em vez disso:

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

const RATE = 5 // Higher values catch up faster

function FollowSystem(dt: number) {
	const transform = Transform.getMutable(follower)
	const target = Transform.get(engine.PlayerEntity).position
	// The same smoothing at any frame rate
	const t = 1 - Math.exp(-RATE * dt)
	transform.position = Vector3.lerp(transform.position, target, t)
}

engine.addSystem(FollowSystem)
```

A mesma fórmula funciona para rotações com `Quaternion.slerp()`.

### Rodar entre dois ângulos através de um sistema

Para rodar suavemente entre dois ângulos, use o algoritmo *slerp* (*(interpolação* esférica *lerp*, mas funciona com rotações de quaternion.

A função `slerp()` recebe três parâmetros:

* O [quaternion](https://en.wikipedia.org/wiki/Quaternion) ângulo da rotação de origem
* O [quaternion](https://en.wikipedia.org/wiki/Quaternion) ângulo da rotação de destino
* A quantidade, um valor entre 0 e 1 que representa a fração da translação a efetuar.

{% hint style="info" %}
**💡 Dica**: pode passar valores de rotação em [euler](https://en.wikipedia.org/wiki/Euler_angles) graus (de 0 a 360) usando `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)
```

Para implementar isso na sua cena, recomendamos armazenar os dados usados pela função `Slerp()` num [componente personalizado](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/arquitetura/custom-components.md). Também é necessário definir um sistema que implemente a rotação gradual em cada frame.

```ts
// definir component personalizado
const RotateSlerpData = {
	start: Schemas.Quaternion,
	end: Schemas.Quaternion,
	fraction: Schemas.Float,
	speed: Schemas.Float,
}

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

// define system
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)

// create entity
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" %}
**📔 Nota**: em alternativa, poderia representar a rotação com ângulos de euler como valores `Vector3` e usar uma função `Lerp()` , mas isso implicaria uma conversão de `Vector3` para `Quaternion` em cada frame. Os valores de rotação são armazenados internamente como quaternions no componente `Transform` , por isso, é mais eficiente trabalhar com quaternions na cena.
{% endhint %}

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

Uma abordagem mais simples, mas menos eficiente, tira partido da função `Quaternion.rotateTowards` e evita a utilização de componentes personalizados.

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

No exemplo acima `Quaternion.rotateTowards` recebe três argumentos: a rotação inicial, a rotação final pretendida e o incremento máximo por frame. Neste caso, como o incremento máximo é de `dt * 10` graus, a rotação será efetuada ao longo de cerca de 9 segundos.

Note que o System também verifica se a rotação está concluída e, em caso afirmativo, remove o System do Engine. Caso contrário, o System continuaria a efetuar cálculos em cada frame, mesmo depois de a rotação estar concluída.

### Alterar a escala entre dois tamanhos através de um System

Se quiser que uma Entity altere de tamanho suavemente e sem mudar as proporções, use o algoritmo de *lerp* (interpolação linear) do `Scalar` objecto.

Por outro lado, se quiser alterar os eixos em proporções diferentes, use `Vector3` para representar a escala de origem e a escala de destino e, em seguida, use a função *lerp* do `Vector3`.

A `lerp()` do `Scalar` recebe três parâmetros:

* Um número para a escala de origem
* Um número para a escala de destino
* A quantidade, um valor entre 0 e 1 que representa a proporção da escala a aplicar.

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

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

Para implementar este lerp na sua Scene, recomendamos criar um Component personalizado para armazenar as informações necessárias. Também precisa de definir um System que implemente o redimensionamento gradual em cada frame.

```ts
// definir component personalizado
const ScaleTransportData = {
	start: Schemas.Number,
	end: Schemas.Number,
	fraction: Schemas.Float,
	speed: Schemas.Float,
}

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

// define system
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)

// create entity
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://2402076176-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoPnXBby9S6MrsW83Y9qZ%2Fuploads%2Fgit-blob-a430afcd10636fc6852e1b7b5e5157e0dcd9944f%2Flerp-scale.webp?alt=media)

### Mover-se a velocidades irregulares entre dois pontos através de um sistema

Ao usar o método lerp, pode tornar a velocidade do movimento não linear. No exemplo anterior, incrementamos a quantidade de lerp por um valor definido a cada frame, mas também poderíamos usar uma função matemática para aumentar o número exponencialmente ou de outras formas que resultem num ritmo de movimento diferente.

Também pode usar uma função que produz resultados recorrentes, como uma função seno, para descrever um movimento de ida e volta.

Muitas vezes, estas transições não lineares podem dar muita vida a uma cena. Um movimento que acelera ao longo de uma curva ou abranda gradualmente pode dizer muito sobre a natureza de um objeto ou personagem. Pode até tirar partido de funções matemáticas que acrescentam efeitos de ressalto.

```ts
// definir component personalizado
const MoveTransportData = {
	start: Schemas.Vector3,
	end: Schemas.Vector3,
	fraction: Schemas.Float,
	speed: Schemas.Float,
}

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

// define system
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)
	}
}

// map the lerp fraction to an exponential curve
function interpolate(t: number) {
	return t * t
}

engine.addSystem(LerpMove)

// create entity
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,
})
```

O exemplo acima é igual ao exemplo de lerp linear que mostrámos anteriormente, mas o `fraction` campo é mapeado para um valor não linear em cada tick. Este valor não linear é usado para calcular a função `lerp` , resultando num movimento que segue uma curva exponencial.

Também pode mapear uma transição de rotação ou escala da mesma forma que se mostra acima, mapeando uma transição linear para uma curva.

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

### Seguir um caminho através de um sistema

Pode fazer com que uma Entity percorra uma matriz de vetores, realizando um movimento lerp entre cada um deles para seguir um caminho mais complexo.

```ts
// definir component personalizado
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
)

// define system
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)

// create entity
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,
})
```

O exemplo acima define um caminho 3D composto por quatro vetores 3D. O `PathTransportData` componente personalizado contém os mesmos dados usados pelo componente personalizado no exemplo de *lerp* acima, mas acrescenta uma matriz `path` , com todos os pontos do nosso caminho, e um campo `pathTargetIndex` para acompanhar o segmento do caminho que está a ser usado no momento.

O sistema é muito semelhante ao sistema do exemplo de *lerp* mas, quando uma ação lerp é concluída, define o `target` e `origin` campos para novos valores. Se chegarmos ao fim do percurso, voltamos ao primeiro valor do percurso.

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

## Tweens de textura

Para fazer uma textura deslizar suavemente, use o `Tween` componente com a função `setTextureMove` .

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

O tween de textura recebe as seguintes informações:

* `entity`: A entidade cuja textura será movida
* `start`: Um Vector2 para a posição inicial
* `end`: Um Vector2 para a posição final
* `duration`: Quantos milissegundos demora a deslocação entre as duas posições

Este outro parâmetro opcional também está disponível:

* `movementType`: (opcional), define se o movimento será no campo de deslocamento ou de repetição. Por predefinição, usa o deslocamento.
* `easingFunction`: A função de easing a utilizar. Consulte [Tweens não lineares](#non-linear-tweens).

## Movimento constante da textura

Para fazer uma textura deslizar continuamente, use o `Tween` componente com a função `setTextureMoveContinuous` .

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

O tween contínuo de textura recebe as seguintes informações:

* `entity`: A entidade cuja textura será movida
* `direction`: Um Vector2 para a direção do movimento
* `speed`: Quantas unidades por segundo a entidade se moverá

Este outro parâmetro opcional também está disponível:

* `movementType`: define se o movimento será no campo de deslocamento ou de repetição. Por predefinição, usa o deslocamento.
* `duration`: Durante quantos milissegundos manter o movimento. Após esse período, o movimento para.

Saiba mais sobre tweens de textura na [secção Tweens de textura](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/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-pt/scenes-sdk7/fundamentos-de-conteudo-3d/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.
