Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Animation

继承: Resource < RefCounted < Object

存放的是用于对引擎中的任何对象进行动画处理的数据。

描述

这个资源存放的是用于对引擎中的任何对象进行动画处理的数据。动画分为轨道,轨道必须与节点关联。向轨道添加定时关键帧(事件)后,节点的状态可以随时间变化。

# 创建动画,让“Enemy”节点在 2.0 秒内
# 向右移动 100 像素。
var animation = Animation.new()
var track_index = animation.add_track(Animation.TYPE_VALUE)
animation.track_set_path(track_index, "Enemy:position:x")
animation.track_insert_key(track_index, 0.0, 0)
animation.track_insert_key(track_index, 2.0, 100)
animation.length = 2.0

动画只是数据的容器,必须添加至 AnimationPlayer 等节点才能进行播放。动画轨道分为不同的类型,不同的类型有各自不同的专属方法。可用的类型请查看 TrackType

注意:对于 3D 的位置、旋转、缩放,推荐使用专门的 TYPE_POSITION_3DTYPE_ROTATION_3DTYPE_SCALE_3D 轨道类型,不要使用 TYPE_VALUE,性能更高。

教程

属性

float

length

1.0

LoopMode

loop_mode

0

float

step

0.1

方法

int

add_track ( TrackType type, int at_position=-1 )

StringName

animation_track_get_key_animation ( int track_idx, int key_idx ) const

int

animation_track_insert_key ( int track_idx, float time, StringName animation )

void

animation_track_set_key_animation ( int track_idx, int key_idx, StringName animation )

float

audio_track_get_key_end_offset ( int track_idx, int key_idx ) const

float

audio_track_get_key_start_offset ( int track_idx, int key_idx ) const

Resource

audio_track_get_key_stream ( int track_idx, int key_idx ) const

int

audio_track_insert_key ( int track_idx, float time, Resource stream, float start_offset=0, float end_offset=0 )

bool

audio_track_is_use_blend ( int track_idx ) const

void

audio_track_set_key_end_offset ( int track_idx, int key_idx, float offset )

void

audio_track_set_key_start_offset ( int track_idx, int key_idx, float offset )

void

audio_track_set_key_stream ( int track_idx, int key_idx, Resource stream )

void

audio_track_set_use_blend ( int track_idx, bool enable )

Vector2

bezier_track_get_key_in_handle ( int track_idx, int key_idx ) const

Vector2

bezier_track_get_key_out_handle ( int track_idx, int key_idx ) const

float

bezier_track_get_key_value ( int track_idx, int key_idx ) const

int

bezier_track_insert_key ( int track_idx, float time, float value, Vector2 in_handle=Vector2(0, 0), Vector2 out_handle=Vector2(0, 0) )

float

bezier_track_interpolate ( int track_idx, float time ) const

void

bezier_track_set_key_in_handle ( int track_idx, int key_idx, Vector2 in_handle, float balanced_value_time_ratio=1.0 )

void

bezier_track_set_key_out_handle ( int track_idx, int key_idx, Vector2 out_handle, float balanced_value_time_ratio=1.0 )

void

bezier_track_set_key_value ( int track_idx, int key_idx, float value )

int

blend_shape_track_insert_key ( int track_idx, float time, float amount )

float

blend_shape_track_interpolate ( int track_idx, float time_sec ) const

void

clear ( )

void

compress ( int page_size=8192, int fps=120, float split_tolerance=4.0 )

void

copy_track ( int track_idx, Animation to_animation )

int

find_track ( NodePath path, TrackType type ) const

int

get_track_count ( ) const

StringName

method_track_get_name ( int track_idx, int key_idx ) const

Array

method_track_get_params ( int track_idx, int key_idx ) const

int

position_track_insert_key ( int track_idx, float time, Vector3 position )

Vector3

position_track_interpolate ( int track_idx, float time_sec ) const

void

remove_track ( int track_idx )

int

rotation_track_insert_key ( int track_idx, float time, Quaternion rotation )

Quaternion

rotation_track_interpolate ( int track_idx, float time_sec ) const

int

scale_track_insert_key ( int track_idx, float time, Vector3 scale )

Vector3

scale_track_interpolate ( int track_idx, float time_sec ) const

int

track_find_key ( int track_idx, float time, FindMode find_mode=0 ) const

bool

track_get_interpolation_loop_wrap ( int track_idx ) const

InterpolationType

track_get_interpolation_type ( int track_idx ) const

int

track_get_key_count ( int track_idx ) const

float

track_get_key_time ( int track_idx, int key_idx ) const

float

track_get_key_transition ( int track_idx, int key_idx ) const

Variant

track_get_key_value ( int track_idx, int key_idx ) const

NodePath

track_get_path ( int track_idx ) const

TrackType

track_get_type ( int track_idx ) const

int

track_insert_key ( int track_idx, float time, Variant key, float transition=1 )

bool

track_is_compressed ( int track_idx ) const

bool

track_is_enabled ( int track_idx ) const

bool

track_is_imported ( int track_idx ) const

void

track_move_down ( int track_idx )

void

track_move_to ( int track_idx, int to_idx )

void

track_move_up ( int track_idx )

void

track_remove_key ( int track_idx, int key_idx )

void

track_remove_key_at_time ( int track_idx, float time )

void

track_set_enabled ( int track_idx, bool enabled )

void

track_set_imported ( int track_idx, bool imported )

void

track_set_interpolation_loop_wrap ( int track_idx, bool interpolation )

void

track_set_interpolation_type ( int track_idx, InterpolationType interpolation )

void

track_set_key_time ( int track_idx, int key_idx, float time )

void

track_set_key_transition ( int track_idx, int key_idx, float transition )

void

track_set_key_value ( int track_idx, int key, Variant value )

void

track_set_path ( int track_idx, NodePath path )

void

track_swap ( int track_idx, int with_idx )

UpdateMode

value_track_get_update_mode ( int track_idx ) const

Variant

value_track_interpolate ( int track_idx, float time_sec ) const

void

value_track_set_update_mode ( int track_idx, UpdateMode mode )


枚举

enum TrackType:

TrackType TYPE_VALUE = 0

值轨道设置节点属性中的值,但仅限于那些可以被插值的属性。对于 3D 位置/旋转/缩放,出于性能原因,建议使用专用的 TYPE_POSITION_3DTYPE_ROTATION_3DTYPE_SCALE_3D 轨道类型而不是 TYPE_VALUE

TrackType TYPE_POSITION_3D = 1

3D 位置轨道(值存储在 Vector3 中)。

TrackType TYPE_ROTATION_3D = 2

3D 旋转轨道(值存储在 Quaternion 中)。

TrackType TYPE_SCALE_3D = 3

3D 缩放轨道(值存储在 Vector3 中)。

TrackType TYPE_BLEND_SHAPE = 4

混合形状轨道。

TrackType TYPE_METHOD = 5

方法轨道会在各个关键帧上使用给定参数的调用函数。

TrackType TYPE_BEZIER = 6

贝塞尔轨道可以用来根据自定义曲线对数值进行插值。它们也可以用来对向量和颜色的子属性进行动画处理(例如 Color 的 Alpha 值)。

TrackType TYPE_AUDIO = 7

音频轨道可以用来通过任意类型的 AudioStreamPlayer 播放音频流。该流可以在动画中进行修剪和预览。

TrackType TYPE_ANIMATION = 8

动画轨道会在其他 AnimationPlayer 节点中播放动画。


enum InterpolationType:

InterpolationType INTERPOLATION_NEAREST = 0

无插值(最邻近的值)。

InterpolationType INTERPOLATION_LINEAR = 1

线性插值。

InterpolationType INTERPOLATION_CUBIC = 2

三次插值。这看起来比线性插值更平滑,但插值成本更高。对于从外部软件导入的复杂 3D 动画,坚持使用 INTERPOLATION_LINEAR,即使它需要使用更高的动画帧率作为回报。

InterpolationType INTERPOLATION_LINEAR_ANGLE = 3

具有最短路径旋转的线性插值。

注意:结果值总是归一化的,可能与关键帧的值不匹配。

InterpolationType INTERPOLATION_CUBIC_ANGLE = 4

具有最短路径旋转的三次插值。

注意:结果值总是归一化的,可能与关键帧的值不匹配。


enum UpdateMode:

UpdateMode UPDATE_CONTINUOUS = 0

在关键帧之间更新并保持值。

UpdateMode UPDATE_DISCRETE = 1

在关键帧更新。

UpdateMode UPDATE_CAPTURE = 2

与线性插值相同,但如果第一个关键帧不在第 0 秒,则会从当前值进行插值(即在运行时动态插值)。


enum LoopMode:

LoopMode LOOP_NONE = 0

在动画的两端,动画将停止播放。

LoopMode LOOP_LINEAR = 1

在动画的两端,动画会在不改变播放方向的情况下重复播放。

LoopMode LOOP_PINGPONG = 2

在动画的两端重复进行播放和反向播放。


enum LoopedFlag:

LoopedFlag LOOPED_FLAG_NONE = 0

该标志指示动画在没有任何循环的情况下继续进行。

LoopedFlag LOOPED_FLAG_END = 1

该标志表示动画已到达动画的末尾并且刚好在循环处理之后。

LoopedFlag LOOPED_FLAG_START = 2

该标志表示动画已经到达动画的开始并且刚好在循环处理之后。


enum FindMode:

FindMode FIND_MODE_NEAREST = 0

查找最近的时间键。

FindMode FIND_MODE_APPROX = 1

仅查找与时间相近的键。

FindMode FIND_MODE_EXACT = 2

仅查找与时间匹配的键。


属性说明

float length = 1.0

  • void set_length ( float value )

  • float get_length ( )

动画的总长度(单位为秒)。

注意:长度不以最后一个关键帧为界,因为这个关键帧可能位于结束前或结束后,以确保正确的插值和循环。


LoopMode loop_mode = 0

确定动画播放期间动画时间轴两端的行为。 这用于动画循环的正确插值,以及提示播放器必须重新启动动画。


float step = 0.1

  • void set_step ( float value )

  • float get_step ( )

动画步长值。


方法说明

int add_track ( TrackType type, int at_position=-1 )

向动画添加轨道。


StringName animation_track_get_key_animation ( int track_idx, int key_idx ) const

返回由 key_idx 标识的键处的动画名称。track_idx 必须是动画轨道的索引。


int animation_track_insert_key ( int track_idx, float time, StringName animation )

在给定的 time(以秒为单位)插入一个值为 animation 的键。track_idx 必须是动画轨道的索引。


void animation_track_set_key_animation ( int track_idx, int key_idx, StringName animation )

key_idx 标识的键设置为值 animationtrack_idx 必须是动画轨道的索引。


float audio_track_get_key_end_offset ( int track_idx, int key_idx ) const

返回由 key_idx 标识的键的结束偏移量。track_idx 必须是音频轨道的索引。

结束偏移量是在音频流结束时截断的秒数。


float audio_track_get_key_start_offset ( int track_idx, int key_idx ) const

返回由 key_idx 标识的键的起始偏移量。track_idx 必须是音频轨道的索引。

起始偏移量是在音频流开始时截断的秒数。


Resource audio_track_get_key_stream ( int track_idx, int key_idx ) const

返回由 key_idx 标识的键的音频流。track_idx 必须是音频轨道的索引。


int audio_track_insert_key ( int track_idx, float time, Resource stream, float start_offset=0, float end_offset=0 )

time 秒处插入音频轨道关键帧。track_idx 必须是音频轨道的索引。

stream 是要播放的 AudioStream 资源。start_offset 是音频流开头截断的秒数,而 end_offset 是在结尾处截断的秒数。


bool audio_track_is_use_blend ( int track_idx ) const

如果 track_idx 处的轨道将与其他动画混合,则返回 true


void audio_track_set_key_end_offset ( int track_idx, int key_idx, float offset )

将由 key_idx 标识的键的结束偏移量设置为值 offsettrack_idx 必须是音频轨道的索引。


void audio_track_set_key_start_offset ( int track_idx, int key_idx, float offset )

将由 key_idx 标识的键的起始偏移量设置为值 offsettrack_idx 必须是音频轨道的索引。


void audio_track_set_key_stream ( int track_idx, int key_idx, Resource stream )

将由 key_idx 标识的键的流设置为值 streamtrack_idx 必须是音频轨道的索引。


void audio_track_set_use_blend ( int track_idx, bool enable )

设置轨道是否将与其他动画混合。如果为 true,音频播放音量会根据混合值而变化。


Vector2 bezier_track_get_key_in_handle ( int track_idx, int key_idx ) const

返回由 key_idx 识别的键的入点手柄,track_idx 必须是贝赛尔曲线轨道的索引。


Vector2 bezier_track_get_key_out_handle ( int track_idx, int key_idx ) const

返回由 key_idx 识别的键的出点手柄,track_idx 必须是贝赛尔曲线轨道的索引。


float bezier_track_get_key_value ( int track_idx, int key_idx ) const

返回由 key_idx 识别的键的值,track_idx 必须是贝塞尔轨道的索引。


int bezier_track_insert_key ( int track_idx, float time, float value, Vector2 in_handle=Vector2(0, 0), Vector2 out_handle=Vector2(0, 0) )

在给定的时间 time 秒处插入贝塞尔轨道键。track_idx 必须是贝塞尔轨道的索引。

in_handle 是添加的贝塞尔曲线点的左侧权重,out_handle 是右侧权重,而 value 是这个点的实际值。


float bezier_track_interpolate ( int track_idx, float time ) const

返回给定 time 处的插值(以秒为单位)。track_idx 必须是贝塞尔轨道的索引。


void bezier_track_set_key_in_handle ( int track_idx, int key_idx, Vector2 in_handle, float balanced_value_time_ratio=1.0 )

key_idx 所标识的键的入点手柄设置为 in_handle 值。track_idx 必须是贝塞尔轨道的索引。


void bezier_track_set_key_out_handle ( int track_idx, int key_idx, Vector2 out_handle, float balanced_value_time_ratio=1.0 )

将由 key_idx 确定的关键帧的出点手柄设置为 out_handle。参数 track_idx 必须是贝塞尔轨道的索引。


void bezier_track_set_key_value ( int track_idx, int key_idx, float value )

key_idx 所标识的键值设置为给定值。track_idx 必须是贝塞尔轨道的索引。


int blend_shape_track_insert_key ( int track_idx, float time, float amount )

在给定的混合形状轨道中插入一个关键帧。返回键索引。


float blend_shape_track_interpolate ( int track_idx, float time_sec ) const

返回位于给定时间(以秒为单位)的插值后的混合形状值。track_idx 必须是混合形状轨道的索引。


void clear ( )

清除动画(清除所有轨道并重置所有)。


void compress ( int page_size=8192, int fps=120, float split_tolerance=4.0 )

就地压缩动画及其所有轨道。这将使 track_is_compressed 一旦在这个 Animation 上被调用就会返回 true。压缩后的轨道在播放时需要更少的内存,并且这被设计用于从外部3D软件导入的复杂的3D动画(比如过场动画)。压缩是有损失的,但现实中通常不会注意到这种差异。

注意:压缩轨道有各种限制(比如不能从编辑器中编辑),所以只有在你真正需要时才使用压缩动画。


void copy_track ( int track_idx, Animation to_animation )

to_animation 添加一个新轨道,该轨道是该动画中给定轨道的副本。


int find_track ( NodePath path, TrackType type ) const

返回指定轨迹的索引。如果没有找到,返回 -1。


int get_track_count ( ) const

返回动画中的轨道数。


StringName method_track_get_name ( int track_idx, int key_idx ) const

返回一个方法轨道的方法名。


Array method_track_get_params ( int track_idx, int key_idx ) const

返回给定方法轨道中给定键的方法要调用的参数值。


int position_track_insert_key ( int track_idx, float time, Vector3 position )

在给定的 3D 位置轨道中插入关键帧。返回该关键帧的索引。


Vector3 position_track_interpolate ( int track_idx, float time_sec ) const

返回位于给定时间(以秒为单位)的插值后的位置值。track_idx 必须是 3D 位置轨道的索引。


void remove_track ( int track_idx )

通过指定轨道索引来移除一个轨道。


int rotation_track_insert_key ( int track_idx, float time, Quaternion rotation )

在给定的 3D 旋转轨道中插入关键帧。返回该关键帧的索引。


Quaternion rotation_track_interpolate ( int track_idx, float time_sec ) const

返回位于给定时间(以秒为单位)的插值后的旋转值。track_idx 必须是 3D 旋转轨道的索引。


int scale_track_insert_key ( int track_idx, float time, Vector3 scale )

在给定的 3D 缩放轨道中插入关键帧。返回该关键帧的索引。


Vector3 scale_track_interpolate ( int track_idx, float time_sec ) const

返回位于给定时间(以秒为单位)的插值后的缩放值。track_idx 必须是 3D 缩放轨道的索引。


int track_find_key ( int track_idx, float time, FindMode find_mode=0 ) const

按时间查找给定轨道中的关键帧索引。也可选择只在给定大约/准确时间的情况下查找。


bool track_get_interpolation_loop_wrap ( int track_idx ) const

如果 track_idx 处的轨道环绕插值循环,则返回 true。新建的轨道默认都会环绕插值循环。


InterpolationType track_get_interpolation_type ( int track_idx ) const

返回给定轨道的插值类型。


int track_get_key_count ( int track_idx ) const

返回给定轨道中关键帧的数量。


float track_get_key_time ( int track_idx, int key_idx ) const

返回关键帧所在的时间。


float track_get_key_transition ( int track_idx, int key_idx ) const

返回给定关键帧的过渡曲线(缓动)(见内置数学函数 @GlobalScope.ease)。


Variant track_get_key_value ( int track_idx, int key_idx ) const

返回给定轨道中给定关键帧的值。


NodePath track_get_path ( int track_idx ) const

获取轨道的路径。有关路径格式的详细信息,请参阅 track_set_path


TrackType track_get_type ( int track_idx ) const

获取轨道的类型。


int track_insert_key ( int track_idx, float time, Variant key, float transition=1 )

在给定的轨道中插入一个通用关键帧。返回关键帧索引。


bool track_is_compressed ( int track_idx ) const

如果轨道被压缩,则返回 true,否则返回 false。另见 compress


bool track_is_enabled ( int track_idx ) const

如果启用了索引 track_idx 处的轨道,则返回 true


bool track_is_imported ( int track_idx ) const

如果给定的轨道是被导入的,返回 true。否则返回 false


void track_move_down ( int track_idx )

将轨道下移。


void track_move_to ( int track_idx, int to_idx )

将轨道 track_idx 的索引位置改为 to_idx 中定义的位置。


void track_move_up ( int track_idx )

将轨道上移。


void track_remove_key ( int track_idx, int key_idx )

在指定的轨道上按索引移除一个键。


void track_remove_key_at_time ( int track_idx, float time )

在给定轨道中的 time 移除一个键。


void track_set_enabled ( int track_idx, bool enabled )

启用/禁用给定的轨道。轨道默认为启用。


void track_set_imported ( int track_idx, bool imported )

将指定的轨道设置为导入或不导入。


void track_set_interpolation_loop_wrap ( int track_idx, bool interpolation )

如果为 true,则 track_idx 处的轨道环绕插值循环。


void track_set_interpolation_type ( int track_idx, InterpolationType interpolation )

设置指定轨道的插值类型。


void track_set_key_time ( int track_idx, int key_idx, float time )

设置现有关键帧的时间。


void track_set_key_transition ( int track_idx, int key_idx, float transition )

设置指定关键帧的过渡曲线(缓动)(参阅内置数学函数 @GlobalScope.ease)。


void track_set_key_value ( int track_idx, int key, Variant value )

设置现有关键帧的值。


void track_set_path ( int track_idx, NodePath path )

设置轨道的路径。路径必须是指向场景树节点的有效路径,必须从将要实现动画的节点的父节点开始指定。控制属性或骨骼的轨道必须在路径后面加上它们的名字,用 ":" 分隔。

例如,"character/skeleton:ankle""character/mesh:transform/local"


void track_swap ( int track_idx, int with_idx )

将轨道 track_idx 的索引位置与轨道 with_idx 的索引位置互换。


UpdateMode value_track_get_update_mode ( int track_idx ) const

返回值轨道的更新模式。


Variant value_track_interpolate ( int track_idx, float time_sec ) const

返回位于给定时间(以秒为单位)的插值后的值。track_idx 必须是值轨道的索引。


void value_track_set_update_mode ( int track_idx, UpdateMode mode )

设置值轨道的更新模式(请参阅 UpdateMode)。