So seeing as I utterly failed at trying to keep a weekly blog going, I figured I’d at least post some tutorials. I’ve got a lot more to share on the Unreal Engine side of things than I do things that I’m working on and want to talk about. This first series of tutorials covers creating voxel-based terrain in Unreal Engine 4. Below you can see a few examples of what you could create using something very similar to what we’ll be making in this tutorial series.

This slideshow requires JavaScript.

This process is actually relatively simple, and a basic setup can take as little as a couple of hours to get going. I’ll be assuming you have a basic knowledge of C++ and Unreal Engine 4 during this tutorial, so don’t expect me to cover anything really basic like how to create a project or what a pointer is. With that said, let’s get on with the tutorial.

What Do We Need?

The requirements for a voxel-based terrain system are quite simple. The three main things we need to accomplish are generating the voxels, storing the voxels, and displaying the voxels in the world. In this tutorial we’ll be using two open source libraries and Unreal Engine 4. The two libraries we’ll be using are PolyVox and AccidentalNoiseLibrary.

PolyVox will be used for several important parts of our terrain, such as managing the data and generating the mesh from our voxels. Seeing as PolyVox hasn’t had a stable release in a long time, and the newer version available from their Bitbucket repository has many improvements, we will be using the unstable Develop branch. At the time of writing this tutorial the PolyVox Develop branch is on commit f4c4bf9, so keep in mind that there might be some API differences if you decide to use a newer version.

AccidentalNoiseLibrary will also be used for a very important part of our voxel terrain: the actual terrain generation. AccidentalNoiseLibrary (referred to as ANL from now on) is a noise generation library as the name suggests, and it’s absolutely packed with features that will let you get just the look you’re aiming for. Some of the features we’ll be using include scaling, turbulence, and blending. I’ve setup a fork of this library for use with this tutorial, and I will keep this tutorial up to date if I make any changes to that fork.

Finally, we obviously need Unreal Engine 4 for this tutorial, seeing as it is a tutorial for that engine after all. We’ll use the latest stable build from the Epic Games Launcher, which is currently 4.10.4 for this tutorial. Onward to project setup!

Setting Up The Project

Creating The Project

Alright, lets go ahead and create a new project in Unreal Engine 4. We’re going to be doing a good bit of C++ for this tutorial so go ahead and create whatever kind of code project you prefer. Personally I’m going to be going with an empty C++ project with no starter content to keep things simple. Once you have the project opened, go ahead and navigate to the project folder.

Downloading The Libraries

First things first, we need to bring in our libraries. Create a folder in the root of your project directory called ThirdParty, inside that folder go ahead and clone the libraries using Git. Once we have our libraries downloaded there really isn’t that much more to do with PolyVox, however, ANL needs to be compiled. We’re not going to compile the library now though, because we still have a few setup steps to do.

Telling The Engine Where The Libraries Are Located

Up next we need to tell the engine to include our header files and link the ANL library. Go ahead and open up the project with your preferred code editor if it’s not already open. Next you need to find the ProjectName.Build.cs file and open it up. You should be presented with something similar to what I have below.

using System.IO; // Make sure you are using System.IO! Its not in here by default!
using UnrealBuildTool;

public class VoxelTerrain : ModuleRules
{
    // Some versions of the engine might have the ModulePath and ThirdPartyPath variables defined already
    // 4.10.4 doesn't so we need to add them!

    // The path to our game module; e.g. ProjectFolder/Source/ModuleName/
    private string ModulePath
    {
        get { return Path.GetDirectoryName(RulesCompiler.GetModuleFilename(this.GetType().Name)); }
    }

    // The path to our Third Party code assets; e.g. ProjectFolder/ThirdParty/
    private string ThirdPartyPath
    {
        get { return Path.GetFullPath(Path.Combine(ModulePath, "../../ThirdParty/")); }
    }

    public VoxelTerrain(TargetInfo Target)
    {
        PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore" });

        PrivateDependencyModuleNames.AddRange(new string[] {  });

        ////////////////////// Custom Voxel Terrain Stuff Starts Here //////////////////////////////////////
        // You will need to compile and add additional libraries if you want to use this on platforms not listed below!
        switch (Target.Platform)
        {
            // 64-bit Windows
            case UnrealTargetPlatform.Win64:
                PublicAdditionalLibraries.Add(Path.Combine(ThirdPartyPath, "accidental-noise-library", "build", "ANL", "x64", "ANL.lib"));
                break;

            // 32-bit Windows
            case UnrealTargetPlatform.Win32:
                PublicAdditionalLibraries.Add(Path.Combine(ThirdPartyPath, "accidental-noise-library", "build", "ANL", "x86", "ANL.lib"));
                break;

            // Mac
            case UnrealTargetPlatform.Mac:
                PublicAdditionalLibraries.Add(Path.Combine(ThirdPartyPath, "accidental-noise-library", "build", "ANL", "Universal", "libANL.a"));
                break;
            
            // Linux
            case UnrealTargetPlatform.Linux:
                PublicAdditionalLibraries.Add(Path.Combine(ThirdPartyPath, "accidental-noise-library", "build", "ANL", "x64", "libANL.a"));
                break;

            default:
                break;
        }

        // Include the headers for PolyVox and ANL so we can access them later.
        PublicIncludePaths.Add(Path.Combine(ThirdPartyPath, "polyvox", "include"));
        PublicIncludePaths.Add(Path.Combine(ThirdPartyPath, "accidental-noise-library"));
        ////////////////////// End Voxel Terrain Stuff //////////////////////////////////////////////////////
    }
}

You might have already noticed that there are some sections in that code that you don’t have in your file. Those sections are what you need to add in order to tell the engine where the new libraries are at. Just in case you’re not familiar C# or with the way the UnrealBuildTool works, I’ll give a quick overview of what each section does.

using System.IO; // Make sure you are using System.IO! Its not in here by default!

Tells the build tool that we want to use the System.IO namespace, its pretty similar to how using works in C++.

    // The path to our game module; e.g. ProjectFolder/Source/ModuleName/
    private string ModulePath
    {
        get { return Path.GetDirectoryName(RulesCompiler.GetModuleFilename(this.GetType().Name)); }
    }

    // The path to our Third Party code assets; e.g. ProjectFolder/ThirdParty/
    private string ThirdPartyPath
    {
        get { return Path.GetFullPath(Path.Combine(ModulePath, "../../ThirdParty/")); }
    }

Sets up two read-only string members that we can use later on to get the path to our module or the ThirdParty folder we created earlier. Not strictly required, but it does help to simplify the code when you’re dealing with a large build file.

        ////////////////////// Custom Voxel Terrain Stuff Starts Here //////////////////////////////////////
        // You will need to compile and add additional libraries if you want to use this on platforms not listed below!
        switch (Target.Platform)
        {
            // 64-bit Windows
            case UnrealTargetPlatform.Win64:
                PublicAdditionalLibraries.Add(Path.Combine(ThirdPartyPath, "accidental-noise-library", "build", "ANL", "x64", "ANL.lib"));
                break;

            // 32-bit Windows
            case UnrealTargetPlatform.Win32:
                PublicAdditionalLibraries.Add(Path.Combine(ThirdPartyPath, "accidental-noise-library", "build", "ANL", "x86", "ANL.lib"));
                break;

            // Mac
            case UnrealTargetPlatform.Mac:
                PublicAdditionalLibraries.Add(Path.Combine(ThirdPartyPath, "accidental-noise-library", "build", "ANL", "Universal", "libANL.a"));
                break;
            
            // Linux
            case UnrealTargetPlatform.Linux:
                PublicAdditionalLibraries.Add(Path.Combine(ThirdPartyPath, "accidental-noise-library", "build", "ANL", "x64", "libANL.a"));
                break;

            default:
                break;
        }

        // Include the headers for PolyVox and ANL so we can access them later.
        PublicIncludePaths.Add(Path.Combine(ThirdPartyPath, "polyvox", "include"));
        PublicIncludePaths.Add(Path.Combine(ThirdPartyPath, "accidental-noise-library"));
        ////////////////////// End Voxel Terrain Stuff //////////////////////////////////////////////////////

Finally we have the section that actually tells the UnrealBuildTool where everything is and what it needs to link to our module. There are two important member variables in use here:

• PublicAdditionalLibraries: This member of ModuleRules allows us to tell the UnrealBuildTool what additional libraries our module will link to during the build process.
• PublicIncludePaths: This member of ModuleRules instructs the UnrealBuildTool to add folders to our include path.

Compiling ANL For Use in Unreal Engine 4

Alright, so the last hurdle we need to clear before we can compile our project for the first time is compiling ANL. In older versions of ANL this process felt kind of complicated due to errors with third-party libraries and CMake, however, newer versions make use of premake, which makes the process infinitely simpler.

I have created a custom fork of ANL for the purpose of making this as easy to set up as possible. It has some benefits like premake5 support, and no third-party libraries. The removed functionality from the third-party libraries was a Lua interpreter and a Lua binding, neither of which we can use with Unreal Engine 4 in its default state. In the future I might make a plugin that integrates Lua in Unreal Engine 4, however, for now we’re not going to need these libraries.

The first step in the build process for ANL is to download premake5. You can find premake5 over at http://premake.github.io/. Go ahead and download the latest version of premake5 for your operating system. Once you have it downloaded, place it inside the ProjectName/ThirdParty/accidental-noise-library/ folder.

The second step is to open a terminal or command prompt in the folder to run premake. On Windows you can simply hold shift and right-click in the folder, which will give you the usual context menu with the added option to open a command prompt in the current folder. Once you have your command prompt open, all you’ll need to do is run premake. In my case I needed to run the command premake5 vs2015.

It is worth noting that the premake command might be different for you if you’re not using Visual Studio 2015. If you’re not sure what command to run then run premake5 --help and find the section labeled Actions. In the Actions section look for the IDE that you wish to generate files for, and then run the appropriate premake command. For example, if I wanted to generate files for Visual Studio 2015, then I would run premake5 vs2013.

Now all we need to do is compile the ANL solution. To do that go ahead and open up the project file that you just generated with premake5, in my case the file I needed to open was called ANL.sln and it was placed in the build sub-directory. Once you’ve got that open compile the ANL project in the Release configuration for your platform, and after a large amount of warnings fly by you should have a compiled copy of ANL!

Compiling The Unreal Engine 4 Project and Conclusion

The final step in this part of the tutorial is the simplest one yet: compiling the actual game project. Once you’ve done that you will be ready for the next part of this tutorial, which will be available in the near future. If you have any trouble getting this to work feel free to ask for help in the comments, or if you don’t want it to be seen by everyone for some reason, I have a contact page at the top of the website.

In the next part of this tutorial we’ll start to make use of the libraries we setup today. I plan on starting with really basic usage of the libraries, and moving up to more advanced uses like being able to edit the terrain in real-time, generating the terrain while in the editor, and possibly tools to edit the terrain in the editor.

Edit: I accidentally used .so instead of .a for the Linux and Mac targets, if you’ve used this tutorial and couldn’t compile the project for Linux or Mac then that could be why!