Inherits: VoxelGenerator

Graph-based voxel generator.


Generates voxel data from a graph of per-voxel operations.

The graph must be created, compiled, and only then blocks can be generated.

It can be used with SDF-based smooth terrain, and also blocky terrains.

Warning: methods to modify the graph should only be called from the main thread.


Type Name Default
bool debug_block_clipping false
float sdf_clip_threshold 1.5
int subdivision_size 16
bool use_optimized_execution_map true
bool use_subdivision true
bool use_xz_caching true


Return Signature
void bake_sphere_bumpmap ( Image im, float ref_radius, float sdf_min, float sdf_max )
void bake_sphere_normalmap ( Image im, float ref_radius, float strength )
void clear ( )
Dictionary compile ( )
Vector2 debug_analyze_range ( Vector3 min_pos, Vector3 max_pos ) const
void debug_load_waves_preset ( )
float debug_measure_microseconds_per_voxel ( bool use_singular_queries )
VoxelGraphFunction get_main_function ( ) const


  • node_name_changed( int node_id )

Property Descriptions

  • bool debug_block_clipping = false

When enabled, if the graph outputs SDF data, generated blocks that would otherwise be clipped will be inverted. This has the effect of them showing up as "walls artifacts", which is useful to visualize where the optimization occurs.

  • float sdf_clip_threshold = 1.5

When generating SDF blocks for a terrain, if the range analysis of a block is beyond this threshold, its SDF data will be considered either fully 1, or fully -1. This optimizes memory and processing time.

  • int subdivision_size = 16

When generating SDF blocks for a terrain, and if block size is divisible by this value, range analysis will operate on such subdivision. This allows to optimize away more precise areas. However, it may not be set too small otherwise overhead will outweight the benefits.

  • bool use_optimized_execution_map = true

If enabled, when generating blocks for a terrain, the generator will attempt to skip specific nodes if they are found to have no importance in specific areas.

  • bool use_subdivision = true

If enabled, VoxelGeneratorGraph.subdivision_size will be used.

  • bool use_xz_caching = true

If enabled, the generator will run only once branches of the graph that only depend on X and Z. This is effective when part of the graph generates a heightmap, as this part is not volumetric.

Method Descriptions

Bakes a spherical bumpmap (or heightmap) using SDF output produced by the generator, if any. The bumpmap uses a panorama projection.

ref_radius: radius of the sphere on which heights will be sampled.

strength: strength of produced normals, may default to 1.0.

Bakes a spherical normalmap using SDF output produced by the generator, if any. The normalmap uses a panorama projection. It is assumed the generator produces a spherical shape (like a planet). Such normalmap can be used to add more detail to distant views of a terrain using this generator.

ref_radius: radius of the sphere on which normals will be sampled.

strength: strength of produced normals, may default to 1.0.

Note: an alternative is to use distance normals feature with VoxelLodTerrain.

Erases all nodes and connections from the graph.

Compiles the graph so it can be used to generate blocks.

If it succeeds, the returned result is a dictionary with the following layout:

    "success": true

If it fails, the returned result may contain a message and the ID of a graph node that could be the cause:

    "success": false,
    "node_id": int,
    "message": String

The node ID will be -1 if the error is not about a particular node.

Generated on Sep 12, 2023