Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Introdução aos recursos de animação

O nó AnimationPlayer permite que você crie desde animações simples até animações complexas.

Neste guia, você aprenderá a:

Trabalhar com o Painel de Animação
Animar qualquer propriedade de qualquer nó
Criar uma animação simples

No Godot, você pode animar qualquer coisa disponível no Inspetor, como transformações de nós, sprites, elementos de interface, partículas, visibilidade e cor de materiais, entre outros. Também é possível modificar valores de variáveis de script e até mesmo chamar funções.

Criar um nó AnimationPlayer

Para usar as ferramentas de animação, primeiro temos que criar um nó AnimationPlayer.

O tipo de nó AnimationPlayer é o contêiner de dados para suas animações. Um único nó AnimationPlayer pode armazenar múltiplas animações, que podem fazer transição automaticamente entre si.

Após criar um nó AnimationPlayer, clique nele para abrir o Painel de Animação na parte inferior da viewport.

O painel de animação consiste em quatro partes:

Controles de animação (ou seja, adicionar, carregar, salvar e excluir animações)
Lista de faixas
A linha do tempo com quadros-chave
A linha do tempo e os controles de trilha, onde você pode ampliar a linha do tempo e editar trilhas, por exemplo.

A animação por computador depende de quadros-chave

Um keyframe define o valor de uma propriedade em um ponto no tempo.

Formas de diamante representam keyframes na linha do tempo. Uma linha entre dois keyframes indica que o valor não muda entre eles.

Você define valores para as propriedades de um nó e cria quadros-chave (keyframes) de animação para eles. Quando a animação é executada, o motor interpolará os valores entre os quadros-chave, fazendo com que eles mudem gradualmente ao longo do tempo.

Dois quadros-chave são tudo o que é necessário para obter um movimento suave

A linha do tempo (timeline) define quanto tempo a animação vai durar. Você pode inserir quadros-chave em vários pontos e alterar o tempo deles.

Cada linha no Painel de Animação é uma faixa (track) de animação que referencia uma propriedade Normal ou de Transformação de um nó. Cada faixa armazena um caminho para um nó e sua propriedade afetada. Por exemplo, a faixa de posição na ilustração refere-se à propriedade position do nó Sprite2D.

Dica

Se você animar a propriedade errada, poderá editar o caminho de uma trilha a qualquer momento clicando duas vezes nela e digitando o novo caminho. Reproduza a animação utilizando o botão "Play from beginning" Reproduzir desde o início (ou pressionando Shift + D) para ver as alterações imediatamente.

Tutorial: Criando uma animação simples

Configuração da cena

Para este tutorial, criaremos um nó Sprite com um AnimationPlayer como filho. Vamos animar o sprite para se mover entre dois pontos na tela.

Aviso

AnimationPlayer herda de Node em vez de Node2D ou Node3D, o que significa que os nós filhos não herdarão a transformação dos nós pais devido à presença de um Node simples na hierarquia.

Portanto, não é recomendável adicionar nós que tenham uma transformação 2D/3D como filho de um nó AnimationPlayer.

O sprite contém uma textura de imagem. Para este tutorial, selecione o nó Sprite2D, clique em Texture no Inspetor e depois clique em Load. Selecione o ícone padrão do Godot para a textura do sprite.

Adicionando uma animação

Selecione o nó AnimationPlayer e clique no botão "Animation" no editor de animação. Na lista, selecione "New" ( Adicionar animação ) para adicionar uma nova animação. Digite um nome para a animação na caixa de diálogo.

Gerenciando bibliotecas de animação

Para fins de reutilização, a animação é registrada em uma lista no recurso de biblioteca de animação. Se você adicionar uma animação ao AnimationPlayer sem especificar nenhuma configuração específica, a animação será registrada na biblioteca de animação [Global] que o AnimationPlayer possui por padrão.

Se houver múltiplas bibliotecas de animação e você tentar adicionar uma animação, uma caixa de diálogo aparecerá com opções.

Adicionar uma nova animação com opção de biblioteca

Adicionando uma faixa

Para adicionar uma nova trilha ao seu sprite, selecione-o e observe a barra de ferramentas:

Esses interruptores e botões permitem adicionar keyframes para posição, rotação e escala do nó selecionado. Como estamos animando apenas a posição do sprite, certifique-se de que apenas o interruptor de posição esteja selecionado. Os interruptores selecionados aparecem em azul.

Clique no botão de chave para criar o primeiro keyframe. Como ainda não temos uma trilha configurada para a propriedade Position, o Godot oferecerá criá-la automaticamente. Clique em Create.

O Godot criará uma nova trilha e inserirá o primeiro keyframe no início da linha do tempo:

O segundo quadro-chave

Precisamos definir a posição final do sprite e quanto tempo ele levará para chegar até lá.

Digamos que queremos que ele leve dois segundos para se mover entre os pontos. Por padrão, a animação dura apenas um segundo, então altere a duração da animação para 2 nos controles localizados à direita do cabeçalho da linha do tempo do painel de animação.

Agora, mova o sprite para a direita, até sua posição final. Você pode usar a Ferramenta de mover na barra de ferramentas ou definir o valor X de Position no Inspetor.

Clique no cabeçalho da linha do tempo próximo da marca de dois segundos no painel de animação e, em seguida, clique no botão de chave na barra de ferramentas para criar o segundo keyframe.

Reproduzir a animação

Clique no botão "Reproduzir desde o início" ().

Eba! Nossa animação está funcionando:

Reprodução automática ao carregar

Você pode fazer com que uma animação seja reproduzida automaticamente quando a cena do nó AnimationPlayer inicia ou se junta a outra cena. Para fazer isso, clique no botão "Autoplay on load" no editor de animação, que fica bem ao lado do botão de editar.

O ícone correspondente também aparecerá na frente do nome da animação, para que você possa identificar facilmente qual é a animação com reprodução automática.

Vai e volta

O Godot possui um recurso interessante que podemos usar em animações. Quando a Repetição de Animação (Animation Looping) está ativada, mas nenhum quadro-chave é especificado no final da animação, o primeiro quadro-chave também se torna o último.

Isso significa que podemos estender a duração da animação para quatro segundos agora, e o Godot também calculará os quadros do último quadro-chave de volta ao primeiro, movendo nosso sprite de um lado para o outro.

Você pode alterar esse comportamento modificando o modo de loop da trilha. Isso é abordado no próximo capítulo.

Configurações de faixa

Cada trilha de propriedade possui um painel de configurações em sua extremidade, onde é possível definir o modo de atualização, a interpolação da trilha e o modo de loop.

O modo de atualização de uma faixa informa a Godot quando atualizar os valores de propriedade. Isso pode ser:

Contínuo: Atualiza a propriedade a cada quadro
Discreto: Apenas atualiza a propriedade nos keyframes
Capture: se o tempo do primeiro keyframe for maior que 0.0, o valor atual da propriedade será lembrado e misturado com a primeira chave da animação. Por exemplo, você pode usar o modo Capture para mover um nó que esteja em qualquer posição para uma localização específica.

Normalmente você utilizará o modo "Continuous". Os outros tipos são usados para criar animações complexas por script.

A interpolação da trilha informa ao Godot como calcular os valores dos quadros entre keyframes. Os seguintes modos de interpolação são suportados:

Nearest(Mais próximo): defina o valor do quadro-chave mais próximo
Linear: defina o valor com base em um cálculo de função linear entre os dois quadros-chave
Cúbico: defina o valor com base em um cálculo de função cúbica entre os dois quadros-chave
Linear Angle (Apenas aparece em propriedades de rotação): Modo linear com rotação pelo caminho mais curto
Cubic Angle (Apenas aparece em propriedades de rotação): Modo cúbico com rotação pelo caminho mais curto

Com interpolação cúbica, a animação é mais lenta nos keyframes e mais rápida entre eles, resultando em movimentos mais naturais. A interpolação cúbica é amplamente utilizada em animações de personagens. A interpolação linear realiza mudanças em velocidade constante, produzindo um efeito mais robótico.

O Godot suporta dois modos de loop, que afetam a animação quando ela está configurada para repetir:

Clamp loop interpolation: Quando esta opção é selecionada, a animação para após o último quadro-chave desta faixa. Quando o primeiro quadro-chave for atingido novamente, a animação será redefinida para seus valores.
Wrap loop interpolation: Quando esta opção é selecionada, Godot calcula a animação após o último quadro-chave para atingir os valores do primeiro quadro-chave novamente.

Quadros-chave para outras propriedades

O sistema de animação do Godot não é restrito a posição, rotação e escala. Você pode animar qualquer propriedade.

Se você selecionar seu sprite enquanto o painel de animação estiver visível, o Godot exibirá um pequeno botão de keyframe no Inspector para cada propriedade do sprite. Clique em um desses botões para adicionar uma trilha e um keyframe à animação atual.

Editar quadro-chave

Você pode clicar em um quadro-chave na linha do tempo da animação para exibir e editar seu valor no Inspetor.

Editor de quadros-chave editando uma chave

Você também pode editar o valor de suavização (easing) para um keyframe aqui, clicando e arrastando sua curva de easing. Isso diz ao Godot como interpolar a propriedade animada quando ela atinge este keyframe.

Você pode ajustar suas animações dessa maneira até que o movimento "pareça certo."

Usando faixas RESET

Você pode configurar uma animação RESET especial para conter a "pose padrão". Isso é usado para garantir que a pose padrão seja restaurada quando você salvar a cena e abri-la novamente no editor.

Para faixas existentes, você pode adicionar uma animação chamada "RESET" (com distinção entre maiúsculas e minúsculas) e adicionar faixas para cada propriedade que deseja redefinir. O único quadro-chave deve estar no tempo 0 e dar a ele o valor padrão desejado para cada faixa.

Se a propriedade Reset On Save do AnimationPlayer estiver definida como true, a cena será salva com os efeitos da animação de redefinição aplicada (como se tivesse sido buscada para o tempo 0.0). Isso afeta apenas o arquivo salvo – as faixas de propriedade no editor permanecem onde estavam.

Se desejar redefinir as trilhas no editor, selecione o nó AnimationPlayer, abra o painel inferior Animation e escolha Apply Reset no menu suspenso Edit do editor de animação.

Ao usar o ícone de quadro-chave ao lado de uma propriedade no inspetor, o editor solicitará que você crie automaticamente uma faixa RESET.

Nota

As faixas RESET também são usadas como valores de referência para mistura (blending). Veja também Para uma melhor mistura.

Onion Skinning (Pele de cebola)

O editor de animação do Godot permite usar o papel cebola (onion skinning) enquanto você cria uma animação. Para ativar esse recurso, clique no ícone de cebola no canto superior direito do editor de animação. Agora, haverá cópias vermelhas transparentes do que está sendo animado em suas posições anteriores na animação.

O botão de três pontos ao lado do botão de onion skinning abre um menu suspenso que permite ajustar como ele funciona, incluindo a capacidade de usar o papel cebola para quadros futuros.

Marcadores de animação

Marcadores de animação podem ser usados para reproduzir uma parte específica de uma animação em vez dela inteira. Aqui está um exemplo de caso de uso: há um arquivo de animação que possui um personagem realizando duas ações distintas, e o projeto exige a animação inteira, bem como ambas as ações individualmente. Em vez de criar duas animações adicionais, marcadores podem ser colocados na linha do tempo, e ambas as ações agora podem ser reproduzidas individualmente.

Para adicionar um marcador a uma animação, clique com o botão direito no espaço acima da linha do tempo e selecione Insert Marker....

../../_images/animation_marker_click_area.webp

Todos os marcadores exigem um nome exclusivo dentro da animação. Você também pode definir a cor dos marcadores para uma melhor organização.

Para reproduzir a parte da animação entre dois marcadores, use os métodos play_section_with_markers() e play_section_with_markers_backwards(). Se nenhum marcador inicial for especificado, o início da animação será usado; e se nenhum marcador final for especificado, o fim da animação será usado.

Se o marcador final estiver após o fim da animação, o AnimationPlayer limitará (clamp) o final da seção para que não ultrapasse o fim da animação.

Para visualizar a animação entre dois marcadores, use Shift + Clique para selecionar os marcadores. Quando dois estiverem selecionados, o espaço entre eles deve ser destacado em vermelho.

../../_images/animation_marker_selected.webp

Agora, todos os botões de reprodução de animação agirão como se a área selecionada fosse a animação inteira. Play Animation from Start tratará o primeiro marcador como o início da animação, Play Animation Backwards from End tratará o segundo marcador como o fim, e assim por diante.