Tilesets - voxraygames/worldbuilding GitHub Wiki
A tileset is a set of 6 (or sometimes 16) voxel models or brushes that the game will automatically place for you fitting to neighboring objects of the same tileset.
For example, here are two tilesets, an orange and a green one, made as simple voxel models in MagicaVoxel (you can find these in mats/base/tilesets/multi_tileset_example.vox):
When using any of these in game in the editor, the game will automatically pick the right model from the set of 6, at the correct rotation, to fit:
The best part is that this works even in-game, if a player destroys one of these blocks, the remaining blocks will adapt to the new shape.
Tileset metadata
Notice that the orange green are separate, which is because they are different tilesets. A tileset is determined by the tileset metadata, for example { tileset: "my_green_tileset1" } (for more on model metadata, see Model Metadata). You want to make sure that all 6 different configurations have the same tileset name. You can see how this is specified for the example tiles above in mats/base/tilesets/multi_tileset_example.json.
Model naming
The names of the models (either the filename, or if all in a single multi .vox file, the names of models in there) should end in the given index (which corresponds to the 6 pictures above):
_0: none of the surrounding tiles match this one, i.e. a tile that has clearly marked borders/edges on all sides._1: only 1 side is the same, i.e. a peninsula looking tile._2: 2 sides the same, adjacent, i.e. a corner._3: 3 sides the same, i.e. an object on the edge of a larger shape._4: 4 sides the same, i.e. an object in the center._5: 2 sides the same, but on opposite sides, i.e. the middle of a line.
Brushes
Rather than voxel models, you can also make these out of brushes. To do so, first create the 6 brushes in a world, then save them out into individual brush files, and then add .json metadata to these files as per the above (you can see many examples of such brush files in brush/3x3 for example, and a world where they were created in worlds/dev/base_tileset.world). Then, when these brushes are loaded into a new world (and thus the new metadata takes effect) you can build with these brushes and see them auto-adapt like above.
Here's an example of tileset brushes used for landscape in-game:
Variants
Since having just one object for each of the 6 configurations may lead to repetitive looking tiling, you can also specify variants for each. This is done by yet another number counter in the filename, e.g. brush/myset/mybrush_0_1.mvfb says this is configuration 1 (from the above list), variant 0. You can have as many variants as you want, counting up from 0, and the game will automatically load them all and pick randomly from each placement.
16 configurations.
The above tilesets have 6 configurations because they auto-rotate where possible, so you don't have to create 4 copies of some of them. By using rotation, the 6 configurations are used in 16 possible cases total (because we have 4 sides, each side can either be the same tileset object or not, giving 4 binary choices, resulting in 2^4 = 16).
But that assumes the design of the tile works with rotation. If you want to create a tileset where the tiles really shouldn't rotate (because the design includes a feature, like a wood-grain, that is intended to always go in the same direction), you can optionally specify 16 configurations directly instead of 6.
This is of course a lot more work, and uses more memory, so use this only when needed.
To do this, the tileset name must include the string 16, e.g. { tileset: "my_green_tileset16_1" }. The game will now know to load 16 voxel models or brushes (named all the way up to _15), and when placing them, will use these 16 configurations directly with no rotation.
The 16 configurations look like this:
(You can find these example tiles also in mats/base/tilesets/multi_tileset_example.vox, they were created as an example of a design that does not rotate, not to look pretty).
The ordering in terms of the indices is:
0 1 2 3
4 5 6 7
8 9 10 11
12 13 14 15
Be sure in MagicaVoxel that you have the default orientation, which is the X axis (red) going towards the right, and Y (green) up. Also, if you make some of these by rotating other models in MagicaVoxel, be sure to rotate the voxels (done by going into voxel edit mode, then using rotate around Z), not rotating the object (which you get by using rotate in the "scene" mode).