ReadMe

Grid Toolkit

Utilitary API to proceed operations on abstract grids such as tile extraction, raycasting, and pathfinding.

API References

---

Usage

All you need to use this API is a bi-dimensional array of tiles ordered in row major order (see below).

What is a tile ? Any object (custom class, struct, component, ...) that implements the very light ITile (IWeightedTile for DijkstraGrid) interface of this library. This interface requires three properties getters:

• bool IsWalkable . Must return if the tile can be walk/see throught (for pathfinding/raycasting)
• int X . Must return the horizontal position of the tile into the grid
• int Y . Must return the vertical position of the tile into the grid
• float Weight . Only for IWeightedTile Must return the cost movement to enter this tile (minimum 1f).

This API is using a namespace so you have to add a using instruction to the scripts that will use this library:

using Caskev.GridToolkit;

---

MajorOrder

When working with two-dimensional arrays there is two ways of storing tiles, first rows then lines or the opposite.
This is called the Major Order. The most common major order used in C languages (and the one used in this library) is the row major order, meaning that the first index of the array represents the row index and the second index represents the column index.

Be aware that the row index actually indicates the vertical position of the tile in the grid, and the column index indicates the horizontal position of the tile in the grid, as it can be counter intuitive. For more information you can refer to this Wikipedia article.

---

API

---

Extraction

---

Allows you to extract tiles on a grid.
Provides shape extraction (rectangles, circles, cones and lines) and neighbors extraction with a lot of parameters.

---

You can extract tiles from shapes.

• GetTilesInARectangle

  YourCustomTileType[] tiles = Extraction.GetTilesInARectangle(grid, centerTile, rectangleSize);

• GetTilesInACircle

  YourCustomTileType[] tiles = Extraction.GetTilesInACircle(grid, centerTile, radius);

• GetTilesInACone

  YourCustomTileType[] tiles = Extraction.GetTilesInACone(grid, startTile, length, openingAngle, direction);

• GetTilesOnALine

  YourCustomTileType[] tiles = Extraction.GetTilesOnALine(grid, startTile, length, direction);

---

You can extract neighbors of a tile (if existing).

• GetTileNeighbour

  YourCustomTileType upperNeighbour = Extraction.GetTileNeighbour(grid, tile, Vector2Int.up);

• GetTileNeighbours

  YourCustomTileType[] neighbours = Extraction.GetTileNeighbours(grid, tile);

• GetTileOrthogonalsNeighbours

  YourCustomTileType[] orthogonalNeighbours = Extraction.GetTileOrthogonalsNeighbours(grid, tile);

• GetTileDiagonalsNeighbours

  YourCustomTileType[] diagonalsNeighbours = Extraction.GetTileDiagonalsNeighbours(grid, tile);

---

Each extraction method has a variant to check if a specific tile would be extracted

• IsTileInARectangle

  bool isTileInARectangle = Extraction.IsTileInARectangle(grid, tile, centerTile, rectangleSize);

• IsTileInACircle

  bool isTileInACircle = Extraction.IsTileInACircle(grid, tile, centerTile, radius);

• IsTileInACone

  bool isTileInACone = Extraction.IsTileInACone(grid, tile, centerTile, length, openingAngle, direction);

• IsTilesOnALine

  bool isTilesOnALine = Extraction.IsTilesOnALine(grid, tile, centerTile, length, direction);

• IsTileNeighbor

  bool isTileRightNeighbor = Extraction.IsTileNeighbor(tile, neighbor, Vector2Int.right);

• IsTileOrthogonalNeighbor

  bool isTileOrthogonalNeighbor = Extraction.IsTileOrthogonalNeighbor(tile, neighbor);

• IsTileDiagonalNeighbor

  bool isTileDiagonalNeighbor = Extraction.IsTileDiagonalNeighbor(tile, neighbor);

• IsTileAnyNeighbor

  bool isTileNeighbor = Extraction.IsTileAnyNeighbor(tile, neighbor);

---

Raycasting

---

Allows you to cast lines of sight and cones of vision on a grid

---

You can get the line of sight from a tile (a line that "stops" at the first encountered unwalkable tile).
Many signatures are available to specify the length and direction of the line.

• GetLineOfSight

  YourCustomTileType[] lineOfSight = Raycasting.GetLineOfSight(grid, startTile, destinationTile);

  ---

  You can get the cone of vision from a tile.
  Many signatures are available to specify the length and direction of the cone.
• GetConeOfVision

  YourCustomTileType[] coneOfVision = Raycasting.GetConeOfVision(grid, startTile, openingAngle, destinationTile);

  ---

  You can check if a line of sight or a cone of vision is clear (no non-walkable tile encountered)
• IsLineOfSightClear

  bool isLineClear = Raycasting.IsLineOfSightClear(grid, startTile, destinationTile);

• IsConeOfVisionClear

  bool isConeClear = Raycasting.IsConeOfVisionClear(grid, startTile, destinationTile);

---

Pathfinding

---

Allows you to calculate paths between tiles.
This API offers several ways to do pathfinding, depending on your needs.

You can generate objects that can be seen as layers of data on top of your grid. Once generated, these objects allows you to get paths with almost no performance cost.

A DirectionPath object holds direction data for all tiles on the path between two tiles.
A DijkstraPath object holds both direction and distance data for all tiles on the path between two tiles.

A DirectionField object holds direction data between a target tile and all the tiles that are accessible to this target into a specified maximum distance range.
A DijkstraField object holds both direction and distance data between a target tile and all the tiles that are accessible to this target into a specified maximum distance range.

A DirectionGrid object holds direction data between a target tile and all the tiles that are accessible to this target, on the entire grid.
A DijkstraGrid object holds both direction and distance data between a target tile and all the tiles that are accessible to this target, on the entire grid.

A DirectionAtlas object holds DirectionGrid objects for each tile.
A DijkstraAtlas object holds DijkstraGrid objects for each tile.

Note that, obviously, any path calculation is valid as long as the user grid, walkable states (and weights for dijkstra objects) of the tiles, remains unchanged

---

Diagonals Movements

DiagonalPolicy

By default, paths are calculated with orthogonal movements only (up, down, left, right). This is the most efficient way to calculate paths. You can allow diagonal movements but you have to decide the tolerance regarding the walls common neibours. You can use the DiagonalsPolicy optional parameter, in any pathfinding calculation method, to allow and tune diagonal movements.

Take a look at this schematic to understand how it works:

DiagonalsWeight (Only available with Dijkstra objects)

When moving diagonally from one tile to another, there is actually more distance covered than when moving with orthogonal movement. Mathematically, when the orthogonal distance between two adjacent tiles is 1, then the diagonal distance between two diagonally adjacent tiles is roughly 1.414. The detailed calculation is Sqrt(x_distance²+y_distance²). Although it is the most commonly used diagonal movement cost value, you can decide to use any value superior or equal to 1.

---

Asynchronous

Every pathfinding calculation method has an asynchronous variant, that returns a Task, with additional optional parameters to handle cancellation and be notified of progress.

---

Direction path

A DirectionPath object holds direction data for all tiles on the path between two tiles.

To generate a DirectionPath, use the GenerateDirectionPath method that needs the grid, the target tile and the *start** tile from which to calculate the path, as parameters.

YourCustomTileType[] directionPath = Pathfinding.GenerateDirectionPath(grid, targetTile, startTile);

---

Disjktra path

A DijkstraPath object holds both direction and distance data for all tiles on the path between two tiles.

To generate a DijkstraPath, use the GenerateDisjktraPath method that needs the grid, the target tile and the *start** tile from which to calculate the path, as parameters.

YourCustomTileType[] dijkstraPath = Pathfinding.GenerateDisjktraPath(grid, targetTile, startTile);

---

DirectionField

A DirectionField object holds direction data between a target tile and all the tiles that are accessible to this target into a specified maximum distance range.

To generate a DirectionField object, use the GenerateDirectionField method that needs the grid and the target tile from which to calculate the paths, as parameters.

DirectionField directionField = Pathfinding.GenerateDirectionField(grid, targetTile);

You can access and iterate over all the accessible tiles.

• GetAccessibleTile

  for (int i = 0; i < directionField.AccessibleTilesCount; i++)
  {
      YourCustomTileType tile = directionField.GetAccessibleTile(grid, i);
  }

---

DijkstraField

A DijkstraField object holds both direction and distance data between a target tile and all the tiles that are accessible to this target into a specified maximum distance range.

To generate a DijkstraField object, use the GenerateDijkstraField method that needs the grid and the target tile from which to calculate the paths, as parameters.

DijkstraField dijkstraField = Pathfinding.GenerateDijkstraField(grid, targetTile);

You can access and iterate over all the accessible tiles and also get their distance to the target.

• GetAccessibleTile

  for (int i = 0; i < dijkstraField.AccessibleTilesCount; i++)
  {
      YourCustomTileType tile = dijkstraField.GetAccessibleTile(grid, i);
      float distance = dijkstraField.GetDistanceToTarget(grid, tile);
  }

---

DirectionGrid

A DirectionGrid object holds direction data between a target tile and all the tiles that are accessible to this target, on the entire grid.

To generate a DirectionGrid object, use the GenerateDirectionGrid method that needs the grid and the target tile from which to calculate the paths, as parameters.

DirectionGrid directionGrid = Pathfinding.GenerateDirectionGrid(grid, targetTile);

You can retrieve the tile that has been used as the target to generate this DirectionGrid.

• GetTarget

  YourCustomTileType targetTile = directionGrid.GetTarget(grid);

You can get all the tiles on the path from a tile to the target.

• GetPathToTarget

  YourCustomTileType[] tiles = directionGrid.GetPathToTarget(grid, startTile);

Or you can get all the tiles on the path from the target to a tile.

• GetPathFromTarget

  YourCustomTileType[] tiles = directionGrid.GetPathFromTarget(grid, destinationTile);

You can know if a tile is accessible from the target tile. This is useful before calling the following DirectionGrid methods that only takes an accessible tile as parameter.

• IsTileAccessible

  bool isTileAccessible = directionGrid.IsTileAccessible(grid, tile);

You can get the next tile on the path between the target and a tile.

• GetNextTileFromTile

  YourCustomTileType nextTile = directionGrid.GetNextTileFromTile(grid, tile);

You can get the next tile direction on the path between the target and a tile (in 2D grid coordinates). NextTileDirection is an enum representing the eight possible directions.

• GetNextTileDirectionFromTile

  NextTileDirection nextTileDirection = directionGrid.GetNextTileDirectionFromTile(grid, tile);

You can serialize the generated DirectionGrid to a byte array. Usefull for path baking in edit time.

• ToByteArray

  byte[] serializedDirectionGrid = directionGrid.ToByteArray();

You can deserialize a byte array to a DirectionGrid. Usefull for loading baked paths at runtime.

• FromByteArray

  DirectionGrid directionGrid = DirectionGrid.FromByteArray(grid, serializedDirectionGrid);

---

DijkstraGrid

A DijkstraGrid object holds both direction and distance data between a target tile and all the tiles that are accessible to this target, on the entire grid.

To generate a DijkstraGrid object, use the GenerateDijkstraGrid method that needs the grid and the target tile from which to calculate the paths, as parameters.

DijkstraGrid dijkstraGrid = Pathfinding.GenerateDijkstraGrid(grid, targetTile);

You can get the distance between the target and a tile.

• GetDistanceToTarget

  float distance = dijsktraMap.GetDistanceToTarget(grid, tile);