Constructing Grids

[info]This tutorial explains how to construct a grid in code. If you want to setup grids in the editor instead, see Working with grids in the editor.[/info]

Each grid type has several static functions defined with which you can construct grids of various shapes.

There are also mechanisms for defining your own shapes.

Shape Construction Using Shape Builder Functions

The first method is to transform and combine existing shapes. Here is an example of how it looks:

PointyHexGrid grid = PointyHexGrid
.BeginShape()
  .FatRectangle(2, 11)
  .Translate(6, -4)
  .Union()
  .FatRectangle(8,3)
  .Translate(-3, -1)
.EndShape();

Let’s take this example step by step and see how the resulting shape is formed.

PointyHexGrid grid = PointyHexGrid
.BeginShape()
  .FatRectangle(2, 11)
.EndShape();

This creates a 2×11 fat rectangle. Notice the origin is in the bottom left corner; this is the default position for fat rectangles.

PointyHexGrid grid = PointyHexGrid
.BeginShape()
  .FatRectangle(2, 11)
  .Translate(6, -4)
.EndShape();

The next line translates this shape. Note that the coordinates change, but the actual position of the grid in space may not change (this depends on the map you use). You can now see the bottom left corner has coordinates (6, -4). This corresponds to our translation.

PointyHexGrid grid = PointyHexGrid
.BeginShape()
  .FatRectangle(2, 11)
  .Translate(6, -4)
  .Union()
  .FatRectangle(8,3)
.EndShape();

The Union operator must be followed by a shape operator. It combines the shape built before to the shape that immediately follows the union operator. In this case, we combine it with another fat rectangle, this time with dimensions 8×3. As before, the new fat rectangle’s bottom left corner coordinate is (0, 0).

PointyHexGrid grid = PointyHexGrid
.BeginShape()
  .FatRectangle(2, 11)
  .Translate(6, -4)
  .Union()
  .FatRectangle(8,3)
  .Translate(-3, -1)
.EndShape();

The final line translates the entire shape by the given amount. This translation puts the origin at the center of the cross. As before, the bottom-left corner of the newest fat rectangle is now at coordinates (-3, -1), which corresponds to our translation.

There are three operators to combine shapes:

• Union: The resulting shape has the cells contained by either shapes.
• Intersection: The resulting shape has the cells contained in both shapes.
• Difference: The resulting shape has the cells contained in the first shape that are not in the second shape.
• Symmetric Difference: The resulting shape has the cells contained in the first shape and second shape that are not in both.

Translate is the only transformation operator provided.

Shape Construction Using Membership Functions

The second method allows you to specify a function that tests whether a cell is in your grid or not. You can do this by using the constructor of the grid. You will also need to specify the dimensions of the storage rectangle, and a possible offset.

The first step is to determine what the storage rectangle is for your shape. For hex grids, it’s a staggered rectangle the contains the shape. You will need to offset the grid, so that the bottom left corner is the origin. Let’s see how this works. We will define our own hexagon function with sides of length three. The membership function looks like this:

private static void IsInsideHexagon(PointyHexPoint point)
{
  return point.Magnitude < 3;
}

The image below shows the hexagon in its storage rect, and the coordinates of the bottom left corner that we need to use for the offset.

With this information, we can now construct the grid as follows:

PointyHexPoint offset = new PointyHexPoint(-1, -2);

PointyHexGrid grid = 
   new PointyHexGrid(5, 5, x => IsInsideHexagon(x + offset), offset);