Animation

继承： Resource < RefCounted < Object

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

描述

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

GDScriptC#

# 创建动画，让“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

// 创建动画，让“Enemy”节点在 2.0 秒内
// 向右移动 100 像素。
var animation = new Animation();
int trackIndex = animation.AddTrack(Animation.TrackType.Value);
animation.TrackSetPath(trackIndex, "Enemy:position:x");
animation.TrackInsertKey(trackIndex, 0.0f, 0);
animation.TrackInsertKey(trackIndex, 2.0f, 100);
animation.Length = 2.0f;

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

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

教程

• 动画教程索引

属性

方法

枚举

enum TrackType: 🔗

TrackType TYPE_VALUE = 0

值轨道设置节点属性中的值，但仅限于那些可以被插值的属性。对于 3D 位置/旋转/缩放，出于性能原因，建议使用专用的 TYPE_POSITION_3D、TYPE_ROTATION_3D 和 TYPE_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

与 UPDATE_CONTINUOUS 相同，但是会捕获当前对象的取值并在部分方法中进行插值。另见 AnimationMixer.capture、AnimationPlayer.playback_auto_capture 和 AnimationPlayer.play_with_capture。

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

仅查找与时间一致的关键帧。

属性说明

bool capture_included = false 🔗

• bool is_capture_included()

如果包含捕获轨道，则返回 true。这是一个只读的缓存值，旨在提升性能。

float length = 1.0 🔗

• void set_length(value: float)

• float get_length()

动画的总长度（单位为秒）。

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

LoopMode loop_mode = 0 🔗

• void set_loop_mode(value: LoopMode)

• LoopMode get_loop_mode()

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

float step = 0.0333333 🔗

• void set_step(value: float)

• float get_step()

动画步长值。

方法说明

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

向动画添加轨道。

StringName animation_track_get_key_animation(track_idx: int, key_idx: int) const 🔗

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

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

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

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

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

float audio_track_get_key_end_offset(track_idx: int, key_idx: int) const 🔗

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

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

float audio_track_get_key_start_offset(track_idx: int, key_idx: int) const 🔗

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

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

Resource audio_track_get_key_stream(track_idx: int, key_idx: int) const 🔗

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

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

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

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

bool audio_track_is_use_blend(track_idx: int) const 🔗

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

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

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

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

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

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

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

void audio_track_set_use_blend(track_idx: int, enable: bool) 🔗

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

Vector2 bezier_track_get_key_in_handle(track_idx: int, key_idx: int) const 🔗

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

Vector2 bezier_track_get_key_out_handle(track_idx: int, key_idx: int) const 🔗

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

float bezier_track_get_key_value(track_idx: int, key_idx: int) const 🔗

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

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

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

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

float bezier_track_interpolate(track_idx: int, time: float) const 🔗

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

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

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

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

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

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

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

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

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

float blend_shape_track_interpolate(track_idx: int, time_sec: float, backward: bool = false) const 🔗

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

void clear() 🔗

清除动画（清除所有轨道并重置所有）。

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

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

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

void copy_track(track_idx: int, to_animation: Animation) 🔗

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

int find_track(path: NodePath, type: TrackType) const 🔗

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

int get_track_count() const 🔗

返回动画中的轨道数。

StringName method_track_get_name(track_idx: int, key_idx: int) const 🔗

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

Array method_track_get_params(track_idx: int, key_idx: int) const 🔗

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

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

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

Vector3 position_track_interpolate(track_idx: int, time_sec: float, backward: bool = false) const 🔗

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

void remove_track(track_idx: int) 🔗

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

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

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

Quaternion rotation_track_interpolate(track_idx: int, time_sec: float, backward: bool = false) const 🔗

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

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

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

Vector3 scale_track_interpolate(track_idx: int, time_sec: float, backward: bool = false) const 🔗

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

int track_find_key(track_idx: int, time: float, find_mode: FindMode = 0, limit: bool = false, backward: bool = false) const 🔗

根据时间查找给定轨道中的关键帧索引号。查找时可以要求与给定时间近似/一致。

如果 limit 为 true，则不会返回动画范围外的关键帧。

如果 backward 为 true，则会按照反方向执行需要单向处理的方法。

例如 find_mode 为 FIND_MODE_NEAREST 时，如果查找的位置不存在关键帧，那么就会查找并返回该位置之前的第一个关键帧，而如果 backward 为 true，则会返回该位置之后的第一个关键帧。

bool track_get_interpolation_loop_wrap(track_idx: int) const 🔗

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

InterpolationType track_get_interpolation_type(track_idx: int) const 🔗

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

int track_get_key_count(track_idx: int) const 🔗

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

float track_get_key_time(track_idx: int, key_idx: int) const 🔗

返回关键帧所在的时间。

float track_get_key_transition(track_idx: int, key_idx: int) const 🔗

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

Variant track_get_key_value(track_idx: int, key_idx: int) const 🔗

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

NodePath track_get_path(track_idx: int) const 🔗

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

TrackType track_get_type(track_idx: int) const 🔗

获取轨道的类型。

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

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

bool track_is_compressed(track_idx: int) const 🔗

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

bool track_is_enabled(track_idx: int) const 🔗

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

bool track_is_imported(track_idx: int) const 🔗

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

void track_move_down(track_idx: int) 🔗

将轨道下移。

void track_move_to(track_idx: int, to_idx: int) 🔗

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

void track_move_up(track_idx: int) 🔗

将轨道上移。

void track_remove_key(track_idx: int, key_idx: int) 🔗

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

void track_remove_key_at_time(track_idx: int, time: float) 🔗

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

void track_set_enabled(track_idx: int, enabled: bool) 🔗

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

void track_set_imported(track_idx: int, imported: bool) 🔗

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

void track_set_interpolation_loop_wrap(track_idx: int, interpolation: bool) 🔗

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

void track_set_interpolation_type(track_idx: int, interpolation: InterpolationType) 🔗

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

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

设置现有关键帧的时间。

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

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

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

设置现有关键帧的值。

void track_set_path(track_idx: int, path: NodePath) 🔗

Sets the path of a track. Paths must be valid scene-tree paths to a node and must be specified starting from the AnimationMixer.root_node that will reproduce the animation. Tracks that control properties or bones must append their name after the path, separated by ":".

For example, "character/skeleton:ankle" or "character/mesh:transform/local".

void track_swap(track_idx: int, with_idx: int) 🔗

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

UpdateMode value_track_get_update_mode(track_idx: int) const 🔗

返回值轨道的更新模式。

Variant value_track_interpolate(track_idx: int, time_sec: float, backward: bool = false) const 🔗

返回在给定时间点（单位为秒）插值后的值。track_idx 必须是值轨道的索引号。

backward 影响的主要是从轨道获取关键帧的方向，与 track_find_key 的结果一致，此处的轨道指根据 AnimationMixer.ANIMATION_CALLBACK_MODE_DISCRETE_FORCE_CONTINUOUS 转换的 UPDATE_DISCRETE 轨道。

void value_track_set_update_mode(track_idx: int, mode: UpdateMode) 🔗

设置值轨道的更新模式（请参阅 UpdateMode）。