Communitygithub.com

godot-animation

Anima jogos Godot 4.x — clipes e bibliotecas do AnimationPlayer, máquinas de estado e espaços de mistura do AnimationTree, animação de sprites, Tweens (incluindo subtweens 4.4 e tween_await 4.7), seções e marcadores de animação, animação esquelética 3D, retargeting e o framework IK 4.6 (TwoBoneIK3D, FABRIK3D, CCDIK3D, SplineIK3D). Use para animação de personagens, movimento de UI, cutscenes, movimento procedural ou conectar animação ao estado do jogo. Funciona em conjunto com as ferramentas godot-mcp godot_animation_*.

O que é godot-animation?

Esta skill fornece um guia completo para criação de animações no Godot 4.x, cobrindo desde animação simples de sprites 2D até sistemas complexos de esqueleto 3D e IK. Ela explica quando usar Tween (para movimentos rápidos e descartáveis como UI pop, knockback e fades), AnimationPlayer (para clipes autorais como ciclos de caminhada e cutscenes), AnimatedSprite2D (para sprites quadro a quadro) e AnimationTree (para lógica de estados e blending, como idle↔run↔jump). A documentação inclui regras práticas, exemplos de código GDScript e uma tabela de referência das ferramentas godot-mcp disponíveis para criar e gerenciar animações programaticamente. Também aborda recursos avançados das versões 4.4 a 4.7, como subtweens, retargeting de animação entre esqueletos humanos e o novo framework IK (TwoBoneIK3D, FABRIK3D, CCDIK3D, SplineIK3D). Ao final, oferece dicas de depuração para problemas comuns como clipes que não tocam, propriedades que resetam, máquinas de estado travadas e jitter em animações 3D. A skill é útil para animadores técnicos, desenvolvedores de jogos e qualquer pessoa que precise implementar animação de forma eficiente no Godot Engine.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Yuki-az-23/noit-godot-skills/tree/HEAD/skills/godot-animation

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Animação no Godot

Escolha a Ferramenta

NecessidadeUse
Movimento rápido e descartável via código (pop de UI, knockback, fade)Tween (create_tween())
Clipes autorais (ciclo de caminhada, porta, cutscene)AnimationPlayer
Sprites 2D quadro a quadroAnimatedSprite2D + SpriteFrames, ou AnimationPlayer animando Sprite2D.frame
Blending e lógica de estados (idle↔run↔jump, movimento 8 direções)AnimationTree com máquina de estados ou espaço de mistura
Mira procedural de ossos, posicionamento de pés, alcanceFamília SkeletonModifier3D (IK, LookAt, restrições)

Ferramentas de Animação do godot-mcp

TarefaFerramenta
Adicionar estrutura AnimationPlayer/AnimationTree a uma cenagodot_animation_setup_scene
Criar, listar ou ler clipesgodot_animation_create_clip, godot_animation_list_clips, godot_animation_read_clip
Adicionar ou remover quadros-chavegodot_animation_add_keyframe, godot_animation_remove_keyframe
Planejar uma máquina de estados ou espaço de mistura do AnimationTreegodot_animation_build_state_machine_plan, godot_animation_build_blend_space_plan

Use godot_help tool="<nome>" para modelos de argumentos. Valide com godot_validate_scene, então execute a cena para ver o movimento. A evidência da árvore de cena por si só não prova que uma animação parece correta; use uma captura de tela em tempo de execução ou uma verificação manual (veja godot-interactive).

AnimationPlayer

  • Clipes residem em AnimationLibraries. A biblioteca padrão tem o nome vazio "", então play("walk") é abreviação de play("/walk"), e outras bibliotecas são acessadas como play("combat/slash").
  • Caminhos de trilha são relativos a root_node (padrão .., o pai do player): NodePath("Sprite2D:frame"), NodePath(".:position").
  • Mantenha uma animação RESET com o valor de repouso de cada propriedade animada. O editor a usa para restaurar o estado e evitar diffs sujos na cena.
  • Chame métodos a partir de trilhas Call Method (sons de passos, spawn de hitbox) em vez de verificar o tempo no código.
  • Reproduza por seção ou marcadores (4.4+): play_section_with_markers("attack", &"windup_end", &"recover_start") para repetir ou pular parte de um clipe.
  • animation_finished(anim_name) é emitido para clipes não repetitivos. No 4.7, o argumento current_animation_changed foi renomeado para anim_name; conecte via Callable para que a mudança não importe.
  • 4.6: get_queue() retorna Array[StringName], e is_animation_active() foi adicionado.
@onready var anim: AnimationPlayer = $AnimationPlayer

func attack() -> void:
    anim.play("attack")
    await anim.animation_finished
    anim.play("idle")

AnimationTree

AnimationTree (anim_player = ../AnimationPlayer, active = true)
└── tree_root: AnimationNodeStateMachine
    ├── Locomotion: AnimationNodeBlendSpace2D (idle/walk/run por velocidade)
    ├── Jump, Fall, Land
    └── Attack (OneShot via AnimationNodeBlendTree)
@onready var tree: AnimationTree = $AnimationTree
@onready var playback: AnimationNodeStateMachinePlayback = tree.get("parameters/playback")

func _physics_process(_delta: float) -> void:
    tree.set("parameters/Locomotion/blend_position", velocity / max_speed)
    if not is_on_floor() and velocity.y > 0.0:
        playback.travel("Fall")
  • Caminhos de parâmetros vêm da árvore. Passe o mouse sobre um parâmetro no inspetor para copiar seu caminho exato.
  • Use condições de avanço de transição ou expressões (advance_expression) para transições orientadas por dados, e travel() para aquelas orientadas por código.
  • Para one-shots (ataques, hits), defina parameters/<OneShot>/request como AnimationNodeOneShot.ONE_SHOT_REQUEST_FIRE.
  • AnimationNodeExtension (4.4, experimental) permite escrever nós de mistura personalizados em GDScript.

Tweens

var t := create_tween().set_trans(Tween.TRANS_BACK).set_ease(Tween.EASE_OUT)
t.tween_property(self, "scale", Vector2.ONE * 1.2, 0.12)
t.tween_property(self, "scale", Vector2.ONE, 0.12)

# Passos paralelos
t = create_tween().set_parallel()
t.tween_property(sprite, "modulate:a", 0.0, 0.3)
t.tween_property(sprite, "position:y", sprite.position.y - 20.0, 0.3)
t.chain().tween_callback(queue_free)

# 4.4+: aninhar um tween reutilizável
var shake := create_tween()
for i in 4:
    shake.tween_property(camera, "offset", Vector2(randf_range(-6, 6), randf_range(-6, 6)), 0.03)
var seq := create_tween()
seq.tween_subtween(shake)
seq.tween_property(camera, "offset", Vector2.ZERO, 0.05)

# 4.4+: continuar animando enquanto Engine.time_scale está reduzido (hit-stop, UI durante câmera lenta)
create_tween().set_ignore_time_scale().tween_property(ui, "modulate:a", 1.0, 0.2)

# 4.7+: pausar uma sequência até que um sinal seja disparado
var intro := create_tween()
intro.tween_property(title, "modulate:a", 1.0, 0.5)
intro.tween_await(dialogue_box.closed)
intro.tween_property(title, "modulate:a", 0.0, 0.5)

Regras:

  • Tweens vinculados por create_tween() a um nó morrem com esse nó. Mate o tween anterior antes de iniciar um conflitante: if _t and _t.is_valid(): _t.kill().
  • Árvores pausadas pausam tweens a menos que set_pause_mode(Tween.TWEEN_PAUSE_PROCESS) seja usado.
  • Use set_process_mode(Tween.TWEEN_PROCESS_PHYSICS) para tweens que movem corpos físicos.

Animação Esquelética 3D

  • Importe animações de glTF (.glb). Defina modos de repetição e divida clipes na caixa de diálogo de Importação Avançada, não após a importação.
  • Retargeting: use um SkeletonProfileHumanoid BoneMap na importação para compartilhar animações entre modelos humanoides. RetargetModifier3D (4.4+) copia poses entre esqueletos em tempo de execução.
  • Pilha de SkeletonModifier3D (filhos de Skeleton3D, processados em ordem):
    • LookAtModifier3D (4.4+): rastreamento de cabeça e olhos com limites de ângulo.
    • SpringBoneSimulator3D (4.4+): cabelo, caudas, balanço tipo pano, com SpringBoneCollision*3D.
    • AimModifier3D, CopyTransformModifier3D, ConvertTransformModifier3D (4.5+): restrições de osso.
    • IK (4.6+): TwoBoneIK3D (braços e pernas, determinístico), FABRIK3D/CCDIK3D/JacobianIK3D (cadeias iterativas), SplineIK3D (espinhas e tentáculos ao longo de um Path3D), com limites JointLimitationCone3D e BoneTwistDisperser3D e LimitAngularVelocityModifier3D para resultados naturais. O antigo SkeletonIK3D está obsoleto em favor destes.
    • ModifierBoneTarget3D (4.5+): um Node3D que segue um osso, útil como alvo de IK ou ponto de anexação.
  • Receita de IK de pé: raycast para baixo a partir de cada pé, mova um Marker3D alvo até o ponto de impacto, acione TwoBoneIK3D para cada perna e desloque o quadril pela menor diferença do pé.

Depuração

  1. Um clipe toca mas nada se move: o caminho da trilha está errado em relação a root_node, ou um AnimationTree está ativo e sobrescrevendo o player.
  2. Uma propriedade volta ao estado anterior: outra trilha ou a animação RESET anima a mesma propriedade, ou um tween e uma animação disputam o controle.
  3. Uma máquina de estados está presa: verifique as condições de transição e o switch_mode, e monitore playback.get_current_node().
  4. Tremulação em 3D: ative a interpolação de física ou anime no mesmo modo de processo que o movimento.

Habilidades Relacionadas