VoxelTool¶
Inherits: RefCounted
Inherited by: VoxelToolBuffer, VoxelToolLodTerrain, VoxelToolMultipassGenerator, VoxelToolTerrain
Helper class to easily access and modify voxels
Description:¶
Abstract interface to access and edit voxels. It allows accessing individual voxels, or doing bulk operations such as carving large chunks or copy/paste boxes.
It's not a class to instantiate alone, you may get it from the voxel objects you want to work with, because it has multiple derived implementations.
By default, if an operation overlaps a non-editable area (if not loaded yet for example), the operation will be cancelled. This behavior may vary in derived classes.
Properties:¶
| Type | Name | Default |
|---|---|---|
| ChannelId | channel | |
| int | eraser_value | |
| Mode | mode | |
| float | sdf_scale | |
| float | sdf_strength | |
| float | texture_falloff | |
| int | texture_index | |
| float | texture_opacity | |
| int | value |
Methods:¶
| Return | Signature |
|---|---|
| int | color_to_u16 ( Color color ) static |
| int | color_to_u16_weights ( Color _unnamed_arg0 ) static |
| int | color_to_u32 ( Color color ) static |
| void | copy ( Vector3i src_pos, VoxelBuffer dst_buffer, int channels_mask=255, bool with_metadata=true ) |
| void | do_box ( Vector3i begin, Vector3i end ) |
| void | do_mesh ( VoxelMeshSDF mesh_sdf, Transform3D transform, float isolevel=0.0 ) |
| void | do_path ( PackedVector3Array points, PackedFloat32Array radii ) |
| void | do_point ( Vector3i pos ) |
| void | do_sphere ( Vector3 center, float radius ) |
| int | get_voxel ( Vector3i pos ) |
| float | get_voxel_f ( Vector3i pos ) |
| Variant | get_voxel_metadata ( Vector3i pos ) const |
| void | grow_sphere ( Vector3 sphere_center, float sphere_radius, float strength ) |
| bool | is_area_editable ( AABB box ) const |
| Color | normalize_color ( Color _unnamed_arg0 ) static |
| void | paste ( Vector3i dst_pos, VoxelBuffer src_buffer, int channels_mask=255 ) |
| void | paste_masked ( Vector3i dst_pos, VoxelBuffer src_buffer, int channels_mask, int mask_channel, int mask_value ) |
| void | paste_masked_writable_list ( Vector3i position, VoxelBuffer voxels, int channels_mask, int src_mask_channel, int src_mask_value, int dst_mask_channel, PackedInt32Array dst_writable_list ) |
| VoxelRaycastResult | raycast ( Vector3 origin, Vector3 direction, float max_distance=10.0, int collision_mask=4294967295 ) |
| void | set_raycast_normal_enabled ( bool enabled ) |
| void | set_voxel ( Vector3i pos, int v ) |
| void | set_voxel_f ( Vector3i pos, float v ) |
| void | set_voxel_metadata ( Vector3i pos, Variant meta ) |
| void | smooth_sphere ( Vector3 sphere_center, float sphere_radius, int blur_radius ) |
| Vector4i | u16_indices_to_vec4i ( int _unnamed_arg0 ) static |
| Color | u16_weights_to_color ( int _unnamed_arg0 ) static |
| int | vec4i_to_u16_indices ( Vector4i _unnamed_arg0 ) static |
Enumerations:¶
enum Mode:
- MODE_ADD = 0 --- When editing VoxelBuffer.CHANNEL_SDF, will add matter. Useful for building.
- MODE_REMOVE = 1 --- When editing VoxelBuffer.CHANNEL_SDF, will subtract matter. Useful for digging.
- MODE_SET = 2 --- Replace voxel values without any blending. Useful for blocky voxels.
- MODE_TEXTURE_PAINT = 3 --- When editing VoxelBuffer.CHANNEL_SDF in smooth Terrain, enables texture painting. The value of texture_index will be added to texture indices of the affected voxels. The texture's weight will be blended based on the values of texture_falloff and texture_opacity. Results will differ depending on which texturing mode is used by the mesher.
Property Descriptions¶
ChannelId channel¶
Set which channel will be edited. When used on a terrain node, it will default to the first available channel, based on the stream and generator.
int eraser_value¶
Sets which value will be used to erase voxels when editing the VoxelBuffer.CHANNEL_TYPE channel in MODE_REMOVE mode. Only relevant for blocky voxels.
Mode mode¶
Sets how do_* functions will behave. This may vary depending on the channel.
float sdf_scale¶
When working with smooth voxels, applies a scale to the signed distance field. A high scale (1 or higher) will tend to produce blocky results, and a low scale (below 1, but not too close to zero) will tend to be smoother.
This is related to the Depth configuration on voxels. For 8-bit and 16-bit, there is a limited range of values the Signed Distance Field can take, and by default it is clamped to -1..1, so the gradient can only range across 2 voxels. But when LOD is used, it is better to stretch that range over a longer distance, and this is achieved by scaling SDF values.
float sdf_strength¶
When editing VoxelBuffer.CHANNEL_SDF of smooth Terrains in MODE_ADD or MODE_REMOVE, determines the interpolation phase between current values and values set by the tool. Can be interpreted as the amount of "matter" added or subtracted.
float texture_falloff¶
Range [0.001..1.0]. Determines texture blending strength when tool is set to MODE_TEXTURE_PAINT. Lower values produce sharper transitions. Can be compared to brush softness in an image editing program. This is only relevant with smooth voxels and texturing modes that support long gradients.
int texture_index¶
Index of the texture used in smooth voxel texture painting mode. The choice of this index depends on the way you setup rendering of textured voxel meshes (for example, layer index in a texture array).
float texture_opacity¶
Range [0.0..1.0]. Determines the maximum weight of a texture_index when tool is set to MODE_TEXTURE_PAINT. Can be compared to brush opacity in an image editing program.
int value¶
Sets which voxel value will be used. This is not relevant when editing VoxelBuffer.CHANNEL_SDF.
Method Descriptions¶
int color_to_u16( Color color )¶
Encodes normalized 4-float color into 16-bit integer data. It is used with the COLOR channel, in cases where the channel represents direct colors (without using a palette).
int color_to_u16_weights( Color _unnamed_arg0 )¶
Encodes normalized 4-float color into 16-bit integer data, for use with the WEIGHTS channel.
int color_to_u32( Color color )¶
Encodes normalized 4-float color into 32-bit integer data, for use with the COLOR channel.
void copy( Vector3i src_pos, VoxelBuffer dst_buffer, int channels_mask=255, bool with_metadata=true )¶
Copies voxels in a box and stores them in the passed buffer. The source format will overwrite the destination.
src_pos is the lowest corner of the box, and its size is determined by the size of dst_buffer.
channels_mask is a bitmask where each bit tells which channels will be copied. Example: 1 << VoxelBuffer.CHANNEL_SDF to get only SDF data. Use VoxelBuffer.ALL_CHANNELS_MASK if you want them all.
void do_box( Vector3i begin, Vector3i end )¶
Operate on a rectangular cuboid section of the terrain.
With blocky voxels, begin and end are inclusive.
With smooth voxels, end is exclusive.
You may choose which operation to do before calling this function, by setting mode. With blocky voxels, you may also set value to choose which voxel ID to use.
void do_mesh( VoxelMeshSDF mesh_sdf, Transform3D transform, float isolevel=0.0 )¶
Applies the given mesh shape to the terrain. The model must be baked into a signed distance field with VoxelMeshSDF. transform may be used to position, rotate and scale the model. Non-uniform scale might introduce artifacts. isolevel is a distance that inflates or contracts the model if increased or decreased respectively. Quality depends on resolution of the model's SDF, and performance will be lower than primitive shapes such as do_sphere.
void do_path( PackedVector3Array points, PackedFloat32Array radii )¶
Traces a "tube" defined by a list of points, each having a corresponding radius to control the width of the tube at each point. The begin and end of the path is rounded. This is equivalent to placing/carving multiple connected capsules with varying top/bottom radius. The path is not using bezier or splines, each point is connected linearly to the next. If you need more smoothness, you may add points to areas that need them. The more points, the slower it is.
void do_point( Vector3i pos )¶
Operates on a single voxel.
You may choose which operation to do before calling this function, by setting mode. With blocky voxels, you may also set value to choose which voxel ID to use.
This function is not well adapted to smooth voxels, and can introduce blockyness.
void do_sphere( Vector3 center, float radius )¶
Operate on voxels within a sphere.
You may choose which operation to do before calling this function, by setting mode. With blocky voxels, you may also set value to choose which voxel ID to use.
int get_voxel( Vector3i pos )¶
Gets data from voxel at pos coordinates. The returned value will be an unsigned integer. The meaning of the value depends on channel the tool is set to.
When using VoxelBuffer.CHANNEL_SDF for smooth voxels, the returned value will be an encoded value, so you may use get_voxel_f to get a float value instead.
float get_voxel_f( Vector3i pos )¶
Gets data from voxel at pos coordinates, interpreting it as a floating-point SDF value. This is recommended to query the VoxelBuffer.CHANNEL_SDF channel for smooth voxels.
Variant get_voxel_metadata( Vector3i pos )¶
Gets arbitrary data attached to a specific voxel.
void grow_sphere( Vector3 sphere_center, float sphere_radius, float strength )¶
Adds/removes (depending on mode) a value to/from all voxels within a sphere. Added/removed value will be equal to strength at the center of the sphere, and decreases linearly to zero at the surface of the sphere. Voxels outside the sphere will not be affected.
sphere_center is position in the terrain that will be smoothed out.
sphere_radius radius of a sphere from the center where voxel values will be affected. Should be greater than zero.
strength value that controls maximal value that will be added/removed to/from voxels. Suggested range is [0, 10].
Note 1: This is currently implemented only for terrain that uses SDF data (smooth voxels).
Note 2: This is meant to be analogous to Surface tool from Unreal Engine Voxel Plugin.
Note 3: This method assumes terrain SDF is coherent. If it isn't, you may notice differences in speeds at which terrain erodes or grows. For example, some generators fallback to a constant SDF when far away from the surface in order to speed up calculations (see VoxelGeneratorGraph.sdf_clip_threshold).
Note 4: If you want to use this method to dig terrain "smoothly" by calling it every frame, an alternative is to use do_sphere but instead of the center being on the surface, move it back by about 0.95% of the radius so only a small fraction of the sphere will penetrate, digging a hole progressively.
bool is_area_editable( AABB box )¶
Returns true if the specified voxel area can be edited. This can also be interpreted as the area being "loaded". Note: when using LOD, only the nearest LOD (0) is editable. Other factors can influence whether an area is editable or not, such as streaming mode or terrain bounds.
Color normalize_color( Color _unnamed_arg0 )¶
A helper method to set the sum of channels of the Color to 1.
void paste( Vector3i dst_pos, VoxelBuffer src_buffer, int channels_mask=255 )¶
Paste voxels in a box from the given buffer at a specific location.
dst_pos is the lowest corner of the box, and its size is determined by the size of src_buffer.
channels_mask is a bitmask where each bit tells which channels will be modified. Example: 1 << VoxelBuffer.CHANNEL_SDF only write SDF data. Use VoxelBuffer.ALL_CHANNELS_MASK if you want them all.
void paste_masked( Vector3i dst_pos, VoxelBuffer src_buffer, int channels_mask, int mask_channel, int mask_value )¶
Paste voxels in a box from the given buffer at a specific location. Voxels having a specific value in a mask channel will not be pasted.
dst_pos is the lowest corner of the box, and its size is determined by the size of src_buffer.
channels_mask is a bitmask where each bit tells which channels will be modified. Example: 1 << VoxelBuffer.CHANNEL_SDF only write SDF data. Use VoxelBuffer.ALL_CHANNELS_MASK if you want them all.
src_mask_channel channel from the source buffer that will be used to lookup mask values.
src_mask_value if voxels of the source buffer have this value in the channel specified for masking, then they won't be pasted.
void paste_masked_writable_list( Vector3i position, VoxelBuffer voxels, int channels_mask, int src_mask_channel, int src_mask_value, int dst_mask_channel, PackedInt32Array dst_writable_list )¶
Paste voxels in a box from the given buffer at a specific location. Voxels having a specific value in a mask channel of the source buffer will not be pasted, and existing voxels at the destination will only be modified if they have specific values.
dst_pos is the lowest corner of the box, and its size is determined by the size of src_buffer.
channels_mask is a bitmask where each bit tells which channels will be modified. Example: 1 << VoxelBuffer.CHANNEL_SDF only write SDF data. Use VoxelBuffer.ALL_CHANNELS_MASK if you want them all.
src_mask_channel channel from the source buffer that will be used to lookup mask values.
src_mask_value if voxels of the source buffer have this value in the channel specified for masking, then they won't be pasted.
dst_mask_channel channel from the destination that will be used to select writable voxels.
dst_writable_list List of values the destination voxels must have in order to be written to. Values in that list must be between 0 and 65535. A very large amount of values can also affect performance.
VoxelRaycastResult raycast( Vector3 origin, Vector3 direction, float max_distance=10.0, int collision_mask=4294967295 )¶
Runs a voxel-based raycast to find the first hit from an origin and a direction. Coordinates are in world space.
Returns a result object if a voxel got hit, otherwise returns null.
This is useful when colliders cannot be relied upon. It might also be faster (at least at short range), and is more precise to find which voxel is hit. It internally uses the DDA algorithm.
collision_mask is currently only used with blocky voxels. It is combined with VoxelBlockyModel.collision_mask to decide which voxel types the ray can collide with.
void set_raycast_normal_enabled( bool enabled )¶
Sets whether raycast will compute hit normals. This is true by default.
void set_voxel( Vector3i pos, int v )¶
Sets the raw integer value of a specific voxel on the current channel.
void set_voxel_f( Vector3i pos, float v )¶
Sets the signed distance field (SDF) value a specific voxel. This should preferably be used on the SDF channel.
void set_voxel_metadata( Vector3i pos, Variant meta )¶
Attaches arbitrary data on a specific voxel. Old data is replaced. Passing null will erase metadata.
If the underlying voxels can be saved, this metadata will also be saved, so make sure the data supports serialization (i.e you can't put nodes or arbitrary objects in it).
void smooth_sphere( Vector3 sphere_center, float sphere_radius, int blur_radius )¶
Smoothens out terrain by performing box blur in a spherical area. Strength will be maximal at the center of the sphere, and decreases linearly to zero at the surface of the sphere. Voxels outside the sphere will not be affected.
sphere_center is position in the terrain that will be smoothed out.
sphere_radius radius of a sphere from the center where voxel values will be affected. Should be greater than zero.
blur_radius half the box blur length that will be sampled to calculate average voxel values. Higher values results in more aggressive smoothing. Should be at least 1.
Note 1: This is currently implemented only for terrain that uses SDF data (smooth voxels).
Note 2: Beware of using high sphere_radius and high blur_radius as the performance can drop quickly if this is called 60 times a second.
Vector4i u16_indices_to_vec4i( int _unnamed_arg0 )¶
Decodes raw voxel integer data from the INDICES channel into a 4-integer vector.
Color u16_weights_to_color( int _unnamed_arg0 )¶
Decodes raw voxel integer data from the WEIGHTS channel into a normalized 4-float color.
int vec4i_to_u16_indices( Vector4i _unnamed_arg0 )¶
Encodes a 4-integer vector into 16-bit integer voxel data, for use in the INDICES channel.
Generated on Jan 26, 2026