Animation

继承： Resource < RefCounted < Object

保存可用于为引擎中的任何内容设置动画的数据。

描述

这个资源包含可以用于在引擎中动画化任何事物的数据。动画被分为轨道，每个轨道必须链接到一个节点。通过在轨道中添加定时关键帧（事件），可以随时间变化更改该节点的状态。

S3ScriptC#

# 这会生成一个动画，使 "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_3D、TYPE_ROTATION_3D和TYPE_SCALE_3D轨道类型，而不是TYPE_VALUE，以提高性能。

属性

bool	capture_included	false
float	length	1.0
LoopMode	loop_mode	0
float	step	0.0333333

方法

void	add_marker(name: StringName, time: float)
int	add_track(type: TrackType, at_position: int = -1)
StringName	animation_track_get_key_animation(track_idx: int, key_idx: int) const
int	animation_track_insert_key(track_idx: int, time: float, animation: StringName)
void	animation_track_set_key_animation(track_idx: int, key_idx: int, animation: StringName)
float	audio_track_get_key_end_offset(track_idx: int, key_idx: int) const
float	audio_track_get_key_start_offset(track_idx: int, key_idx: int) const
Resource	audio_track_get_key_stream(track_idx: int, key_idx: int) const
int	audio_track_insert_key(track_idx: int, time: float, stream: Resource, start_offset: float = 0, end_offset: float = 0)
bool	audio_track_is_use_blend(track_idx: int) const
void	audio_track_set_key_end_offset(track_idx: int, key_idx: int, offset: float)
void	audio_track_set_key_start_offset(track_idx: int, key_idx: int, offset: float)
void	audio_track_set_key_stream(track_idx: int, key_idx: int, stream: Resource)
void	audio_track_set_use_blend(track_idx: int, enable: bool)
Vector2	bezier_track_get_key_in_handle(track_idx: int, key_idx: int) const
Vector2	bezier_track_get_key_out_handle(track_idx: int, key_idx: int) const
float	bezier_track_get_key_value(track_idx: int, key_idx: int) const
int	bezier_track_insert_key(track_idx: int, time: float, value: float, in_handle: Vector2 = Vector2(0, 0), out_handle: Vector2 = Vector2(0, 0))
float	bezier_track_interpolate(track_idx: int, time: float) const
void	bezier_track_set_key_in_handle(track_idx: int, key_idx: int, in_handle: Vector2, balanced_value_time_ratio: float = 1.0)
void	bezier_track_set_key_out_handle(track_idx: int, key_idx: int, out_handle: Vector2, balanced_value_time_ratio: float = 1.0)
void	bezier_track_set_key_value(track_idx: int, key_idx: int, value: float)
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
void	clear()
void	compress(page_size: int = 8192, fps: int = 120, split_tolerance: float = 4.0)
void	copy_track(track_idx: int, to_animation: Animation)
int	find_track(path: ItemPath, type: TrackType) const
StringName	get_marker_at_time(time: float) const
Color	get_marker_color(name: StringName) const
PackedStringArray	get_marker_names() const
float	get_marker_time(name: StringName) const
StringName	get_next_marker(time: float) const
StringName	get_prev_marker(time: float) const
int	get_track_count() const
bool	has_marker(name: StringName) 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
void	optimize(allowed_velocity_err: float = 0.01, allowed_angular_err: float = 0.01, precision: int = 3)
int	position_track_insert_key(track_idx: int, time: float, position: Vector3)
Vector3	position_track_interpolate(track_idx: int, time_sec: float, backward: bool = false) const
void	remove_marker(name: StringName)
void	remove_track(track_idx: int)
int	rotation_track_insert_key(track_idx: int, time: float, rotation: Quaternion)
Quaternion	rotation_track_interpolate(track_idx: int, time_sec: float, backward: bool = false) const
int	scale_track_insert_key(track_idx: int, time: float, scale: Vector3)
Vector3	scale_track_interpolate(track_idx: int, time_sec: float, backward: bool = false) const
void	set_marker_color(name: StringName, color: Color)
int	track_find_key(track_idx: int, time: float, find_mode: FindMode = 0, limit: bool = false, backward: bool = false) const
bool	track_get_interpolation_loop_wrap(track_idx: int) const
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
Variant	track_get_key_value(track_idx: int, key_idx: int) const
ItemPath	track_get_path(track_idx: int) const
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
bool	track_is_enabled(track_idx: int) const
bool	track_is_imported(track_idx: int) const
void	track_move_down(track_idx: int)
void	track_move_to(track_idx: int, to_idx: int)
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)
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)
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)
void	track_set_key_value(track_idx: int, key: int, value: Variant)
void	track_set_path(track_idx: int, path: ItemPath)
void	track_swap(track_idx: int, with_idx: int)
UpdateMode	value_track_get_update_mode(track_idx: int) const
Variant	value_track_interpolate(track_idx: int, time_sec: float, backward: bool = false) const
void	value_track_set_update_mode(track_idx: int, mode: UpdateMode)

---

枚举

enum TrackType: 🔗

TrackType TYPE_VALUE = 0

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

TrackType TYPE_POSITION_3D = 1

3D位置跟踪（值存储在Vector3s中）。

TrackType TYPE_ROTATION_3D = 2

3D旋转轨迹（值存储在Quaternions中）。

TrackType TYPE_SCALE_3D = 3

3D比例轨道（值存储在Vector3s中）。

TrackType TYPE_BLEND_SHAPE = 4

混合形状轨道。

TrackType TYPE_METHOD = 5

方法跟踪每个键具有给定参数的调用函数。

TrackType TYPE_BEZIER = 6

Bezier轨迹用于使用自定义曲线插入值。它们还可用于为向量和颜色的子属性设置动画（例如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()

动画步长值。

---

方法说明

void add_marker(name: StringName, time: float) 🔗

向此动画添加标记。

---

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必须是Animation Track的索引。

---

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（以秒为单位）插入Bezier Track键。track_idx必须是Bezier Track的索引。

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句柄设置为valuein_handle。track_idx必须是Bezier轨道的索引。

---

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标识的键的输出句柄设置为valueout_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: ItemPath, type: TrackType) const 🔗

返回指定曲目的索引。如果未找到曲目，则返回-1。

---

StringName get_marker_at_time(time: float) const 🔗

返回位于给定时间的标记的名称。

---

Color get_marker_color(name: StringName) const 🔗

返回给定标记的颜色。

---

PackedStringArray get_marker_names() const 🔗

返回此动画中的每个标记，按时间升序排序。

---

float get_marker_time(name: StringName) const 🔗

返回给定标记的时间。

---

StringName get_next_marker(time: float) const 🔗

返回给定时间之后最接近的标记。如果不存在这样的标记，则返回一个空字符串。

---

StringName get_prev_marker(time: float) const 🔗

返回给定时间之前最接近的标记。如果不存在这样的标记，则返回一个空字符串。

---

int get_track_count() const 🔗

返回动画中的轨道量。

---

bool has_marker(name: StringName) const 🔗

如果此动画包含具有给定名称的标记，则返回true。

---

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

返回方法轨道的方法名称。

---

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

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

---

void optimize(allowed_velocity_err: float = 0.01, allowed_angular_err: float = 0.01, precision: int = 3) 🔗

优化动画及其所有轨道。这将仅保留使动画保持在指定范围内所需的尽可能多的键。

---

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_marker(name: StringName) 🔗

从此动画中删除具有给定名称的标记。

---

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比例轨道的索引。

---

void set_marker_color(name: StringName, color: Color) 🔗

设置给定标记的颜色。

---

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 🔗

返回给定音轨中给定键的值。

---

ItemPath 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: ItemPath) 🔗

设置轨道的路径。路径必须是到节点的有效场景树路径，并且必须从将再现动画的AnimationMixer.root_node开始指定。控制属性或骨骼的轨道必须在路径后面附加它们的名称，由"："分隔。

例如，“字符/骨架：脚踝”或“字符/网格：转换/本地”。

---

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主要影响轨道的键检索方向，其中UPDATE_DISCRETE由AnimationMixer.ANIMATION_CALLBACK_MODE_DISCRETE_FORCE_CONTINUOUS转换以将结果与track_find_key()匹配。

---

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

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