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

AStarGrid2D

繼承： RefCounted < Object

A* 的一種實作，用於尋找疏鬆 2D 網格中兩點之間的最短路徑。

說明

AStarGrid2D 是 AStar2D 的變體，專門用於部分 2D 網格。由於不需手動建立並連接點，使用上更為簡單。此類同時支援多種啟發式、對角線移動模式，並提供跳點模式以加速運算。

要使用 AStarGrid2D，只需設定網格的 region，必要時設定 cell_size，然後呼叫 update()：

var astar_grid = AStarGrid2D.new()
astar_grid.region = Rect2i(0, 0, 32, 32)
astar_grid.cell_size = Vector2(16, 16)
astar_grid.update()
print(astar_grid.get_id_path(Vector2i(0, 0), Vector2i(3, 4))) # 會輸出 [(0, 0), (1, 1), (2, 2), (3, 3), (3, 4)]
print(astar_grid.get_point_path(Vector2i(0, 0), Vector2i(3, 4))) # 會輸出 [(0, 0), (16, 16), (32, 32), (48, 48), (48, 64)]

AStarGrid2D astarGrid = new AStarGrid2D();
astarGrid.Region = new Rect2I(0, 0, 32, 32);
astarGrid.CellSize = new Vector2I(16, 16);
astarGrid.Update();
GD.Print(astarGrid.GetIdPath(Vector2I.Zero, new Vector2I(3, 4))); // 會輸出 [(0, 0), (1, 1), (2, 2), (3, 3), (3, 4)]
GD.Print(astarGrid.GetPointPath(Vector2I.Zero, new Vector2I(3, 4))); // 會輸出 [(0, 0), (16, 16), (32, 32), (48, 48), (48, 64)]

若要從尋路網格中移除某點，必須先使用 set_point_solid() 將其標記為「實心」。

教學

使用 AStarGrid2D 的網格導航範例

屬性

CellShape	cell_shape	`0`
Vector2	cell_size	`Vector2(1, 1)`
Heuristic	default_compute_heuristic	`0`
Heuristic	default_estimate_heuristic	`0`
DiagonalMode	diagonal_mode	`0`
bool	jumping_enabled	`false`
Vector2	offset	`Vector2(0, 0)`
Rect2i	region	`Rect2i(0, 0, 0, 0)`
Vector2i	size	`Vector2i(0, 0)`

方法

float	_compute_cost(from_id: Vector2i, to_id: Vector2i) virtual const
float	_estimate_cost(from_id: Vector2i, end_id: Vector2i) virtual const
void	clear()
void	fill_solid_region(region: Rect2i, solid: bool = true)
void	fill_weight_scale_region(region: Rect2i, weight_scale: float)
Array[Vector2i]	get_id_path(from_id: Vector2i, to_id: Vector2i, allow_partial_path: bool = false)
Array[Dictionary]	get_point_data_in_region(region: Rect2i) const
PackedVector2Array	get_point_path(from_id: Vector2i, to_id: Vector2i, allow_partial_path: bool = false)
Vector2	get_point_position(id: Vector2i) const
float	get_point_weight_scale(id: Vector2i) const
bool	is_dirty() const
bool	is_in_bounds(x: int, y: int) const
bool	is_in_boundsv(id: Vector2i) const
bool	is_point_solid(id: Vector2i) const
void	set_point_solid(id: Vector2i, solid: bool = true)
void	set_point_weight_scale(id: Vector2i, weight_scale: float)
void	update()

列舉

enum Heuristic: 🔗

Heuristic HEURISTIC_EUCLIDEAN = 0

歐氏啟發式，公式如下：

dx = abs(to_id.x - from_id.x)
dy = abs(to_id.y - from_id.y)
result = sqrt(dx * dx + dy * dy)

注意：這也是 AStar3D 與 AStar2D 預設使用的內部啟發式（含可能的 z 軸）。

Heuristic HEURISTIC_MANHATTAN = 1

曼哈頓啟發式，公式如下：

dx = abs(to_id.x - from_id.x)
dy = abs(to_id.y - from_id.y)
result = dx + dy

注意：此啟發式預期搭配僅允許四向正交移動的情況（將 diagonal_mode 設為 DIAGONAL_MODE_NEVER）。

Heuristic HEURISTIC_OCTILE = 2

Octile 啟發式，公式如下：

dx = abs(to_id.x - from_id.x)
dy = abs(to_id.y - from_id.y)
f = sqrt(2) - 1
result = (dx < dy) ? f * dx + dy : f * dy + dx;

Heuristic HEURISTIC_CHEBYSHEV = 3

切比雪夫啟發式，公式如下：

dx = abs(to_id.x - from_id.x)
dy = abs(to_id.y - from_id.y)
result = max(dx, dy)

Heuristic HEURISTIC_MAX = 4

代表 Heuristic 列舉的大小。

enum DiagonalMode: 🔗

DiagonalMode DIAGONAL_MODE_ALWAYS = 0

尋路演算法將忽略目標格周圍的實心鄰格，允許沿對角線通過。

DiagonalMode DIAGONAL_MODE_NEVER = 1

尋路演算法將完全忽略對角線，路徑僅允許正交移動。

DiagonalMode DIAGONAL_MODE_AT_LEAST_ONE_WALKABLE = 2

若在特定路段的相鄰格周圍至少有兩個障礙物，尋路演算法將避免使用對角線。

DiagonalMode DIAGONAL_MODE_ONLY_IF_NO_OBSTACLES = 3

若在特定路段的相鄰格周圍存在任意障礙物，尋路演算法將避免使用對角線。

DiagonalMode DIAGONAL_MODE_MAX = 4

代表 DiagonalMode 列舉的大小。

enum CellShape: 🔗

CellShape CELL_SHAPE_SQUARE = 0

矩形格形。

CellShape CELL_SHAPE_ISOMETRIC_RIGHT = 1

菱形格形（等角視覺）。格座標佈局：水平軸朝右上，垂直軸朝右下。

CellShape CELL_SHAPE_ISOMETRIC_DOWN = 2

菱形格形（等角視覺）。格座標佈局：水平軸朝右下，垂直軸朝左下。

CellShape CELL_SHAPE_MAX = 3

代表 CellShape 列舉的大小。

屬性說明

CellShape cell_shape = 0 🔗

void set_cell_shape(value: CellShape)
CellShape get_cell_shape()

格形類型，決定點在網格中的放置方式。若變更此屬性，搜尋下一條路徑前需呼叫 update()。

Vector2 cell_size = Vector2(1, 1) 🔗

void set_cell_size(value: Vector2)
Vector2 get_cell_size()

格子的實際尺寸，用於計算 get_point_path() 回傳的座標。若變更此屬性，搜尋下一條路徑前需呼叫 update()。

Heuristic default_compute_heuristic = 0 🔗

void set_default_compute_heuristic(value: Heuristic)
Heuristic get_default_compute_heuristic()

預設 Heuristic，當未覆寫 _compute_cost() 時，用以計算兩點間成本。

Heuristic default_estimate_heuristic = 0 🔗

void set_default_estimate_heuristic(value: Heuristic)
Heuristic get_default_estimate_heuristic()

預設 Heuristic，當未覆寫 _estimate_cost() 時，用以計算目前點與終點之間的成本。

DiagonalMode diagonal_mode = 0 🔗

void set_diagonal_mode(value: DiagonalMode)
DiagonalMode get_diagonal_mode()

指定的 DiagonalMode，用於強制路徑避免或允許特定對角線。

bool jumping_enabled = false 🔗

void set_jumping_enabled(value: bool)
bool is_jumping_enabled()

啟用或停用跳點功能以略過中繼點並加速搜尋演算法。

注意：目前啟用此功能後，尋路時將不考慮權重比例。

Vector2 offset = Vector2(0, 0) 🔗

void set_offset(value: Vector2)
Vector2 get_offset()

網格的位移量，用於計算 get_point_path() 回傳的座標。若變更此屬性，搜尋下一條路徑前需呼叫 update()。

Rect2i region = Rect2i(0, 0, 0, 0) 🔗

void set_region(value: Rect2i)
Rect2i get_region()

可供尋路使用的網格區域。若變更此屬性，搜尋下一條路徑前需呼叫 update()。

Vector2i size = Vector2i(0, 0) 🔗

void set_size(value: Vector2i)
Vector2i get_size()

已棄用： Use region instead.

網格尺寸（各軸上、邊長為 cell_size 的格數）。若變更此屬性，搜尋下一條路徑前需呼叫 update()。

方法說明

float _compute_cost(from_id: Vector2i, to_id: Vector2i) virtual const 🔗

計算兩個連接點之間成本時呼叫。

注意：此函式在預設的 AStarGrid2D 類別中為隱藏。

float _estimate_cost(from_id: Vector2i, end_id: Vector2i) virtual const 🔗

估算某點與路徑終點之間成本時呼叫。

注意：此函式在預設的 AStarGrid2D 類別中為隱藏。

void clear() 🔗

清空網格並將 region 設為 Rect2i(0, 0, 0, 0)。

void fill_solid_region(region: Rect2i, solid: bool = true) 🔗

將指定的 region 區域填入所給的實心標記值。

注意：呼叫此函式後無需再次呼叫 update()。

void fill_weight_scale_region(region: Rect2i, weight_scale: float) 🔗

為網格中指定的 region 設定給定的權重比例。

注意：呼叫此函式後無需再次呼叫 update()。

Array[Vector2i] get_id_path(from_id: Vector2i, to_id: Vector2i, allow_partial_path: bool = false) 🔗

Returns an array with the IDs of the points that form the path found by AStar2D between the given points. The array is ordered from the starting point to the ending point of the path.

If from_id point is disabled, returns an empty array (even if from_id == to_id).

If from_id point is not disabled, there is no valid path to the target, and allow_partial_path is true, returns a path to the point closest to the target that can be reached.

Note: When allow_partial_path is true and to_id is solid the search may take an unusually long time to finish.

Array[Dictionary] get_point_data_in_region(region: Rect2i) const 🔗

返回一個陣列，內容為位於 region 內各點的資料字典（id: Vector2i、position: Vector2、solid: bool、weight_scale: float）。

PackedVector2Array get_point_path(from_id: Vector2i, to_id: Vector2i, allow_partial_path: bool = false) 🔗

Returns an array with the points that are in the path found by AStarGrid2D between the given points. The array is ordered from the starting point to the ending point of the path.

If from_id point is disabled, returns an empty array (even if from_id == to_id).

If from_id point is not disabled, there is no valid path to the target, and allow_partial_path is true, returns a path to the point closest to the target that can be reached.

Note: This method is not thread-safe; it can only be used from a single Thread at a given time. Consider using Mutex to ensure exclusive access to one thread to avoid race conditions.

Additionally, when allow_partial_path is true and to_id is solid the search may take an unusually long time to finish.

Vector2 get_point_position(id: Vector2i) const 🔗

回傳與指定 id 相關聯之點的位置。

float get_point_weight_scale(id: Vector2i) const 🔗

回傳與指定 id 相關聯之點的權重係數。

bool is_dirty() const 🔗

指出網格參數已變更，需要呼叫 update()。

bool is_in_bounds(x: int, y: int) const 🔗

若 x 與 y 組成的座標位於 region 內，則回傳 true；相當於 region.has_point(Vector2i(x, y))。

bool is_in_boundsv(id: Vector2i) const 🔗

若向量 id 位於 region 內，則回傳 true；相當於 region.has_point(id)。

bool is_point_solid(id: Vector2i) const 🔗

若某點被停用於尋路，則回傳 true。預設所有點皆為啟用狀態。

void set_point_solid(id: Vector2i, solid: bool = true) 🔗

啟用或停用指定點的尋路功能，可用於製造障礙物。預設所有點皆啟用。

注意：呼叫此函式後無需再次呼叫 update()。

void set_point_weight_scale(id: Vector2i, weight_scale: float) 🔗

設定指定 id 點的 weight_scale。在計算從鄰近點移動至此點的段落成本時，會將 _compute_cost() 的結果乘以此值。

注意：呼叫此函式後無需再次呼叫 update()。

void update() 🔗

根據目前參數更新網格內部狀態，以便進行路徑搜尋。若變更了 region、cell_size 或 offset 等參數，必須呼叫此方法。當需要更新時， is_dirty() 會回傳 true。

注意：此操作會清除所有點的實心與權重比例資料。