--- name: animation-patterns description: "Animation code patterns: Godot BlendSpace2D locomotion, AnimationNodeStateMachine transitions, root motion integration, IK foot planting, call-method animation events, and a Unity 2D freeform blend tree. Use when implementing character locomotion, animation state logic, or IK in a game." --- # Animation Patterns ## Godot AnimationTree BlendSpace2D Locomotion ```gdscript # Locomotion blend tree setup - driven by velocity class_name PlayerAnimator extends Node @onready var animation_tree: AnimationTree = $AnimationTree @onready var body: CharacterBody3D = get_parent() const BLEND_PATH := "parameters/LocomotionBlend/blend_position" const SPEED_PATH := "parameters/SpeedBlend/blend_amount" func _physics_process(_delta: float) -> void: var velocity := body.velocity var speed := velocity.length() # 2D blend space: X=strafe (-1 left, 1 right), Y=forward (0 idle, 1 run) # Normalize by max speed so blend space uses [0,1] range var horizontal := body.global_transform.basis.x.dot(velocity) / 6.0 var forward := -body.global_transform.basis.z.dot(velocity) / 6.0 animation_tree.set(BLEND_PATH, Vector2(horizontal, forward)) animation_tree.set(SPEED_PATH, speed / 6.0) # 6.0 = max run speed # AnimationTree configuration (in Godot editor): # Root: AnimationNodeStateMachine # State "Locomotion": AnimationNodeBlendSpace2D # Points: # (0, 0) = "idle" clip # (0, 1) = "run_forward" clip # (1, 0) = "strafe_right" clip # (-1, 0) = "strafe_left" clip # (0, -1) = "walk_backward" clip # Blend mode: Interpolation (linear) # State "Jump": AnimationNodeAnimation ("jump" clip, no loop) # State "Land": AnimationNodeAnimation ("land" clip, no loop) # Transitions: # Locomotion -> Jump: condition "is_jumping" (bool param) # Jump -> Land: advance condition "animation_finished" # Land -> Locomotion: advance condition "animation_finished" ``` ## AnimationNodeStateMachine Transitions (GDScript) ```gdscript # Trigger state transitions through AnimationTree parameters func jump() -> void: animation_tree.set("parameters/conditions/is_jumping", true) # Reset after one frame so it acts as a trigger await get_tree().process_frame animation_tree.set("parameters/conditions/is_jumping", false) func land() -> void: animation_tree.set("parameters/conditions/is_landing", true) await get_tree().process_frame animation_tree.set("parameters/conditions/is_landing", false) # Reading current state name for logic decisions func get_current_animation() -> StringName: var playback: AnimationNodeStateMachinePlayback = animation_tree.get( "parameters/playback" ) return playback.get_current_node() func is_in_state(state_name: StringName) -> bool: return get_current_animation() == state_name ``` ## Root Motion Integration ```gdscript # Apply AnimationTree root motion to CharacterBody3D class_name RootMotionCharacter extends CharacterBody3D @onready var animation_tree: AnimationTree = $AnimationTree func _physics_process(delta: float) -> void: # Get root motion delta from animation (in local space) var root_motion: Vector3 = animation_tree.get_root_motion_position() # Transform from local animation space to world space var world_motion: Vector3 = global_transform.basis * root_motion # Apply gravity separately (root motion only handles horizontal locomotion) if not is_on_floor(): velocity.y -= 9.8 * delta else: velocity.y = 0.0 # Override XZ velocity with root motion velocity.x = world_motion.x / delta velocity.z = world_motion.z / delta move_and_slide() ``` ## Inverse Kinematics - Foot Planting ```gdscript # Foot IK using SkeletonIK3D nodes class_name FootIK extends Node @export var skeleton: Skeleton3D @export var left_ik: SkeletonIK3D @export var right_ik: SkeletonIK3D @export var raycast_distance: float = 1.5 @export var ik_blend_speed: float = 10.0 var _left_ik_weight: float = 0.0 var _right_ik_weight: float = 0.0 func _physics_process(delta: float) -> void: _update_foot_ik(left_ik, "LeftFoot", delta, _left_ik_weight) _update_foot_ik(right_ik, "RightFoot", delta, _right_ik_weight) func _update_foot_ik(ik: SkeletonIK3D, bone_name: String, delta: float, weight: float) -> void: var bone_idx := skeleton.find_bone(bone_name) var bone_global_pos := skeleton.get_bone_global_pose(bone_idx).origin bone_global_pos = skeleton.global_transform * bone_global_pos var space_state := get_world_3d().direct_space_state var query := PhysicsRayQueryParameters3D.create( bone_global_pos + Vector3.UP * 0.5, bone_global_pos + Vector3.DOWN * raycast_distance, 0b0001 # ground layer only ) var result := space_state.intersect_ray(query) if result: # Align IK target to ground surface var target_xform := Transform3D( Basis(result.normal), # orient to slope result.position ) ik.target = target_xform _left_ik_weight = move_toward(_left_ik_weight, 1.0, delta * ik_blend_speed) else: _left_ik_weight = move_toward(_left_ik_weight, 0.0, delta * ik_blend_speed) ik.interpolation = _left_ik_weight ``` ## Animation Events via Call Method Track ```gdscript # Receiver script on character (animation calls these via Method Track) class_name CharacterAnimationReceiver extends Node signal footstep_left signal footstep_right signal attack_hit_start signal attack_hit_end # Called by AnimationPlayer Method Track at frame of left foot contact func on_footstep_left() -> void: footstep_left.emit() # Determine surface material for correct footstep sound _play_footstep_sound(-1.0) # -1 = left func on_footstep_right() -> void: footstep_right.emit() _play_footstep_sound(1.0) func on_attack_active() -> void: attack_hit_start.emit() func on_attack_inactive() -> void: attack_hit_end.emit() func _play_footstep_sound(side: float) -> void: # Raycast down to detect surface material # Surface material -> audio bus send to correct footstep pool pass ``` ## Unity Animator Blend Tree - 2D Freeform Directional (C#) ```csharp // Drive Animator blend tree from CharacterController velocity public class PlayerAnimatorController : MonoBehaviour { private Animator _animator; private CharacterController _controller; // Animator parameter hashes - cache to avoid string lookup cost private static readonly int SpeedX = Animator.StringToHash("SpeedX"); private static readonly int SpeedZ = Animator.StringToHash("SpeedZ"); private static readonly int IsGrounded = Animator.StringToHash("IsGrounded"); private static readonly int JumpTrigger = Animator.StringToHash("Jump"); private const float AnimDampTime = 0.1f; // Smooth parameter changes private void Awake() { _animator = GetComponent(); _controller = GetComponent(); } private void Update() { // Project world velocity into local character space Vector3 localVelocity = transform.InverseTransformDirection(_controller.velocity); float normalizedX = localVelocity.x / 6f; float normalizedZ = localVelocity.z / 6f; // Damped parameter update prevents blend tree pops _animator.SetFloat(SpeedX, normalizedX, AnimDampTime, Time.deltaTime); _animator.SetFloat(SpeedZ, normalizedZ, AnimDampTime, Time.deltaTime); _animator.SetBool(IsGrounded, _controller.isGrounded); } public void TriggerJump() => _animator.SetTrigger(JumpTrigger); } ``` ## Anti-Patterns - **Driving blend positions with Input.get_vector()**: Use actual velocity, not input. Input doesn't account for acceleration, sliding, or external forces. - **String parameter lookups in Update**: Use `Animator.StringToHash()` or Godot's StringName cache. String allocation per frame is measurable overhead. - **IK every frame on background characters**: Gate IK evaluation on distance from camera. Disable SkeletonIK3D when character is >15m from camera. - **Animation events for collision detection**: Don't enable hit boxes via animation events alone. Events can miss frames. Use a dedicated AttackComponent that checks animation state. - **Single monolithic blend tree**: Split locomotion, combat, and interaction into separate Animator layers (Unity) or nested AnimationNodeStateMachines (Godot).