VoxelToolTerrain¶

Implementation of VoxelTool specialized for uses on VoxelTerrain.

Description:¶

Functions in this class are specific to VoxelTerrain. For generic functions, you may also check VoxelTool.

It's not a class to instantiate alone, you may get it from VoxelTerrain using the get_voxel_tool() method.

Methods:¶

Return	Signature
void	do_hemisphere ( Vector3 center, float radius, Vector3 flat_direction, float smoothness=0.0 )
void	for_each_voxel_metadata_in_area ( AABB voxel_area, Callable callback )
void	run_blocky_random_tick ( AABB area, int voxel_count, Callable callback, int batch_count=16, int tags_mask=4294967295 )

Method Descriptions¶

void do_hemisphere( Vector3 center, float radius, Vector3 flat_direction, float smoothness=0.0 )¶

Operates on a hemisphere, where flat_direction is pointing away from the flat surface (like a normal). smoothness determines how the flat part blends with the rounded part, with higher values producing softer more rounded edge.

void for_each_voxel_metadata_in_area( AABB voxel_area, Callable callback )¶

Executes a function for each voxel holding metadata in the given area.

The given callback takes two arguments: voxel position (Vector3i), voxel metadata (Variant).

IMPORTANT: inserting new or removing metadata from inside this function is not allowed.

void run_blocky_random_tick( AABB area, int voxel_count, Callable callback, int batch_count=16, int tags_mask=4294967295 )¶

Picks random voxels within the specified area. If voxel models have VoxelBlockyModel.random_tickable set to true and VoxelBlockyModel.tags_mask matches any bit in tags_mask, executes a function on them. This only works for terrains using VoxelMesherBlocky.

The given callback takes two arguments: voxel position (Vector3i), voxel value (int).

The purpose of batch_count is to optimize the picking process through the internal data structure. The algorithm goes as follows: voxel_count is divided in batches of length batch_count. For each batch, a random block intersecting area is chosen, and batch_count voxels are picked at random inside of it. If voxel_count is not divisible by batch_count, an extra block will be picked to do the remainder.

batch can bias randomness by concentrating picks in specific blocks, but if this function is used every frame over time, that bias should average out. If you want no bias at all, set batch_count to 1.

Generated on Jan 26, 2026