Skip to end of metadata
Go to start of metadata

Voxel Objects have been deprecated in CRYENGINE 3.5 and beyond.


Voxel Technology allows you to create complex 3 dimensional organic meshes in the editor. It is exposed in the editor through the use of Voxel Objects.

Every Voxel Object has an internal 3D grid of voxels (usually 32x32x32 elements). Every element contains information such as if the unit is full or empty, what surface type is being used and what the base color is.

This array is used as input for the mesh generator. During editing the designer modifies an array of voxels and every change causes re-generation of mesh so the designer receives immediate visual feedback. Voxel Objects can be used in both outdoor and indoor situations.

After completing this tutorial, you will be able to create an overhanging cliff and a cave using voxel technology.

Creating a Cliff with an Overhang

Voxel Objects can be used together with the heightmap to improve the look of the terrain. It is possible to model entire terrain purely using Voxel Objects, but it is much more efficient in memory usage and rendering speed not to.

It's best practice to model most of the terrain with a heightmap, and then use Voxel Objects to add nice features to it.

Setting Up the Voxel Area

To start, it is useful to turn on the visual display of terrain sectors grid by typing e_TerrainBBoxes 1 into the console. This will cause blue bounding boxes depicting the terrain sectors to appear in the perspective viewport.

Your first step is to create a cliff. Create a hill that looks like the one in the next image.

To create a seamless integration between the Voxel Object and the heightmap, you need to align the Voxel Object to the heightmap's grid sectors in the X and Y position.

The simplest way to do this is to activate Snap to grid before placing the Voxel Object. The size of the grid should be set to 64 meters, which is the size of a terrain sector.

Now, go to the RollupBar and select Misc and then VoxelObject, and drag a new Voxel Object into the level.

Initially, the Voxel Object will be empty and you will see only its empty, red box helper object.


Now, make the Voxel Object render the terrain surface, instead of the heightmap engine. Select the Voxel Object and activate the LinkToTerrain checkbox in the VoxelObject parameters.

Visually, there should be no difference apart from the blinking of the currently selected Voxel Object.

Technical information

The LinkToTerrain option does not copy the heightmap data into the voxel array. It just enables the usage of the heightmap during Voxel Object mesh generation. This way, you can still use the heightmap editor and layer painter in the voxelized area. Copying of heightmap data into a Voxel Object is also possible, and and is described in the next example.

VoxelObject Params




Shows which material is currently assigned to it.

Minimal Spec

Used for setting in which hardware configuration the entity is rendered or not, not recommend to be changed for river tool, as rivers should be rendered on all specs.


Specifies if the voxel should not be rendered in indoor visarea or not.


Turns the realtime shadow maps for the voxel object on/off


Specifies if the voxel geometry should be used as an occluder to hide geometry behind it.


Turns the RAM lighting on/off


Changes the distance at which certain LODs (level of detail) get turned on/off.


Changes the distance at voxel object is rendered or not.


This will link the voxel object to the terrain (see SnapToTerrain) how to build a better transition to the surrounding terrain.


This will generate low poly versions of the voxel geometry so you get a better performance when the voxel object is further away.


See below.

Smart Base Color

If this option is turned on the ground texture from the heightmap is used instead of the one specified in the voxel painters material section.


ComputeAO In case of Voxel Objects - Ambient Occlusion is a value pre-calculated for every vertex. This value says how open or how occluded this vertex is relative to environment around.

By default during lighting calculations this value just modulates ambient color for the vertex. This feature can be activated in Voxel Object properties by enabling ComputeAO checkbox.

Here you can see cave scene (with one light source):

AO is disabled.AO is enabled.

Editing the Voxels

In the RollupBar, go to Terrain -> Voxel Painter, and set the type to Create. Now, start adding overhanging geometry to the top edge of the cliff by clicking where you want to draw voxels.

To begin, it may help to increase the size of the Brush Radius to 25 and the Voxel Size to 16. This will help the results to be very visible.

In addition, using the Align Plane functions is good for controlling the geometry you create.

  • First click Setup position, move and rotate the plane where you want to, then click Align to plane.
  • Now, paint the voxel on the plane.
  • Use the Brush Setting Type Blur to remove sharp edges.

Try to create an overhang like the one in the following picture.

Creating a Cave

This example shows how to make a cave in the same small hill. First, place a Voxel Object over the desired area, as you did previously. In order to go under the terrain surface, you need to tell the game's physics engine that you want to have a hole here.

In the RollupBar, go to Terrain and then Holes and make a hole in the area where you want to make the entrance to the cave. Please note that this will be a change only in the heightmap, not the Voxel Object.

The difference between making a cave and the previous example, is that the LinkToTerrain option will not allow us to create a hole under the terrain, as it only allows you to add features on top.

Instead of using LinkToTerrain, use copy heightmap data. In this way you will have full control over this area using the Voxel Painter tool.

Select Voxel Object, make sure that LinkToTerrain is selected, and press the Copy Terrain into Voxel button in the Voxel Object properties.

The hole in the heightmap that you painted earlier will be not visible anymore – the Voxel Object has covered over the original (hole-less) terrain sector.

Now you can start making the cave. In the RollupBar, open Terrain and then Voxel Painter, select brush type Subtract.

Make a cave by keeping click holding while moving on the area where the hole should be. Again, using the Align to plane function here can be useful.

Changing the Material of a Voxel Object

In Brush Settings, select Material from the Type dropdown box, then select one of the materials in the surface types box. Now you can paint on the voxel area by clicking the mouse button.

In the same way as cliff materials are used for usual terrain painting, materials that are painted on voxels should have 3 sub-materials, one for each of the x, y, and z axes.

So as a base let's use the following material: materials\terrain\cliff_grey_3d.

If needed, you can make a new layer in the Terrain Texture Layers window, or use an existing layer for the voxel object.

Brush Settings

Type of Brush



The default brush. Press the left mouse button to create additional geometry above the surface of your voxel.


Carves the shape of your brush into your voxel when you have the left mouse button pressed, used to create caves and indents.


Will smooth out hard geometry edges on the spot where you paint.


Use this brush type to paint with the material selected in the surface type box below. Please note, this only applies a material, and not detail texture or coloration. Please apply these to your terrain before you place your voxel.

Copy Terrain

Restores the original terrain that you copied into your voxel with the at the point where the Normal terrain, directly copied into voxel.


For painting voxels there is just one type of brush available.


Changes the how big the radius of your brush is, in meters.

Align to Plane

Toggles the alignment plane. The alignment plane is a flat object which can be manipulated and "drawn on" using the regular voxel brushes.

Setup Position

Allows you to set the position of the alignment plan, using the normal object positional manipulators.

Init Position

Moves the alignment plane to the mouse pointer. Left click to place it down in position.

Plane Size

Allows you to adjust the size of the plane, setting the length of an edge of the plane in meters.

Surface Types

Here you can choose one of the surface types that you want to paint on the voxel walls and floors (make sure you select just like cliffs materials with 3 slots). Please see the Painting Terrain tutorial for more information.

Mesh Generation Options

Update PhysicsUpdates the physics of the voxel in realtime. Disabling this will cause the painting process to only apply to the existing physics of the voxel. Anything new that is painted will not automatically be physicalised.
This can be useful for gaining fine control when painting on your voxel object. Enabling this again and painting will update the physics of the voxel.
Simplify MeshOptimizes the voxel mesh, removing any unnecessary polygons.



  • No labels