VoxelTool

Inherits: RefCounted

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.

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_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
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 )
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 [enum VoxelBuffer.CHANNEL_SDF], will add matter. Useful for building.
  • MODE_REMOVE = 1 --- When editing [enum 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

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.

Sets how do_* functions will behave. This may vary depending on the channel.

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.

Sets which voxel value will be used. This is not relevant when editing VoxelBuffer.CHANNEL_SDF.

Method Descriptions

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.

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.

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.

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.

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 that will be used to lookup mask values.

src_mask_value if voxels have this value in the channel specified for masking, then they won't be pasted.

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.

Sets the raw integer value of a specific voxel on the current channel.

Sets the normalized decimal value of a specific voxel. This should preferably be used when modifying voxels on the SDF channel.

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.

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.

Encodes a 4-integer vector into 16-bit integer voxel data, for use in the INDICES channel.

Generated on Sep 12, 2023