Voxel Data Items

A big limitation of voxel graphs is that you don't have any contextual data: you can add noise, but it's very hard to add a ravine or a cave at a specific position.

To solve that, I've introduced the concept of Data Items: these are data that you can place into your scene and can read back into your graph.

They are extremely generic (just data), so they can be used to create ravines, perlin worms, tunnels using splines, mountains...

Builtin data items are included in /Voxel/VoxelDataItems/

Usage examples are included in /Voxel/Examples/VoxelGraphs/PerlinWorms

Examples

Quick Start

Creating a new data item type

You can create a new data item type by creating a new Voxel Graph Data Item Config

Here you can set the data that your data item will take:

Defining the shape of a data item

Create a new voxel graph. Add a new Data Item Parameters node, and set the corresponding config in its details:

Then, use that data in your graph to create your shape:

Placing the data items

To easily generate data items, a new Voxel Placeable Item Manager class has been added. Create a blueprint inheriting from it:

In that blueprint, override the On Generate and On Clear events. On Generate will be called to generate the items. On Clear will be called to reset the manager (the random seeds etc), allowing to reuse it.

Add a new random stream variable to your graph:

Then add a new Add Data Item node corresponding to your config. This is a custom blueprint node that will have its inputs automatically filled with the config pins:

Then create the following graph.

Start and End are public variables
The Bounds input must contain the data item entirely. Since we use some gradient perturb, we have to extend the bounds given by Start & End a bit.
Make sure to set the Generator property

In On Clear, we need to reset our random stream:

Using the data item in a graph

Create a new voxel graph, and switch your preview to be X Y:

Add a new Data Item Sample, and preview its output pin (by right clicking it):

You will see a black screen: that's because we don't have any data item yet.

In the Voxel World Settings on the left, set your placeable item manager class:

You should now see something like that:

If you change your placeable item manager Start and End config in the preview settings, you should see the shape change:

As you can see, you can very easily iterate on the generation settings that way!

Now, stop previewing the pin, and change the graph to be the following:

You should now see this:

And if you increase the smoothness of the intersection (eg to 50):

Adding the data items to a voxel world

Create a new voxel world, and set its generator to the graph we just created.

You will notice it has no tunnel: to fix that, set its placeable item class, just like in the voxel graph:

You should now see a beautiful tunnel!

Debugging data items

Placeable item managers have access to two special debug functions:

These will draw in both the graph 2D/3D preview & the voxel world!

Make sure your placeable item manager class has the Debug option on

In the 3D preview, you can turn off the Heightmap Mode and set the 2D Preview Color to Material to get this:

The debug is fully 3D, eg:

You can also tick Debug Bounds to check that the bounds you provided when adding the data item are correct:

Perlin Worms

Perlin Worms are a nice way to make complex cave networks. You can read more about them here: http://libnoise.sourceforge.net/examples/worms/

In the plugin, just use the Add Worms function:

It will create a fancy pattern like this:

There are many settings you can tune - check their tooltips for more info!

If the turns are too sharp, you can increase the Smoothness property:

Performance

Data items are spatially hashed by being put into the voxel data octree, so that only nearby items are evaluated.

If you switch the preview mode to Cost:

You will be able to see how cost increases as more data items are sampled:

To improve that, try to make the items bounds as tight as possible.

Storing all the data items in the octree can also end up taking a lot of memory. You can check that using the stat voxelmemory command:

as well as the stat voxelcounters command:

If memory becomes an issue, try increasing voxel.data.MaxPlaceableItemsPerOctree.

Splines

Splines are a powerful way to add tunnels/caves. Both additive and subtractive splines are supported.

To add a spline to your scene, make sure you are using the FlatWorldGenerator and add Voxel Content/Blueprints/VoxelSpline. If you change its channel in its detail panel to Channel 1 it will be additive.

Internally, the flat world generator will do a smooth union with all the data items in the channel 1, and a smooth subtraction & invert with the ones in channel 0. You can configure that in its settings (as well as other stuff like smnoothness):