skip to Main Content

Scripting Support (C#)

Snippets

Note for new developers!

If you’re new to programming, you may find overwhelmed by the large list of C# functions and properties. We have created a few useful scripts for new developers called “Snippets”. They’re scripts you can add to gameobjects to perform simple tasks, like “move this object to target cell” without coding.

These snippets are just fancy wrappers for the API provided by Terrain Grid System so you can take a look into them and learn how do they use the API.

The available snippets can be found in the Component menu:

For example, let’s say you have a gameobject you want to move on the grid. You can add the script “TGS Move To Cell” to your gameobject and enter the row and column in the inspector:

If you would like more snippets or have any question please send us an email or use our support forum. We’ll gladly add more snippets for you 

Important! These snippets just provide like the 1% of functionality provided by the API and are meant to introduce you into some common features. If you already know how to program in C# then you can go directly to the next section and learn the API (it’s not that complex after all!).

 

Use Terrain Grid System from scripting

You can instantiate the prefab “TerrainGridSystem“ or add it to the scene from the Editor as explained in the “How to use this asset in your project” section. Once the prefab is in the scene, you can access the functionality from code through the static instance property:

To get the cell beneath a gameobject in your scene use CellGetAtPosition and pass the world space coordinate:

 

Cell cell = tgs.CellGetAtPosition(Vector3 position, Vector3 wordSpace);

To fade surrounding cells:

List<Cell>neighbours = tgs.CellGetNeighbours(sphereCell);


foreach(Cell cell in neighbours){

 tgs.CellFadeOut(cell, Color.red, 2.0f)
}

To fade cells by row and column:

const int size = 3;
for (int j=sphereCell.row - size; j<=sphereCell.row + size;j++) {

       for (int k=sphereCell.column - size; k<=sphereCell.column + size; k++) {

            int cellIndex = tgs.CellGetIndex(j,k, true);

            tgs.CellFadeOut(cellIndex, Color.blue, 1.0f);

       }

}

Take a look at the demo scenes included in the asset for more sample code!

Public API Structure

All TerrainGridSystem API is exposed through TerrainGridSystem class. This is a single component that has been split for convenience in several files located in TerrainGridSystem/Scripts folder:

  • TerrainGridSystem: contains generic functions and properties.

  • TGSCells: all cell-related.

  • TGSTerritories: all territory-related.

  • TGSPathfinding: pathfinding stuff.

  • TGSConfig: this is the component that stores the cell configuration when you use and export the cell setup using the Grid Editor.

Note that the above are just filenames, but the class is the same “TerrainGridSystem”. This approach follows the partial class standard in C# to make easy the reorganization of “God” (or big) utility classes. This means that you will be just using the traditional gameObject.GetComponent<TerrainGridSystem>() or just TerrainGridSystem.instance to get a reference to the API, irrespective of the number of classes files.

Thanks to this file organization you can easily check the different public properties and functions of the API by category (cell-related, territory-related, …)

Complete list of public properties, methods and events

Basic grid functions

tgs.SetTerrain(gameObject): specifies the terrain gameobject linked to the grid. Usually this is set in Editor time but you can also call thi method if you instantiate the prefab at runtime. Instead of instantiating the prefab you can just call AddTerrainGridSystem() directly on any gameobject including your terrain gameobject (AddTerrainGridSystem is an extension method for GameObject class).

tgs.numCells: desired number of cells for irregular topology. The actual generated cells will vary depending on the topology.

tgs.ColumnCount: number of columns for boxed and hexagonal types.

tgs.RowCount: number of rows for boxed and hexagonal types.

tgs.SetDimensions(int rows, int columns, bool keepCellSize): sets the number of rows and columns in one step (only hexagonal or box grid topology). This is faster than settings rowCount and columnCount separately. The parameter keepCellSize determines if the individual cell size is preserved (only valid for hexagonal and box topologies).

tgs.seed: seed constant for the random generator.

tgs.gridCenter: the center of the grid with respect to its parent (0,0 = center).

tgs.gridCenterWorldPosition: sets or retrieves the center of the grid in world space coordinates. You can also call tgs.SetGridCenterWorldPosition method instead.

tgs.gridScale: the scale of the grid with respect to its parent (1,1 = full terrain/grid size)

tgs.cellSize: directly sets the individual cell size (Vector2). Setting this property will recalculate the grid scale accordingly.

tgs.gridMask: optional texture used to defined cells visibility. The texture is matched against the whole grid parent surface. An alpha value of 0 means cell will be invisible.

tgs.gridTopology: type of cells (Irregular, Box, Hexagonal, …)

tgs.gridRelaxation: relaxation factor for the irregular topology (defaults 1). It creates more homogeneous irregular grids but has a performance hit during the creation of the grid (not afterwards).

tgs.gridCurvature: will bend cell edges for all topologies. It will add more vertex count to the mesh so it’s only available on grids with less than 100 cells.

tgs.terrainCenter: returns the world space position of the center of the terrain.

tgs.bounds: the bounds of the grid in world space. This property does not account for height.

tgs.gridElevation: vertical offset of the grid with respect to the terrain for fine-tuning z-fighting issues.

tgs.gridElevationBase: vertical position for the grid, used to elevate grid over terrain. Both gridElevation and gridElevationBase are added when computing the position of the grid. Use gridElevationBase if you want the grid to float above the terrain and gridElevation for small height adjustments.

tgs.gridCameraOffset: dynamic camera-oriented displacement. This will move the mesh towards the camera.

tgs.gridNormalOffset: general offset of the mesh from the terrain. This will make the grid “grow” in all directions. This will impact performance during the mesh creation.

tgs.gridDepthOffset: Z-Buffer offset for the grid system shaders. Very cheap method to prevent z-fighting which can be combined with above methods. You should use this property first to adjust your grid.

tgs.gridRoughness: gripping factor for the mesh. The lower the value the better fit of the mesh to the terrain.

tgs.nearClipFade: distance from the camera for the fade in effect of the grid. Useful in first-person-view games.

tgs.nearClipFadeFallOff: falloff or gradient amount for the fade in effect.

tgs.voronoiSites: optionally set a list of starting Voronoi site positions. The list will be completed up to numCells if voronoiSites list provided has less items.

Basic grid functions

tgs.cells: return a List<Cell> of all cells/states records.

tgs.showCells: whether to show or not the cells borders.

tgs.cellHighlighted: returns the cell/state object in the cells list under the mouse cursor (or null if none).

tgs.cellHighlightedIndex: returns the cell/state index in the cells list under the mouse cursor (or -1 if none).

tgs.cellHighlightNonVisible: sets if invisible cells should be highlighted when pointer is over them (default is true).

tgs.cellLastClickedIndex: returns the index of last cell clicked.

tgs.cellHighlightColor: color for the highlight of cells.

tgs.cellHighlightNonVisible: set to true if you want to be able to highlight invisible cells.

tgs.cellBorderColor color for all cells borders.

tgs.cellBorderAlpha: helper method to change only the alpha of cell borders.

tgs.CellSetTag(int cellIndex, int tag): assigns a cell a user-defined integer tag. Cell can be later retrieved very quickly with CellGetWithTag.

tgs.CellGetWithTag(int tag): retrieves a cell previously tagged with an integer using the method CellSetTag.

tgs.CellGetIndex(Cell cell): returns the index of the provided cell object in the Cells collection.

tgs.CellGetIndex(row, column, clampToBorders): returns the index of the provided Cell by row and column. Use clampToBorders = true to limit row/column to edges of the grid or to allow wrap around edges otherwise.

tgs.CellGetPosition(int cellIndex): returns the center of a cell in the world space.

tgs.CellGetRect(int cellIndex): returns the 2D rectangle enclosing the cell in local space (-0.5..0.5 range).

tgs.CellGetRectWorldSpace(int cellIndex): returns the 3D bounds of the cell in world space.

tgs.CellGetVertexCount(int cellIndex): returns the number of vértices of any cell.

tgs.CellGetVertexPosition(int cellIndex, int vertexIndex): returns the world space position of any vertex of a cell.

tgs.CellGetAtPosition(Vector3 position, Vector3 wordSpace): returns the cell that contains position (in local space coordinates which ranges from -0.5 to 0.5 or from a point in world space).

tgs.CellGetAtPosition(int column, int row): returns the cell located at given row and col (only boxed and hexagonal topologies).

tgs.CellGetInArea(Bounds bounds, List<int>indices, float padding = 0, bool checkAllVertices = false)

Returns a list of cell indices contained in the bounds or under those bounds (eg. under a gameobject’s collider bounds). Padding is an optional margin that adds or substract to the boundary. When checkAllVertices is true, not only the center but all cell vertices are checked.

tgs.CellGetInArea(Collider collider, List<int>indices, int resolution, float padding = 0, float offset = 0)

Returns a list of cell indices contained under a collider. Resolution and padding are used to defined the granularity of the algorithm which tests cells inside the projected collider bounds. Offset can be used to modify the projection axis.

tgs.CellGetWithinCone(int cellIndex, Vector2 direction, float maxDistance, float angle, List<int> cellIndices)

Returns a list of cells contained in a cone defined by a starting cell, a direction, max distance and angle in degrees (max distance is defined in local space coordinates of grid being the borders at -0.5 and 0.5)

tgs.GetCellsWithinCone(int cellIndex, int targetCellIndex, float angle, List<int> cellIndices)

Returns a list of cells contained in a cone defined by a starting cell, target cell and angle in degrees.

tgs.CellGetNeighbour(int cellIndex, int side): returns the index of the adjacent cell by its side name (top, right, bottom left, …).

tgs.CellGetNeighbours(int cellIndex, …): returns a list of neighbour cells to a specific cell optionally specifying the maximum number of steps, maximum total cross cost, cell group mask and other options.

tgs.CellGetNeighboursWithinRange(int cellIndex, …): similar to CellGetNighbours method but accepts min and max distance.

tgs.CellGetHexagonDistance(index1, index2): returns the number of steps to reach cell2 from cell1 in an hexagonal grid. This method does not take into account cell groups nor blocking cells.

tgs.CellMerge(Cell 1, Cell 2): merges two cells into the first one.

tgs.CellSetTerritory(int cellIndex, int territoryIndex): changes the territory of a cell and updates boundaries. Call Redraw() to update the grid afterwards.

tgs.CellToggleRegionSurface(cellIndex, visible, color, refreshGeometry): colorize one cell’s surface with specified color. Use refreshGeometry to ignore cached surfaces (usually you won’t do this).

tgs.CellToggleRegionSurface(cellIndex, visible, color, refreshGeometry, texture): color and texture one cell’s surface with specified color. Use refreshGeometry to ignore cached surfaces (usually you won’t do this). Texture can be scaled, panned and/or rotated adding optional parameters to this function call.

tgs.CellToggleRegionSurface(int cellIndex, bool visible, Color color, bool refreshGeometry, Texture2D texture, Vector2 textureScale, float textureRotation, bool overlay): same but allows to specify a texture scale and rotation and optionally if the colored surface will be shown on top of objects.

tgs.CellHideRegionSurface(int cellIndex): uncolorize/clears one cell’s surface.

tgs.CellHideRegionSurfaces(): uncolorize/clears all cells.

tgs.CellFadeOut(int cellIndex, color, duration, repetitions): colorizes a cell and fades it out for duration in seconds.

tgs.CellFlash(int cellIndex, color, duration, repetitions): flashes a cell from given color to default cell color for duration in seconds.

tgs.CellBlink(int cellIndex, color, duration, repetitions): blinks a cell from current color to a given color and back to original cell color for duration in seconds.

tgs.CellColorTemp(int cellIndex, color, duration): temporarily colors a cell or group of cells.

tgs.CellCancelAnimations(cellIndex): removes any effect on a cell or group of cells.

tgs.CellGetColor(cellIndex): returns current cell’s fill color.

tgs.CellGetTexture(cellIndex): returns current cell’s fill texture.

tgs.CellSetTexture(cellIndex, texture): sets the texture for a cell. Similar to CellToggleRegionSurface.

tgs.CellSetColor(cellIndex, color): sets the color for a cell. Similar to CellToggleRegionSurface.

tgs.CellSetMaterial(cellIndex, material): assigns user defined material to a cell.

tgs.CellGetNormal(cellIndex): returns the terrain normal at the center of the cell.

tgs.CellIsBorder: returns true if the cell sits at the edges of the grid.

tgs.CellIsVisible: returns true if the cell is visible.

tgs.CellSetVisible: makes a cell or group of cells visible or invisible.

tgs.CellSetBorderVisible: makes a cell’s border visible or invisible.

tgs.CellGetGameObject: returns the cell surface gameobject.

tgs.CellScaleSurface: applies a scale to a colored/textured cell surface.

tgs.CellRemove: completely removes a cell from the grid. Call Redraw() to update the grid afterwards.

tgs.CellSetCanCross: specifies if a cell can be part fo a route returned by Pathfinding methods. This method is used to specify blocking cells.

tgs.CellSetGroup: assigns a cell to a group. Groups can be used to use certain cells or not when calling FindPath, CellGetNeigbhours or CellGetLineOfSight. Using groups you can create different kind of blocking cells. See demo scene 12 for an example.

tgs.CellGetGroup: gets the group of a cell.

tgs.CellGetFromGroup: gets all cell indices from a group.

tgs.CellSetSideCrossCost/CellGetSideCrossCost: sets or obtain the crossing cost for a cell and a specific edge with option to apply that cost to any direction (ie. existing or entering the cell through that edge).

tgs.CellSetAllSidesCrossCost: convenient method to quickly assign a crossing cost to a cell regardless of the edge used to travel.

tgs.CellGetConfigurationData: retrieves a string-packed description of the cells properties. Use CellSetConfigurationData to load the configuration.

tgs.CellSetConfigurationData: loads a configuration of cells from a string.

tgs.CellGetSettings: similar to CellGetConfigurationData but returns an array of TGSConfigEntry values (one per cell). A TGSConfigEntry is a struct that contains important attributes about each cell.

tgs.CellSetSettings: similar to CellSetConfigurationData but accepts an array of TGSConfigEntry values.

tgs.CellAddSprite(int cellIndex, Sprite sprite, bool adjustScale): creates a gameobject with a given sprite and positions/scale it to match a given cell.

Territory related

tgs.numTerritoriess: desired number of territories (1-number of cells).

tgs.territories: return a List<Territory> of all territories.

tgs.showTerritories: whether to show or not the territories borders.

tgs.showTerritoriesOuterBorder: whether to show or not the territories perimeter around the grid.

tgs.territoryHighlighted: returns the Territory object for the territory under the mouse cursor (or null).

tgs.territoryHighlightedIndex: returns the index of territory under the mouse cursor (or -1 if none).

tgs.territoryLastClickedIndex: returns the index of last territory clicked.

tgs.territoryHighlightColor: color for the highlight of territories.

tgs.territoryFrontiersColor: color for all territory frontiers.

tgs.territoryDisputedFrontiersColor: color for shared frontiers between two territories.

tgs.territoryFrontiersAlpha: helper method to change only the alpha of territory frontiers.

tgs.colorizeTerritories: whether to fill or not the territories.

tgs.colorizedTerritoriesAlpha: transparency level for colorized territories.

tgs.TerritoryToggleRegionSurface(territoryIndex, visible, color, refreshGeometry): colorize one territory’s surface with specified color. Use refreshGeometry to ignore cached surfaces (usually you won’t do this).

tgs.TerritoryToggleRegionSurface(territoryIndex, visible, color, refreshGeometry, texture): color and texture one territory’s surface with specified color. Use refreshGeometry to ignore cached surfaces (usually you won’t do this). Texture can be scaled, panned and/or rotated adding optional parameters to this function call.

tgs.TerritoryToggleRegionSurface(cellIndex, visible, color, refreshGeometry, texture, textureScale, textureRotation, overlay): same but allows to specify a texture scale and rotation and optionally if the colored surface will be shown on top of objects.

tgs.TerritorySetMaterial(territoryIndex, material): assigns user defined material to a territory.

tgs.TerritoryHideRegionSurface(territoryIndex): uncolorize/clears one territory’s surface.

tgs.TerritoryGetNeighbours(territoryIndex): returns a list of neighbour territories to a specific territory.

tgs.TerritoryGetCells(territoryIndex, regionIndex): returns a list of cells belonging to a territory or any of its regions.

tgs.TerritoryGetAtPosition(position): returns the territory that contains position (in local space coordinates).

tgs.TerritoryGetPosition(territoryIndex): returns the center of the territory in world space.

tgs.TerritoryGetRectWorldSpace(territoryIndex): returns the boundaries of the territory in world space coordinates.

tgs.TerritoryGetVertexCount(territoryIndex): returns the number of points of the territory polygon.

tgs.TerritoryGetVertexPosition(territoryIndex, vertexIndex): returns the position of the specified vertex in world space coordinates.

tgs.TerritoryFadeOut(territoryIndex, color, duration, repetitions): colorizes a territory and fades it out for duration in seconds.

tgs.TerritoryFlash(territoryIndex, color, duration, repetitions): flashes a territory from given color to default territory color for duration in seconds.

tgs.TerritoryBlink(territoryIndex, color, duration, repetitions): blinks a territory from current color to a given color and back to original territory color for duration in seconds.

tgs.TerritoryColorTemp(cellIndex, color, duration): temporarily colors a territory or group of territories.

tgs.TerritoryCancelAnimations(territoryIndex): removes any effect on a territory.

tgs.TerritoryIsVisible(territoryIndex): returns true if territory is visible.

tgs.TerritorySetVisible(territoryIndex): makes a territory visible or invisible.

tgs.TerritorySetBorderVisible: makes a territory’s border visible or invisible.

tgs.TerritorySetFrontierColor(territoryIndex, color): assigns a new color for the frontiers of a given territory.

tgs.CreateTerritories(texture, neutral): generate territories based on distinct colors contained in the provided texture ignoring neutral color.

tgs.TerritorySetNeutral(territoryIndex, neutral): specifies if a given territory should be considered as neutral. Neutral territories do not dispute frontiers.

tgs.TerritoryIsNeutral(territoryIndex): returns true if the given territory is neutral.

tgs.TerritoryGetFrontier(territoryIndex, regionIndex): returns a list of points (Vector2) that form a territory frontier.

tgs.TerritoryGetFrontierCells(territoryIndex, otherTerritoryIndex, ref List<int> cellIndices): returns a list of cells that form a territory frontier. Optionally restrict to frontier with another territory index.

tgs.TerritoryGetGameObject: returns the territory’s surface gameobject.

tgs.TerritoryScaleSurface: applies a scale to a colored/textured territory surface.

tgs.TerritoryDrawFrontier(territoryIndex, adjacentTerritoryIndex, material, color): draws the frontier around the territory specified by territoryIndex. Optional parameters include: adjacentTerritoryIndex (only draw frontier shared by those two territories), a material or a color.

Note: this method returns the gameobject for the newly drawn frontier. You’re responsible of disposing this gameobject or redrawing it since TGS won’t refresh it nor destroy it when changing the grid.

User interaction / Highlighting

tgs.highlightMode: choose between None, Territories or Cells. Defaults to Cells.

tgs.highlightFadeAmount: alpha range for the fading effect of highlighted cells/territories (0-1).

tgs.highlightMinimumTerrainDistance: minimum distance to the terrain to allow highlighting of cells/territories.

tgs.HighlightTerritoryRegion(territoryIndex, refreshGeometry, regionIndex): manually highlights a territory region. RefreshGeometry can be used to force creation of the highlight mesh (usually not required). RegionIndex can be used to highlight a specific region of a territory if it’s split in several zones (usually not required).

tgs.HideTerritoryRegionHighlight(territoryIndex): hides the highlight of the territory.

tgs.HighlightCellRegion(cellIndex, refreshGeometry): manually highlights a cell region.

tgs.HideCellRegionHiglight(cellIndex): hides the highlight of the cell.

tgs.overlayMode: decide whether the highlight is shown always on top or takes into account z-buffer which will make it more fancy and part of the scene.

tgs.localCursorPosition: the current cursor position on the grid (mouse over the grid) in local grid coordinates. Use tgs.transform.TransformPoint(x) method to convert to world space coordinates.

tgs.localCursorLastClickedPosition: the position of the last click on the grid in local grid coordinates. Use tgs.transform.TransformPoint(x) method to convert to world space coordinates.

Path Finding & LOS related

tgs.CellGetSideBlocksLOS(cellIndex, side, blocks): returns whether a cell’s side blocks line of sight.

tgs.CellSetSideBlocksLOS(cellIndex, side, blocks): specify whether a cell’s side blocks line of sight.

tgs.CellSetCanCross: specifies if this cell blocks any path.

tgs.CellSetCrossCost: specifies the cost to enter a cell (defaults to 1).

tgs.CellSetSideCrossCost: specifies the cost to enter or exit a cell through a specific edge.

tgs.FindPath(cellIndexStart, cellIndexEnd): returns a list of cell indices that form the path.

tgs.FindPath(cellIndexStart, cellIndexEnd, out totalCost, maxSearchCost, maxSteps): returns a list of cell indices that form the path and the totalCost for the path. Optionally pass a maxCost and maxSteps (use OnCellCross event to return custom costs for any cell).

tgs.FindPath(cellIndexStart, int cellIndexEnd, List<int> cellIndices, out float totalCost, float maxSearchCost = 0, int maxSteps = 0, int cellGroupMask = -1, CanCrossCheckType canCrossCheckType = CanCrossCheckType.Default, bool ignoreCellCosts = false, bool includeInvisibleCells = true): returns a list of cell indices that form the optimal path between two cells with extra parameters:

  • cellGroupMask: bitwise mask to filter which cells can be included in the path based on their group value (set any cell group value using CellSetGroup method).

  • canCrossCheckType: specifies how “canCross” flag of each cell should be used. This parameter let you include or exclude start or end cells that has canCross disabled. A cell can be set to “block” by using CellSetCanCross method.

  • ignoreCellCosts: ignores any custom cost assigned to a cell.

  • includeInvisibleCells: if hidden cell can be used in the path.

tgs.CellGetLineOfSight(startPosition, endPosition, …): returns true or false if there’s a line of sight from the starting cell to target cell. It also returns the list of cells in the line as well as the world positions.

tgs.CellGetLine(startPosition, endPosition, …): returns a list of cells that form a line between two cells with options.

tgs.CellTestLineOfSight(startIndex, indices, …): removes any cell index from the indices list that are not visible from the given starting cell.

Other useful instance methods

tgs.instance: reference to the actual Terrain Grid System component on the scene.

tgs.HideAll: hides all surfaces and clears the internal cache (cached surfaces are kept in memory).

tgs.ClearAll: hides all surfaces and clears the internal cache (surfaces are destroyed and memory freed, and will need to be generated again if a cell/territory is colored/textured).

tgs.Redraw: forces a redraw of the grid mesh. Optionally set the parameter reuseTerrainData to true to speed up computation if terrain has not changed.

tgs.RedrawCells(List<Cell>): forces a redraw of specific cells. This is faster than redrawing the entire grid when only a subset of cells is required.

tgs.CancelAnimations: similar to CellCancelAnimations or TerritoryCancelAnimations but stops any animation over the grid (flash, blink, fadeout, color temp, etc.).

Other useful static methods

TerrainGridSystem.grids: list that contains all grids in the scene.

TerrainGridSystem.GetGridAt(position): returns the grid that contains a given position.

Events

Note: in order to support multi-grid setups, all events receive the reference to the grid as the first parameter so you always know which grid is triggering the event.

tgs.OnCellEnter: triggered when pointer enters a cell.

tgs.OnCellExit: triggered when pointer exits a cell.

tgs.OnCellMouseDown: triggered when user presses mouse button on a cell.

tgs.OnCellMouseUp: triggered when user releases mouse button on a cell.

tgs.OnCellClick: triggered when user presses and releases the mouse pointer on the same cell.

tgs.OnCellHighlight: triggered when a cell is goint to be highlighted (usually when pointer is over it). A ref parameter allows you to cancel highlight and implement your own coloring system.

tgs.OnCellDragStart: triggered when user starts dragging on a cell.

tgs.OnCellDrag: triggered while user drags.

tgs.OnCellDragEnd: triggered while user released the left button while dragging.

tgs.OnTerritoryEnter: triggered when pointer enters a territory.

tgs.OnTerritoryExit: triggered when pointer exits a territory.

tgs.OnTerritoryMouseDown: triggered when user presses mouse button on a territory.

tgs.OnTerritoryMouseUp: triggered when user releases mouse button on a territory.

tgs.OnTerritoryClick: triggered when user presses and releases mouse button on the same territory.

tgs.OnTerritoryHighlight: triggered when a territory is goint to be highlighted (usually when pointer is over it). A ref parameter allows you to cancel highlight and implement your own coloring system.

tgs.OnPathFindingCrossCell: triggered when path finding algorithm estimates cost to this cell. You can use this event to return extra cost and customize path results.

tgs.OnRectangleSelection: triggered when user completes a rectangle selection. Read “Rectangle Selections” section for details.

tgs.OnRectangleDrag: triggered when user drags a rectangle selection. Read “Rectangle Selections” section for details.

Handling cells and territories

Please, refer to demo scripts included in demo scenes for example of API usage, like selecting, merging and toggling cells visibility, …

Rectangle Selection

Demo scene 20 showcases how to use the OnRectangleSelection event.

Firstly, to enable rectangle selection you must call tgs.enableRectangleSelection = true. At this point, user will be able to click and drag a rectangle. When the user drags a selection, the even OnRectangleDrag fites. And when he/she completes the rectangle selection (by releasing the mouse button), the event OnRectangleSelection is fired:

The following code corresponds to demo scene 20. It allows the user to select a rectangle of cells and color them in red:

using System.Collections.Generic;
using UnityEngine;
using TGS;

public class Demo20 : MonoBehaviour {

    TerrainGridSystem tgs;

    void Start() {
        tgs = TerrainGridSystem.instance;
        tgs.enableRectangleSelection = true;
        tgs.OnRectangleSelection += SelectCells;
        tgs.OnRectangleDrag += HighlightRectangleArea;

        tgs.OnCellClick += (grid, cellIndex, buttonIndex) => PaintCell(cellIndex);
    }

    void PaintCell(int cellIndex) {
        tgs.CellSetColor(cellIndex, Color.red);
    }

    void SelectCells(TerrainGridSystem grid, Vector2 localPosStart, Vector2 localPosEnd) {
        List<int> cells = new List<int>();
        tgs.CellGetInArea(localPosStart, localPosEnd, cells);

        // Hides all surfaces (and clear cache)
        tgs.ClearAll();

        // Color selection
        tgs.CellSetColor(cells, Color.yellow);
    }

    void HighlightRectangleArea(TerrainGridSystem grid, Vector2 localPosStart, Vector2 localPosEnd) {
        List<int> cells = new List<int>();
        tgs.CellGetInArea(localPosStart, localPosEnd, cells);

        // Hides all surfaces (but keep them in cache)
        tgs.HideAll();

        // Color current selection
        tgs.CellSetColor(cells, new Color(0, 0, 1, 0.25f));
    }

}

Custom user data

There are 3 ways you can add custom data to cells and territories:

Option 1

Using the attrib property. Every cell or territory object has an “attrib” property which is a JSON object that can store any number of custom fields.

For example, you coud use:

tgs.cells[10].attrib[“resource”] = “coal”;

This will store the word “coal” associated to the key “resource” of cell with index 10.

Option 2

Using the tag property. Each cell has a “tag” property which is a basic integer. You can use this field for any purpose like storing the id of some other object that’s managed by you.

Option 3

Extending the cell or territory class. Both classes are defined with the C# partial keyword which allows you to add custom fields or methods in another file. The compiler will simply merge the contents of both files when compiling the class. The benefit of adding your custom fields/properties in a different file is that it doesn’t get overwritten when you upgrade to a newer version of the asset.

Back To Top