What are space maps?

Space maps are objects that transform 3D space in some way; they scale, rotate, twist, or otherwise transform 3D vectors. Mathematically, a space map is a function from Vector3 to Vector3. Space maps can be used in reverse as well; so if you apply a space map to a set of points, you can reverse the operation and recover the original points (although not always completely).

Where is space maps used in Grids 2?

Ultimately, a grid is a subdivision of space into discrete cells. The simplest way to divide space into discrete cells is to say a point (x, y) belongs to the grid point (round(x), round(y)). This gives us a square grid, with cells exactly one unit wide and tall.

• Space maps allow us to make square grids with cells of any dimension.
• Space maps allow us to turn square grids into diamond grids (with a 45-degree rotation), isometric grids (with a rotation and non-uniform scale) and non-square rectangular grids (with a non-uniform scale).
• Space maps allows us to turn square grids into polar grids (using a polar transform).
• Space maps allow us to turn square grids into hex grids (with a shear) provided we also use a special "hex round" operation instead of the simple round described above.
• Space maps allows us to freely distort our grids; for example, to apply a height map, or put the grid on the surface of a torus, or to turn the grid into a spiral.

This all boils down to the following: space maps are used by grid builders to know where your cells are in Unity world space.

Why are there not separate maps for 1D, 2D and 3D?

All space maps in Grids 2 are 3D, even ones that are probably only useful for 2D or 1D grids. The short answer is that it simplifies the design of space maps and how they are used significantly. (Our first attempt at space maps used separate maps for different dimensions; it was extremely messy, and too daunting to complete).

In the examples above, we talked about space maps as if they are can be 2D – those maps are 3D maps that don’t change the z coordinate. A map that changes a rect grid into a hex grid is really a map that changes a cube grid into stacks of hex grids.

What does the space map node editor do exactly?

It allows us to build a space map. You can do the same in code, but it is more convenient to do it interactively in the editor. Grid builders use these space maps to build grids, but you can also use them for other purposes (for example, to build meshes, to animate particles, or even for color transforms).

How do I use the node editor?

To make a new space map graph, you can select Space Map Graph from Assets | Create | Grids in the menu or context menu in the project window. To edit the graph, select it, and click on the Edit button in the inspector. To build the space map graph, follow these steps:

1. Add the nodes you need to make the space map you require, and set their fields to the correct values. To remove a node, click on the “Remove” button on the node. To remove all nodes, click the “Clear” button at the top of the node editor tool bar.
2. Add one output node.
3. Link them in sequence, with the output node at the end of the sequence. To link the output of node A to the input of node B, click on the “Add link” button on node A, and click on node B. To remove a link, click on the red dot on the link.
4. In complicated graphs, you may want to rename the nodes so it is easier to know what is going on. You can do this by clicking on the node name and typing a new name. (Since Grids 2.1)
5. While tweaking the node graph, it may be useful to skip over a node temporarily. You can do this by clicking on the "Disable" button. This will make the node simply route its input to its output without processing. (Since Grids 2.1)

What does the Recompute button do?

It lets all nodes recompute and save values for internal use. This is specifically designed for nodes with a random element, to allow nodes to select new random values. In general, you don’t want these to be recomputed every time the map is accessed, otherwise it will give you different results each time you query the grid. Currently, all nodes are deterministic, so this feature is not used. We may introduce random nodes in the future, or you may want to add your own random nodes.

What do all the nodes do exactly?

Heading	Description
Rect	This used to be the starting point of all rect-based maps and is the identity map (it leaves Vector3 unchanged). However, we changed nodes to make this unnecessary (all nodes without inputs operate as if they have the identity map as input).
Diamond	This makes a rect grid into a diamond grid (a square grid rotated by 45 degrees).
Isometric	This makes a rect grid into an isometric grid (where the angles between the axes are 60 degrees).
Pointy Hex and Flat Hex	This changes a rect grid into a hex grid (either pointy or flat). This space map is usually combined with the hex round map.
Translate	Used to translate points.
Scale	Used to scale points.
Rotate	Used to rotate points around the origin.
Permute Coordinates	Used to change the order of coordinates. For example, when selecting XZY, the z and y coordinates are swapped.This is useful, for example, for changing a grid in the XY plane to one in the XZ plane.
General Matrix	Used for arbitrary linear transforms. To work correctly, the matrix should be invertible.
Polar XY Map	Used to warp points around a circle. The point `(X, Y, Z)` is transformed to the point `(r * cos(f * X * 2 *pi), r * sin(f * X * 2 *pi), Z)`, where `r` is the radius of the node, and `f` is the frequency.
Twirl XY	This rotates points an amount proportional to their distance from the origin.
Height Map	Used to add a Z-offset to coordinates based on the gray value of a color in a given texture.

Can I create my own space map nodes?

Yes! Here is how:

1. Make a new C# file, and in it define a class that extends from ProjectSpaceMapNode<TInput, TOutput>.
2. Override the Transform method. It takes a IMap<Vector3, Vector3>, and returns a IMap<Vector3, Vector3>.
3. In the body of the Transform method, create a new map (use the state methods in the Map class).
4. If the input is null, return the map, otherwise compose the input with the new map and return the result.
5. Add the SpaceMapNode attribute to the class. The attribute takes two arguments – a string and an integer.
6. The string is the name that will be used for the node’s button in the graph editor. The integer should be 3 (it's for the number of dimensions, but remember all maps are 3D). To have the map appear in a group, give it a name like this: groupName/nodeName.
7. Once your project has recompiled in Unity, the new node will be available in the node editor.