Animación en Godot
Elegir la Herramienta
| Necesidad | Usar |
|---|---|
| Movimiento rápido desde código (UI emergente, retroceso, fundido) | Tween (create_tween()) |
| Clips creados (ciclo de caminar, puerta, cinemática) | AnimationPlayer |
| Sprites 2D cuadro a cuadro | AnimatedSprite2D + SpriteFrames, o AnimationPlayer animando Sprite2D.frame |
| Mezcla y lógica de estados (idle↔run↔jump, movimiento 8 direcciones) | AnimationTree con máquina de estados o espacio de mezcla |
| Apuntado de huesos procedural, colocación de pies, alcance | Familia SkeletonModifier3D (IK, LookAt, restricciones) |
Herramientas de Animación de godot-mcp
| Tarea | Herramienta |
|---|---|
| Agregar estructura AnimationPlayer/AnimationTree a una escena | godot_animation_setup_scene |
| Crear, listar o leer clips | godot_animation_create_clip, godot_animation_list_clips, godot_animation_read_clip |
| Agregar o eliminar keyframes | godot_animation_add_keyframe, godot_animation_remove_keyframe |
| Planificar una máquina de estados o espacio de mezcla para AnimationTree | godot_animation_build_state_machine_plan, godot_animation_build_blend_space_plan |
Usa godot_help tool="<nombre>" para ver las plantillas de argumentos. Valida con godot_validate_scene, luego ejecuta la escena para ver el movimiento. La evidencia del árbol de escenas por sí sola no prueba que una animación se vea bien; usa una captura de pantalla en tiempo de ejecución o una verificación manual (consulta godot-interactive).
AnimationPlayer
- Los clips viven en AnimationLibraries. La librería predeterminada tiene el nombre vacío
"", así queplay("walk")es abreviatura deplay("/walk"), y otras librerías se usan conplay("combat/slash"). - Las rutas de las pistas son relativas a
root_node(por defecto.., el padre del reproductor):NodePath("Sprite2D:frame"),NodePath(".:position"). - Mantén una animación
RESETcon el valor de reposo de cada propiedad animada. El editor la usa para restaurar el estado y evitar diferencias sucias en la escena. - Llama a métodos desde pistas Call Method (sonidos de pasos, generar hitbox) en lugar de sondear el tiempo en código.
- Reproduce por sección o marcadores (4.4+):
play_section_with_markers("attack", &"windup_end", &"recover_start")para repetir o saltar parte de un clip. animation_finished(nombre_anim)se dispara para clips no repetitivos. 4.7 renombró el argumento decurrent_animation_changedaanim_name; conéctalo por Callable para que el cambio no importe.- 4.6:
get_queue()devuelveArray[StringName], y se agregóis_animation_active().
@onready var anim: AnimationPlayer = $AnimationPlayer
func atacar() -> 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 según velocidad)
├── Jump, Fall, Land
└── Attack (OneShot mediante 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")
- Las rutas de los parámetros provienen del árbol. Pasa el cursor sobre un parámetro en el inspector para copiar su ruta exacta.
- Usa condiciones de avance de transición o expresiones (
advance_expression) para transiciones basadas en datos, ytravel()para las basadas en código. - Para efectos de un solo disparo (ataques, golpes), establece
parameters/<OneShot>/requestaAnimationNodeOneShot.ONE_SHOT_REQUEST_FIRE. AnimationNodeExtension(4.4, experimental) permite escribir nodos de mezcla personalizados en 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)
# Pasos 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+: anidar un tween reutilizable
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+: seguir animando mientras Engine.time_scale está ralentizado (hit-stop, UI durante cámara lenta)
create_tween().set_ignore_time_scale().tween_property(ui, "modulate:a", 1.0, 0.2)
# 4.7+: pausar una secuencia hasta que se dispare una señal
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)
Reglas:
- Los Tweens creados con
create_tween()en un nodo mueren con ese nodo. Mata el tween anterior antes de iniciar uno conflictivo:if _t and _t.is_valid(): _t.kill(). - Los árboles en pausa pausan los tweens a menos que se use
set_pause_mode(Tween.TWEEN_PAUSE_PROCESS). - Usa
set_process_mode(Tween.TWEEN_PROCESS_PHYSICS)para tweens que mueven cuerpos físicos.
Animación Esquelética 3D
- Importa animaciones desde glTF (
.glb). Configura modos de bucle y divide clips en el diálogo de Importación Avanzada, no después de la importación. - Retargeting: usa un BoneMap de
SkeletonProfileHumanoidal importar para compartir animaciones entre modelos humanoides.RetargetModifier3D(4.4+) copia poses entre esqueletos en tiempo de ejecución. - Pila de SkeletonModifier3D (hijos de
Skeleton3D, procesados en orden):LookAtModifier3D(4.4+): seguimiento de cabeza y ojos con límites de ángulo.SpringBoneSimulator3D(4.4+): cabello, colas, sacudidas similares a tela, conSpringBoneCollision*3D.AimModifier3D,CopyTransformModifier3D,ConvertTransformModifier3D(4.5+): restricciones de huesos.- IK (4.6+):
TwoBoneIK3D(brazos y piernas, determinista),FABRIK3D/CCDIK3D/JacobianIK3D(cadenas iterativas),SplineIK3D(espinas y tentáculos a lo largo de unPath3D), con límitesJointLimitationCone3DyBoneTwistDisperser3DyLimitAngularVelocityModifier3Dpara resultados naturales. El antiguoSkeletonIK3Destá obsoleto en favor de estos. ModifierBoneTarget3D(4.5+): un Node3D que sigue un hueso, útil como objetivo IK o punto de anclaje.
- Receta para IK de pies: haz raycast hacia abajo desde cada pie, mueve un Marker3D objetivo al punto de impacto, maneja
TwoBoneIK3Dpara cada pierna y desplaza las caderas según el delta del pie más bajo.
Depuración
- Un clip se reproduce pero nada se mueve: la ruta de la pista es incorrecta respecto a
root_node, o un AnimationTree está activo y anulando el reproductor. - Una propiedad vuelve a su estado anterior: otra pista o RESET anima la misma propiedad, o un tween y una animación compiten por ella.
- Una máquina de estados se queda atascada: verifica las condiciones de transición y el
switch_mode, y observaplayback.get_current_node(). - Temblor en 3D: activa la interpolación de física, o anima en el mismo modo de proceso que el movimiento.