Description

An animation player is used for general-purpose playback of animations. It contains a dictionary ofAnimationLibrary resources and custom blend times between animation transitions.

Some methods and properties use a single key to reference an animation directly. These keys are formatted as the key for the library, followed by a forward slash, then the key for the animation within the library, for example"movement/run". If the library's key is an empty string (known as the default library), the forward slash is omitted, being the same key used by the library.

AnimationPlayer is better-suited thanTween for more complex animations, for example ones with non-trivial timings. It can also be used overTween if the animation track editor is more convenient than doing it in code.

Updating the target properties of animations occurs at the process frame.

Tutorials

• 2D Sprite animation

• Animation documentation index

• Third Person Shooter (TPS) Demo

Properties

Methods

Signals

animation_changed(old_name:StringName, new_name:StringName)🔗

Emitted when a queued animation plays after the previous animation finished. See alsoqueue().

Note: The signal is not emitted when the animation is changed viaplay() or by anAnimationTree.

current_animation_changed(name:String)🔗

Emitted whencurrent_animation changes.

Enumerations

enumAnimationProcessCallback:🔗

AnimationProcessCallbackANIMATION_PROCESS_PHYSICS =0

Deprecated: SeeAnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS.

AnimationProcessCallbackANIMATION_PROCESS_IDLE =1

Deprecated: SeeAnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_IDLE.

AnimationProcessCallbackANIMATION_PROCESS_MANUAL =2

Deprecated: SeeAnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_MANUAL.

enumAnimationMethodCallMode:🔗

AnimationMethodCallModeANIMATION_METHOD_CALL_DEFERRED =0

Deprecated: SeeAnimationMixer.ANIMATION_CALLBACK_MODE_METHOD_DEFERRED.

AnimationMethodCallModeANIMATION_METHOD_CALL_IMMEDIATE =1

Deprecated: SeeAnimationMixer.ANIMATION_CALLBACK_MODE_METHOD_IMMEDIATE.

Property Descriptions

Stringassigned_animation🔗

• voidset_assigned_animation(value:String)

• Stringget_assigned_animation()

If playing, the current animation's key, otherwise, the animation last played. When set, this changes the animation, but will not play it unless already playing. See alsocurrent_animation.

Stringautoplay =""🔗

• voidset_autoplay(value:String)

• Stringget_autoplay()

The key of the animation to play when the scene loads.

Stringcurrent_animation =""🔗

• voidset_current_animation(value:String)

• Stringget_current_animation()

The key of the currently playing animation. If no animation is playing, the property's value is an empty string. Changing this value does not restart the animation. Seeplay() for more information on playing animations.

Note: While this property appears in the Inspector, it's not meant to be edited, and it's not saved in the scene. This property is mainly used to get the currently playing animation, and internally for animation playback tracks. For more information, seeAnimation.

floatcurrent_animation_length🔗

• floatget_current_animation_length()

The length (in seconds) of the currently playing animation.

floatcurrent_animation_position🔗

• floatget_current_animation_position()

The position (in seconds) of the currently playing animation.

boolmovie_quit_on_finish =false🔗

• voidset_movie_quit_on_finish_enabled(value:bool)

• boolis_movie_quit_on_finish_enabled()

Iftrue and the engine is running in Movie Maker mode (seeMovieWriter), exits the engine withSceneTree.quit() as soon as an animation is done playing in thisAnimationPlayer. A message is printed when the engine quits for this reason.

Note: This obeys the same logic as theAnimationMixer.animation_finished signal, so it will not quit the engine if the animation is set to be looping.

boolplayback_auto_capture =true🔗

• voidset_auto_capture(value:bool)

• boolis_auto_capture()

Iftrue, performsAnimationMixer.capture() before playback automatically. This means justplay_with_capture() is executed with default arguments instead ofplay().

Note: Capture interpolation is only performed if the animation contains a capture track. See alsoAnimation.UPDATE_CAPTURE.

floatplayback_auto_capture_duration =-1.0🔗

• voidset_auto_capture_duration(value:float)

• floatget_auto_capture_duration()

See alsoplay_with_capture() andAnimationMixer.capture().

Ifplayback_auto_capture_duration is negative value, the duration is set to the interval between the current position and the first key.

EaseTypeplayback_auto_capture_ease_type =0🔗

• voidset_auto_capture_ease_type(value:EaseType)

• EaseTypeget_auto_capture_ease_type()

The ease type of the capture interpolation. See alsoEaseType.

TransitionTypeplayback_auto_capture_transition_type =0🔗

• voidset_auto_capture_transition_type(value:TransitionType)

• TransitionTypeget_auto_capture_transition_type()

The transition type of the capture interpolation. See alsoTransitionType.

floatplayback_default_blend_time =0.0🔗

• voidset_default_blend_time(value:float)

• floatget_default_blend_time()

The default time in which to blend animations. Ranges from 0 to 4096 with 0.01 precision.

floatspeed_scale =1.0🔗

• voidset_speed_scale(value:float)

• floatget_speed_scale()

The speed scaling ratio. For example, if this value is1, then the animation plays at normal speed. If it's0.5, then it plays at half speed. If it's2, then it plays at double speed.

If set to a negative value, the animation is played in reverse. If set to0, the animation will not advance.

Method Descriptions

StringNameanimation_get_next(animation_from:StringName)const🔗

Returns the key of the animation which is queued to play after theanimation_from animation.

voidanimation_set_next(animation_from:StringName, animation_to:StringName)🔗

Triggers theanimation_to animation when theanimation_from animation completes.

voidclear_queue()🔗

Clears all queued, unplayed animations.

floatget_blend_time(animation_from:StringName, animation_to:StringName)const🔗

Returns the blend time (in seconds) between two animations, referenced by their keys.

AnimationMethodCallModeget_method_call_mode()const🔗

Deprecated: UseAnimationMixer.callback_mode_method instead.

Returns the call mode used for "Call Method" tracks.

floatget_playing_speed()const🔗

Returns the actual playing speed of current animation or0 if not playing. This speed is thespeed_scale property multiplied bycustom_speed argument specified when calling theplay() method.

Returns a negative value if the current animation is playing backwards.

AnimationProcessCallbackget_process_callback()const🔗

Deprecated: UseAnimationMixer.callback_mode_process instead.

Returns the process notification in which to update animations.

PackedStringArrayget_queue()🔗

Returns a list of the animation keys that are currently queued to play.

NodePathget_root()const🔗

Deprecated: UseAnimationMixer.root_node instead.

Returns the node which node path references will travel from.

floatget_section_end_time()const🔗

Returns the end time of the section currently being played.

floatget_section_start_time()const🔗

Returns the start time of the section currently being played.

boolhas_section()const🔗

Returnstrue if an animation is currently playing with section.

boolis_playing()const🔗

Returnstrue if an animation is currently playing (even ifspeed_scale and/orcustom_speed are0).

voidpause()🔗

Pauses the currently playing animation. Thecurrent_animation_position will be kept and callingplay() orplay_backwards() without arguments or with the same animation name asassigned_animation will resume the animation.

See alsostop().

voidplay(name:StringName = &"", custom_blend:float = -1, custom_speed:float = 1.0, from_end:bool = false)🔗

Plays the animation with keyname. Custom blend times and speed can be set.

Thefrom_end option only affects when switching to a new animation track, or if the same track but at the start or end. It does not affect resuming playback that was paused in the middle of an animation. Ifcustom_speed is negative andfrom_end istrue, the animation will play backwards (which is equivalent to callingplay_backwards()).

TheAnimationPlayer keeps track of its current or last played animation withassigned_animation. If this method is called with that same animationname, or with noname parameter, the assigned animation will resume playing if it was paused.

Note: The animation will be updated the next time theAnimationPlayer is processed. If other variables are updated at the same time this is called, they may be updated too early. To perform the update immediately, calladvance(0).

voidplay_backwards(name:StringName = &"", custom_blend:float = -1)🔗

Plays the animation with keyname in reverse.

This method is a shorthand forplay() withcustom_speed=-1.0 andfrom_end=true, so see its description for more information.

voidplay_section(name:StringName = &"", start_time:float = -1, end_time:float = -1, custom_blend:float = -1, custom_speed:float = 1.0, from_end:bool = false)🔗

Plays the animation with keyname and the section starting fromstart_time and ending onend_time. See alsoplay().

Settingstart_time to a value outside the range of the animation means the start of the animation will be used instead, and settingend_time to a value outside the range of the animation means the end of the animation will be used instead.start_time cannot be equal toend_time.

voidplay_section_backwards(name:StringName = &"", start_time:float = -1, end_time:float = -1, custom_blend:float = -1)🔗

Plays the animation with keyname and the section starting fromstart_time and ending onend_time in reverse.

This method is a shorthand forplay_section() withcustom_speed=-1.0 andfrom_end=true, see its description for more information.

voidplay_section_with_markers(name:StringName = &"", start_marker:StringName = &"", end_marker:StringName = &"", custom_blend:float = -1, custom_speed:float = 1.0, from_end:bool = false)🔗

Plays the animation with keyname and the section starting fromstart_marker and ending onend_marker.

If the start marker is empty, the section starts from the beginning of the animation. If the end marker is empty, the section ends on the end of the animation. See alsoplay().

voidplay_section_with_markers_backwards(name:StringName = &"", start_marker:StringName = &"", end_marker:StringName = &"", custom_blend:float = -1)🔗

Plays the animation with keyname and the section starting fromstart_marker and ending onend_marker in reverse.

This method is a shorthand forplay_section_with_markers() withcustom_speed=-1.0 andfrom_end=true, see its description for more information.

voidplay_with_capture(name:StringName = &"", duration:float = -1.0, custom_blend:float = -1, custom_speed:float = 1.0, from_end:bool = false, trans_type:TransitionType = 0, ease_type:EaseType = 0)🔗

See alsoAnimationMixer.capture().

You can use this method to use more detailed options for capture than those performed byplayback_auto_capture. Whenplayback_auto_capture isfalse, this method is almost the same as the following:

capture(name,duration,trans_type,ease_type)play(name,custom_blend,custom_speed,from_end)

Ifname is blank, it specifiesassigned_animation.

Ifduration is a negative value, the duration is set to the interval between the current position and the first key, whenfrom_end istrue, uses the interval between the current position and the last key instead.

Note: Theduration takesspeed_scale into account, butcustom_speed does not, because the capture cache is interpolated with the blend result and the result may contain multiple animations.

voidqueue(name:StringName)🔗

Queues an animation for playback once the current animation and all previously queued animations are done.

Note: If a looped animation is currently playing, the queued animation will never play unless the looped animation is stopped somehow.

voidreset_section()🔗

Resets the current section if section is set.

voidseek(seconds:float, update:bool = false, update_only:bool = false)🔗

Seeks the animation to theseconds point in time (in seconds). Ifupdate istrue, the animation updates too, otherwise it updates at process time. Events between the current frame andseconds are skipped.

Ifupdate_only istrue, the method / audio / animation playback tracks will not be processed.

Note: Seeking to the end of the animation doesn't emitAnimationMixer.animation_finished. If you want to skip animation and emit the signal, useAnimationMixer.advance().

voidset_blend_time(animation_from:StringName, animation_to:StringName, sec:float)🔗

Specifies a blend time (in seconds) between two animations, referenced by their keys.

voidset_method_call_mode(mode:AnimationMethodCallMode)🔗

Deprecated: UseAnimationMixer.callback_mode_method instead.

Sets the call mode used for "Call Method" tracks.

voidset_process_callback(mode:AnimationProcessCallback)🔗

Deprecated: UseAnimationMixer.callback_mode_process instead.

Sets the process notification in which to update animations.

voidset_root(path:NodePath)🔗

Deprecated: UseAnimationMixer.root_node instead.

Sets the node which node path references will travel from.

voidset_section(start_time:float = -1, end_time:float = -1)🔗

Changes the start and end times of the section being played. The current playback position will be clamped within the new section. See alsoplay_section().

voidset_section_with_markers(start_marker:StringName = &"", end_marker:StringName = &"")🔗

Changes the start and end markers of the section being played. The current playback position will be clamped within the new section. See alsoplay_section_with_markers().

If the argument is empty, the section uses the beginning or end of the animation. If both are empty, it means that the section is not set.

voidstop(keep_state:bool = false)🔗

Stops the currently playing animation. The animation position is reset to0 and thecustom_speed is reset to1.0. See alsopause().

Ifkeep_state istrue, the animation state is not updated visually.

Note: The method / audio / animation playback tracks will not be processed by this method.