Animação no Godot
Escolha a Ferramenta
| Necessidade | Use |
|---|---|
| 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 quadro | AnimatedSprite2D + 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, alcance | Família SkeletonModifier3D (IK, LookAt, restrições) |
Ferramentas de Animação do godot-mcp
| Tarefa | Ferramenta |
|---|---|
| Adicionar estrutura AnimationPlayer/AnimationTree a uma cena | godot_animation_setup_scene |
| Criar, listar ou ler clipes | godot_animation_create_clip, godot_animation_list_clips, godot_animation_read_clip |
| Adicionar ou remover quadros-chave | godot_animation_add_keyframe, godot_animation_remove_keyframe |
| Planejar uma máquina de estados ou espaço de mistura do AnimationTree | godot_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ãoplay("walk")é abreviação deplay("/walk"), e outras bibliotecas são acessadas comoplay("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
RESETcom 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 argumentocurrent_animation_changedfoi renomeado paraanim_name; conecte via Callable para que a mudança não importe.- 4.6:
get_queue()retornaArray[StringName], eis_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, etravel()para aquelas orientadas por código. - Para one-shots (ataques, hits), defina
parameters/<OneShot>/requestcomoAnimationNodeOneShot.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
SkeletonProfileHumanoidBoneMap 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, comSpringBoneCollision*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 umPath3D), com limitesJointLimitationCone3DeBoneTwistDisperser3DeLimitAngularVelocityModifier3Dpara resultados naturais. O antigoSkeletonIK3Destá 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
TwoBoneIK3Dpara cada perna e desloque o quadril pela menor diferença do pé.
Depuração
- 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. - 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.
- Uma máquina de estados está presa: verifique as condições de transição e o
switch_mode, e monitoreplayback.get_current_node(). - Tremulação em 3D: ative a interpolação de física ou anime no mesmo modo de processo que o movimento.