> 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/3d-model-animations.md).

# Animações de Modelos 3D

Como animar modelos 3D na sua scene

Modelos 3D no formato *.glTF* e *.glb* podem incluir quantas animações quiser. As animações indicam à malha como se mover, especificando uma série de *keyframes* distribuídos ao longo do tempo. Em seguida, a malha faz a transição de uma pose para outra para simular um movimento contínuo.

A maioria das animações de modelos 3D são [*animações esqueléticas*](https://en.wikipedia.org/wiki/Skeletal_animation). Essas animações simplificam a geometria complexa do modelo, transformando-a numa «figura de palitos» e ligando cada vértice da malha ao *bone* mais próximo do *esqueleto*. Os modeladores ajustam o esqueleto para criar diferentes poses, e a malha estica e dobra para acompanhar esses movimentos.

Em alternativa, as *animações de vértices* animam um modelo sem necessidade de um esqueleto. Estas animações especificam diretamente a posição de cada vértice do modelo. Decentraland também suporta este tipo de animação.

Consulte [Animações](https://github.com/decentraland/docs/blob/main/creator/3d-modeling/animations.md) para obter detalhes sobre como criar animações para um modelo 3D. Leia [Componentes de forma](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/shape-components.md) para saber como importar um modelo 3D para uma scene.

{% hint style="info" %}
**💡 Dica**: as animações costumam ser mais adequadas para mover algo sem alterar a sua posição, e não para mudar a posição de uma entidade. Por exemplo, pode definir uma animação para mover os pés de uma personagem sem sair do lugar, mas, para alterar a localização da entidade, é melhor usar o componente Transform. Consulte [Posicionar entidades](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/fundamentos-de-conteudo-3d/move-entities.md) para obter mais detalhes.
{% endhint %}

## Verificar se um modelo 3D tem animações

Nem todos os ficheiros *glTF* incluem animações. Para verificar se há alguma disponível, pode fazer o seguinte:

* Se estiver a usar o [VS Code](https://code.visualstudio.com/)(recomendado), instale a extensão *GLTF Tools* e visualize aí o conteúdo de um ficheiro glTF.
* Abra o site [Babylon Sandbox](https://sandbox.babylonjs.com/) e arraste o ficheiro glTF (e quaisquer dependências *.jpg* ou *.bin* ) para o browser.
* Abra o ficheiro *.glTF* num editor de texto e desça até encontrar *"animations":*.

{% hint style="info" %}
**💡 Dica**: nas *esqueléticas* animações, o nome de uma animação costuma ser composto pelo nome do armature, um sublinhado e o nome da animação. Por exemplo `myArmature_animation1`.
{% endhint %}

## Reprodução automática

Se um modelo 3D incluir animações, o comportamento predefinido é reproduzir sempre a primeira em ciclo contínuo.

Para evitar este comportamento, adicione um `Animator` à entidade que contém o modelo e, em seguida, controle explicitamente a reprodução das animações. Se existir um `Animator` na entidade, todas as animações têm, por predefinição, o estado `playing: false` e têm de ser reproduzidas manualmente.

{% hint style="info" %}
**💡 Dica**: no [Scene Editor](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/primeiros-passos/about-editor.md), pode adicionar visualmente um componente **Animator** . Consulte [Adicionar componentes](https://docs.decentraland.org/creator/content-creator-pt/scene-editor/construir/components.md#add-components). Também pode controlar animações 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 %}

## Controlar animações explicitamente

Um componente `Animator` é utilizado para aceder a todas as animações da entidade e pode ser usado para indicar explicitamente à entidade que reproduza ou pare uma animação. O componente `Animator` inclui um array de `states`, que tem de incluir um objeto para cada animação que o modelo 3D pode executar. Um único componente `Animator` pode incluir tantos estados quantos forem necessários.

```ts
// Create entity
const shark = engine.addEntity()

// Add a 3D model to it
GltfContainer.create(shark, {
	src: 'models/shark.glb',
})

Animator.create(shark, {
	states: [
		{
			clip: 'swim',
			playing: true,
			loop: true,
		},
	],
})
```

Cada objeto `state` regista se uma animação está atualmente a ser reproduzida.

{% hint style="warning" %}
**📔 Nota**: o componente `Animator` tem de ser importado através de

> `import { Animator } from "@dcl/sdk/ecs"`

Consulte [Imports](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/primeiros-passos/coding-scenes.md#imports) para saber como lidar com eles facilmente.
{% endhint %}

## Obter uma animação

Obtenha um clip do `Animator` pelo nome, utilizando a função `.Animator.getClip()` . Esta função devolve uma versão mutável do objeto de estado da animação.

```ts
const swimAnim = Animator.getClip(sharkEntity, 'swim')
```

`Animator.getClip` requer os seguintes parâmetros:

* `entity`: A entidade do componente `Animator` que pretende consultar.
* `clipName`: String com o nome do clip que pretende obter.

`Animator.getClip` obtém uma versão mutável do estado da animação, permitindo-lhe modificar livremente os valores devolvidos por esta função.

```ts
const swimAnim = Animator.getClip(sharkEntity, 'swim')
swimAnim.loop = false
```

{% hint style="warning" %}
**📔 Nota**: Se tentar usar `Animator.getClip()` para obter um clip que não está listado no componente `Animator` , é gerado um erro. Use `Animator.getClipOrNull()` se preferir obter uma resposta `null` nesse caso, em vez de um erro.
{% endhint %}

## Reproduzir uma animação

O campo `.playing` num estado de animação determina se a animação está atualmente em reprodução. Tenha em atenção que podem estar várias animações em reprodução em simultâneo num único modelo 3D.

Use a função `Animator.playSingleAnimation()` num objeto `AnimationState` .

```ts
Animator.playSingleAnimation(sharkEntity, 'swim')
```

Se a entidade estiver a reproduzir outras animações, `Animator.playSingleAnimation` irá pará-las.

`Animator.playSingleAnimation` requer os seguintes parâmetros:

* `entity`: A entidade do componente `Animator` que pretende afetar.
* `clipName`: String com o nome do clip que pretende reproduzir.
* `resetCursor`: *(opcional)* Se *true*, reproduz a animação desde o início, mesmo que tenha sido pausada anteriormente. Se *false*, a animação continua a ser reproduzida a partir do ponto em que foi pausada. Predefinição: *true*.

```ts
Animator.playSingleAnimation(sharkEntity, 'swim', false)
```

A tabela seguinte resume o comportamento de `Animator.playSingleAnimation()` com diferentes valores para a propriedade `resetCursor` :

|                               | `resetCursor` = *false*                      | `resetCursor` = *true* (predefinição) |
| ----------------------------- | -------------------------------------------- | ------------------------------------- |
| **Em reprodução**             | Não tem efeito.                              | É reproduzida desde o início.         |
| **Em pausa**                  | Retoma a partir do último frame reproduzido. | É reproduzida desde o início.         |
| **Concluída (sem repetição)** | É reproduzida desde o início.                | É reproduzida desde o início.         |

## Animações em loop

Por predefinição, as animações são reproduzidas em loop, repetindo-se indefinidamente.

Altere esta definição definindo a propriedade `loop` no objeto `state` .

```ts
Animator.create(shark, {
	states: [
		{
			clip: 'bite',
			playing: true,
			loop: false,
		},
	],
})
```

Se `loop` estiver definido como *false*, a animação é reproduzida apenas uma vez e depois para, mantendo a pose do último frame.

## Parar uma animação

Para parar todas as animações que uma entidade está a reproduzir, use `Animator.stopAllAnimations()`.

```ts
Animator.stopAllAnimations(shark)
```

`Animator.stopAllAnimations` requer os seguintes parâmetros:

* `entity`: A entidade do componente `Animator` que pretende afetar.
* `resetCursor`: *(opcional)* Se *true*, regressa à pose do primeiro frame da animação. Se *false*, permanece em pausa na pose atual. Predefinição: *true*.

{% hint style="warning" %}
**📔 Nota**: Ao reproduzir uma animação com `Animator.playSingleAnimation`, esta função trata de parar todas as outras animações em segundo plano. Nesse caso, não é necessário parar explicitamente as outras animações.
{% endhint %}

Quando uma animação sem repetição termina, por predefinição, o modelo 3D permanece na última pose. A propriedade `shouldReset` controla o que acontece quando uma animação parada é reproduzida novamente: se *true*, a animação é restaurada ao seu estado inicial (o primeiro frame, ou o último frame se estiver a ser reproduzida com uma `speed`) sempre que passa de parada para em reprodução. Se *false* (o valor predefinido), retoma a partir de onde estava.

```ts
Animator.create(shark, {
	states: [
		{
			clip: 'bite',
			playing: true,
			shouldReset: true,
			loop: true,
		},
	],
})
```

Também pode usar `Animator.stopAllAnimations()` em qualquer momento para repor explicitamente a pose no primeiro frame da animação.

{% hint style="warning" %}
**📔 Nota**: Repor a pose é uma alteração abrupta. Se quiser que o modelo passe suavemente para outra pose, reproduza a outra animação e misture as duas, ajustando gradualmente as respetivas propriedades `weight` . Consulte [Peso da animação](#animation-weight).
{% endhint %}

## Detetar quando uma animação termina

Quando uma animação sem repetição termina, o Engine define a propriedade `playing` do estado dessa animação novamente como *false*. O código da sua Scene pode ler este valor para saber quando a animação terminou, por exemplo, para iniciar outra animação imediatamente a seguir.

```ts
let wasPlaying = false

engine.addSystem(() => {
	const animator = Animator.get(shark)
	const biteState = animator.states.find((state) => state.clip === 'bite')
	const isPlaying = biteState?.playing ?? false

	if (wasPlaying && !isPlaying) {
		console.log('bite animation finished')
		// chain the next animation
		Animator.playSingleAnimation(shark, 'swim')
	}

	wasPlaying = isPlaying
})
```

{% hint style="warning" %}
**📔 Nota**: Ao consultar o estado da animação a cada frame, leia-o sempre através de `Animator.get()` (apenas de leitura). Não use `Animator.getClip()` nem `Animator.getMutable()` para consultar o estado: estes métodos devolvem uma versão mutável do componente, que o assinala como alterado a cada frame e provoca trabalho de sincronização desnecessário.

A propriedade `playing` só é alterada pelo Engine quando a animação termina por si própria. As animações em loop são reproduzidas até serem paradas, por isso nunca alteram a propriedade por si mesmas; as animações com `speed` definido como 0 nunca terminam.
{% endhint %}

{% hint style="warning" %}
**📔 Nota**: Esta funcionalidade só é suportada no cliente Desktop.
{% endhint %}

## Lidar com várias animações

Se um modelo 3D tiver várias animações incluídas, um único componente `Animator` pode lidar com todas elas.

```ts
// Create entity
const shark = engine.addEntity()

// Add a 3D model to it
GltfContainer.create(shark, {
	src: 'models/shark.glb'
})

Animator.create(shark, {
	states:[{
			clip: "swim",
			playing: true,
			loop: true
		}, {
			clip: "bite",
			playing: true,
			loop: true
		}
	]
})
```

No exemplo acima, duas animações são controladas por objetos `state` separados e, em seguida, ambas são atribuídas ao mesmo componente `Animator` .

Cada osso de uma animação só pode ser afetado por uma animação de cada vez, a menos que essas animações tenham um `weight` cuja soma seja igual ou inferior a 1.

Se uma animação afetar apenas as pernas de uma personagem e outra afetar apenas a cabeça, podem ser reproduzidas ao mesmo tempo sem qualquer problema. Mas, se ambas afetarem as pernas da personagem, terá de reproduzir apenas uma de cada vez ou reproduzi-las com valores de `weight` mais baixos.

Se, no exemplo acima, a animação `bite` afetar apenas a boca do tubarão e a animação `swim` afetar apenas os ossos da coluna do tubarão, ambas podem ser reproduzidas ao mesmo tempo.

{% hint style="warning" %}
**📔 Nota**: `Animator.playSingleAnimation()` interrompe todas as outras animações que a Entity estiver a reproduzir. Para reproduzir várias animações ao mesmo tempo, modifique manualmente a propriedade `playing` nos estados das animações.
{% endhint %}

## Velocidade da animação

Altere a velocidade de reprodução de uma animação modificando a propriedade `speed` . O valor predefinido da velocidade é 1.

```ts
Animator.create(shark, {
	states: [
		{
			clip: 'swim',
			playing: true,
			loop: true,
			speed: 2,
		},
	],
})
```

Defina um valor inferior a 1 para reproduzir a animação mais lentamente, por exemplo, 0,5 para reproduzi-la a metade da velocidade. Defina um valor superior a 1 para reproduzi-la mais rapidamente, por exemplo, 2 para reproduzi-la ao dobro da velocidade.

```ts
const swimAnim = Animator.getClip(sharkEntity, 'swim')

swimAnim.speed = 0.5
```

## Peso da animação

A propriedade `weight` permite que um único modelo execute várias animações ao mesmo tempo, calculando uma média ponderada de todos os movimentos envolvidos. O valor de `weight` determina a importância atribuída a essa animação na média.

Por predefinição, `weight` é igual a *1*. O valor de `weight` não pode ser superior a *1*.

```ts
Animator.create(shark, {
	states: [
		{
			clip: 'swim',
			playing: true,
			loop: true,
			weight: 0.2,
		},
	],
})
```

O valor de `weight` de todas as animações ativas numa Entity deve totalizar 1 em qualquer momento. Se a soma for inferior a 1, a média ponderada utilizará a posição predefinida do armature na parte restante do cálculo.

Por exemplo, no exemplo de código acima, estamos a reproduzir a animação *swim* que tem apenas um valor de `weight` de *0.2*. Este movimento de natação será bastante subtil: apenas 20% da intensidade definida pela animação. Os restantes 80% do cálculo utilizam valores da postura predefinida do armature.

O `weight` a propriedade pode ser utilizada de formas interessantes, por exemplo, a `weight` propriedade de *swim* poderia ser definida proporcionalmente à velocidade a que o tubarão está a nadar, para não ter de criar várias animações para nadar depressa e devagar.

Também pode alterar o valor de `weight` gradualmente ao iniciar e parar uma animação, para lhe dar uma transição mais natural e evitar saltos da pose predefinida para a primeira pose da animação.

{% hint style="warning" %}
**📔 Nota**: O valor de `weight` adicionado a todas as animações que atuam sobre um osso de um modelo 3D não pode ser superior a 1. Se mais do que uma animação afetar os mesmos ossos ao mesmo tempo, os respetivos valores de weight têm de somar menos de 1.
{% endhint %}

```ts
const swimAnim = Animator.getClip(sharkEntity, 'swim')

swimAnim.weight = 0.5
```


---

# 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/3d-model-animations.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.
