VoxelLodTerrain¶
Inherits: VoxelNode
Voxel volume using variable level of detail.
Description:¶
Renders large terrain using variable level of details. This is preferably used with smooth meshing such as VoxelMesherTransvoxel. Blocky meshers can be used, but currently don't have as much support for LOD.
Properties:¶
Methods:¶
Enumerations:¶
enum ProcessCallback:
- PROCESS_CALLBACK_IDLE = 0 --- The node will use
_processfor the part of its logic running on the main thread. - PROCESS_CALLBACK_PHYSICS = 1 --- The node will use
_physics_processfor the part of its logic running on the main thread. - PROCESS_CALLBACK_DISABLED = 2 --- The node will not update. Use with caution!
enum DebugDrawFlag:
- DEBUG_DRAW_OCTREE_NODES = 0
- DEBUG_DRAW_OCTREE_BOUNDS = 1
- DEBUG_DRAW_MESH_UPDATES = 2
- DEBUG_DRAW_EDIT_BOXES = 3
- DEBUG_DRAW_VOLUME_BOUNDS = 4
- DEBUG_DRAW_EDITED_BLOCKS = 5
- DEBUG_DRAW_MODIFIER_BOUNDS = 6
- DEBUG_DRAW_ACTIVE_MESH_BLOCKS = 7
- DEBUG_DRAW_VIEWER_CLIPBOXES = 8
- DEBUG_DRAW_LOADED_VISUAL_AND_COLLISION_BLOCKS = 9
- DEBUG_DRAW_ACTIVE_VISUAL_AND_COLLISION_BLOCKS = 10
- DEBUG_DRAW_FLAGS_COUNT = 12
enum StreamingSystem:
- STREAMING_SYSTEM_LEGACY_OCTREE = 0 --- Loads chunks around the viewer in a spherical pattern. Does not support multiple viewers. Does not support collision-only viewers. Does not support "no viewers" (will assume origin instead). Does not support per-viewer view distance, only view_distance is used. This was the first system to be implemented, therefore it remains available as default for compatibility.
- STREAMING_SYSTEM_CLIPBOX = 1 --- Loads chunks around the viewer in concentric boxes. Supports multiple viewers and collision-only viewers. This is a better system for multiplayer streaming. Due to simplifications, chunk locations at each LOD might be less optimal than STREAMING_SYSTEM_LEGACY_OCTREE.
Property Descriptions¶
bool cache_generated_blocks = false¶
If enabled, streaming the terrain will keep generated voxel data in memory around viewers, even if it wasn't edited. This can speedup voxel queries on non-edited areas and allows VoxelStream.save_generator_output to work, but increases memory usage significantly.
This option is not supported when full_load_mode_enabled is enabled.
int collision_layer = 1¶
Collision layer used by generated colliders. Check Godot documentation for more information.
int collision_lod_count = 0¶
How many LOD levels are set to generate colliders, starting from LOD 0. Setting this property to 0 means all LODs have collision.
float collision_margin = 0.04¶
Collision margin used by generated colliders. Note that it may depend on which physics engine is used under the hood, as some don't use margins.
int collision_mask = 1¶
Collision mask used by generated colliders. Check Godot documentation for more information.
int collision_update_delay = 0¶
How long to wait before updating colliders after an edit, in milliseconds. Collider generation is expensive, so the intent is to smooth it out.
bool debug_draw_active_mesh_blocks = false¶
(This property has no documentation)
bool debug_draw_active_visual_and_collision_blocks = false¶
(This property has no documentation)
bool debug_draw_edit_boxes = false¶
(This property has no documentation)
bool debug_draw_edited_blocks = false¶
(This property has no documentation)
bool debug_draw_enabled = false¶
(This property has no documentation)
bool debug_draw_loaded_visual_and_collision_blocks = false¶
(This property has no documentation)
bool debug_draw_mesh_updates = false¶
(This property has no documentation)
bool debug_draw_modifier_bounds = false¶
(This property has no documentation)
bool debug_draw_octree_bounds = false¶
(This property has no documentation)
bool debug_draw_octree_nodes = false¶
(This property has no documentation)
bool debug_draw_shadow_occluders = false¶
(This property has no documentation)
bool debug_draw_viewer_clipboxes = false¶
(This property has no documentation)
bool debug_draw_volume_bounds = false¶
(This property has no documentation)
bool debug_draw_voxel_metadata = false¶
(This property has no documentation)
bool full_load_mode_enabled = false¶
If enabled, data streaming will be turned off, and all voxel data will be loaded from the stream into memory.
This removes several constraints, such as being able to edit anywhere and allowing distant normalmaps to include edited regions. This comes at the expense of more memory usage. However, only edited regions use memory, so in practice it can be good enough.
bool generate_collisions = true¶
If enabled, chunked colliders will be generated from meshes.
int lod_count = 4¶
How many LOD levels to use. This should be tuned alongside lod_distance: if you want to see very far, you need more LOD levels. This allows blocks to become larger the further away they are, to keep their numbers to an acceptable amount. In contrast, too few LOD levels means regions far away will have to use too many small blocks, which can affect performance.
float lod_distance = 48.0¶
How far LOD 0 extends from the viewer. Each parent LOD will extend twice as far as their children LOD levels. When full_load_mode_enabled is disabled, this also defines how far edits are allowed.
For further control of LODs beyond 0, see secondary_lod_distance.
float lod_fade_duration = 0.0¶
When set greater than 0, enables LOD fading. When mesh blocks get split/merged as level of detail changes, they will fade to make the transition less noticeable (or at least more pleasant). This feature requires to use a specific shader, check the online documentation or examples for more information.
Material material¶
Material used for the surface of the volume. The main usage of this node is with smooth voxels, which means if you want more than one "material" on the ground, you need to use splatmapping techniques with a shader. In addition, many features require shaders to work properly. Check the online documentation or examples for more information.
Note: if you use a ShaderMaterial, it will be instanced on every chunk in order to support per-chunk/LOD features, so dynamic changes done to parameters will not apply. You can use global uniforms to workaround this limitation.
int mesh_block_size = 16¶
Size of meshes used for chunks of this volume, in voxels. Can only be set to either 16 or 32. Using 32 is expected to increase rendering performance, and slightly increase the cost of edits.
int normalmap_begin_lod_index = 2¶
From which LOD index normalmaps will be generated. There won't be normalmaps below this index.
bool normalmap_enabled = false¶
Enables generation of distant normalmaps. This is a feature used with smooth terrain only (SDF). It is an expensive feature but allows to bring a lot more detail to distant ground.
This feature requires to use a specific shader, check the online documentation or examples for more information.
int normalmap_max_deviation_degrees = 60¶
(This property has no documentation)
bool normalmap_octahedral_encoding_enabled = false¶
Enables octahedral compression of normalmaps, which reduces memory usage caused by distant normalmaps by about 33%, with some impact on visual quality. Your shader may be modified accordingly to decode them.
int normalmap_tile_resolution_max = 8¶
Maximum resolution of tiles in distant normalmaps.
int normalmap_tile_resolution_min = 4¶
Minimum resolution of tiles in distant normalmaps.
This is the resolution at which normalmaps will begin with, at the LOD level defined in normalmap_begin_lod_index. Resolutions will double at each LOD level, until they reach normalmap_tile_resolution_max.
bool normalmap_use_gpu = false¶
Enables GPU detail normalmaps generation, which can speed it up. This is only valid for generators that support it. Vulkan is required.
bool run_stream_in_editor = true¶
Sets wether the generator and the stream will run in the editor. This setting may turn on automatically if either contain a script, as multithreading can clash with script reloading in unexpected ways.
float secondary_lod_distance = 48.0¶
Controls the size of each LOD above LOD 0, in voxels relative to those LODs (voxels of LOD N are twice as big than LOD N-1). Higher values allow to see further away before detail are decimated, but is more expensive.
Note that it will not necessarily be respected accurately, and will rather be used as a target minimum distance.
This is only used when streaming_system is set to STREAMING_SYSTEM_CLIPBOX. In other cases, lod_distance is used.
To control LOD 0, see lod_distance.
StreamingSystem streaming_system = STREAMING_SYSTEM_LEGACY_OCTREE (0)¶
Selects the underlying algorithm used to determine when to load and unload chunks around viewers as they move around.
bool threaded_update_enabled = false¶
When enabled, this node will run a large part of its update cycle in a separate thread. Otherwise, it will run on the main thread.
bool use_gpu_generation = false¶
Enables GPU block generation, which can speed it up. This is only valid for generators that support it. Vulkan is required.
int view_distance = 512¶
Maximum distance viewers can have. If a viewer has a larger distance, it will be clamped. Note that this is only a hint and not an exact boundary. Terrain may load within that distance, but can continue beyond it, rounding up to block size of the biggest LOD.
If your terrain size is finite (like an island or planet) and you want to keep it in view, you may want to set this value to a very large number. This is mainly useful for infinite terrains where a cap is desired.
AABB voxel_bounds = AABB(-536870900, -536870900, -536870900, 1073741800, 1073741800, 1073741800)¶
Bounds within which volume data can exist (loaded or not), in voxels. By default, it is pseudo-infinite. If you make a planet, island or some sort of arena, you may want to choose a finite size.
Note, because this volume uses chunks with LOD, these bounds will snap to the closest chunk boundary.
Method Descriptions¶
int debug_dump_as_scene( String path, bool include_instancer )¶
Saves the current state of the terrain as a Godot scene file. Can be used to inspect meshes and instances in more detail in the editor.
int debug_get_data_block_count( )¶
Get how many voxel data chunks are currently loaded
Dictionary debug_get_data_block_info( Vector3 block_pos, int lod )¶
Gets some debug information about a specific voxel data chunk.
{
"loading_state": int,
}
bool debug_get_draw_flag( DebugDrawFlag flag_index )¶
Gets whether a specific debug drawing flag is enabled.
This method always returns false in exported games.
int debug_get_mesh_block_count( )¶
Gets how many meshes the terrain currently has.
Dictionary debug_get_mesh_block_info( Vector3 block_pos, int lod )¶
Gets some debug information about a specific mesh.
{
"transition_mask": int,
"recomputed_transition_mask": int,
"loaded": bool,
"meshed": bool,
"mesh_state": int,
"visible": bool,
"visual_active": bool,
"collision_active": bool
}
Array debug_get_octrees_detailed( )¶
Gets debug information about the grid of octrees used to stream the terrain at multiple levels of detail.
The returned array contains alternating Vector3i and Array values, where each pair corresponds to one octree at a specific position:
[
Vector3i,
Array,
Vector3i,
Array,
...
]
The array after positions contains info about one octree:
[
int (node state),
null or Array (children info)
]
When children info is not null, it contains 8 arrays structured the same way, and may be recursively traversed to obtain the state of every node of the octree.
Array debug_print_sdf_top_down( Vector3i center, Vector3i extents )¶
Captures a top-down representation of the signed distance field (SDF) at multiple LOD levels within a specific area. The returned array contains an image for each LOD.
Array debug_raycast_mesh_block( Vector3 origin, Vector3 dir )¶
Gets the non-empty mesh chunk positions from a rough world-space ray, up to a distance of 256 units. All LODs are checked.
The returned array contains:
[
{
"position": Vector3i,
"lod": int
},
...
]
void debug_set_draw_flag( DebugDrawFlag flag_index, bool enabled )¶
Sets a specific debug drawing flag. Note that debug drawing must also be enabled for it to be visible.
This method does nothing in exported games.
int get_data_block_region_extent( )¶
(This method has no documentation)
int get_data_block_size( )¶
Gets the size of one cunic data block in voxels.
VoxelGenerator get_normalmap_generator_override( )¶
(This method has no documentation)
int get_normalmap_generator_override_begin_lod_index( )¶
(This method has no documentation)
ProcessCallback get_process_callback( )¶
Gets which callback is used to run the main thread update of this node.
Dictionary get_statistics( )¶
Gets debug information about how much time is spent processing the terrain.
The returned dictionary has the following structure:
{
"time_detect_required_blocks": int,
"time_request_blocks_to_load": int,
"time_process_load_responses": int,
"time_request_blocks_to_update": int,
"time_process_update_responses": int,
"remaining_main_thread_blocks": int,
"dropped_block_loads": int,
"dropped_block_meshs": int,
"updated_blocks": int,
"blocked_lods": int
}
Times are in microseconds.
VoxelTool get_voxel_tool( )¶
Creates an instance of VoxelTool bound to this volume. Allows to query and edit voxels.
bool is_area_meshed( AABB area_in_voxels, int lod_index )¶
Returns true if the area has been processed by meshing. It does not mean the area actually contains a mesh.
Returns false if the area has not been processed by meshing (therefore it is unknown whethere there should be a mesh here or not).
When streaming terrain, this can be used to determine if an area has fully "loaded", in case the game relies meshes or mesh colliders.
VoxelSaveCompletionTracker save_modified_blocks( )¶
Requests saving of all modified voxels. Saving is asynchronous and will complete some time in the future. If the game quits, the engine will ensure saving tasks get completed before the application shuts down.
Use the returned tracker object to know when saving has completed. However, saves occurring after calling this method won't be tracked by this object.
Note that blocks getting unloaded as the viewer moves around can also trigger saving tasks, independently from this function.
void set_normalmap_generator_override( VoxelGenerator generator_override )¶
(This method has no documentation)
void set_normalmap_generator_override_begin_lod_index( int lod_index )¶
(This method has no documentation)
void set_process_callback( ProcessCallback mode )¶
Sets which process callback is used to run the main thread update of this node. By default, it uses _process.
Vector3i voxel_to_data_block_position( Vector3 voxel_position, int lod_index )¶
Converts a voxel position into a data block position for a specific LOD index.
Vector3i voxel_to_mesh_block_position( Vector3 voxel_position, int lod_index )¶
Converts a voxel position into a mesh block position for a specific LOD index.
Generated on Jan 26, 2026