Currently BURRTOOLS handles cubic grids, grids that use prisms with a base shape that is an equilateral triangle tightly packed spheres and 2 grids based on different tetrahedrons: the rhombic and the tetra-octa grid. The spacegrid is used for all shapes within a puzzle, so you cannot have one shape made out of cubes together with one using another grid. The spacegrid needs to be set before you start with the puzzle. It cannot be changed later on In some situations though it is possible to losslessly convert the complete puzzle (→ Converting Puzzles). The gridtype is selected when you use the New option.
The following chapters will explain some details regarding some of the available grids.
Actually there is just one important thing to know about the sphere grid: It has a relatively severe limitation. This limitation makes it impossible to properly handle shapes with disconnected units.
I don't want to go into too much detail here but the limitation comes from the fact that BURRTOOLS can only handle a finite number of symmetries.
Internally BURRTOOLS has a list of all possible transformation matrices that might transform a shape back onto itself, e.g the shape looks identical to the original untransformed shape. This list of transformations needs to be finite (and as small as possible, because longer lists make the program slower).
Unfortunately the sphere grid has an infinite number of transformations that might transform the shape onto itself. To display the problem let's assume we use the sphere grid in just 2 dimensions and use a square arrangement of spheres. We place one sphere at the origin and add 2 more spheres so that both of those additional spheres have the same distance from the sphere in the origin. If we now place one of the 2 spheres at coordinate (a;a) and the other at (a;-a) then both of them will have the same distance from the sphere in the origin.
The 3 spheres form a triangle with a right angle at the origin. This triangle has a symmetry axis which is a horizontal line from the origin. That means a rotation of 180 degrees around the axis y=0 will result in an identical looking triangle with the outer spheres swapped. This is one of the transformations mentioned above that BURRTOOLS has to check. (See Sphere Grid Problem left image)
If we now move the 2 outer spheres by one unit each. One to the right and the other down. Which results in those spheres at positions (a+1;a-1) and (a-1;-a-1). We again get a rectangular triangle of a slightly different size. This triangle again has a symmetry axis but this axis is slightly rotated clock wise. This would be a different transformation BURRTOOLS has to handle. (See Sphere Grid Problem right image)
You can imagine that there is an infinite number of possibilities to place the spheres, resulting in an infinite number of possible rotation axis and thus an infinite number of transformation matrices.
BURRTOOLS can only handle a finite number of possibilities. I have limited those to the possibilities that you can encounter when you use only completely connected shapes. This problem only occurs because the sphere itself has an infinite number of possible rotation axes.
Connected in this context means that that it is possible to get from each sphere to each other sphere by just jumping from one sphere to the 12 possible neighbours and then further on via the neighbours.
Some of the unconnected shapes might be possible as well but there is no warrant, so if you want to be sure stay with "proper" sphere shapes.
This grid allows the modelling puzzles that have diagonally cut cubes, but more importantly it allows modelling a lot of rhombic dodecahedral based puzzles like Stewart Coffin designs.
The rhombic grid is much more intricate compared to basic grids like the cube grid. So please read this part of the manual thoroughly to avoid problems.
Much of the text below only talks about the rhombic based puzzles and indeed puzzles that just have diagonally cut cubes don't suffer the complexity but I still suggest to read on because it might shed some light on some of the not so obvious things that the program does.
The basic unit of the rhombic grid is a tetrahedron that results when cutting the cube along the 6 45 degree diagonal planes. The result are 24 identical but irregular tetrahedra. To see what I mean have a look at the image below. It contains 2 different versions of the cut up cube. One where the tetrahedron assemble the complete cube and another exploded version of the same cube. To make distinction of the tetrahedra easier I have colourized the tetrahedra layer by layer, always 4 with the same colour. Additionally I made the voxels variable in the first cube so that is is easier to see what shapes they have.
Those variable voxels are a nice trick to see the inner structure of shapes, when the bevel edges are not enough.
The next important thing to know is how are these 24 tetrahedra managed. The picture below shows how it is done.
It can be seen that the 25 voxels of the rhombic grid are mapped onto a 5x5x5 cube of little cubes. Each tetrahedron is represented by exactly one cube.
Between those 24 cubes are 125-24 = 101 empty cubes that don't belong anywhere. It you ever do something manually and modify the grid directly you must take care to always leave those cubes empty or BURRTOOLS will crash. But as long as you only use the program it will take care that that doesn't happen.
Now given those basic units how to we build a rhombic dodecahedron from it?
The basic building blocks are basic units that Stewart Coffin used in his puzzle books to describe the shape of the pieces for his puzzles. This was necessary because of the limited information that can be given using 2 dimensional drawings. But those blocks are still useful to gain an understanding in the mechanics of the rhombic grid.
So let's start with the Rhombic Dodecahedron (RD). From that shape we can derive all other building blocks.
The rhombic dodecahedron is best built starting with a cube of size 2x2x2. That cube can be easily made my creating a 1x1x1 cube (24 voxels) and scaling is up by 2. Now "cut" away the outer corners of the cube so that all that is left is a diamond shaped square rod. Repeat the same process for the other axes. (More details in the RD-Tutorial)
Don't create the dodecahedron by adding 4 pyramids to the 6 sides of the 1x1x1 sized cube. Why that doesn't work is explained below.
If you rotate the rhombic dodecahedron so that you can see only a square can be seen and then remove 3 quarters of the square so that you get a square with halve of the length you will get a six-sided centre block. 6 Pieces of this block will nearly always be the centre of the puzzle. Other blocks will be "glued" to the faces of those 6 six-sided centre blocks.
Cutting up the block further will result in the other blocks like the 2 prism blocks, square octahedron, square pyramid, tetrahedral building block.
Have a look at the image blow. You can see 2 connected identical shapes. They are 2 diagonal star pieces. On the right image the voxels are also made variable to make the inner structure of the shapes visible. What can be seen is that both shapes do have the same outer appearance but a completely different inner structure.
This can only result in problems and it sure does. All building blocks down to the tetrahedral building block can be made in 2 different ways. BURRTOOLS will not be able to match those 2 ways to build a shape. If you make a problem with 2 shapes that are made those 2 different ways and choose one to be the piece and one to be the result you will get no solutions.
This all sounds like a severe problem but luckily it can be solved in a very simple way by scaling all shapes up by 2. The program will then make sure that all shapes are build the same way.
So keep in mind: When something doesn't work as expected or to make a final check of the results scale up by two and check again.
This grid is, just like the rhombic grid, a grid purely made out of tetrahedrons. But here we have 2 different kind of of them. One regular and 4 irregular forming together a cube. The 4 irregular tetrahedrons can be assembled into an octahedron. They have one side with an equilateral triangle and 3 sides that are a diagonally cut square. You can see one of those cubes in an exploded view in image Exploded Tetrahedral Octahedral view. In that image you can see the regular tetrahedron red in the middle and the other blue surrounding it.
There are 2 ways to align the cube assembly of the regular and the 4 irregular tetrahedrons in space. One is a rotation of the other. These 2 possible cubes fill the space of this grid in a checkerboard pattern.
Internally this grid is, again just like the rhombic grid, represented by the cube grid. Each cube in the tetra-octa grid uses a 3x3x3 cube in the cube grid. The central regular tetrahedron occupies the central cube while the 4 irregular cubes are placed in the diagonally opposite corners of the cube (see Figure Tetra-Octa Grid). In the image the red cube represents the regular tetrahedron while the blue cubes represent the other parts.
And just like the rhombic grid this grid also has a problem that might require upscaling in certain situations, so keep that in mind.