VoxelTool¶

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
int	channel
int	eraser_value
int	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
void	copy ( Vector3i src_pos, VoxelBuffer dst_buffer, int channels_mask )
void	do_box ( Vector3i begin, Vector3i end )
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 )
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_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

Property Descriptions¶

int 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 VoxelTool.MODE_REMOVE mode.

int 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 VoxelBuffer.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¶

(This property has no documentation)

float texture_falloff¶

(This property has no documentation)

int texture_index¶

(This property has no documentation)

float texture_opacity¶

(This property has no documentation)

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.

void copy( Vector3i src_pos, VoxelBuffer dst_buffer, int channels_mask )¶

Copies voxels in a box and stores them in the passed buffer.

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 0xff if you want them all.

void do_box( Vector3i begin, Vector3i end )¶

Operate on a rectangular cuboid section of the terrain. begin and end are inclusive. Choose operation and which voxel to use by setting value and mode before calling this function.

void do_path( PackedVector3Array points, PackedFloat32Array radii )¶

(This method has no documentation)

void do_point( Vector3i pos )¶

(This method has no documentation)

void do_sphere( Vector3 center, float radius )¶

(This method has no documentation)

int get_voxel( Vector3i pos )¶

(This method has no documentation)

float get_voxel_f( Vector3i pos )¶

(This method has no documentation)

Variant get_voxel_metadata( Vector3i pos )¶

(This method has no documentation)

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.

bool is_area_editable( AABB box )¶

(This method has no documentation)

Color normalize_color( Color _unnamed_arg0 )¶

(This method has no documentation)

void paste( Vector3i dst_pos, VoxelBuffer src_buffer, int channels_mask )¶

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 0xff 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 0xff 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 0xff 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.

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_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 )¶

(This method has no documentation)

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 Apr 06, 2024