Rather than have every possible voxel block be its own "material" (which would hard to use, as we'll end up with thousands, and then ensuring you have the right materials to build anything would be a crazy puzzle), we have the concept of "canonical" materials.

Every voxel block maps to such a canonical material (when e.g. you destroy an object), and likewise, when you craft a more complex object, you can use these canonical materials to obtain something consisting of more specific voxel blocks as defined by the model.

• mats/canonical contains the canonical materials, so here we find wood.vox etc.
  • See Material List for a full list of materials.
• Voxels files can indicate the material they are made out of:
  • By naming the file such that it starts with the material name, for example mats/building/wood_door.vox.
  • By specifying the material in a metadata .json file, see Model Metadata.
  • If a .vox file contains multiple models (its name starts with multi_), the material can similarly be prefixed to the node name inside MagicaVoxel.
• the engine assigns materials automatically based on this, and a destroyed wood_door causes wood to be placed in the inventory.
• any .vox loaded that does not have a canonical material specified will get the default garbage type assigned which is not used for constructing anything.. this should be avoided.
• if wood_door.vox contains metal bracing, we will optionally allow it to be specified in wood_door.json which blocks are metal. This is only needed if 2 materials are used in a single .vox file, instead, if the 2 material parts are in separate .vox files and then joined into a brush in-game, then this distinction is preserved automatically. See Model Metadata on how to specify this.
• A new material can be introduced by putting an appropriate model in mats/canonical (and a brush in brush/canonical_piles) and then using the same name in model names. See here for a full list: Material List
• Deprecated: You may find filenames, or node names that have a 4 in them, like wood_4_door.vox. This used to be the way to specify the number of rotations required. Because the vast majority of .vox files need 4, 4 rotations is now the DEFAULT, meaning you don't need to specify it anymore. It doesn't hurt having it in the name, and you shouldn't go remove it from old names.

In MagicaVoxel, create a scene that contains multiple voxel blocks you want to use. Make sure for each of them you go into the right-side Outline tab, and for each model in the scene, right click on the default name that says <vox> and replace it with a name that conforms to the above rules, e.g. wood_door.

Now save the file itself with a name that starts with multi_, e.g. mats/buildings/multi_buildingkit2.vox. In the in-engine editor, load this voxel file, and it will instead of just 1 load all the individual models into your inventory, that you can use as normal to build things.

If a map or brush file refers to one such model, it will always load all of them, so best used for models that are indeed used together.

On the technical side: loading such a file will produce multiple Generators, each with a name like mats/buildings/multi_buildingkit2:wood_door. A reference to such a name will cause all of them to be loaded, so future references just resolve without loading.

As with the filenames above, once you set these model names and they are referred to in map or brush files, renaming them will make them not load anymore.

Not to be confused with skeletal animation for the characters, these are simple animations where a voxel model in the world alternates between voxel models to show simple movement, like vegetation waving or fire flickering.

ANY .vox file that contains multiple models and does NOT have the multi_ tag discussed above is regarded by the engine as animated. Not using an animated_ prefix is done on purpose such that it is very easy to make single model files animated later without changing the name. It does risk that this happens by accident, in which case you'll either see an unintended animation in-game, or an error stating not all animation frames are the same size.

Now that we have the feature, animations are super cheap, meaning they don't render any slower than non-animated models, so artists should be encouraged to use this feature where-ever appropriate. In particular, it is even still cheap if there are thousands of instances of an animated model in the scene. The only real cost is of course the extra frames of voxel data, but that should be ok especially for small models.

Currently only 2, 3 or 4 frames supported!

Caveat: it is currently expected that all frames are the same in terms of which blocks are fully empty vs have some voxels in them. That should generally be the case for most animated models, but if this turns out problematic it can be fixed, albeit at some cost.

It is very common to want additional colored variants of a voxel file, which typically results in duplicated data, which is not great for disk space, loading times, and GPU memory usage.

We have a system whereby a .vox files containing only a palette can reuse the objects of another file. These files can even be multi files or animated files discussed above.

To make this work, for any foo.vox, save a copy of this file as e.g. foo.1.pal.vox where you a) first change the palette so the contained objects look different, then b) delete ALL the contained objects. This results in a file that contains only palette and material data (e.g. if in the original file a palette entry was emissive, that is preserved here as well).

When the engine loads foo.1.pal.vox, it knows how to also refer to foo.vox for the actual voxel data, substituting the palette and materials for all contained models. You can also refer to sub-objects like above, so multi_foo.1.pal:sub actually refers to multi_foo:sub since the palette files contains no models at all!

The .pal is required to recognize these palette remappings, and the 1 is called the id, and is just to differentiate if there are multiple such files. This currently doesn't need to be a number but some use cases may require it.

Additionally, if you wish to provide the same palette remapping for all files in a directory, you can save such a file as .1.pal.vox in the directory. Then for any X.vox in that dir, you can refer to X.1.pal.vox and if it doesn't exist will load the .1.pal.vox file to do the remapping.

Metadata: Will try to load foo.1.pal.json first, if that doesn't exist then foo.json, then .json