Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
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
// 创建动画,让“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,性能更高。
教程
属性
|
||
|
||
|
||
|
方法
void |
add_marker(name: StringName, time: float) |
animation_track_get_key_animation(track_idx: int, key_idx: int) const |
|
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) |
audio_track_get_key_end_offset(track_idx: int, key_idx: int) const |
|
audio_track_get_key_start_offset(track_idx: int, key_idx: int) const |
|
audio_track_get_key_stream(track_idx: int, key_idx: int) const |
|
audio_track_insert_key(track_idx: int, time: float, stream: Resource, start_offset: float = 0, end_offset: float = 0) |
|
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) |
bezier_track_get_key_in_handle(track_idx: int, key_idx: int) const |
|
bezier_track_get_key_out_handle(track_idx: int, key_idx: int) const |
|
bezier_track_get_key_value(track_idx: int, key_idx: int) const |
|
bezier_track_insert_key(track_idx: int, time: float, value: float, in_handle: Vector2 = Vector2(0, 0), out_handle: Vector2 = Vector2(0, 0)) |
|
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) |
blend_shape_track_insert_key(track_idx: int, time: float, amount: 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) |
find_track(path: NodePath, type: TrackType) const |
|
get_marker_at_time(time: float) const |
|
get_marker_color(name: StringName) const |
|
get_marker_names() const |
|
get_marker_time(name: StringName) const |
|
get_next_marker(time: float) const |
|
get_prev_marker(time: float) const |
|
get_track_count() const |
|
has_marker(name: StringName) const |
|
method_track_get_name(track_idx: int, key_idx: int) const |
|
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) |
position_track_insert_key(track_idx: int, time: float, position: 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) |
rotation_track_insert_key(track_idx: int, time: float, rotation: Quaternion) |
|
rotation_track_interpolate(track_idx: int, time_sec: float, backward: bool = false) const |
|
scale_track_insert_key(track_idx: int, time: float, scale: Vector3) |
|
scale_track_interpolate(track_idx: int, time_sec: float, backward: bool = false) const |
|
void |
set_marker_color(name: StringName, color: Color) |
track_find_key(track_idx: int, time: float, find_mode: FindMode = 0, limit: bool = false, backward: bool = false) const |
|
track_get_interpolation_loop_wrap(track_idx: int) const |
|
track_get_interpolation_type(track_idx: int) const |
|
track_get_key_count(track_idx: int) const |
|
track_get_key_time(track_idx: int, key_idx: int) const |
|
track_get_key_transition(track_idx: int, key_idx: int) const |
|
track_get_key_value(track_idx: int, key_idx: int) const |
|
track_get_path(track_idx: int) const |
|
track_get_type(track_idx: int) const |
|
track_insert_key(track_idx: int, time: float, key: Variant, transition: float = 1) |
|
track_is_compressed(track_idx: int) const |
|
track_is_enabled(track_idx: int) const |
|
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: NodePath) |
void |
track_swap(track_idx: int, with_idx: int) |
value_track_get_update_mode(track_idx: int) const |
|
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 位置轨道(值存储在 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
。这是一个只读的缓存值,旨在提升性能。
动画的总长度(单位为秒)。
注意:长度不以最后一个关键帧为界,因为这个关键帧可能位于结束前或结束后,以确保正确的插值和循环。
确定动画播放期间动画时间轴两端的行为。 这用于动画循环的正确插值,以及提示播放器必须重新启动动画。
动画步长值。
方法说明
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
必须是动画轨道的索引。
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。
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 🔗
返回早于并最接近给定时刻的标签,若此标签不存在,返回空字符串。
返回动画中的轨道数。
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 🔗
返回给定轨道中给定关键帧的值。
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) 🔗
设置轨道的路径。路径必须是指向某一节点的有效场景树路径,必须从将要播放动画的 AnimationMixer.root_node 开始指定。控制属性或骨骼的轨道必须在路径后面加上它们的名字,用 ":"
分隔。
例如,"character/skeleton:ankle"
或 "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)。