Class reference

AStarGrid2D

Inherits RefCounted

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

Description

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:

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

		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))); // Prints [(0, 0), (1, 1), (2, 2), (3, 3), (3, 4)]
		GD.Print(astarGrid.GetPointPath(Vector2I.Zero, new 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 set_point_solid().

Properties

`int cell_shape = 0`

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

`Vector2 cell_size = Vector2(1, 1)`

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

`int default_compute_heuristic = 0`

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

`int default_estimate_heuristic = 0`

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

`int diagonal_mode = 0`

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

`bool jumping_enabled = false`

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.

`int max_traversals = 0`

The maximum number of points to traverse before giving up. If set to 0, the search will continue until the end point is reached or the whole grid is traversed.

`Vector2 offset = Vector2(0, 0)`

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

`Rect2i region = Rect2i(0, 0, 0, 0)`

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

`Vector2i size = Vector2i(0, 0)`

Deprecated.

Use region instead.

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.

Methods

`float _compute_cost(Vector2i from_id, Vector2i to_id) virtual const`

Called when computing the cost between two connected points. Note that this function is hidden in the default AStarGrid2D class.

`float _estimate_cost(Vector2i from_id, Vector2i end_id) virtual const`

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.

`void clear()`

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

`void fill_solid_region(Rect2i region, bool solid = true)`

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_weight_scale_region(Rect2i region, float weight_scale)`

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.

`Vector2i[] get_id_path(Vector2i from_id, Vector2i to_id, bool allow_partial_path = 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 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.

`Dictionary[] get_point_data_in_region(Rect2i region) const`

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

`PackedVector2Array get_point_path(Vector2i from_id, Vector2i to_id, bool allow_partial_path = 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 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(Vector2i id) const`

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

`float get_point_weight_scale(Vector2i id) const`

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

`bool is_dirty() const`

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

`bool is_in_bounds(int x, int y) 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_boundsv(Vector2i id) 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_point_solid(Vector2i id) const`

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

`void set_point_solid(Vector2i id, bool solid = true)`

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_weight_scale(Vector2i id, float weight_scale)`

Sets the weight_scale for the point with the given id. The weight_scale is multiplied by the result of _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 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.

Constants

`HEURISTIC_EUCLIDEAN = 0`

Enum: Heuristic

The Euclidean heuristic to be used for the pathfinding using the following formula:

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

Note: This is also the internal heuristic used in AStar3D and AStar2D by default (with the inclusion of possible z-axis coordinate).

`HEURISTIC_MANHATTAN = 1`

Enum: Heuristic

The Manhattan heuristic to be used for the pathfinding using the following formula:

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

Note: This heuristic is intended to be used with 4-side orthogonal movements, provided by setting the diagonal_mode to DIAGONAL_MODE_NEVER.

`HEURISTIC_OCTILE = 2`

Enum: Heuristic

The Octile heuristic to be used for the pathfinding using the following formula:

			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_CHEBYSHEV = 3`

Enum: Heuristic

The Chebyshev heuristic to be used for the pathfinding using the following formula:

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

Tutorials

Grid-based Navigation with AStarGrid2D Demo

Source revision 704b10a8e178