Voxel Terrain In Unreal Engine 4 Part 1: Getting Setup

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!

19 comments on “Voxel Terrain In Unreal Engine 4 Part 1: Getting SetupAdd yours →

    1. Whoops, I totally missed your comment on here! To answer the question though: No, you do not need the QT IDE or QT itself unless you decide to follow Part 2.5 of my tutorial series. PolyVox is a header only library, and QT would only be needed if you decided you wanted to compile the example programs that come with it.

  1. Thanks for the tutorial, it’s extremely helpful.

    Quick notes that I had to change, probably because of the latest changes in recent versions of Unreal (4.12.5):

    GetModuleFilename() is deprecated, so I had to use:

    // The path to our game module; e.g. ProjectFolder/Source/ModuleName/
    private string ModulePath
    {
    get { return ModuleDirectory; }
    }

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

  2. I’m also loving this series so far. Just a heads up that I couldn’t get my header files to read the polyvox includes until I changed “PublicIncludePaths.Add(Path.Combine(ThirdPartyPath, “polyvox”, “include”));” to “PublicIncludePaths.Add(Path.Combine(ThirdPartyPath, “polyvox/include”));”

  3. Bit of a compiling error. Followed this lesson to the letter and then thanks to the debug console and some quick searching, I was able to find your more recent 4.5 for the update to UE4.12 and the change from ModulePath to ModuleDirectory.

    Unfortunately, it now throws a different error about not being able to open ANL.lib. Did a little digging around in the files of ..\accidental-noise-library\ , and I think Premake 5 didn’t compile ANL right because ANL.lib is missing. Output log of the original ANL Premake Compile is as follows…

    C:\Users\Name\Documents\Unreal Projects\TerrainTest\ThirdParty\accidental
    -noise-library>premake5 vs2015
    Building configurations…
    Running action ‘vs2015’…
    Generated build/ANL.sln…
    Generated build/ANL/ANL.vcxproj…
    Generated build/ANL/ANL.vcxproj.filters…
    Done (89ms).

    Contents of ..\accidental-noise-library\build\ANL\ are ANL.vcxproj and ANL.vcxproj.filters. Any insight would be appreciated.

    1. Premake doesn’t compile ANL, it generates solution files so you can compile it in an IDE like VS2015. Assuming you’re running Windows (paths in your comment suggest as much), you need to open the project files it generated in VS2015 and build it from there as mentioned in part one of the tutorial.

      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!

      I apologize in advance if you have already done this, but your comment did not say anything about having done anything past the point of running premake.

      1. Alright, thank you! Apparently the issue was that I’ve got the basic understanding of how C++ works and have written in HTML and Lua before, but haven’t used VS until just the other day due to….issues with Microsoft’s handling of the product unrelated to this tutorial or UE4. So I didn’t quite get that you were saying it needed to be compiled in VS2015, and thought Premake did that!

        I also probably should have clarified that the compiling errors I mentioned were thrown by UE4 with the build project files, at the end of the tutorial. Actually using VS to compile ANL seems to have resolved the problem.

    1. Also, what exactly needs to go into the ThirdParty folder? For ANL I have build->ANL->Universal/X64/X86->ANL.lib, but it complains when I try to include the VM/kernel.h. For PolyVox, I have no idea what exactly needs to go into the folder, maybe you could give a small hint there.

      1. For those who need a bit of help to get everything compiling right off the bat and who have newer builds of Unreal Engine (current for me is 4.17.1) (for zero to slight
        coding experience):

        When editing the files, there are a few new changes to the file requirements:

        // 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/")); }
        }

        should become

        // The path to our game module; e.g. ProjectFolder/Source/ModuleName/
        private string ModulePath
        {
        get { return ModuleDirectory; }
        }

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

        Also, ensure the very end of the document looks like so:

        }
        ]

        When you git the files to /ThirdParty/, remember to add a destination file (don’t pre-create it, with programs like Git GUI that can be an issue)

        So the directories should be like so ( or at least how I did it):

        ProjectName/ThirdParty/accidental-noise-library/
        ProjectName/ThirdParty/polyvox/

        When using Premake5, put it directly in your accidental-noise-library root.

        If during precompiling with Premake you can’t navigate to the file and open a cmd instance by right-clicking, then remember to open up your path manually using the cd command

        For me (running UE 4.17.1) the command was:

        cd C:\Users\spins\OneDrive\Documents\Unreal Projects\MyProject\ThirdParty\accidental-noise-library

        Once there, I compiled by inputting premake5 followed by vs and my release year (2015), so the command becomes premake5 vs2015 for me. Remember, don’t proceed it with run or any other command. Just input it as-is.

        Then, in accidental-noise-library, go to build and open ANL.sln

        Once there, find the two boxes near the undo/redo buttons, one should say debug and the other win32.

        Change those boxes to Release and x64 for all 64-bit systems (I also compiled the Universal and Win32 versions by accident lol), then, while ANL is selected in the Solution Explorer, go to Build>Build ANL and wait for the process to be finished.

        To build the project file itself, open MyProject.sln in the root of your project’s folder and go to the Solution Explorer on the right. Drop-down the Games folder and click on MyProject.

        Then, go up to Build > Build MyProject

        Hope I could help!

  4. Hi, I just got a compiling error where it says;

    Unable to start program ‘C:\Users\myname\documents\Unreal Projects\MyProject\ThirdParty\accidental-noise-library\build\ANL\x86\ANL.lib

    C:\Users\myname\documents\Unreal
    Projects\MyProject\ThirdParty\accidental-noise-library\build\ANL\x86\ANL.lib is not a vaild win 32 application.

    This error showed up exactly in that order. What should I do?

  5. Just wanted to say thank you for this tutorial series, as well as give advice.

    If anyone happens to get an error while trying to build ANL saying “cannot find corecrt.h”, follow the instructions in the answer by parsley72 (most upvoted answer) here: https://stackoverflow.com/questions/38290169/cannot-find-corecrt-h-universalcrt-includepath-is-wrong

    I would guess that with newer installations of VS, (for myself, its VS2017) don’t have the Windows CRT SDK installed by default because its considered legacy now.

    Thanks again for doing this tutorial series!

  6. Becareful for the one who had a compil error : cannot open ANL.lib i lost an hour on a idiot error
    2 thing :

    – When you open buil->ANL.sln with visual studio d’ont forget to select you computer format (x86 or 64x) at the top of the new opened visual studio tab before generate build.

    – Accidental noise had an update, the line :
    PublicAdditionalLibraries.Add(Path.Combine(ThirdPartyPath, “accidental-noise-library”, “build”, “ANL”, “x64”, “ANL.lib”)); Had a litle change, this sentence change :

    “accidental-noise-library” TO “accidental-noise-library-master”. it should fix the problem.
    Hope it helped

  7. Hey, this might be a bit late, but could I ask how you made that nice atmosphere around the planet? And how do you make it so that it is less visible on the dark side of the planet?

    1. Hi, this is a pretty late response, but I am using a customized version of the Realistic Atmosphere plugin from the unreal marketplace. The customizations were mostly to improve performance and fix a few issues I encountered at larger scales. For most use cases I believe it will work great out of the box, and it’s definitely worth the money if you’re not familiar with all of the math behind atmosphere visuals.

      https://www.unrealengine.com/marketplace/realistic-atmosphere

Leave a Reply