Class AStarGrid2D

An implementation of A* for finding the shortest path between two points on a partial 2D grid.

Inheritance

RefCounted

Object

AStarGrid2D

Remarks

AStarGrid2D is a variant of AStar2D that is specialized for partial 2D grids. It is simpler to use because it doesn't require you to manually create points and connect them together. This class also supports multiple types of heuristics, modes for diagonal movement, and a jumping mode to speed up calculations.

To use AStarGrid2D, you only need to set the region of the grid, optionally set the cell_size, and then call the update method:

• gdscript
• C#

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))) # Prints [(0, 0), (1, 1), (2, 2), (3, 3), (3, 4)]
print(astar_grid.get_point_path(Vector2i(0, 0), Vector2i(3, 4))) # Prints [(0, 0), (16, 16), (32, 32), (48, 48), (48, 64)]

To remove a point from the pathfinding grid, it must be set as "solid" with AStarGrid2D.set_point_solid.

Properties

cell_shape

The cell shape. Affects how the positions are placed in the grid. If changed, update needs to be called before finding the next path.

var cell_shape : int = 0

Property Value

int

Remarks

• void set_cell_shape(int value)
• int get_cell_shape

cell_size

The size of the point cell which will be applied to calculate the resulting point position returned by AStarGrid2D.get_point_path. If changed, update needs to be called before finding the next path.

var cell_size : Vector2 = Vector2(1, 1)

Property Value

Vector2

Remarks

• void set_cell_size(Vector2 value)
• Vector2 get_cell_size

default_compute_heuristic

The default Heuristic which will be used to calculate the cost between two points if AStarGrid2D._compute_cost was not overridden.

var default_compute_heuristic : int = 0

Property Value

int

Remarks

• void set_default_compute_heuristic(int value)
• int get_default_compute_heuristic

default_estimate_heuristic

The default Heuristic which will be used to calculate the cost between the point and the end point if AStarGrid2D._estimate_cost was not overridden.

var default_estimate_heuristic : int = 0

Property Value

int

Remarks

• void set_default_estimate_heuristic(int value)
• int get_default_estimate_heuristic

diagonal_mode

A specific DiagonalMode mode which will force the path to avoid or accept the specified diagonals.

var diagonal_mode : int = 0

Property Value

int

Remarks

• void set_diagonal_mode(int value)
• int get_diagonal_mode

jumping_enabled

Enables or disables jumping to skip up the intermediate points and speeds up the searching algorithm.

Note: Currently, toggling it on disables the consideration of weight scaling in pathfinding.

var jumping_enabled : bool = false

Property Value

bool

Remarks

• void set_jumping_enabled(bool value)
• bool is_jumping_enabled

offset

The offset of the grid which will be applied to calculate the resulting point position returned by AStarGrid2D.get_point_path. If changed, update needs to be called before finding the next path.

var offset : Vector2 = Vector2(0, 0)

Property Value

Vector2

Remarks

• void set_offset(Vector2 value)
• Vector2 get_offset

region

The region of grid cells available for pathfinding. If changed, update needs to be called before finding the next path.

var region : Rect2i = Rect2i(0, 0, 0, 0)

Property Value

Rect2i

Remarks

• void set_region(Rect2i value)
• Rect2i get_region

size

The size of the grid (number of cells of size cell_size on each axis). If changed, update needs to be called before finding the next path.

var size : Vector2i = Vector2i(0, 0)

Property Value

Vector2i

Remarks

• void set_size(Vector2i value)
• Vector2i get_size

Methods

_compute_cost(Vector2i, Vector2i)

Qualifiers: virtualconst

Called when computing the cost between two connected points.

Note that this function is hidden in the default AStarGrid2D class.

float _compute_cost(Vector2i from_id, Vector2i to_id)

Parameters

from_id Vector2i

to_id Vector2i

_estimate_cost(Vector2i, Vector2i)

Qualifiers: virtualconst

Called when estimating the cost between a point and the path's ending point.

Note that this function is hidden in the default AStarGrid2D class.

float _estimate_cost(Vector2i from_id, Vector2i end_id)

Parameters

from_id Vector2i

end_id Vector2i

clear

Clears the grid and sets the region to Rect2i(0, 0, 0, 0).

void clear

fill_solid_region(Rect2i, bool)

Fills the given region on the grid with the specified value for the solid flag.

Note: Calling update is not needed after the call of this function.

void fill_solid_region(Rect2i region, bool solid)

Parameters

region Rect2i

solid bool

fill_weight_scale_region(Rect2i, float)

Fills the given region on the grid with the specified value for the weight scale.

Note: Calling update is not needed after the call of this function.

void fill_weight_scale_region(Rect2i region, float weight_scale)

Parameters

region Rect2i

weight_scale float

get_id_path(Vector2i, Vector2i, bool)

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

Vector2i[] get_id_path(Vector2i from_id, Vector2i to_id, bool allow_partial_path)

Parameters

from_id Vector2i

to_id Vector2i

allow_partial_path bool

get_point_data_in_region(Rect2i)

Qualifiers: const

Returns an array of dictionaries with point data (id: Vector2i, position: Vector2, solid: bool, weight_scale: float) within a region.

Dictionary[] get_point_data_in_region(Rect2i region)

Parameters

region Rect2i

get_point_path(Vector2i, Vector2i, bool)

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 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. If called from a Thread, it will return an empty array and will print an error message.

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

PackedVector2Array get_point_path(Vector2i from_id, Vector2i to_id, bool allow_partial_path)

Parameters

from_id Vector2i

to_id Vector2i

allow_partial_path bool

get_point_position(Vector2i)

Qualifiers: const

Returns the position of the point associated with the given id.

Vector2 get_point_position(Vector2i id)

Parameters

id Vector2i

get_point_weight_scale(Vector2i)

Qualifiers: const

Returns the weight scale of the point associated with the given id.

float get_point_weight_scale(Vector2i id)

Parameters

id Vector2i

is_dirty

Qualifiers: const

Indicates that the grid parameters were changed and update needs to be called.

bool is_dirty

is_in_bounds(int, int)

Qualifiers: const

Returns true if the x and y is a valid grid coordinate (id), i.e. if it is inside region. Equivalent to region.has_point(Vector2i(x, y)).

bool is_in_bounds(int x, int y)

Parameters

x int

y int

is_in_boundsv(Vector2i)

Qualifiers: const

Returns true if the id vector is a valid grid coordinate, i.e. if it is inside region. Equivalent to region.has_point(id).

bool is_in_boundsv(Vector2i id)

Parameters

id Vector2i

is_point_solid(Vector2i)

Qualifiers: const

Returns true if a point is disabled for pathfinding. By default, all points are enabled.

bool is_point_solid(Vector2i id)

Parameters

id Vector2i

set_point_solid(Vector2i, bool)

Disables or enables the specified point for pathfinding. Useful for making an obstacle. By default, all points are enabled.

Note: Calling update is not needed after the call of this function.

void set_point_solid(Vector2i id, bool solid)

Parameters

id Vector2i

solid bool

set_point_weight_scale(Vector2i, float)

Sets the weight_scale for the point with the given id. The weight_scale is multiplied by the result of AStarGrid2D._compute_cost when determining the overall cost of traveling across a segment from a neighboring point to this point.

Note: Calling update is not needed after the call of this function.

void set_point_weight_scale(Vector2i id, float weight_scale)

Parameters

id Vector2i

weight_scale float

update

Updates the internal state of the grid according to the parameters to prepare it to search the path. Needs to be called if parameters like region, cell_size or offset are changed. is_dirty will return true if this is the case and this needs to be called.

Note: All point data (solidity and weight scale) will be cleared.

void update