Animation

继承： Resource < RefCounted < Object

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

描述

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

GDScriptC#

# 创建动画，让“Enemy”节点在 0.5 秒内
# 向右移动 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, 0.5, 100)

# 创建动画，让“Enemy”节点在 0.5 秒内
# 向右移动 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, 0.5f, 100);

动画只是数据的容器，必须添加至 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

与线性插值相同，但如果第一个关键帧不在第 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

• void set_loop_mode ( LoopMode value )

• LoopMode get_loop_mode ( )

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

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 标识的键设置为值 animation。track_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 标识的键的结束偏移量设置为值 offset。track_idx 必须是音频轨道的索引。

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

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

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

将由 key_idx 标识的键的流设置为值 stream。track_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）。

Previous Next

© 版权所有 2014-present Juan Linietsky, Ariel Manzur and the Godot community (CC BY 3.0). Revision b1c660f7.

Built with Sphinx using a theme provided by Read the Docs.