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 代表一個虛擬 2D 空間，可在其上放置 AnimationRootNode。輸出為包含目前值之三角形頂點（相鄰三節點）依 Vector2 權重計算的線性混合。

可透過 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

Inactive animations are frozen and do not advance.

SyncMode SYNC_MODE_INDEPENDENT = 1

Inactive animations advance with a weight of 0. This is equivalent to the previous sync = true behavior.

SyncMode SYNC_MODE_CYCLIC_MUTABLE = 2

All animations are time-scaled so they stay in sync, with the cycle length dynamically computed from active blend weights. This is self-normalizing: a solo animation plays at normal speed.

Note: If you apply AnimationNodeTimeSeek to the result when handling animations of different lengths, synchronization will be broken. In such cases, it is recommended to use AnimationNodeAnimation.use_custom_timeline to align the animation lengths.

SyncMode SYNC_MODE_CYCLIC_CONSTANT = 3

All animations are time-scaled so they complete one cycle in cyclic_length seconds, keeping them in sync regardless of their individual lengths.

Note: If you apply AnimationNodeTimeSeek to the result when handling animations of different lengths, synchronization will be broken. In such cases, it is recommended to use AnimationNodeAnimation.use_custom_timeline to align the animation lengths.

---

屬性說明

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()

The cycle length in seconds used by SYNC_MODE_CYCLIC_CONSTANT. All animations are time-scaled so they complete one full cycle in this duration. Must be greater than 0 for cyclic sync to take effect.

---

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.

If true, sync mode is enabled (equivalent to SYNC_MODE_INDEPENDENT). This property is kept for backward compatibility.

---

SyncMode sync_mode = 0 🔗

• void set_sync_mode(value: SyncMode)

• SyncMode get_sync_mode()

Controls how animations are synced when blended. See SyncMode for available options.

---

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 = &"") 🔗

Adds a new point with name that represents a node at the position set by pos. You can insert it at a specific index using the at_index argument. If you use the default value for at_index, the point is inserted at the end of the blend points array.

Note: If no name is provided, safe index is used as reference. In the future, empty names will be deprecated, so explicitly passing a name is recommended.

---

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

以點 x、y、z 建立新三角形。三角形可重疊。可透過 at_index 指定插入索引；預設插入於陣列末端。

---

int find_blend_point_by_name(name: StringName) const 🔗

Returns the index of the blend point with the given name. Returns -1 if no blend point with that name is found.

---

int get_blend_point_count() const 🔗

回傳混合空間中的點數量。

---

StringName get_blend_point_name(point: int) const 🔗

Returns the name of the blend point at index 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) 🔗

回傳索引 triangle 三角形中，索引 point 頂點的位置。

---

void remove_blend_point(point: int) 🔗

自混合空間移除索引 point 之點。

---

void remove_triangle(triangle: int) 🔗

自混合空間移除索引 triangle 之三角形。

---

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

Swaps the blend points at indices from_index and to_index, exchanging their positions and properties.

---

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

Sets the name of the blend point at index point. If the name conflicts with an existing point, a unique name will be generated automatically.

---

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

更換索引 point 之點所參照的 AnimationNode。

---

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

更新混合空間中索引 point 點的位置。