# Animações de modelos 3D modelos 3D no *.glTF* e *.glb* format podem incluir quantas animações você quiser. As animações dizem à mesh como se mover, especificando uma série de *keyframes* dispostos ao longo do tempo; a mesh então faz a transição entre uma pose e outra para simular movimento contínuo. A maioria das animações de modelos 3D são [*skeletal animations*](https://en.wikipedia.org/wiki/Skeletal_animation). Essas animações simplificam a geometria complexa do modelo em uma "figura de palito", vinculando cada vertex na mesh ao *bone* mais próximo no *skeleton*. Os modeladores ajustam o skeleton em diferentes poses, e a mesh se estica e se curva para acompanhar esses movimentos. Como alternativa, *vertex animations* animam um modelo sem a necessidade de um skeleton. Essas animações especificam diretamente a posição de cada vertex no modelo. Decentraland também oferece suporte a essas animações. Consulte [Animations](https://github.com/decentraland/docs-creator/blob/main/creator/3d-modeling/animations/README.md) para detalhes sobre como criar animações para um modelo 3D. Leia [Shape components](/creator/content-creator-pt/scenes-sdk7/essenciais-de-conteudo-3d/shape-components.md) para instruções sobre como importar um modelo 3D para uma scene. {% hint style="info" %} **💡 Dica**: As animações geralmente são melhores para mover algo no lugar, não para alterar a posição de um entity. Por exemplo, você pode definir uma animação para mover os pés de um personagem no lugar, mas para alterar a localização do entity é melhor usar o componente Transform. Veja [Positioning entities](/creator/content-creator-pt/scenes-sdk7/essenciais-de-conteudo-3d/move-entities.md) para mais detalhes. {% endhint %} ## Verifique um modelo 3D quanto a 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](https://code.visualstudio.com/)(recomendado), instale a extensão *GLTF Tools* e veja o conteúdo de um arquivo glTF nela. * Abra o arquivo com um editor de texto e role até encontrar [Babylon Sandbox](https://sandbox.babylonjs.com/) site e arraste o arquivo glTF (e quaisquer dependências *.jpg* ou *.bin* ) para o navegador. * Abra o arquivo com um editor de texto e role até encontrar *.glTF* até encontrar *"animations":*. {% hint style="info" %} **💡 Dica**: Em animações *skeletal* , o nome de uma animação costuma ser composto pelo nome da armature, um sublinhado e o nome da animação. Por exemplo `myArmature_animation1`. {% endhint %} ## 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 esse comportamento, adicione um `Animator` componente ao entity que tem o modelo e então trate a reprodução das animações explicitamente. Se um componente `Animator` estiver presente no entity, todas as animações ficam por padrão em um estado `playing: false` e precisam ser reproduzidas manualmente. {% hint style="info" %} **💡 Dica**: No [Scene Editor](/creator/content-creator-pt/scene-editor/comecar/about-editor.md), você pode adicionar um componente **Animator** visualmente. Veja [Add Components](/creator/content-creator-pt/scene-editor/construir/components.md#add-components). Você também pode controlar animações sem código por meio de **Actions**, veja [Torne qualquer item smart](/creator/content-creator-pt/scene-editor/interatividade/make-any-item-smart.md). {% endhint %} ## Tratar animações explicitamente Um `Animator` O componente é usado para acessar todas as animações do entity e pode ser usado para dizer explicitamente ao entity para reproduzir ou parar uma animação. O `Animator` componente inclui um array de `states`, essa 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. ```ts // Criar entity const shark = engine.addEntity() // Adiciona um modelo 3D a ele 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á sendo reproduzida no momento. {% hint style="warning" %} **📔 Nota**: A `Animator` component tem de ser importado via > `import { Animator } from "@dcl/sdk/ecs"` Consulte [Imports](/creator/content-creator-pt/scenes-sdk7/comecar/coding-scenes.md#imports) para saber como lidar com isso facilmente. {% endhint %} ## Buscar uma animação Busque um clip do `Animator` por nome usando a função `.Animator.getClip()` . Essa função retorna 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`: O entity do `Animator` componente que você quer consultar. * `clipName`: String com o nome do clip que você quer buscar. `Animator.getClip` busca uma versão mutável do estado da animação, então você pode modificar livremente os valores do que essa função retorna. ```ts const swimAnim = Animator.getClip(sharkEntity, 'swim') swimAnim.looping = false ``` {% hint style="warning" %} **📔 Nota**: Se você tentar usar `Animator.getClip()` para buscar um clip que existe no modelo 3D, mas não está listado no `Animator` componente, ele retorna `null`. {% endhint %} ## Reproduzir uma animação O `.playing` campo em um estado de animação determina se a animação está sendo reproduzida no momento. Observe que várias animações podem estar sendo reproduzidas em um único modelo 3D ao mesmo tempo. Use o `Animator.playSingleAnimation()` função em um objeto `AnimationState` . ```ts Animator.playSingleAnimation(sharkEntity, 'swim') ``` Se o entity estiver reproduzindo quaisquer outras animações, `Animator.playSingleAnimation` as interrompe. `Animator.playSingleAnimation` requer os seguintes parâmetros: * `entity`: O entity do `Animator` componente que você quer afetar. * `clipName`: String com o nome do clip que você quer reproduzir. * `resetCursor`: *(opcional)* Se *true*, a animação é reproduzida desde o início, mesmo que já tenha sido pausada anteriormente. Se *false*, ela continuará a reprodução a partir de onde foi pausada. Padrão: *true*. ```ts Animator.playSingleAnimation(sharkEntity, 'swim', false) ``` A tabela a seguir resume como `Animator.playSingleAnimation()` se comporta, usando diferentes valores para a propriedade `resetCursor` : | | `reset` = *false* (padrão) | `reset` = *true* | | ---------------------------- | ----------------------------------- | ------------------------ | | **Atualmente em reprodução** | Não tem efeito. | Reproduz desde o início. | | **Pausada** | Retoma do último frame reproduzido. | Reproduz desde o início. | | **Concluída (não em loop)** | Reproduz desde o início. | Reproduz desde o início. | ## Animações em loop Por padrão, as animações são reproduzidas em um loop que continua repetindo a animação para sempre. Altere essa configuração definindo o `loop` propriedade no `state` . ```ts Animator.create(shark, { states: [ { clip: 'bite', playing: true, loop: false, }, ], }) ``` Se `looping` está definido como *false*, a animação é reproduzida apenas uma vez e depois para, permanecendo na postura do último frame. ## Parar uma animação Para parar todas as animações que um entity está reproduzindo, use `Animator.stopAllAnimations()`. ```ts Animator.stopAllAnimations(shark) ``` `Animator.stopAllAnimations` requer os seguintes parâmetros: * `entity`: O entity do `Animator` componente que você quer afetar. * `resetCursor`: *(opcional)* Se *true*, ele retorna para a postura do primeiro frame da animação. Se *false*, permanece pausado na postura atual. Padrão: *true*. {% hint style="warning" %} **📔 Nota**: Ao reproduzir uma animação com `Animator.playSingleAnimation`, essa função cuida de parar todas as outras animações nos bastidores. Você não precisa parar explicitamente as outras animações nesse caso. {% endhint %} Quando uma animação termina de reproduzir uma animação não em loop, por padrão o modelo 3D permanece na última postura que tinha. Para alterar esse comportamento padrão para que, quando a animação terminar, ele volte para a primeira postura, defina o `shouldReset` propriedade para *true*. ```ts Animator.create(shark, { states: [ { name: 'bite', clip: 'bite', playing: true, shouldReset: true, loop: true, }, ], }) ``` Você também pode usar `Animator.stopAllAnimations()` a qualquer momento para definir explicitamente a postura de volta ao primeiro frame da animação. {% hint style="warning" %} **📔 Nota**: Redefinir a postura é uma mudança abrupta. Se você quiser fazer o modelo fazer a transição suavemente para outra postura, você pode: {% endhint %} ## Tratar várias animações Se um modelo 3D tiver várias animações empacotadas nele, um único `Animator` componente pode lidar com todas elas. ```ts // Criar entity const shark = engine.addEntity() // Adiciona um modelo 3D a ele 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` objects `Animator` component. separados e então ambas são atribuídas ao mesmo `bone em uma animação só pode ser afetado por uma animação por vez, a menos que essas animações tenham um` weight que some um valor de 1 ou menos. `bone em uma animação só pode ser afetado por uma animação por vez, a menos que essas animações tenham um` Se uma animação afeta apenas as pernas de um personagem, e outra afeta apenas a cabeça do personagem, então elas podem ser reproduzidas ao mesmo tempo sem problema. Mas se ambas afetam as pernas do personagem, então você deve reproduzir apenas uma por vez, ou reproduzi-las com valores de Se, no exemplo acima, a animação `bite` afetar apenas a boca do tubarão, e a animação `swim` afetar apenas os bones da coluna do tubarão, então ambas podem ser reproduzidas ao mesmo tempo se estiverem em layers separadas. {% hint style="warning" %} **📔 Nota**: `Animator.playSingleAnim()` interrompe todas as outras animações que o entity está reproduzindo no momento. Para reproduzir várias animações ao mesmo tempo, modifique a `playing` propriedade nos estados de animação manualmente. {% endhint %} ## Velocidade da animação Altere a velocidade com que uma animação é reproduzida alterando a propriedade `speed` . O valor de speed é 1 por padrão. ```ts Animator.create(shark, { states: [ { clip: 'swim', playing: true, loop: true, speed: 2, }, ], }) ``` Defina a velocidade abaixo de 1 para reproduzi-la mais devagar, por exemplo 0,5 para reproduzi-la à metade da velocidade. Defina-a acima de 1 para reproduzi-la mais rápido, 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 O `bone em uma animação só pode ser afetado por uma animação por vez, a menos que essas animações tenham um` property permite que um único modelo execute várias animações em diferentes layers ao mesmo tempo, calculando uma média ponderada de todos os movimentos envolvidos na animação. O valor de `bone em uma animação só pode ser afetado por uma animação por vez, a menos que essas animações tenham um` determina quanta importância essa animação terá na média. Por padrão, `bone em uma animação só pode ser afetado por uma animação por vez, a menos que essas animações tenham um` é igual a *1*. O valor de `bone em uma animação só pode ser afetado por uma animação por vez, a menos que essas animações tenham um` não pode ser maior que *1*. ```ts Animator.create(shark, { states: [ { clip: 'swim', playing: true, loop: true, weight: 0.2, }, ], }) ``` O `bone em uma animação só pode ser afetado por uma animação por vez, a menos que essas animações tenham um` valor de todas as animações ativas em um entity deve somar 1 o tempo todo. Se somar menos que 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 reproduzindo a animação *swim* que só tem um `bone em uma animação só pode ser afetado por uma animação por vez, a menos que essas animações tenham um` de *0.2*. Esse movimento de natação será bem sutil: apenas 20% da intensidade definida pela animação. Os 80% restantes do cálculo usam valores da postura padrão da armature. O `bone em uma animação só pode ser afetado por uma animação por vez, a menos que essas animações tenham um` property pode ser usada de formas interessantes, por exemplo o `bone em uma animação só pode ser afetado por uma animação por vez, a menos que essas animações tenham um` propriedade de *swim* poderia ser definido em proporção à rapidez com que o tubarão está nadando, assim você não precisa criar várias animações para nado rápido e lento. Você também pode alterar o valor de `bone em uma animação só pode ser afetado por uma animação por vez, a menos que essas animações tenham um` gradualmente ao iniciar e parar uma animação para dar a ela uma transição mais natural e evitar saltos da pose padrão para a primeira pose na animação. {% hint style="warning" %} **📔 Nota**: O valor adicional de `bone em uma animação só pode ser afetado por uma animação por vez, a menos que essas animações tenham um` de todas as animações que estão atuando em um bone de um modelo 3D não pode ser maior que 1. Se mais de uma animação estiver afetando os mesmos bones ao mesmo tempo, elas precisam ter o peso definido para valores cuja soma seja menor que 1. {% endhint %} ```ts const swimAnim = Animator.getClip(sharkEntity, 'swim') swimAnim.weight = 0.5 ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/essenciais-de-conteudo-3d/3d-model-animations.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.