Animações de modelo 3D

Como animar modelos 3D na sua scene

Modelos 3D em .glTF e .glb formato podem incluir quantas animações quiser neles. As animações dizem ao mesh como se mover, especificando uma série de keyframes que são distribuídos ao longo do tempo; o mesh então faz a transição de uma pose para a outra para simular movimento contínuo.

A maioria das animações de modelos 3D são animações esqueléticas. Estas animações simplificam a geometria complexa do modelo para uma "figura de arame", ligando cada vértice no mesh ao bone mais próximo no skeleton. Os modeladores ajustam o skeleton para diferentes poses, e o mesh estica e se dobra para acompanhar esses movimentos.

Como alternativa, animações de vértices animam um modelo sem necessidade de um skeleton. Estas animações especificam diretamente a posição de cada vértice no modelo. Decentraland também suporta estas animações.

Veja Animations para detalhes sobre como criar animações para um modelo 3D. Leia Shape components para instruções sobre como importar um modelo 3D para uma scene.

💡 Dica: As animações costumam ser melhores para mover algo no lugar, não para alterar a posição de uma entity. Por exemplo, você pode definir uma animação para mover os pés de um personagem no lugar, mas, para mudar a localização da entity, o ideal é usar o componente Transform. Veja Posicionar entities para mais detalhes.

Verificar se um modelo 3D tem animações

Nem todos os glTF files incluem animações. Para ver se há alguma disponível, você pode fazer o seguinte:

• Se estiver usando VS Code(recomendado), instale a extensão GLTF Tools e veja o conteúdo de um arquivo glTF lá.

• Abra o Babylon Sandbox site e arraste o arquivo glTF (e quaisquer .jpg ou .bin dependências) para o browser.

• Abra o .glTF arquivo com um editor de texto e role até encontrar "animations":.

💡 Dica: Em esqueléticas animações, o nome de uma animação costuma ser composto pelo nome da armature, um underscore e o nome da animação. Por exemplo myArmature_animation1.

Reprodução automática

Se um modelo 3D incluir alguma animação, o comportamento padrão é que a primeira delas seja sempre reproduzida em loop.

Para evitar este comportamento, adicione um componente Animator à entity que tem o modelo e depois trate a reprodução das animações explicitamente. Se houver um Animator componente na entity, todas as animações ficam por padrão com o estado playing: false

💡 Dica: Em Scene Editor, você pode adicionar um Animator componente Add Componentsvisualmente. Veja também. Também pode controlar animações sem código através de Actions, veja Make any item smart.

Tratar animações explicitamente

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

// Criar entity
const shark = engine.addEntity()

// Adicionar um modelo 3D a ela
GltfContainer.create(shark, {
	src: 'models/shark.glb',
})

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

Cada state objeto mantém o controle de se uma animação está atualmente a ser reproduzida.

📔 Nota: O Animator componente deve ser importado via

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

Veja Imports para saber como lidar facilmente com isto.

Obter uma animação

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

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

Animator.getClip requer os seguintes parâmetros:

• entity: A entity do Animator componente que você quer consultar.

• clipName: String com o nome do clip que você quer obter.

Animator.getClip obtém uma versão mutável do estado da animação, para que você possa modificar livremente os valores no que esta função devolve.

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

📔 Nota: Se tentar usar Animator.getClip() para obter um clip que não está listado no Animator componente, isso gera um erro. Use Animator.getClipOrNull() se preferir obter uma resposta null nesse caso, em vez de um erro.

Reproduzir uma animação

O campo .playing num estado de animação determina se a animação está atualmente a ser reproduzida. Note que várias animações podem estar a ser reproduzidas num único modelo 3D ao mesmo tempo.

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

Animator.playSingleAnimation(sharkEntity, 'swim')

Se a entity estiver a reproduzir outras animações, Animator.playSingleAnimation as interrompe.

Animator.playSingleAnimation requer os seguintes parâmetros:

• entity: A entity do Animator componente que você quer afetar.

• clipName: String com o nome do clip que você quer reproduzir.

• resetCursor: (opcional) Se true, reproduz a animação desde o início, mesmo que a animação tenha sido pausada anteriormente. Se false, continua a reproduzir a animação a partir de onde foi pausada. Padrão: true.

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

A tabela seguinte resume como Animator.playSingleAnimation() se comporta, usando diferentes valores para a propriedade resetCursor :

	resetCursor = false	resetCursor = true (padrão)
Atualmente a ser reproduzida	Não tem efeito.	Reproduz desde o início.
Pausada	Retoma desde o último frame reproduzido.	Reproduz desde o início.
Terminada (sem loop)	Reproduz desde o início.	Reproduz desde o início.

Animações em loop

Por padrão, as animações são reproduzidas num loop que continua a repetir a animação para sempre.

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

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

Se loop é definido para false, a animação é reproduzida apenas uma vez e depois para, mantendo-se na pose do último frame.

Parar uma animação

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

Animator.stopAllAnimations(shark)

Animator.stopAllAnimations requer os seguintes parâmetros:

• entity: A entity do Animator componente que você quer afetar.

• resetCursor: (opcional) Se true, ela volta para a pose do primeiro frame da animação. Se false, permanece em pausa na pose atual. Padrão: true.

📔 Nota: Ao reproduzir uma animação com Animator.playSingleAnimation, esta função trata de parar todas as outras animações nos bastidores. Nesse caso, você não precisa parar explicitamente as outras animações.

Quando uma animação termina de reproduzir uma animação sem loop, por padrão o modelo 3D permanece na última pose que tinha. A propriedade shouldReset controla o que acontece quando uma animação parada é reproduzida novamente: se true, a animação é restaurada para o seu estado inicial (o seu primeiro frame, ou o seu último frame se estiver a ser reproduzida com uma speednegativa) sempre que passa de parada para reprodução. Se false (o padrão), ela retoma de onde estava.

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

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

📔 Nota: Repor a pose é uma alteração abrupta. Se quiser fazer com que o modelo faça a transição de forma suave para outra pose, reproduza a outra animação e faça a mistura entre as duas, deslocando gradualmente as suas propriedades de weight . Veja Peso da animação.

Detetar quando uma animação termina

Quando uma animação sem loop termina de ser reproduzida, o engine define a propriedade playing desse estado da animação novamente para false. O código da sua scene pode ler este valor para saber quando a animação terminou, por exemplo para encadear outra animação imediatamente a seguir.

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')
		// encadear a próxima animação
		Animator.playSingleAnimation(shark, 'swim')
	}

	wasPlaying = isPlaying
})

📔 Nota: Ao verificar o estado da animação a cada frame, leia-o sempre através de Animator.get() (somente leitura). Não use Animator.getClip() ou Animator.getMutable() para verificação: isto devolve uma versão mutável do componente, o que o marca como alterado em cada frame e provoca trabalho desnecessário de sincronização.

O campo playing A propriedade só é alterada pelo engine quando a animação termina por si própria. Animações em loop reproduzem até serem paradas, por isso nunca alteram a propriedade por conta própria, e animações com speed definida para 0 nunca terminam.

📔 Nota: Esta funcionalidade só é suportada no cliente Desktop.

Lidar com várias animações

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

// Criar entity
const shark = engine.addEntity()

// Adicionar um modelo 3D a ela
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 tratadas por state objetos separados, e depois ambas são atribuídas ao mesmo Animator componente.

Cada bone numa animação só pode ser afetado por uma animação de cada vez, a menos que estas animações tenham um weight que some até um valor de 1 ou menos.

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

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

📔 Nota: Animator.playSingleAnimation() interrompe todas as outras animações que a entity está atualmente a reproduzir. Para reproduzir várias animações ao mesmo tempo, modifique manualmente a propriedade playing nos estados da animação.

Velocidade da animação

Altere a velocidade a que uma animação é reproduzida alterando a propriedade speed . O valor da velocidade é 1 por padrão.

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

Defina a velocidade abaixo de 1 para a reproduzir mais lentamente, por exemplo 0.5 para a reproduzir a metade da velocidade. Defina-a acima de 1 para a reproduzir mais rapidamente, por exemplo 2 para a reproduzir ao dobro da velocidade.

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

swimAnim.speed = 0.5

Peso da animação

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

Por padrão, weight é igual a 1. O valor de weight não pode ser superior a 1.

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

O campo weight o valor de todas as animações ativas numa entity deve somar 1 em todos os momentos. Se somar menos de 1, a média ponderada usará a posição padrão da armature para a parte restante do cálculo.

Por exemplo, no exemplo de código acima, estamos a reproduzir a animação swim que tem apenas um 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 usam valores da pose padrão da armature.

O campo weight A propriedade pode ser usada de formas interessantes, por exemplo a propriedade weight de swim poderia ser definida em proporção à rapidez com que o shark está a nadar, para que não precise de criar várias animações para natação rápida e lenta.

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

📔 Nota: O valor adicional de weight de todas as animações que estão a atuar num bone de um modelo 3D não pode ser superior a 1. Se mais de uma animação estiver a afetar os mesmos bones ao mesmo tempo, elas precisam de ter o weight definido para valores cuja soma seja inferior a 1.

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

swimAnim.weight = 0.5