Voxel Stamps are able to write metadata. Metadata lets you pass around arbitrary information per position. This data can be used in Voxel Graphs to affect the terrain Shape or Surface Types. It can also be passed into materials, and can be queried from C++ and Blueprint for gameplay purposes. It can also be queried by Voxel PCG nodes.

Graphs can be used to write complex values into Metadata.

Metadata is only computed when it's needed for an output. For example, if a Voxel Graph or material queries it. Thousands of stamps writing metadata can exist in your world, but unless the metadata is queried for an output somewhere, they won't have a generation cost.

INFO

Because metadata stamps are only computed when requested, metadata can be used for gameplay purposes (i.e. "is this spot diggable or not") without increasing generation cost.

Assuming the metadata isn't used for a world generation output anywhere (material samples, foliage spawning, etc.), the stamps writing the metadata will only be computed when you query the metadata from your gameplay code or blueprints for specific positions.

Using Metadata to Control Generation

In some cases, you may want to use metadata to control terrain generation; for instances, you may want to apply some extra noise over the entire world based on a NoiseStrength metadata. To do this, you can use the Sample Previous Stamps node. Select it to add metadata outputs in the details panel.

INFO

The Query Metadata node is rarely actually needed. Sample Previous Stamps will almost always do the job more effectively.

When metadata needs to be queried from other places in the stack, Query Metadata nodes can be used. These let you assign a specific layer to query. Note that the layer assigned on the Query Metadata node has to come before the layer the stamp is assigned to. You may need to add a new layer to do this. If so, you likely need to change your Voxel World Layer to Render and layer queries in other places accordingly.

WARNING

Common errors when using metadata in Voxel Graphs:

• Cannot query ...: already queried in the stack. Queried layers: ...
• The Query Metadata node is querying the same layer the stamp is assigned to. Set the layer to an earlier layer, or set the stamp to a later layer. Use a Sample Previous Stamps node instead.

Passing Metadata to Materials

Metadata can very easily be accessed in materials by using the Get Voxel Metadata node.

Note that while this is easy to use, it is not free. Under the hood, the metadata (and a step of indirection) are stored in textures. These textures are generated for any chunk that needs this metadata (automatically determined based on what materials are assigned). Liberal use of metadata in materials can lead to dramatically increased VRAM use. The VRAM used scales directly with the terrain's resolution.