VoxelGeneratorGraph

Inherits: VoxelGenerator

Graph-based voxel generator.

Description:

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.

Properties:

Type Name Default
bool debug_block_clipping false
float sdf_clip_threshold 1.5
int subdivision_size 16
TextureMode texture_mode TEXTURE_MODE_MIXEL4 (0)
bool use_optimized_execution_map true
bool use_subdivision true
bool use_xz_caching true

Methods:

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 )
void generate_image_from_sdf ( Image im, Transform3D transform, Vector2 size )
VoxelGraphFunction get_main_function ( ) const
float raycast_sdf_approx ( Vector3 ray_origin, Vector3 ray_end, float stride ) const

Signals:

node_name_changed( int node_id )

(This signal has no documentation)

Enumerations:

enum TextureMode:

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 air, or fully matter (using high constants, positive or negative). This optimizes memory because chunks entirely underground or in the air will have the same value on every voxel. It also saves processing time because SDF calculations (noise etc) are skipped. To turn off this optimization, set it to a high value.

Downside: if you use operations to edit the terrain assuming coherent SDF, they might behave incorrectly at boundaries where the clipping starts to occur. This is notably the case of VoxelTool.grow_sphere.

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.

TextureMode texture_mode = TEXTURE_MODE_MIXEL4 (0)

Sets which voxel format will be produced by texture outputs, if present.

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, 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

void bake_sphere_bumpmap( Image im, float ref_radius, float sdf_min, float sdf_max )

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.

void bake_sphere_normalmap( Image im, float ref_radius, float strength )

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.

void clear( )

Erases all nodes and connections from the graph.

Dictionary compile( )

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.

Vector2 debug_analyze_range( Vector3 min_pos, Vector3 max_pos )

(This method has no documentation)

void debug_load_waves_preset( )

(This method has no documentation)

float debug_measure_microseconds_per_voxel( bool use_singular_queries )

(This method has no documentation)

void generate_image_from_sdf( Image im, Transform3D transform, Vector2 size )

Genereates SDF data within a plane centered on the given transform spanning its X and Y axes, and stores results in pixels of the image. Samples are centered on pixels.

The image should preferably have a 32-bit float format, and must not be compressed.

VoxelGraphFunction get_main_function( )

Gets the graph used for generation.

float raycast_sdf_approx( Vector3 ray_origin, Vector3 ray_end, float stride )

Generates values along a ray to find the first one where SDF &lt 0.0, and return distance along the ray. If no hit is found, returns -1.0.

This is an approximation: the error margin of the returned value will be up to the given stride.

The longer the distance, the more expensive it is.

The lower the stride, the more expensive and accurate it is.

Generated on Jan 26, 2026