Scripting Support (C#)

advanced scripting

Grids 2D · Scripting Support (C#)

Class: All members on this page belong to the Grid2D component (namespace Grids2D). Access via Grid2D.instance or GetComponent<Grid2D>().

Tip: Access the singleton via Grid2D.instance. Check the demo scenes for practical examples of pathfinding and territory management.

Getting Started

Add the namespace and access the grid singleton:

using Grids2D;

Grid2D grid = Grid2D.instance;

Grid Configuration

GRID_TOPOLOGY gridTopology { get; set; }

Grid type: Irregular (Voronoi), Box, or Hexagonal.

int rowCount { get; set; }

Number of rows (box/hexagonal topologies).

int columnCount { get; set; }

Number of columns (box/hexagonal topologies).

int numCells { get; set; }

Number of cells for irregular topology.

int seed { get; set; }

Randomization seed for cell generation.

bool regularHexagons { get; set; }

Use regular hexagons (hexagonal topology only).

float hexSize { get; set; }

Hexagon size (hexagonal topology).

bool evenLayout { get; set; }

Toggle even corner layout (hexagonal topology).

int gridRelaxation { get; set; }

Number of relaxation iterations used to normalize cell sizes in irregular topology.

float gridCurvature { get; set; }

Curvature factor applied to cell borders.

OVERLAY_MODE overlayMode { get; set; }

Overlay rendering mode: Overlay or Ground.

RENDER_QUEUE renderQueue { get; set; }

Default rendering queue for the grid: Opaque or Transparent.

int sortingOrder { get; set; }

Sorting layer order for grid elements (transparent queue only).

SURFACES_TYPE_ORDER surfacesTypeOrder { get; set; }

Whether cell surfaces render on top of territory surfaces or vice versa.

int gridDepthOffset { get; set; }

Depth offset applied to the grid rendering.

bool respectOtherUI { get; set; }

When enabled, prevents grid interaction if the pointer is over a UI element.

Camera mainCamera { get; set; }

Main camera used for raycasting and position calculations.

Texture2D[] textures

Array of textures available for cell texturing via index.

Texture2D canvasTexture

Canvas texture reference used by the grid.

List<Vector2> voronoiSites { get; set; }

Custom Voronoi site positions for irregular topology. Setting this regenerates the grid.

Display

bool showCells { get; set; }

Toggle cell borders visibility.

Color cellBorderColor { get; set; }

Cell border color.

Color cellHighlightColor { get; set; }

Highlight color when hovering over cells.

HIGHLIGHT_MODE highlightMode { get; set; }

Highlight mode: None, Territories, or Cells.

Texture2D gridMask { get; set; }

Alpha texture for cell visibility (black pixels = invisible cells).

float cellBorderAlpha { get; set; }

Alpha component of the cell border color.

bool cellHighlightNonVisible { get; set; }

Whether invisible cells should also be highlighted when the pointer hovers over them.

float highlightFadeAmount { get; set; }

Amount of fade applied to the highlight effect.

Territories

bool enableTerritories { get; set; }

Enable or disable the territory system.

int numTerritories { get; set; }

Number of territories.

bool showTerritories { get; set; }

Toggle territory borders visibility.

bool colorizeTerritories { get; set; }

Fill territories with colors.

Color territoryHighlightColor { get; set; }

Highlight color for hovered territories.

float colorizedTerritoriesAlpha { get; set; }

Alpha transparency for colorized territory fills.

Color territoryFrontiersColor { get; set; }

Color of territory border lines.

float territoryFrontiersAlpha { get; set; }

Alpha component of the territory border color.

bool showTerritoriesOuterBorders { get; set; }

Toggle visibility of the perimetral/outer border of territories.

bool allowTerritoriesInsideTerritories { get; set; }

Allow territories to be fully surrounded by other territories.

Texture2D territoriesTexture

Texture used to auto-generate territories based on pixel colors.

Color territoriesTextureNeutralColor

Neutral color in the territories texture that does not generate a territory.

State Properties

Cell cellHighlighted { get; }

Cell currently under the pointer (read-only).

int cellHighlightedIndex { get; }

Index of the highlighted cell (read-only).

int cellLastClickedIndex { get; }

Index of the last clicked cell (read-only).

int territoryHighlightedIndex { get; }

Index of the highlighted territory (read-only).

List<Cell> cells

Array of all cells in the grid.

List<Territory> territories

Array of all territories.

Cell cellLastClicked { get; }

Last clicked Cell object (read-only).

Territory territoryHighlighted { get; }

Territory currently under the pointer (read-only).

int territoryLastClickedIndex { get; }

Index of the last clicked territory (read-only).

GameObject highlightedObj { get; }

Reference to the currently highlighted GameObject (cell or territory surface).

bool mouseIsOver

True when the mouse pointer is over the grid.

int lastVertexCount { get; }

Total vertex count of the last grid mesh generation (read-only).

Events

event OnCellEvent OnCellEnter(int cellIndex)

Fired when the pointer enters a cell. Receives int cellIndex.

event OnCellEvent OnCellExit(int cellIndex)

Fired when the pointer leaves a cell.

event OnCellEvent OnCellClick(int cellIndex)

Fired when a cell is clicked.

event OnCellHighlight OnCellHighlight(int cellIndex, ref bool cancelHighlight)

Fired before highlighting a cell. Set cancelHighlight = true to prevent it.

event OnTerritoryEvent OnTerritoryEnter(int territoryIndex)

Fired when the pointer enters a territory.

event OnTerritoryEvent OnTerritoryExit(int territoryIndex)

Fired when the pointer leaves a territory.

event OnTerritoryEvent OnTerritoryClick(int territoryIndex)

Fired when a territory is clicked.

event PathFindingEvent OnPathFindingCrossCell(int cellIndex)

Fired during pathfinding for each cell evaluated. Return a custom cost value.

event OnCellEvent OnCellMouseUp(int cellIndex)

Fired when the mouse button is released over a cell. Receives int cellIndex.

event OnTerritoryHighlight OnTerritoryHighlight(int territoryIndex, ref bool cancelHighlight)

Fired before highlighting a territory. Set cancelHighlight = true to prevent it.

Grid2DMove Helper Events

The Grid2DMove component (namespace Grids2D) is attached to GameObjects moved via CellMoveTo(). Subscribe on the returned component:

event MoveEvent OnMoveEnd(GameObject gameObject)

Triggered when the MoveTo operation finishes and the GameObject reaches its destination.

event CellMoveEvent OnCellMoveEvent(Vector3 destination, int pathStepIndex)

Triggered when the GameObject moves into the next cell along its path.

Cell Methods

int CellGetIndex(int row, int column, bool clampToBorders = true)

Returns the cell index at the specified row and column.

Cell CellGetAtPosition(Vector3 position, bool worldSpace)

Returns the cell at a world or local position.

Vector3 CellGetPosition(int cellIndex)

Returns the world position of a cell's center.

int CellGetRow(int cellIndex)

Returns the row of the cell.

int CellGetColumn(int cellIndex)

Returns the column of the cell.

List<Cell> CellGetNeighbors(int cellIndex)

Returns the list of neighboring cells.

List<int> CellGetNeighbors(int cellIndex, int maxDistance, float maxCost = -1, int cellGroupMask = -1)

Returns cell indices within a specified distance and cost.

int CellGetTerritoryIndex(int cellIndex)

Returns the territory index the cell belongs to.

bool CellSetTerritory(int cellIndex, int territoryIndex)

Assigns a cell to a different territory.

int CellGetIndex(Cell cell)

Returns the index of a cell by its object reference.

Cell CellGetAtPosition(int column, int row)

Returns the cell located at the given column and row.

Vector3 CellGetPosition(int cellIndex, float elevation)

Returns the world position of a cell's center with an elevation offset from the grid surface.

Vector3 CellGetPosition(int row, int column)

Returns the world position of a cell specified by row and column.

Vector3 CellGetPosition(int row, int column, float elevation)

Returns the world position of a cell specified by row and column with elevation.

Bounds CellGetRectWorldSpace(int cellIndex)

Returns the bounding rect enclosing the cell in world space.

int CellGetVertexCount(int cellIndex)

Returns the number of vertices defining the cell polygon.

Vector3 CellGetVertexPosition(int cellIndex, int vertexIndex, float elevation = 0)

Returns the world position of a specific vertex of a cell.

List<Cell> CellGetNeighbors(Cell cell)

Returns a list of neighboring cells for the specified Cell object.

int CellGetGroup(int cellIndex)

Returns the group number of a cell (default 1).

int CellGetFromGroup(int group, int[] indices)

Populates the indices array with cell indices belonging to the given group. Returns the count of matches.

int CellGetTag(int cellIndex)

Returns the integer tag value of a cell.

Cell CellGetWithTag(int tag)

Returns the Cell object associated with a specific tag.

bool CellIsBorder(int cellIndex)

Returns true if the cell is on the grid border.

bool CellIsVisible(int cellIndex)

Returns true if the cell is visible.

Texture2D CellGetTexture(int cellIndex)

Returns the current fill texture of a cell.

int CellGetTextureIndex(int cellIndex)

Returns the texture index (1..32) of a cell, or 0 if no matching texture.

Cell Visual Methods

void CellSetColor(int cellIndex, Color color)

Sets the fill color of a cell.

Color CellGetColor(int cellIndex)

Returns the current fill color of a cell.

void CellSetTexture(int cellIndex, Texture2D texture)

Applies a texture to a cell.

GameObject CellToggle(int cellIndex, bool visible, Color color, bool refreshGeometry = false)

Toggles cell surface visibility with a specific color.

void CellSetVisible(int cellIndex, bool visible)

Shows or hides a cell.

void CellHideAll()

Hides all cell surfaces.

void CellSetBorderVisible(int cellIndex, bool visible)

Shows or hides the border of a specific cell.

void CellHide(int cellIndex)

Hides the surface of a specific cell by index.

GameObject CellSetSprite(int cellIndex, Color tintColor, Sprite sprite)

Sets a sprite as the fill texture of a cell with a tint color.

GameObject CellToggle(int cellIndex, bool visible, Texture2D texture, bool useCanvasRect = false)

Toggles cell surface visibility with a texture.

GameObject CellToggle(int cellIndex, bool visible, Color color, bool refreshGeometry, int textureIndex, bool useCanvasRect = false)

Toggles cell surface visibility with a color and texture index.

GameObject CellToggle(int cellIndex, bool visible, Color color, bool refreshGeometry, Texture2D texture, bool useCanvasRect = false)

Toggles cell surface visibility with a color and texture.

GameObject CellToggle(int cellIndex, bool visible, Color color, bool refreshGeometry, Texture2D texture, Vector2 textureScale, Vector2 textureOffset, float textureRotation)

Toggles cell surface with color, texture, scale, offset, and rotation.

GameObject CellToggle(int cellIndex, bool visible, Color color, bool refreshGeometry, Texture2D texture, Vector2 textureScale, Vector2 textureOffset, float textureRotation, bool rotateInLocalSpace, bool useCanvasRect = false)

Full overload for toggling cell surface with all texture transform options.

Cell Effects

void CellFadeOut(int cellIndex, Color color, float duration)

Fades a cell's color out over time.

void CellFlash(int cellIndex, Color color, float duration)

Flashes a cell with a color.

void CellBlink(int cellIndex, Color color, float duration)

Blinks a cell repeatedly.

void CellFadeOut(Cell cell, Color color, float duration)

Fades a cell's color out over time using a Cell reference.

void CellFadeOut(List<int> cellIndices, Color color, float duration)

Fades a list of cells out over time.

void CellFlash(Cell cell, Color color, float duration)

Flashes a cell with a color using a Cell reference.

void CellFlash(List<int> cellIndices, Color color, float duration)

Flashes a list of cells with a color.

void CellBlink(Cell cell, Color color, float duration)

Blinks a cell repeatedly using a Cell reference.

void CellBlink(List<int> cellIndices, Color color, float duration)

Blinks a list of cells repeatedly.

Cell Pathfinding Properties

void CellSetCanCross(int cellIndex, bool canCross)

Sets whether a cell can be crossed during pathfinding.

void CellSetCrossCost(int cellIndex, float cost)

Sets the movement cost for crossing a cell.

void CellSetSideCrossCost(int cellIndex, CELL_SIDE side, float cost)

Sets the crossing cost for a specific cell side (e.g., walls).

void CellSetSideBlocksLOS(int cellIndex, CELL_SIDE side, bool blocks)

Sets whether a cell side blocks line of sight.

void CellSetGroup(int cellIndex, int group)

Sets the group of a cell for filtering in pathfinding.

void CellSetTag(int cellIndex, int tag)

Sets a custom integer tag on a cell.

float CellGetCrossCost(int cellIndex, CELL_DIRECTION direction = CELL_DIRECTION.Entering)

Returns the crossing cost of a cell (without specifying a specific edge).

void CellSetCrossCost(int cellStartIndex, int cellEndIndex, float cost)

Sets the crossing cost from one adjacent cell to another.

float CellGetCrossCost(int cellStartIndex, int cellEndIndex)

Returns the crossing cost from one adjacent cell to another.

float CellGetSideCrossCost(int cellIndex, CELL_SIDE side, CELL_DIRECTION direction = CELL_DIRECTION.Entering)

Returns the crossing cost for a specific cell side.

bool CellGetSideBlocksLOS(int cellIndex, CELL_SIDE side)

Returns true if the specified cell side blocks line of sight.

Pathfinding Methods

List<int> FindPath(int cellIndexStart, int cellIndexEnd, float maxSearchCost = 0, int maxSteps = 0, int cellGroupMask = -1)

Finds the shortest path between two cells using A*. Returns a list of cell indices or null if no path exists.

cellIndexStart: Starting cell index.
cellIndexEnd: Destination cell index.
maxSearchCost: Maximum total cost. 0 = unlimited.
maxSteps: Maximum path length. 0 = unlimited.
cellGroupMask: Bitmask for allowed cell groups. -1 = all groups.

bool CellGetLineOfSight(int startCellIndex, int endCellIndex, ref List<int> cellIndices, ref List<Vector3> worldPositions)

Checks line of sight between two cells. Returns true if clear. Populates the cells and positions along the line.

int CellGetHexagonDistance(int startCellIndex, int endCellIndex)

Returns the hexagonal grid distance (number of hex steps) between two cells.

HeuristicFormula pathFindingHeuristicFormula { get; set; }

Heuristic formula used to estimate distance during pathfinding.

int pathFindingMaxSteps { get; set; }

Maximum number of steps a path can contain.

float pathFindingMaxCost { get; set; }

Maximum search cost for the pathfinding algorithm.

bool pathFindingUseDiagonals { get; set; }

Whether paths can include diagonal movement between cells (box topology).

float pathFindingHeavyDiagonalsCost { get; set; }

Extra cost multiplier for crossing diagonals.

List<int> FindPath(int cellIndexStart, int cellIndexEnd, float maxSearchCost, out float cost, int maxSteps = 0, int cellGroupMask = -1, CanCrossCheckType canCrossCheck = CanCrossCheckType.Default, float maxCellCrossCost = float.MaxValue)

Finds the shortest path between two cells and outputs the total path cost.

bool CellGetLineOfSight(Vector3 startPosition, Vector3 endPosition, ref List<int> cellIndices, ref List<Vector3> worldPositions, int cellGroupMask = -1, int lineResolution = 2, bool exhaustiveCheck = false)

Checks line of sight between two world positions. Returns true if the path is clear.

void CellGetLine(int startCellIndex, int endCellIndex, ref List<int> cellIndices, ref List<Vector3> worldPositions, int lineResolution = 2)

Returns a line of cells and world positions between two cells (ignoring blocking).

int CellGetBoxDistance(int startCellIndex, int endCellIndex)

Returns the grid distance (Chebyshev) between two cells in box topology.

Territory Methods

GameObject TerritoryToggle(int territoryIndex, bool visible, Color color)

Toggles a territory surface visibility with a color.

Vector3 TerritoryGetPosition(int territoryIndex)

Returns the center position of a territory.

List<Territory> TerritoryGetNeighbors(int territoryIndex)

Returns neighboring territories.

void TerritoryFlash(int territoryIndex, Color color, float duration)

Flashes a territory with a color.

int TerritoryGetIndex(Territory territory)

Returns the index of a territory by its object reference.

Territory TerritoryGetAtPosition(Vector3 localPosition)

Returns the territory at a local-space position.

Vector3 TerritoryGetPosition(Territory territory, float elevation = 0)

Returns the world position of a territory's center using a Territory reference.

Bounds TerritoryGetRectWorldSpace(int territoryIndex)

Returns the bounding rect enclosing the territory in world space.

void TerritoryHideRegionSurface(int territoryIndex)

Hides the surface of a specific territory.

GameObject TerritoryToggle(int territoryIndex, bool visible, Color color, bool refreshGeometry, Texture2D texture, bool useCanvasRect = false)

Toggles territory surface visibility with a color and texture.

GameObject TerritoryToggle(int territoryIndex, bool visible, Color color, Texture2D texture, Vector2 textureScale, Vector2 textureOffset, float textureRotation, bool useCanvasRect = false)

Toggles territory surface with full texture transform options.

void TerritorySetVisible(int territoryIndex, bool visible)

Shows or hides a territory.

bool TerritoryIsVisible(int territoryIndex)

Returns true if the territory is visible.

void TerritorySetBorderVisible(int territoryIndex, bool visible)

Shows or hides the border of a specific territory.

void TerritoryFadeOut(int territoryIndex, Color color, float duration)

Fades a territory's color out over time.

void TerritoryBlink(int territoryIndex, Color color, float duration)

Blinks a territory with a color repeatedly.

void CreateTerritories(Texture2D texture, Color neutral)

Auto-generates territories from a texture. Each distinct color becomes a territory.

Movement

Grid2DMove MoveTo(GameObject o, int cellIndex, float velocity = 0)

Moves a game object to a cell. Returns a Grid2DMove component for tracking.

Grid2DMove MoveTo(GameObject o, List<int> positions, float velocity = 0)

Moves a game object along a path of cell indices.

Grid2DMove MoveTo(GameObject o, int row, int column, float velocity = 0, float elevation = 0)

Moves a game object to a cell specified by row and column.

void MovePause(GameObject o)

Pauses a moving game object.

void MovePauseToggle(GameObject o)

Toggles pause/resume on a moving game object.

void MoveResume(GameObject o)

Resumes movement of a paused game object.

Configuration Save/Load

string CellGetConfigurationData()

Exports the current cell configuration (colors, textures, tags, costs) as a string.

void CellSetConfigurationData(string cellData)

Restores a previously saved cell configuration.

Cell Structure

bool CellMerge(Cell cell1, Cell cell2)

Merges cell2 into cell1. Only neighboring cells can be merged. Returns true on success.

void CellRemove(Cell cell)

Removes a cell from the cells and territories lists.

Drawing

GameObject DrawLine(int cellIndex, CELL_SIDE side, Color color, float width)

Draws a line over a cell side. Returns the line GameObject.

GameObject DrawLine(int cellIndex1, int cellIndex2, Color color, float width)

Draws a line connecting two cell centers. Returns the line GameObject.

Utility

void GenerateMap()

Resets all cells and territories and regenerates the grid. Usually called internally; prefer Redraw().

void Redraw()

Refreshes the grid visual representation. Call after changing grid properties at runtime.

void ReloadGridMask()

Re-reads the grid mask texture and reapplies cell visibility.

void HideHighlightedObject(GameObject go)

Cancels highlighting on a given GameObject. Ignored if it is not the currently highlighted object.

void CheckRay(Ray ray)

Issues a selection check based on a given ray. Used by the editor to manipulate cells from the Scene window.

Key Enums

GRID_TOPOLOGY

Irregular, Box, Hexagonal

HIGHLIGHT_MODE

None, Territories, Cells

CELL_SIDE

TopLeft, Top, TopRight, BottomRight, Bottom, BottomLeft, Left, Right

Code Examples

using UnityEngine;
using Grids2D;

public class GridDemo : MonoBehaviour {
    Grid2D grid;

    void Start() {
        grid = Grid2D.instance;

        // Listen for cell clicks
        grid.OnCellClick += OnCellClicked;

        // Configure pathfinding costs
        grid.CellSetCanCross(10, false);  // Block cell 10
        grid.CellSetCrossCost(20, 3f);   // Make cell 20 expensive
    }

    void OnCellClicked(int cellIndex) {
        // Color the clicked cell
        grid.CellToggle(cellIndex, true, Color.yellow);

        // Find path from cell 0 to clicked cell
        List<int> path = grid.FindPath(0, cellIndex);
        if (path != null) {
            foreach (int idx in path)
                grid.CellFlash(idx, Color.green, 1f);
        }
    }
}

Was this page helpful? |