Table of Contents

Key Concepts

This is a list of the most important concepts in grids, and is important to understand to work with the library effectively.

A grid in the scene

A scene grid is a grid that you can see in your unity scene. It can have one game object per cell (called a tile grid), or can be a single game object such as a mesh (called a mesh grid). You can also have your own presentation.

The scene grid is supported by several classes that makes it "work". This can seem a bit daunting at first, but this is what gives Grids its unique flexibility.

The most important class is the grid data structure - it works like an array, and holds the cell data, and in the case of a tile grid, the game objects that make up the cells.

The grid map is an object that specifies where your cells are in Unity world space. A grid map has two parts: a space map and a round map.

  • The space map represents a distortion of 3D space: it can be a scale, or a shear, or a rotation, or something more complex. The space map determines where cells are, how big they are, and is one way in which hex grids differ from rect grids.
  • The round map determines which chunks of space belongs to each cell. It makes 3D continues space discrete. It is what gives cells their shape; the difference between rect grid and hex grids, but also the difference between hex grids and brick grids.

The grid map combines these two maps, and with that, you can for every grid point know where it is in Unity world space, and for every point in Unity space, which grid point it belongs to.

Grids themselves have shapes; they can be rectangular, or cross-shaped, or hexagonal. (Don't confuse grid shapes with cell shapes!) Grids are constructed from shape objects, and will have the same shape as the one with which it was constructed.

There are two types of shapes: implicit shapes, and explicit shapes.

  • Implicit shapes only supports one function: a Contains method that can check if a grid point is inside the shape. These shapes are used to construct explicit shapes, and are useful in some algorithms.
  • Explicit shapes are implicit shapes that can also produce all their grid points; that is, you can get an enumeration over all points in the shape. Explicit shapes also know their bounds - the interval (1D), rectangle (2D) or bounding box (3D) that contains them. These bounding shapes are themselves implemented as explicit shapes. Because explicit shapes are also implicit shapes, they also supports a Contains method to check whether they contain given grid points.

Grids are explicit shapes that can hold data for each point inside the shape. In this sense, grids work like dictionaries with points as keys and cells as values.

All these classes come together in a grid builder - a component used to build a grid in the scene. And you access the various components using a grid behaviour - a component of your own design where you implement grid logic.

Grids not in the scene

Grids can also be used without a visual representation. These grids are called logic grids, and are used to implement gamelogic. Like scene grids, logic grids are supported by several classes that make them work, but not as many!

Since grids still have shapes, we still need to construct them using shapes. However, we don't need maps, grid builders, or grid behaviours.


Term Definition
Grid Point A grid point is a vector with integer coordinates. Grid points support all the usual vector operations such as addition, subtraction and multiplication with a scalar (which has to be an integer). Grid points can be 2D or 3D. 1D "grid points" are simply integers, and when we use “grid point” when talking about grids of any dimension, we include integers.
Grid A grid is a data structure, similar to an array. Grids can be 1D, 2D, or 3D, and are indexed with @System.Int32, @Gamelogic.Grids2.GridPoint2 or @Gamelogic.Grids2.GridPoint3. Grids can contain any data (integers, game objects, other grids). We usually talk about the data in the grid as its cells – there is one cell for each grid point that is inside the grid. You can also view grids as dictionaries. The grid points are the keys, and the cells are the values.
Shape Grids have a “shape” – they can be rectangular or cross-shaped or any other collection of cells. Shapes are also useful for other purposes, such as in many grid algorithms. You can think of a shape as a set of grid points.
Implicit Shape An implicit shape is an object that can tell whether a grid point is inside the shape or not. Implicit shapes can be 1D, 2D, or 3D. Both explicit shapes and grids themselves are also implicit shapes, so methods that take implicit shapes as parameters can also take explicit shapes and grids.
Explicit Shape An explicit shape is an object that is an implicit shape, and in addition, can produce the points (as an IEnumerable) inside it and give its bounds as a GridInterval (1D), GridRect (2D), or GridBounds (3D). These three objects are themselves explicit shapes. Grids implement all the methods of explicit shapes, so another way to view grids is that they are explicit shapes with a piece of data associated with each grid point inside the shape. Methods that take explicit shapes as parameters, can also take grids in those parameters.
Forward Map A forward map is an object that converts one thing to another. It is similar to Func{T, U}, but does its calculation through a method called Forward.
Reverse Map A reverse map is also an object that converts one thing to another, but represents an inverse function. It is therefore similar to @System.Func`2, but does its calculation through a method called Reverse.
Map A map is both a forward and reverse function. It can convert one thing to another, and can also covert it back. They are almost like invertible mathematical functions, but they may not necessarily be completely invertible. Maps are internally used for converting between Unity world coordinates to grid coordinates.
Space Map A space map is a map that operates on @UnityEngine.Vector3. It can, for example, represent a translation, or rotation, or something more interesting like a polar transform.
Round Map A round map is a map that converts a vector (or float) to a grid point (or int). It basically takes continuous space, and makes it discrete. Rounding (as implemented by @System.Mathf.Round) is one type of operation that can be represented with a round map.
Grid Map A grid map is the functional composition of a space map and a round map. That's a complicated way of saying the maps are applied in sequence. The combination of the space and round map is used to do a conversion from Unity world space and grid space (and vice versa). The GridMap class supports methods such us WorldToGrid so that it easier to get the conversion you want. You should seldom need to work with space maps and round maps individually.
Grid Builder As mentioned before, grids can have any type of data, but you usually want some concrete representation of your grid in the game engine. A grid builder is a component that builds such a concrete grid in the editor.
Tile Grid A tile grid is a grid where each cell is a separate game object (typically a sprite or a mesh).
Mesh Grid A mesh grid is a grid that is a single mesh. There is a grid builder for each type of grid.
Grid Behaviour A grid behaviour is a MonoBehaviour (in fact, a @Gamelogic.Grids2.GLMonoBehaviour) that gives you convenient access to the grid, the grid map, and the grid builder.