Advanced Tutorials

Voxel meshes and templates, when to use each


Crayta provides several tools to help you build large and interesting worlds for your games.

One of the most powerful features provided is the ability to use voxels in various sizes and materials for terrain, structures, objects, etc. At the same time Crayta allows you to organize parts of your scene as reusable components called templates. Templates can be easily duplicated multiple times, and any changes made to the original will automatically propagate to all instances.

In this tutorial we will explore how to use voxel meshes and templates and when to use each.

In Unity doing world building involves using polygon assets called meshes/models that get placed in the scene to assemble a world. Quite often a terrain surface is used in addition, painted using a number of brushes to help you create realistic worlds. 

There isn’t any notion of voxel building in Unity so usually a large number of assets have to be prepared in advance for all parts of the scene to be put together in the Unity editor. The only thing that might resemble Crayta voxel building is the ProBuilder Unity extension that can do part of the scene polygon modelling inside the Unity editor.

Crayta templates on the other hand are very much like Unity prefabs.

Voxel Mesh

Voxel building in Crayta involves adding and editing voxel meshes. Voxel meshes are groups of voxels that contain from a handful (e.g. a simple rock) to millions of voxels (e.g. a complex structure).

When creating a new project a voxel mesh is automatically added, containing a simple terrain surface to start building on.

The voxel mesh is saved to a voxel mesh asset, that can be found in the Library under the Voxel Meshes category. You can create multiple voxel meshes from a single voxel mesh asset simply by dragging and dropping it in your world:

Editing any of these terrain surfaces using the voxel tools will result in changes rendering in all terrain surfaces. This initially can be confusing, the reason is simply because all the terrain surfaces reference the same voxel mesh asset. So any change to that voxel mesh asset is being saved to that asset and in turn updates all voxel meshes referencing that asset.

You can change that behaviour for any voxel mesh by clicking the Create a unique copy of this asset button in the voxel mesh entity properties. That will create a new voxel mesh asset from this voxel mesh and assign it to it. From there and on any change on this voxel mesh will update the new voxel mesh asset created.

From the Library -> Voxel Meshes window you can also create new voxel mesh assets to be used to spawn voxel meshes in the world.


Templates in Crayta is a powerful system that allows you to create reusable groups of entities that can be easily spawned anywhere in your world. At the same time retaining a link to the original template allowing you to make changes at any point to your template and have the changes propagate automatically to all the template instances.

A template can contain any kind of entities and components. You can use it for several things:

  • Collectables
  • Repeating structures
  • User template
  • Player templates
  • Effects etc.

You can easily create a new template by using an entity that already exists in your world. Select it and then click Template -> Create New Template…

This will create a new Template with this entity at the root of the template. From there you can easily add children entities, components etc.

You may spawn instances of a template by using the Library → Templates window and drag/drop your selected templates into the world. Spawned entities will show the full hierarchy of the template in the World Tree editor window and will contain a toolbar with the following template actions:

  • Edit template, will open this template for editing.
  • Copy to template, any changes made to this instance with this button will be saved back to the template and propagate to all template instances.
  • Break template link, this will severe the connection to the template and make this entity a normal World entity. You can do further changes to the entity without having the template override anything.

Voxel Meshes and Templates

Voxel meshes should be used when doing world building and you require parts of your world to be reused. Parts that don’t require any special functionality like scripting or lighting etc.

When those parts require additional components to be added and spawned on each instance a template should be used. Voxel meshes can be added to template entities much like any other component (script, sound, effect etc).

The only thing requiring special attention regarding voxel meshes in templates is the use of the Break template link button. This will break the link to the template, allowing the entity to be edited further without affecting the template. This holds true for all changes except editing voxel meshes attached to this entity or to its children.

This happens because, as we stated above, voxel meshes always reference voxel mesh assets. Breaking the link to a template will keep a reference to the same voxel mesh asset used by the template. So editing the voxel mesh on an entity that has broken the template link will have the, potentially undesirable, effect of editing the voxel mesh asset referenced by the voxel meshes in the template instances.

To stop this behavior, the solution is simple using the Create a unique copy of this asset button on those voxel meshes to create new voxel mesh assets that aren’t referenced by this template.