Import Content
This page describes the various ways you can import content in the plugin: mesh to voxel conversion, heightmap/landscape importers, magica voxel import... These importers require the Pro version of the plugin to be used.
You can find examples of imports in Voxel Content/Examples/Maps/VoxelExample_ImportersMap. These examples can be viewed in the Free version as well!
Landscape Import
The plugin supports importing Unreal Landscapes. The import is perfect: the voxel mesh will exactly match the landscape one.
Unreal Landscape on the left, voxel on the right:
How to import a landscape
To convert an existing Unreal Landscape to voxels, do the following:
Add a new Voxel Landscape Importer to your scene.
Select the landscape you want to import in the Landscape Importer details:
Select the material config you want to use on your voxel world. See Materials. For instance if we want to use a 5 way blend:
Then add your landscape layer infos and select the channel you want them to be stored in:
If you are not using RGB, you need to assign them indices:
Click the Create button, and choose where you want to save your asset
You can then use the imported landscape asset as World Generator:
You can also use your asset in a voxel graph (just drag & drop the asset onto the graph):
You can configure the landscape asset by opening it:
Technical details
Landscape assets heights are stored as float to keep the full precision of the Unreal Landscape.
Landscape assets are compressed on disk. They can take some time to decompress on load.
Heightmap Import
You can import heightmaps up to 16kx16k in the plugin (see Technical Details as to why this limit).
How to import a heightmap
Right click the content browser and choose Voxel Heightmap Asset:
Select your heightmap, the material config you want to use (see Materials) and add your weightmaps. Make sure to assign them a different channel/index:
Click Create. You should now have a heightmap asset!
You can open it to configure it:
You can then either use it as world generator:
Or drag & drop it onto a voxel graph:
Technical details
Heightmap assets heights are stored as uint16. The max size you can import is approximately 16000x16000. Above this resolution, the archive goes beyond 2GB and overflows.
Imported heightmaps do not need to be squares nor power of two.
Heightmap assets are compressed on disk. They can take some time to decompress on load.
You can see the memory used by Heightmap (and Landscape) assets using stat VoxelMemory:
An uncompressed 16k heightmap with materials can take up to 1.2GB, so you should watch that value carefully!
Mesh Import
The plugin supports converting a mesh to voxels. In addition to the shape, the mesh colors can also be copied over.
While the import isn't lossless, it can give some great results:
Original asset on the left, voxel size visualization in the middle, imported voxel asset on the right.
Note that mesh to voxel conversion can also be done at runtime, for instance in the Mesh Stamp tool!
Mesh Requirements
To have the best results, your mesh needs to be watertight. If it's not, you will have leaks in the form of holes in your data asset.
How to import a mesh
Getting started
Drag a new Voxel Mesh Importer to your scene:
You should see something like this:
Each black/white square represents a voxel.
In the importer details, set the mesh you want to import:
Configure the Voxel Size using both the black/white squares size and Expected Size as help:
Importing Colors
If you want to import the mesh colors, tick Paint Colors and choose a material to use:
This material is a bit special: it's going to be rendered to a render target that is then going to be sampled by the mesh importer.
Set your material Shading Model to Unlit:
And plug the color you want to use in Emissive Color (most likely, you want to plug the same thing as Base Color):
Importing Roughness, Metallic and other stuff
The mesh importer also allows you to write into the two Voxel UV Channels.
Tick Paint UVs and select the material you want to use:
As above, your material must be Unlit:
You then need to plug something into Emissive Color.
(R, G) will be written into the first UV channel, and (B, A) into the second.
For instance, we can store Metallic in R (= UV0.X) and 1 - Roughness in G (= UV0.Y):
We can then use these UVs in our voxel material like so:
Note that Voxel UV0 is mapped to TexCoord[1].
Creating & using the mesh
Finally, click the Create button and choose where you want to save your asset:
You will then have a data asset:
Note that the thumbnail is taken the first time you open the data asset, so you might not have one yet.
You can open the data asset by double-clicking it. This will give you access to the Data Asset Editor:
You can use your data asset as world generator:
In a voxel graph by drag and dropping it:
Or in a Voxel Asset Actor by drag & dropping it onto the scene:
Technical details
The conversion works by setting the voxel densities near the mesh surface to their exact distance to the mesh (how near can be configured using Max Voxel Distance from triangle).
Then, the voxels are iterated in a linear sweep to set their sign. If your mesh is not water tight, you will have leaks!
The exact distance field of the mesh can also be computed using the GPU by calling ConvertMeshToDistanceField (not be exposed to BP yet).
Data Assets are compressed on disk, and uncompressed on first load.
You can see the memory used by data assets using stat VoxelMemory:
Magica Voxel Import
Magica Voxel is a popular open-source and free application to design voxel stuff: https://ephtracy.github.io/
The plugin supports importing .vox assets directly:
To do so, just drag & drop your .vox onto the Unreal Content Browser. A popup will appear:
You have two options for the colors.
Use Palette
You'll have to provide the Magica Voxel palette you want to use. This palette will be read by the importer, and the data asset colors will be set to the palette colors.
This is the recommended way of doing it if you want colors, as it then allows you to directly paint colors.
Do not use palette
The palette indices will be stored as Single Index. You can then use them in 2 ways:
In your material, sample a palette using the GetSingleIndexData node:
Set your Material Config to Single Index, and use a Basic Material Collection (see Materials). Watch your Message Log Voxel category to see which indices are needed:
Fill these indices in your collection, and use it on your voxel world:
3D Coat Import
The plugin supports importing .rawvox assets from 3D Coat (https://3dcoat.com/).
Just drag & drop them onto the Unreal Content Browser.
OpenVDB
The plugin supports importing OpenVDB files: just drag & drop them onto the content browser.
Since OpenVDB requires RTTI, the VoxelVDB module is disabled at runtime by default: if you wish to use VDB assets in your game, change it from Editor to Runtime in Voxel.uplugin.
Last updated
