TerraVol is a voxel terrain engine made with and for Unity 3d. It handles real time creation & modification of true volumetric terrains using voxel data and Marching Cube algorithm.

It also comes with a simple Editor Tool directly integrated inside Unity’s editor and allows you to edit your terrains in the scene view.

What is a voxel/volumetric terrain?

Unlike standard terrains in Unity (and in most video games), voxel/volumetric terrains allow the creation of holes, caves, overhanging cliffs, etc. This means that terrain geometry isn't defined by a height map but is instead stored in a more complex 3D structure.

Possibilities offered by a true volumetric terrain are fabulous and will make your game even more enjoyable for the players. This is the future of terrains in video games.

You probably know Minecraft. Minecraft uses a basic and simple kind of voxel terrain. Everything is made with cubes, but still, you can create caves, dig holes, generate material, etc. TerraVol allows you to do the same thing in a realistic world. In other words, TerraVol gives you the power of Minecraft with the graphic quality of a standard terrain.

Why do you need TerraVol?

Simple: to make your game better!

More seriously, it will depend on your needs. Some kind of games won't require TerraVol at all… But a lot of them will! To give you a better idea of what you could do with TerraVol, see the list of its features below.

Main features:

Core functionalities are multithreaded to get a lower impact on the frame rate. [Try the demo: terrain is created without lag]
Procedural terrain generation in real time using Perlin noise. [See the result in the demo]
Real time terraforming. [Try it in the demo: just click!]
Optimized saving system to store terrain information in a file. Dynamic and fast loading. Easier to sync voxels in a multiplayer context.
Supports as many type of blocks as you want thanks to the BlockSet component.
Customizable terrain texturing. Supports multiple materials. Compatible with RTP3 (recommended but not included). [Try both demos!]
Vegetation placement (trees, etc.) using your own assets. [Look at trees in the demo]
Powerful grass generator. [Look at grass in the demo]
Simple-but-robust in-editor builder tool.
3D A* path finder with path smoothing. [Try it in the demo: press 'I' to set the start point at your position, then move where you want and press 'I' again to display the path (if it exists)]
Possibility to limit the size of the terrain in X and/or Z direction. Use it to make 2.5D games! [Try the demo “2.5D World”]

In-Editor Builder Tool features:

Choose between different brushes: cube, sharp cube, sphere, or cylinder.
Choose between different actions: dig, build, flatten, paint.
Choose between any type of block you want. You can add as many type of blocks as you want thanks to the BlockSet component.
Start the tool, click on the scene view, and press 'B' at anytime to build more terrain all around you.
Press 'Z' to undo your actions. You can undo as much actions as you want (since you opened the map).
Toggle between "One action per click" / "continuous editing".
Toggle "Delta-edit" mode and customize brush strength.
Note about grass placement: if you want to place/remove grass, you have to create a new type of block in the Block-Set with 'vegetation enabled' property set to what you want. Then, simply select it in the 'Current type of block' select-box and choose the 'Paint' action to affect the ground without modifying terrain shape. This may look a bit unintuitive, but this is mandatory because terrain creation is driven by blocks data only (ie. voxels).

What do you get when you buy TerraVol?

All TerraVol sources to make the magic works and give you full control over the system.
Simple triplanar shader for texturing (pre-compiled).
Two example scenes.
Free updates through the asset-store.
A fantastic and extremely easy way to distinguish yourself and make a game which doesn't sound like any other.

Feedback and requests

If you find a bug, if you think something is missing, or want to give some feedback, please do not hesitate to contact me.

I will continue to update, fix, and improve TerraVol, and free updates will be provided through the Asset Store. You will pay only once!

Also, please tell me if anything is missing in the documentation.

You can contact me at: terravol.unity@gmail.com

If you appreciate the product and want to support it, I would be extremely thankful if you rate TerraVol on the Asset Store and maybe write a comment. This will definitely help. Thank you in advance!

Getting started

It is strongly recommended to get a look to the example scenes given with TerraVol. It contains all stuff needed to start using TerraVol and can make a good starting point for a new project.

One scene contains the editor builder tool while the other one will be prefered to make purely procedurally generated worlds.

Understanding the basics

You won’t need to know a lot of things to work with TerraVol, but you should know this:

The Map (i.e. the terrain) is composed of “Chunks”.
Chunks are composed of 8x8x8 blocks. A chunk is basically a portion of terrain.
Each block (ie. voxel) contains some information in order to create the terrain geometry and texture it.
When working with trees, grass, etc. you should always consider them inside their chunk (depending on their world position) to keep good performance. You can see an example of this in the TerraVolEnhance script (see below for more information).

How to use TerraVol in your existing project?

If you want to integrate TerraVol in an existing project/scene, follow these instructions:

Create a GameObject in your scene (GameObject -> Create empty) and name it “BlockSet”.
Select the previously created game object and add the BlockSet component to it (Add Component -> TerraVol -> BlockSet).
Inside the BlockSet component, add a Block named “Default” with a material index of 0 and add a material to the “materials” array (see Using BlockSet component section).
Create another GameObject in your scene (GameObject -> Create empty) and name it “Map”.
Select the previously created game object (Map) and add the Terra Map Generator component (Add Component -> TerraVol -> Map Generator) and the Map component (Add Component -> TerraVol -> Map).
The Map component should be already populated with working values. You will see later how these values can be modified to do exactly what you want.
Now select your BlockSet object and drag it to the “Block Set” property of the TerraMap component.
Select the player’s camera and drag it to the “Player Camera” property of the TerraMapGenerator component.
If you want the player to be able to edit the terrain in real-time, add the In-Game Builder Tool component to it (Add Component -> TerraVol -> In-Game Builder Tool).
That’s all. Press play and see the magic!
Wait… you may also want to edit your terrain inside the Unity editor! To be able to do that, you have to add the Terra Builder component to your Map object (Add Component -> TerraVol -> In-Editor Builder Tool).
Now you are ready to use the power of TerraVol directly inside the editor.

Setting-up parameters

TerraMap parameters

blockSet: this is the BlockSet object of your scene. It contains information about voxel types. (see the example scene)
buildDynamically: if true, terrain will be built dynamically at runtime. This allow you to build only a small portion of terrain before the game starts and then build the rest of the terrain during the game without lag.
limitSize: if true, the size of the terrain will be limited. Otherwise terrain will be theorically infinite.
Max X: if limitSize is true, this will be the maximum value of X coordinate a chunk can have.
Min X: if limitSize is true, this will be the minimum value of X coordinate a chunk can have.
Max Z: if limitSize is true, this will be the maximum value of Z coordinate a chunk can have.
Min Z: if limitSize is true, this will be the minimum value of Z coordinate a chunk can have.
sizeX/ZAtStart: size (in Chunk’s unit) of the map that will be built before the game starts.
minY: defines the bottom of the map, in Chunk’s unit. For example, a value of -2 means that the bottom of the map is at y = -2 * Chunk.SIZE_Y_TOTAL.
buildDistance: distance (in Chunk’s unit) from camera where chunks must be built. For example, a value of 6 means that the draw distance of the terrain is 6 * Chunk.SIZE_X_TOTAL on X axis and 6 * Chunk.SIZE_Z_TOTAL on Z axis.
hideFarAwayChunks: do the chunks which are far away from the camera should be hidden? This can help to maintain a constant frame rate.
hideDistance: distance (in Chunk’s unit) from camera where chunks shouldn't be rendered anymore.
blockSizeX/Y/Z: size of a block in world’s unit (ie. a voxel).
loadPath: path of terra file to load. Can be "Assets/somepath/somefile.terra". If empty, a new terrain will be procedurally generated.
generateGrass: if true, grass will be generated over the terrain (‘Is Vegetation Enabled’ must be checked on blocks were you want the grass to be created. See the BlockSet component).
grassMaterial: material that will be used for rendering grass.
grassSize: horizontal size of each blade of grass.
grassHeight: base height of grass (will vary during generation).
grassDirtyHeight: defines at what height grass is considered as ‘dirty’ (used for color variations).
grassMinHeight: blades of grass that have a height lower than this value won’t be rendered.
grassTextureTileX: texture horizontal tiling on each blade.
grassDensity: can be 1, 2 or 3.
grassColor: base color for grass.
grassDirtyColor: base color for dirty grass.
grassMaxSlopeAngle: prevent grass from being placed on the ground if the slope is too big.
windStrength: strength of wind affecting the grass.
grassDrawDistance: grass draw distance from the camera.
trees: array of tree prefabs. These trees will be placed over the terrain. All prefabs must be tagged with ‘Tree’ tag.
treesDeepInTheGround: array of float values, giving how deep in the ground each type of tree must be placed. It must have the same length than ‘trees’ array.
treesDensity: density of trees.

TerraMapGenerator parameters

playerCamera: reference of the player camera.
Roughness affect the terrain so it doesn’t look so smooth.
Granularity affect the terrain generation. The lower is granularity, the more the terrain will have holes, arches, cliffs, etc.
Height coef. of cliffs affect the size of cliffs.
Height coef. of hills affect the size of hills.
Max Height of cliffs is the maximum size (in block units) of cliffs.
Max Height of hills is the maximum size (in block units) of hills.
Min Height of ground is the minimum altitude of the ground.

BlockSet parameters

Block Set gives you control over terrain texturing.

Blocks array contains all type of blocks (ie. voxels) you want to use in your terrain:

Name: put anything you want, but remember that a BlockSet must always contains at least a block named “Default”. You will be able to retrieve blocks in your scripts using method map.GetBlockSet().GetBlock("Name of my block").
Material index: this is the index (in the Materials array of the Block Set) of the material to be used.
Vertex color: this will be used during mesh generation to determine the color of vertices (mesh.color). Useful for vertex blending.
Is Destructible: if set to true, this block will be destructible through map.Dig method. Otherwise, it won’t be affected by digging.
Priority: tells TerraVol which type of block to choose if it has the choice between two of them when building the terrain. TerraVol will always choose the highest priority.
IsVegetationEnabled: if true, vegetation can be placed on this block.

Materials array contains all materials you want to use on your terrain. The property “material index” of blocks refers to the index of the material in this array.

In-Editor Builder Tool

TerraVol allows to model and texture voxel terrains directly inside the editor. The Terra Builder component is the component that makes it possible. To use it, just add it to your Map game object (i.e. the object on which you added the TerraMap component).

This tool is very simple to use. You have only a few parameters that make it possible to sculpt the terrain and paint textures on the ground.

Here is a description of each parameter:

One action per click only: toggle continuous editing.
Delta-edit: toggle delta-edit mode to edit terrain with smaller/smoother changes.
Brush strength is the value that will be added to voxels’ isovalue when modeling the terrain if ‘Delta-edit’ mode is enabled.
Distance of effect is the maximum distance of effect you can have from the editor camera.
Flatten Height: y coordinate to which you want to flatten the ground.
Action is the type of action you want to do. You can dig, build, flatten an area, or paint textures on the ground.
Brush is the type of brush you want to use.
Current type of block allows you to choose which block you want to be put when you do an action. This is particularly useful when painting textures as each block can have a different texture/material.
Start In-editor Builder button: launch the scripts that will load, generate, and build the terrain. You have to press this button before you can do any action.
Save Map button allows you to save terrain data to a file.
Reload from file will reload data from the file and rebuild the terrain.
Reset and re-create terrain randomly button will generate a new terrain and build it from scratch.

Save and load your terrain

TerraVol Maps can be saved & loaded through files. It uses a very fast serialization technology.

You will need to save Unity’s scene separately. To save your map, use map.Save(string path) method where path is the full path of the file (name included) where you want to save it. To load your map, use map.Load(string path) method where path is the full path of the file (name included) from which you want to load it.

With the in-editor tool, you can save the terrain thanks to the “Save Map” button.

Edit the terrain in your scripts

You may want to let your player edit the terrain and so, you would like to know how to edit it from scripts.

To see the full API documentation, see http://terravol.com/api_v2/

This is actually extremely simple. Any modification must be done through the “action system”, using WorldRecorder.Instance.PerformAction(new ActionData( ….. )).

ActionData represents an action performed on the terrain. Its constructor takes several parameters:

position: Absolute block position of the 'center' of the action.
size: Size of brush. If brush is a cube, this is the size of the cube along X, Y and Z axis. If brush if a sphere, only size.x is taken into account as the radius of the sphere. If brush is a cylinder, size.x is the radius of the cylinder and size.y is its height.
blockType: Type of block that will replace current types of blocks.
type: Type of action (ie. Dig/Build/Flatten/Paint).
brush: Type of brush (ie. Cube/Sharp-cube/Sphere/Cylinder).
createVegetation: If true, vegetation will be (re)created after action has been performed.
force: If true, all blocks will be affected even if they are indestructible.

Typical examples of actions

You should get a look to the Builder.cs script. This is a very good starting point to start using TerraVol in your scripts.

Here is an example of how you could dig into the ground:

WorldRecorder.Instance.PerformAction(new ActionData(Chunk.ToTerraVolPosition(position), radius * Vector3.one, block, ActionDataType.Dig, BrushType.Sphere));

Customizing TerraVol without modifying the source code

TerraVolEnhance script is made for that. You can do a lot only by modifying this script.

See API Reference for more information.

Using RTP3 with TerraVol

If you find that TerraVol’s default shader isn’t advanced enough, and want to obtain better looking terrain with parallax mapping and other nice things, you can use RTP3 (you will find it on the Asset Store).

This is extremely easy to use it with TerraVol. Follow these steps:

Open the file ReliefTerrainVertexBlendTriplanar.shader and comment the line #define LOCAL_SPACE_UV
Replace the terrain material in the BlockSet component by the one you will find in ReliefPack/Shaders/ReliefTerrain/VertexControl
Open Chunk.cs and uncomment the line #define TERRAVOL_RTP3
You will probably have to change the vertex color of your blocks in the BlockSet component because RTP3 map it differently. For example, ‘Default’ block should be red (with alpha value equals to 0).
That’s all.

Making biomes

TerraVol allows to use multiple materials on a same terrain thanks to the BlockSet component. This feature makes possible to have different biomes on a map.

This tutorial will show you how to define biome areas and how to make a soft and nice transition between them.

Define areas for your biomes

You will have to make your own "region" system to handle the creation of biomes. This can be either very simple or very complex depending on your needs. This section gives a basic example, but once you'll have read it you'll be able to make your own region system to fit your needs.

The best way to do that is to customize TerraVolEnhance script. We are going to see how you can define two different regions thanks to the OnBlockGenerateBeforeInThread method.

This method allows you to tell TerraVol which type of block to use depending on its position.

To keep it simple, we will define two regions like this:

all blocks which have an x coordinate below 50 will be in the region n°1
all blocks which have an x coordinate above 50 will be in the region n°2

So we're going to have a straight border between our regions. This is a bit basic but it gives you the idea. If you want to make it more sophisticated, you could use a splatmap for example, but it won't be explained here as it is another topic.

To make our regions defined above, we're now going to implement the OnBlockGenerateBefore method like this:

if (position.x > 50)

return "WinterDefault"; // WinterDefault block will be used

else

return null: // Default block will be used

Adding the new blocks

The second thing to do is to add a "WinterDefault" block to our BlockSet.

First, create a new terrain material and set a snow texture instead of a grass texture.

Then, select the BlockSet object of your scene and add a new material to the materials array. Drag & drop the previously created material to the second index of the array.

Finally, add a new block to the blocks array. Name it "WinterDefault", change the color to black (and no Alpha), and set its material index to the index of the material you've just added before (ie. 1)

Here we go. If you press play you should see the two biomes (grass/snow) on your terrain.

Making transitions between biomes

Currently, there is no transition between our biomes and it's really ugly.

Let's see how to handle it.

The best way is to share a same texture between the two materials.

Select your first material and add a half-snow half-grass texture on the green channel.

Select your second material and add the same texture on the green channel too.

Create a new type of block, name it "Transition", set the material index to your first material and the vertex color to green.

Create a new type of block, name it "WinterTransition", set the material index to your second material and the vertex color to green.

Now, modify the OnBlockGenerateBefore method like this:

if (position.x > 60)

return "WinterDefault"; // WinterDefault block will be used

else if (position.x > 50)

return "WinterDefaultTransition"; // WinterDefaultTransition block will be used

else if (position.x > 40)

return "Transition"; // Transition block will be used

else

return null: // Default block will be used

Done! You should now have a smooth transition between your biomes.

Frequently asked questions

How do I resize the terrain?

Terrain can be resize thanks to the Map parameters. Do not use scale property of the Map object. For more details, you should get a look to the “Setting Map parameters” section, it will tell you exactly what parameters you need to modify.

Can I change the size of digging/building brush?

Sure you can! See “Edit the terrain in your scripts” section for more information.

Can I change the speed of digging/building?

Again, you can! See “Edit the terrain in your scripts” section for more information.

Does TerraVol support multiple materials on a single terrain?

Yes! Thanks to the materials array of the BlockSet component, you can use as many materials as you want with your terrain. See “BlockSet parameters” for more details.

Where can I find better shaders for terrain texturing?

On the Asset Store. There are some very good terrain shaders. I strongly recommend RTP3 (see “Using RTP3 with TerraVol” section).

Can I use normal mapping on the terrain?

Yes but you will have to buy a better shader on the Asset Store or make on by yourself. I strongly recommend RTP3 (see “Using RTP3 with TerraVol” section).

Is there any API reference?

Yes, right there: http://terravol.com/api_v2/