Index · Object → RefCounted → AStarGrid2D

AStarGrid2D

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

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

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

Properties

var cell_shape: AStarGrid2D.CellShape = 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.

var cell_size: Vector2 = 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.

var default_compute_heuristic: AStarGrid2D.Heuristic = 0

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

var default_estimate_heuristic: AStarGrid2D.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.

var diagonal_mode: AStarGrid2D.DiagonalMode = 0

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

var jumping_enabled: bool = 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.

var offset: Vector2 = 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.

var region: Rect2i = 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.

var size: Vector2i = Vector2i(0, 0)

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

func _compute_cost(from_id: Vector2i, to_id: Vector2i) -> float

Called when computing the cost between two connected points.

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

func _estimate_cost(from_id: Vector2i, end_id: Vector2i) -> float

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.

func clear() -> void

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

func fill_solid_region(region: Rect2i, solid: bool = true) -> void

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.

func fill_weight_scale_region(region: Rect2i, weight_scale: float) -> void

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.

func get_id_path(from_id: Vector2i, to_id: Vector2i, allow_partial_path: bool = false) -> Vector2i[]

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.

func get_point_data_in_region(region: Rect2i) -> Dictionary[]

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

func get_point_path(from_id: Vector2i, to_id: Vector2i, allow_partial_path: bool = false) -> PackedVector2Array

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.

func get_point_position(id: Vector2i) -> Vector2

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

func get_point_weight_scale(id: Vector2i) -> float

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

func is_dirty() -> bool

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

func is_in_bounds(x: int, y: int) -> bool

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

func is_in_boundsv(id: Vector2i) -> bool

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

func is_point_solid(id: Vector2i) -> bool

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

func set_point_solid(id: Vector2i, solid: bool = true) -> void

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.

func set_point_weight_scale(id: Vector2i, weight_scale: float) -> void

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.

func update() -> void

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.

Inherited from RefCounted (4)
func init_ref() -> bool
func reference() -> bool
func unreference() -> bool
Inherited from Object (62)
func _get(property: StringName) -> Variant
func _get_property_list() -> Dictionary[]
func _init() -> void
func _iter_get(iter: Variant) -> Variant
func _iter_init(iter: Array) -> bool
func _iter_next(iter: Array) -> bool
func _notification(what: int) -> void
func _set(property: StringName, value: Variant) -> bool
func _to_string() -> String
func _validate_property(property: Dictionary) -> void
func add_user_signal(signal: String, arguments: Array = []) -> void
func call(method: StringName) -> Variant
func callv(method: StringName, arg_array: Array) -> Variant
func cancel_free() -> void
func connect(signal: StringName, callable: Callable, flags: int = 0) -> Error
func disconnect(signal: StringName, callable: Callable) -> void
func emit_signal(signal: StringName) -> Error
func free() -> void
func get(property: StringName) -> Variant
func get_class() -> String
func get_incoming_connections() -> Dictionary[]
func get_indexed(property_path: NodePath) -> Variant
func get_meta(name: StringName, default: Variant = null) -> Variant
func get_meta_list() -> StringName[]
func get_method_list() -> Dictionary[]
func get_property_list() -> Dictionary[]
func get_signal_connection_list(signal: StringName) -> Dictionary[]
func get_signal_list() -> Dictionary[]
func has_meta(name: StringName) -> bool
func has_method(method: StringName) -> bool
func has_signal(signal: StringName) -> bool
func is_class(class: StringName) -> bool
func is_connected(signal: StringName, callable: Callable) -> bool
func notification(what: int, reversed: bool = false) -> void
func remove_meta(name: StringName) -> void
func remove_user_signal(signal: StringName) -> void
func set(property: StringName, value: Variant) -> void
func set_block_signals(enable: bool) -> void
func set_deferred(property: StringName, value: Variant) -> void
func set_indexed(property_path: NodePath, value: Variant) -> void
func set_message_translation(enable: bool) -> void
func set_meta(name: StringName, value: Variant) -> void
func set_script(script: Variant) -> void
func set_translation_domain(domain: StringName) -> void
func to_string() -> String
func tr(message: StringName, context: StringName = &"") -> String
func tr_n(message: StringName, plural_message: StringName, n: int, context: StringName = &"") -> String

Signals

Inherited from Object (2)

Enums & Constants

enum Heuristic
HEURISTIC_EUCLIDEAN = 0

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

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

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

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)
HEURISTIC_MAX = 4

Represents the size of the Heuristic enum.

enum DiagonalMode
DIAGONAL_MODE_ALWAYS = 0

The pathfinding algorithm will ignore solid neighbors around the target cell and allow passing using diagonals.

DIAGONAL_MODE_NEVER = 1

The pathfinding algorithm will ignore all diagonals and the way will be always orthogonal.

DIAGONAL_MODE_AT_LEAST_ONE_WALKABLE = 2

The pathfinding algorithm will avoid using diagonals if at least two obstacles have been placed around the neighboring cells of the specific path segment.

DIAGONAL_MODE_ONLY_IF_NO_OBSTACLES = 3

The pathfinding algorithm will avoid using diagonals if any obstacle has been placed around the neighboring cells of the specific path segment.

DIAGONAL_MODE_MAX = 4

Represents the size of the DiagonalMode enum.

enum CellShape
CELL_SHAPE_SQUARE = 0

Rectangular cell shape.

CELL_SHAPE_ISOMETRIC_RIGHT = 1

Diamond cell shape (for isometric look). Cell coordinates layout where the horizontal axis goes up-right, and the vertical one goes down-right.

CELL_SHAPE_ISOMETRIC_DOWN = 2

Diamond cell shape (for isometric look). Cell coordinates layout where the horizontal axis goes down-right, and the vertical one goes down-left.

CELL_SHAPE_MAX = 3

Represents the size of the CellShape enum.