godot-docs/classes/class_astargrid2d.rst

:github_url: hide

.. DO NOT EDIT THIS FILE!!!
.. Generated automatically from Godot engine sources.
.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py.
.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AStarGrid2D.xml.

.. _class_AStarGrid2D:

AStarGrid2D
===========

**Inherits:** :ref:`RefCounted<class_RefCounted>` **<** :ref:`Object<class_Object>`

A\* (or "A-Star") pathfinding tailored to find the shortest paths on 2D grids.

Description
-----------

Compared to :ref:`AStar2D<class_AStar2D>` you don't need to manually create points or connect them together. It also supports multiple type of heuristics and modes for diagonal movement. This class also provides a jumping mode which is faster to calculate than without it in the :ref:`AStar2D<class_AStar2D>` class.

In contrast to :ref:`AStar2D<class_AStar2D>`, you only need set the :ref:`size<class_AStarGrid2D_property_size>` of the grid, optionally set the :ref:`cell_size<class_AStarGrid2D_property_cell_size>` and then call the :ref:`update<class_AStarGrid2D_method_update>` method:

::

    var astar_grid = AStarGrid2D.new()
    astar_grid.size = Vector2i(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)

Properties
----------

+----------------------------------------------------+------------------------------------------------------------------------+--------------------+
| :ref:`Vector2<class_Vector2>`                      | :ref:`cell_size<class_AStarGrid2D_property_cell_size>`                 | ``Vector2(1, 1)``  |
+----------------------------------------------------+------------------------------------------------------------------------+--------------------+
| :ref:`Heuristic<enum_AStarGrid2D_Heuristic>`       | :ref:`default_heuristic<class_AStarGrid2D_property_default_heuristic>` | ``0``              |
+----------------------------------------------------+------------------------------------------------------------------------+--------------------+
| :ref:`DiagonalMode<enum_AStarGrid2D_DiagonalMode>` | :ref:`diagonal_mode<class_AStarGrid2D_property_diagonal_mode>`         | ``0``              |
+----------------------------------------------------+------------------------------------------------------------------------+--------------------+
| :ref:`bool<class_bool>`                            | :ref:`jumping_enabled<class_AStarGrid2D_property_jumping_enabled>`     | ``false``          |
+----------------------------------------------------+------------------------------------------------------------------------+--------------------+
| :ref:`Vector2<class_Vector2>`                      | :ref:`offset<class_AStarGrid2D_property_offset>`                       | ``Vector2(0, 0)``  |
+----------------------------------------------------+------------------------------------------------------------------------+--------------------+
| :ref:`Vector2i<class_Vector2i>`                    | :ref:`size<class_AStarGrid2D_property_size>`                           | ``Vector2i(0, 0)`` |
+----------------------------------------------------+------------------------------------------------------------------------+--------------------+

Methods
-------

+-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`float<class_float>`                           | :ref:`_compute_cost<class_AStarGrid2D_method__compute_cost>` **(** :ref:`Vector2i<class_Vector2i>` from_id, :ref:`Vector2i<class_Vector2i>` to_id **)** |virtual| |const|   |
+-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`float<class_float>`                           | :ref:`_estimate_cost<class_AStarGrid2D_method__estimate_cost>` **(** :ref:`Vector2i<class_Vector2i>` from_id, :ref:`Vector2i<class_Vector2i>` to_id **)** |virtual| |const| |
+-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                                | :ref:`clear<class_AStarGrid2D_method_clear>` **(** **)**                                                                                                                    |
+-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`PackedVector2Array<class_PackedVector2Array>` | :ref:`get_id_path<class_AStarGrid2D_method_get_id_path>` **(** :ref:`Vector2i<class_Vector2i>` from_id, :ref:`Vector2i<class_Vector2i>` to_id **)**                         |
+-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`PackedVector2Array<class_PackedVector2Array>` | :ref:`get_point_path<class_AStarGrid2D_method_get_point_path>` **(** :ref:`Vector2i<class_Vector2i>` from_id, :ref:`Vector2i<class_Vector2i>` to_id **)**                   |
+-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`                             | :ref:`is_dirty<class_AStarGrid2D_method_is_dirty>` **(** **)** |const|                                                                                                      |
+-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`                             | :ref:`is_in_bounds<class_AStarGrid2D_method_is_in_bounds>` **(** :ref:`int<class_int>` x, :ref:`int<class_int>` y **)** |const|                                             |
+-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`                             | :ref:`is_in_boundsv<class_AStarGrid2D_method_is_in_boundsv>` **(** :ref:`Vector2i<class_Vector2i>` id **)** |const|                                                         |
+-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| :ref:`bool<class_bool>`                             | :ref:`is_point_solid<class_AStarGrid2D_method_is_point_solid>` **(** :ref:`Vector2i<class_Vector2i>` id **)** |const|                                                       |
+-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                                | :ref:`set_point_solid<class_AStarGrid2D_method_set_point_solid>` **(** :ref:`Vector2i<class_Vector2i>` id, :ref:`bool<class_bool>` solid=true **)**                         |
+-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| void                                                | :ref:`update<class_AStarGrid2D_method_update>` **(** **)**                                                                                                                  |
+-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Enumerations
------------

.. _enum_AStarGrid2D_Heuristic:

.. _class_AStarGrid2D_constant_HEURISTIC_EUCLIDEAN:

.. _class_AStarGrid2D_constant_HEURISTIC_MANHATTAN:

.. _class_AStarGrid2D_constant_HEURISTIC_OCTILE:

.. _class_AStarGrid2D_constant_HEURISTIC_CHEBYSHEV:

.. _class_AStarGrid2D_constant_HEURISTIC_MAX:

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)

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

- **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 :ref:`Heuristic<enum_AStarGrid2D_Heuristic>` enum.

----

.. _enum_AStarGrid2D_DiagonalMode:

.. _class_AStarGrid2D_constant_DIAGONAL_MODE_ALWAYS:

.. _class_AStarGrid2D_constant_DIAGONAL_MODE_NEVER:

.. _class_AStarGrid2D_constant_DIAGONAL_MODE_AT_LEAST_ONE_WALKABLE:

.. _class_AStarGrid2D_constant_DIAGONAL_MODE_ONLY_IF_NO_OBSTACLES:

.. _class_AStarGrid2D_constant_DIAGONAL_MODE_MAX:

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 :ref:`DiagonalMode<enum_AStarGrid2D_DiagonalMode>` enum.

Property Descriptions
---------------------

.. _class_AStarGrid2D_property_cell_size:

- :ref:`Vector2<class_Vector2>` **cell_size**

+-----------+----------------------+
| *Default* | ``Vector2(1, 1)``    |
+-----------+----------------------+
| *Setter*  | set_cell_size(value) |
+-----------+----------------------+
| *Getter*  | get_cell_size()      |
+-----------+----------------------+

The size of the point cell which will be applied to calculate the resulting point position returned by :ref:`get_point_path<class_AStarGrid2D_method_get_point_path>`. If changed, :ref:`update<class_AStarGrid2D_method_update>` needs to be called before finding the next path.

----

.. _class_AStarGrid2D_property_default_heuristic:

- :ref:`Heuristic<enum_AStarGrid2D_Heuristic>` **default_heuristic**

+-----------+------------------------------+
| *Default* | ``0``                        |
+-----------+------------------------------+
| *Setter*  | set_default_heuristic(value) |
+-----------+------------------------------+
| *Getter*  | get_default_heuristic()      |
+-----------+------------------------------+

The default :ref:`Heuristic<enum_AStarGrid2D_Heuristic>` which will be used to calculate the path if :ref:`_compute_cost<class_AStarGrid2D_method__compute_cost>` and/or :ref:`_estimate_cost<class_AStarGrid2D_method__estimate_cost>` were not overridden.

----

.. _class_AStarGrid2D_property_diagonal_mode:

- :ref:`DiagonalMode<enum_AStarGrid2D_DiagonalMode>` **diagonal_mode**

+-----------+--------------------------+
| *Default* | ``0``                    |
+-----------+--------------------------+
| *Setter*  | set_diagonal_mode(value) |
+-----------+--------------------------+
| *Getter*  | get_diagonal_mode()      |
+-----------+--------------------------+

A specific :ref:`DiagonalMode<enum_AStarGrid2D_DiagonalMode>` mode which will force the path to avoid or accept the specified diagonals.

----

.. _class_AStarGrid2D_property_jumping_enabled:

- :ref:`bool<class_bool>` **jumping_enabled**

+-----------+----------------------------+
| *Default* | ``false``                  |
+-----------+----------------------------+
| *Setter*  | set_jumping_enabled(value) |
+-----------+----------------------------+
| *Getter*  | is_jumping_enabled()       |
+-----------+----------------------------+

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

----

.. _class_AStarGrid2D_property_offset:

- :ref:`Vector2<class_Vector2>` **offset**

+-----------+-------------------+
| *Default* | ``Vector2(0, 0)`` |
+-----------+-------------------+
| *Setter*  | set_offset(value) |
+-----------+-------------------+
| *Getter*  | get_offset()      |
+-----------+-------------------+

The offset of the grid which will be applied to calculate the resulting point position returned by :ref:`get_point_path<class_AStarGrid2D_method_get_point_path>`. If changed, :ref:`update<class_AStarGrid2D_method_update>` needs to be called before finding the next path.

----

.. _class_AStarGrid2D_property_size:

- :ref:`Vector2i<class_Vector2i>` **size**

+-----------+--------------------+
| *Default* | ``Vector2i(0, 0)`` |
+-----------+--------------------+
| *Setter*  | set_size(value)    |
+-----------+--------------------+
| *Getter*  | get_size()         |
+-----------+--------------------+

The size of the grid (number of cells of size :ref:`cell_size<class_AStarGrid2D_property_cell_size>` on each axis). If changed, :ref:`update<class_AStarGrid2D_method_update>` needs to be called before finding the next path.

Method Descriptions
-------------------

.. _class_AStarGrid2D_method__compute_cost:

- :ref:`float<class_float>` **_compute_cost** **(** :ref:`Vector2i<class_Vector2i>` from_id, :ref:`Vector2i<class_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.

----

.. _class_AStarGrid2D_method__estimate_cost:

- :ref:`float<class_float>` **_estimate_cost** **(** :ref:`Vector2i<class_Vector2i>` from_id, :ref:`Vector2i<class_Vector2i>` to_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.

----

.. _class_AStarGrid2D_method_clear:

- void **clear** **(** **)**

Clears the grid and sets the :ref:`size<class_AStarGrid2D_property_size>` to :ref:`Vector2i.ZERO<class_Vector2i_constant_ZERO>`.

----

.. _class_AStarGrid2D_method_get_id_path:

- :ref:`PackedVector2Array<class_PackedVector2Array>` **get_id_path** **(** :ref:`Vector2i<class_Vector2i>` from_id, :ref:`Vector2i<class_Vector2i>` to_id **)**

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.

----

.. _class_AStarGrid2D_method_get_point_path:

- :ref:`PackedVector2Array<class_PackedVector2Array>` **get_point_path** **(** :ref:`Vector2i<class_Vector2i>` from_id, :ref:`Vector2i<class_Vector2i>` to_id **)**

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.

\ **Note:** This method is not thread-safe. If called from a :ref:`Thread<class_Thread>`, it will return an empty :ref:`PackedVector3Array<class_PackedVector3Array>` and will print an error message.

----

.. _class_AStarGrid2D_method_is_dirty:

- :ref:`bool<class_bool>` **is_dirty** **(** **)** |const|

Indicates that the grid parameters were changed and :ref:`update<class_AStarGrid2D_method_update>` needs to be called.

----

.. _class_AStarGrid2D_method_is_in_bounds:

- :ref:`bool<class_bool>` **is_in_bounds** **(** :ref:`int<class_int>` x, :ref:`int<class_int>` y **)** |const|

Returns ``true`` if the ``x`` and ``y`` is a valid grid coordinate (id).

----

.. _class_AStarGrid2D_method_is_in_boundsv:

- :ref:`bool<class_bool>` **is_in_boundsv** **(** :ref:`Vector2i<class_Vector2i>` id **)** |const|

Returns ``true`` if the ``id`` vector is a valid grid coordinate.

----

.. _class_AStarGrid2D_method_is_point_solid:

- :ref:`bool<class_bool>` **is_point_solid** **(** :ref:`Vector2i<class_Vector2i>` id **)** |const|

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

----

.. _class_AStarGrid2D_method_set_point_solid:

- void **set_point_solid** **(** :ref:`Vector2i<class_Vector2i>` id, :ref:`bool<class_bool>` solid=true **)**

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

----

.. _class_AStarGrid2D_method_update:

- 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 :ref:`size<class_AStarGrid2D_property_size>`, :ref:`cell_size<class_AStarGrid2D_property_cell_size>` or :ref:`offset<class_AStarGrid2D_property_offset>` are changed. :ref:`is_dirty<class_AStarGrid2D_method_is_dirty>` will return ``true`` if this is the case and this needs to be called.

.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`
.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)`
.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)`
.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)`