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 other game engines like UE4 or Unity the world creation usually involves using polygon assets called meshes or models that get placed in the scene to assemble a world. Quite often a terrain or landscape 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 UE4 or Unity so usually a large number of assets have to be prepared in advance in a separate 3d package for all parts of the scene to be put together in the editor. The only thing that might resemble Crayta voxel building is the BSP editor in UE4 or ProBuilder Unity extension that can do part of the scene polygon modelling inside the editor.

Crayta templates on the other hand are very much like UE4 Actor Blueprints or 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 terrain voxel always appears by default when you make a new game.

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:

Here I have added three new instances of the Box Voxel mesh.

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.

By editing one box, the red material appears on the others as well.

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.

By making this a unique mesh, you can see that the change only applies to the one box.

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:

  • A specific group of meshes, sounds, effects to make an object or set of objects that can be reused.
  • Entities that contain scripts and are reusable in some way or spawned e.g. doors and projectiles.
  • Player characters, as most of the time you would want them to behave in the same way across all instances.
Templates can be used to group several entities that make up a reusable object in your game.

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 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 the parent entity or to its children.

This happens because voxel meshes are created as instances, and will share any changes with the base Voxel Mesh you originally created. So, editing the voxel mesh on any entity that has a broken template link, will have potentially undesirable effects 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.