Communitygithub.com

godot-animation

Anima juegos de Godot 4.x: clips y librerías de AnimationPlayer, máquinas de estados y espacios de mezcla de AnimationTree, animación de sprites, Tweens (incluyendo subtweens 4.4 y tween_await 4.7), secciones y marcadores de animación, animación esquelética 3D, retargeting y el framework IK 4.6 (TwoBoneIK3D, FABRIK3D, CCDIK3D, SplineIK3D). Úsalo para animación de personajes, movimiento de UI, cinemáticas, movimiento procedural o conectar animaciones al estado del juego. Se complementa con las herramientas godot_animation_* de godot-mcp.

¿Qué es godot-animation?

Esta habilidad proporciona una guía completa para la animación en Godot 4.x, cubriendo los sistemas clave: AnimationPlayer para clips creados, AnimationTree para máquinas de estados y mezcla, y Tweens para animaciones desde código. También incluye animación esquelética 3D con retargeting y el nuevo framework IK de la versión 4.6, así como técnicas para animación de sprites 2D y debugging. La documentación detalla cómo y cuándo usar cada herramienta, con ejemplos prácticos de código GDScript y tablas de referencia rápida. Está diseñada para agentes de IA (como Claude Code, Cursor o Codex) que trabajen con el ecosistema de Godot, y se integra con las herramientas godot_animation_* del paquete godot-mcp para automatizar tareas como crear clips, añadir keyframes o planificar máquinas de estados. La habilidad es útil tanto para desarrolladores de juegos como para asistentes de IA que necesiten generar o modificar animaciones en proyectos Godot.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Animación en Godot

Elegir la Herramienta

NecesidadUsar
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 cuadroAnimatedSprite2D + 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, alcanceFamilia SkeletonModifier3D (IK, LookAt, restricciones)

Herramientas de Animación de godot-mcp

TareaHerramienta
Agregar estructura AnimationPlayer/AnimationTree a una escenagodot_animation_setup_scene
Crear, listar o leer clipsgodot_animation_create_clip, godot_animation_list_clips, godot_animation_read_clip
Agregar o eliminar keyframesgodot_animation_add_keyframe, godot_animation_remove_keyframe
Planificar una máquina de estados o espacio de mezcla para AnimationTreegodot_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í que play("walk") es abreviatura de play("/walk"), y otras librerías se usan con play("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 RESET con 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 de current_animation_changed a anim_name; conéctalo por Callable para que el cambio no importe.
  • 4.6: get_queue() devuelve Array[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, y travel() para las basadas en código.
  • Para efectos de un solo disparo (ataques, golpes), establece parameters/<OneShot>/request a AnimationNodeOneShot.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 SkeletonProfileHumanoid al 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, con SpringBoneCollision*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 un Path3D), con límites JointLimitationCone3D y BoneTwistDisperser3D y LimitAngularVelocityModifier3D para resultados naturales. El antiguo SkeletonIK3D está 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 TwoBoneIK3D para cada pierna y desplaza las caderas según el delta del pie más bajo.

Depuración

  1. 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.
  2. 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.
  3. Una máquina de estados se queda atascada: verifica las condiciones de transición y el switch_mode, y observa playback.get_current_node().
  4. Temblor en 3D: activa la interpolación de física, o anima en el mismo modo de proceso que el movimiento.

Skills relacionados