AnimationPlayer

Inherits: Node < Object

Animation 资源的容器和播放器。

描述

动画播放器用于 Animation 资源的通用播放。它包含一个动画字典（使用名称进行索引）和自定义动画转换之间的混合时间。此外，动画可以在不同的通道中播放和混合。

AnimationPlayer 比 Tween 更适合用于事先知道最终值的动画。例如，由于编辑器提供的动画工具，用 AnimationPlayer 节点更容易完成屏幕的淡入淡出。这个特殊的例子也可以用 Tween 节点来实现，但就需要通过代码来完成一切。

更新动画的目标属性是在处理时进行的。

教程

• Animation tutorial index

• 2D Sprite animation

• Third Person Shooter Demo

属性

方法

信号

• animation_changed ( String old_name, String new_name )

当队列中前一个动画播放完毕，要播放下一个动画时触发信号，参见 queue。

注意：如果是通过 play 方法或 AnimationTree 改变的动画，该信号不会触发。

• animation_finished ( String anim_name )

当动画播放结束时通知。

• animation_started ( String anim_name )

当动画开始播放时通知。

• caches_cleared ( )

当缓存被清除时，通过clear_caches自动或手动通知。

枚举

enum AnimationProcessMode:

• ANIMATION_PROCESS_PHYSICS = 0 —- 在物理过程中处理动画。在为物理物体设置动画时，这特别有用。

• ANIMATION_PROCESS_IDLE = 1 —- 在空闲过程中处理动画。

• ANIMATION_PROCESS_MANUAL = 2 —- 不处理动画。使用advance手动处理动画。

enum AnimationMethodCallMode:

• ANIMATION_METHOD_CALL_DEFERRED = 0 —- 在动画过程中批量调用方法，然后在处理完事件后再进行调用。这样就避免了在播放过程中涉及删除节点或修改AnimationPlayer的错误。

• ANIMATION_METHOD_CALL_IMMEDIATE = 1 —- 在动画中达到时立即进行方法调用。

属性说明

• String assigned_animation

如果正在播放，则为当前的动画；否则为上次播放的动画。当设置时，将改变动画，但不会播放它，除非当前正在播放。参阅 current_animation。

• String autoplay

场景加载时要播放的动画名称。

• String current_animation

当前播放的动画的名称。如果没有动画正在播放，该属性的值是一个空字符串。改变这个值不会重新启动动画。关于播放动画的更多信息请参阅play。

注意： 虽然这个属性出现在检查器中，但它不是用来编辑的，也不会保存在场景中。该属性主要用于获取当前播放的动画，内部用于动画播放轨道。有关详细信息，请参阅动画Animation。

• float current_animation_length

当前正在播放的动画的长度（秒）。

• float current_animation_position

当前播放的动画的位置（以秒为单位）。

• AnimationMethodCallMode method_call_mode

方法调用轨道所使用的调用模式。

• bool playback_active

如果true，根据流程相关通知更新动画。

• float playback_default_blend_time

混合动画的默认时间。范围从 0 到 4096，精度为 0.01。

• AnimationProcessMode playback_process_mode

更新动画的过程通知。

• float playback_speed

速度缩放比。例如，如果这个值是1，那么动画以正常速度播放。如果是0.5，则以半速播放。如果是2，则以双倍速度播放。

• bool reset_on_save

这由编辑器使用。如果设置为 true，场景在保存时将应用重置动画的效果（就像它回到 0 时间点），然后在保存后恢复原状。

换句话说，保存的场景文件将包含“默认状态”，是由重置动画定义，如果有，编辑器保持节点在保存前的值。

• NodePath root_node

节点路径引用将从其运行的节点。

方法说明

• Error add_animation ( String name, Animation animation )

向播放器中添加动画 animation，后续通过键 name 访问。

• void advance ( float delta )

移动动画时间轴上的位置并立即更新动画。delta 是要移动的时间，单位为秒。会处理位于当前帧和 delta 之间的事件。

• String animation_get_next ( String anim_from ) const

返回队列中下一个动画的名称。

• void animation_set_next ( String anim_from, String anim_to )

当 anim_from 动画完成后，触发 anim_to 动画。

• void clear_caches ( )

AnimationPlayer 缓存动画节点。如果一个节点消失，它可能不会注意到；clear_caches 强制它再次更新缓存。

• void clear_queue ( )

清除所有已排队、未播放的动画。

• String find_animation ( Animation animation ) const

返回 animation 的名称，如果没有找到，则返回一个空字符串。

• Animation get_animation ( String name ) const

返回键为 name 的 Animation 动画，未找到时为 null。

• PoolStringArray get_animation_list ( ) const

返回存储的动画名称列表。

• float get_blend_time ( String anim_from, String anim_to ) const

获取两个动画之间的混合时间（以秒为单位），由它们的名称引用。

• float get_playing_speed ( ) const

获取当前动画的实际播放速度，如果没有播放则为0。这个速度是调用play方法时指定的playback_speed属性乘以custom_speed参数。

• PoolStringArray get_queue ( )

返回当前排队播放的动画名称列表。

• bool has_animation ( String name ) const

如果AnimationPlayer存储了带有namewith keyAnimation，返回true。

• bool is_playing ( ) const

如果正在播放动画，则返回 true。

• void play ( String name=””, float custom_blend=-1, float custom_speed=1.0, bool from_end=false )

播放键名为 name 的动画。可以设置自定义混合时间和速度。如果 custom_speed 为负，from_end =true，则动画将向后播放（相当于调用 play_backwards）。

AnimationPlayer 使用 assigned_animation 跟踪其当前或最后播放的动画。如果使用相同的动画名 name 或没有 name 参数调用此方法，则分配的动画将在暂停时继续播放，或者在停止时重新启动（请参阅 stop，同时暂停和停止。如果动画已经在播放，它将继续播放。

注意：下次处理 AnimationPlayer 时，动画将被更新。如果在调用的同时更新了其他变量，则它们可能更新得太早。要立即执行更新，请调用 advance(0)。

• void play_backwards ( String name=””, float custom_blend=-1 )

反向播放键名称为 name 的动画。

这个方法是 play 的简写，只是其中参数设为 custom_speed = -1.0 和 from_end = true，所以更多信息请参阅其描述。

• void queue ( String name )

当当前动画播放完毕后，排队等待播放。

注意：如果当前正在播放循环动画，除非以某种方式停止循环动画，否则排队的动画将永远不会播放。

• void remove_animation ( String name )

移除按键name的动画。

• void rename_animation ( String name, String newname )

将键值为name的现有动画重命名为newname。

• void seek ( float seconds, bool update=false )

将动画寻道到时间点 seconds（单位为秒）。update 为 true 时会同时更新动画，否则会在处理时更新。当前帧和 seconds 之间的事件会被跳过。

• void set_blend_time ( String anim_from, String anim_to, float sec )

指定两个动画之间的混合时间（以秒为单位），以它们的名称为参照。

• void stop ( bool reset=true )

停止或暂停当前播放的动画。如果 reset 为 true，会将动画位置重置为 0、播放速度重置为 1.0。

如果 reset 为 false，则会保留 current_animation_position。不带参数调用 play 或 play_backwards 或者使用与 assigned_animation 相同的动画名称将恢复动画。