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...

AnimationNodeBlendSpace2D

继承： AnimationRootNode < AnimationNode < Resource < RefCounted < Object

一组放置在 2D 坐标上的 AnimationRootNode，在三个相邻节点之间交叉淡化。被 AnimationTree 使用。

描述

AnimationNodeBlendTree 使用的资源。

AnimationNodeBlendSpace2D 代表放置 AnimationRootNode 的虚拟 2D 空间。输出的是使用 Vector2 权重对相邻的三个动画进行线性混合的结果。此处的“相邻”指的是构成包含当前值的三角形的三个 AnimationRootNode。

你可以使用 add_blend_point() 向混合空间中添加顶点，将 auto_triangles 设为 true 可以将其自动三角形化。否则，请使用 add_triangle() 和 remove_triangle() 手动对混合空间进行三角形化。

教程

• 使用 AnimationTree

• 第三人称射击（TPS）演示

属性

bool	auto_triangles	true
BlendMode	blend_mode	0
float	cyclic_length	0.0
Vector2	max_space	Vector2(1, 1)
Vector2	min_space	Vector2(-1, -1)
Vector2	snap	Vector2(0.1, 0.1)
bool	sync
SyncMode	sync_mode	0
String	x_label	"x"
String	y_label	"y"

方法

void	add_blend_point(node: AnimationRootNode, pos: Vector2, at_index: int = -1, name: StringName = &"")
void	add_triangle(x: int, y: int, z: int, at_index: int = -1)
int	find_blend_point_by_name(name: StringName) const
int	get_blend_point_count() const
StringName	get_blend_point_name(point: int) const
AnimationRootNode	get_blend_point_node(point: int) const
Vector2	get_blend_point_position(point: int) const
int	get_triangle_count() const
int	get_triangle_point(triangle: int, point: int)
void	remove_blend_point(point: int)
void	remove_triangle(triangle: int)
void	reorder_blend_point(from_index: int, to_index: int)
void	set_blend_point_name(point: int, name: StringName)
void	set_blend_point_node(point: int, node: AnimationRootNode)
void	set_blend_point_position(point: int, pos: Vector2)

---

信号

triangles_updated() 🔗

每当创建、移除混合空间的三角形，或当其中一个顶点改变位置时发出。

---

枚举

enum BlendMode: 🔗

BlendMode BLEND_MODE_INTERPOLATED = 0

动画之间的插值是线性的。

BlendMode BLEND_MODE_DISCRETE = 1

混合空间播放混合位置最接近的动画节点的动画。可用于逐帧的 2D 动画。

BlendMode BLEND_MODE_DISCRETE_CARRY = 2

类似于 BLEND_MODE_DISCRETE，但在最后一个动画的播放位置开始新的动画。

---

enum SyncMode: 🔗

SyncMode SYNC_MODE_NONE = 0

处于非活动状态的动画会被冻结，且不会继续播放（不会推进进度）。

SyncMode SYNC_MODE_INDEPENDENT = 1

非活动状态的动画会以 0 的权重继续播放（推进进度）。这等同于以前 sync = true 时的行为。

SyncMode SYNC_MODE_CYCLIC_MUTABLE = 2

所有动画都会进行时间缩放以保持同步，其周期长度会根据活动的混合权重动态计算。这是一种自我归一化（self-normalizing）的机制：当只有一个动画单独播放时，它会以正常速度播放。

注意： 如果你在混合不同长度的动画时，对结果应用了 AnimationNodeTimeSeek（时间查找）节点，同步将会被破坏。在这种情况下，建议使用 AnimationNodeAnimation.use_custom_timeline（使用自定义时间轴）来对齐动画的长度。

SyncMode SYNC_MODE_CYCLIC_CONSTANT = 3

所有动画都会进行时间缩放，以确保它们都在 cyclic_length 秒内刚好完成一个循环，从而让它们保持同步，完全不受各自原始长度的影响。

注意： 如果你在混合不同长度的动画时，对结果应用了 AnimationNodeTimeSeek（时间查找）节点，同步将会被破坏。在这种情况下，建议使用 AnimationNodeAnimation.use_custom_timeline（使用自定义时间轴）来对齐动画的长度。

---

属性说明

bool auto_triangles = true 🔗

• void set_auto_triangles(value: bool)

• bool get_auto_triangles()

如果为 true，混合空间会自动进行三角测量。每次使用 add_blend_point() 和 remove_blend_point() 添加或移除点时，网格都会更新。

---

BlendMode blend_mode = 0 🔗

• void set_blend_mode(value: BlendMode)

• BlendMode get_blend_mode()

控制动画之间的插值。

---

float cyclic_length = 0.0 🔗

• void set_cyclic_length(value: float)

• float get_cyclic_length()

SYNC_MODE_CYCLIC_CONSTANT 模式所使用的周期长度（以秒为单位）。所有的动画都会进行时间缩放，以确保在这个时长内刚好完整地循环一次。该数值必须大于 0，循环同步（cyclic sync）才会生效。

---

Vector2 max_space = Vector2(1, 1) 🔗

• void set_max_space(value: Vector2)

• Vector2 get_max_space()

用于点的位置的混合空间的 X 轴和 Y 轴的上限。请参阅 add_blend_point()。

---

Vector2 min_space = Vector2(-1, -1) 🔗

• void set_min_space(value: Vector2)

• Vector2 get_min_space()

用于点的位置的混合空间的 X 轴和 Y 轴的下限。请参阅 add_blend_point()。

---

Vector2 snap = Vector2(0.1, 0.1) 🔗

• void set_snap(value: Vector2)

• Vector2 get_snap()

移动点时要吸附到的位置增量。

---

bool sync 🔗

• void set_use_sync(value: bool)

• bool is_using_sync()

已弃用： Use sync_mode instead.

如果设为 true（真），则启用同步模式（等同于 SYNC_MODE_INDEPENDENT）。保留该属性是为了向后兼容。

---

SyncMode sync_mode = 0 🔗

• void set_sync_mode(value: SyncMode)

• SyncMode get_sync_mode()

控制动画在混合时的同步方式。可用的选项见 SyncMode。

---

String x_label = "x" 🔗

• void set_x_label(value: String)

• String get_x_label()

混合空间 X 轴的名称。

---

String y_label = "y" 🔗

• void set_y_label(value: String)

• String get_y_label()

混合空间 Y 轴的名称。

---

方法说明

void add_blend_point(node: AnimationRootNode, pos: Vector2, at_index: int = -1, name: StringName = &"") 🔗

在 pos（位置）处，添加一个带有 name（名称）且代表 node（节点）的新点。你可以使用 at_index 参数将其插入到指定的索引位置。如果你使用 at_index 的默认值，该点会被插入到混合点数组的末尾。

注意： 如果没有提供名称，系统会使用安全的索引作为参考。未来空名称将会被弃用，因此强烈建议显式地传入一个名称。

---

void add_triangle(x: int, y: int, z: int, at_index: int = -1) 🔗

使用三个点 x、y 和 z 创建一个新三角形。三角形可以重叠。可以使用 at_index 参数在特定索引处插入三角形。如果使用 at_index 的默认值，该点将插入到混合点数组的末尾。

---

int find_blend_point_by_name(name: StringName) const 🔗

返回具有给定 name 的混合点的索引。如果未找到具有该名称的混合点，则返回 -1。

---

int get_blend_point_count() const 🔗

返回混合空间中的点的数量。

---

StringName get_blend_point_name(point: int) const 🔗

返回索引 point 处的混合点的名称。

---

AnimationRootNode get_blend_point_node(point: int) const 🔗

返回索引 point 处的点所引用的 AnimationRootNode。

---

Vector2 get_blend_point_position(point: int) const 🔗

返回索引 point 处的点的位置。

---

int get_triangle_count() const 🔗

返回混合空间中三角形的数量。

---

int get_triangle_point(triangle: int, point: int) 🔗

返回索引 point 处的点在索引 triangle 的三角形中的位置。

---

void remove_blend_point(point: int) 🔗

从混合空间中移除索引 point 处的点。

---

void remove_triangle(triangle: int) 🔗

从混合空间中移除索引 triangle 处的三角形。

---

void reorder_blend_point(from_index: int, to_index: int) 🔗

交换位于 from_index 和 to_index 索引处的混合点（blend points），互换它们的位置和属性。

---

void set_blend_point_name(point: int, name: StringName) 🔗

设置索引为 point 的混合点的名称。如果该名称与现有的点发生冲突（即重名），系统会自动生成一个唯一的名称。

---

void set_blend_point_node(point: int, node: AnimationRootNode) 🔗

更改索引 point 处的点所引用的 AnimationNode。

---

void set_blend_point_position(point: int, pos: Vector2) 🔗

更新混合空间中索引 point 处的点的位置。