Space Maps

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 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 boil 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 to 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.

So 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:

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.

Add one output node.

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.

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)

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?

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).

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 Use to add a Z-offset to coordinates based on the grey value of a color in a given texture.

Can I create my own space map nodes?

Yes! Here is how:

Make a new C# file, and in it define a class that extends from ProjectSpaceMapNode<Vector3, Vector3>.

Override the Transform method. It takes a IMap<Vector3, Vector3>, and returns a IMap<Vector3, Vector3>.

In the body of the Transform method, create a new map (use the state methods in the Map class).

If the input is null, return the map, otherwise compose the input with the new map and return the result.

Add the SpaceMapNode attribute to the class. The attribute takes two arguments – a string and an integer. 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”.

Once your project has recompiled in Unity, the new node will be available in the node editor.