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.

Properties:¶

Methods:¶

Enumerations:¶

enum ProcessCallback:

• PROCESS_CALLBACK_IDLE = 0 --- The node will use _process for the part of its logic running on the main thread.
• PROCESS_CALLBACK_PHYSICS = 1 --- The node will use _physics_process for 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_FLAGS_COUNT = 7

Property Descriptions¶

• 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.

• 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 full_load_mode_enabled = false

If enabled, data streaming will be turned off, and all voxel data will be loaded from the VoxelLodTerrain.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 VoxelLodTerrain.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 VoxelLodTerrain.full_load_mode_enabled is disabled, this also defines how far edits are allowed.

• 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.

• 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

• 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 VoxelLodTerrain.normalmap_begin_lod_index. Resolutions will double at each LOD level, until they reach VoxelLodTerrain.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 VoxelLodTerrain.generator and the VoxelLodTerrain.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.

• 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 where terrain will load around viewers. If your terrain size is finite (like for a 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.

• AABB voxel_bounds = AABB(-5.36871e+08, -5.36871e+08, -5.36871e+08, 1.07374e+09, 1.07374e+09, 1.07374e+09)

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 )

• int debug_get_data_block_count( )

• Dictionary debug_get_data_block_info( Vector3 block_pos, int lod )

• bool debug_get_draw_flag( int flag_index )

• int debug_get_mesh_block_count( )

• Dictionary debug_get_mesh_block_info( Vector3 block_pos, int lod )

• Array debug_get_octrees_detailed( )

• bool debug_is_draw_enabled( )

• Array debug_print_sdf_top_down( Vector3i center, Vector3i extents )

• Array debug_raycast_mesh_block( Vector3 origin, Vector3 dir )

• void debug_set_draw_enabled( bool enabled )

• void debug_set_draw_flag( int flag_index, bool enabled )

• int get_data_block_region_extent( )

• int get_data_block_size( )

Gets the size of one cunic data block in voxels.

• VoxelGenerator get_normalmap_generator_override( )

• int get_normalmap_generator_override_begin_lod_index( )

• int 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
}

• VoxelTool get_voxel_tool( )

Gets 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.

• void 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.

There is currently no reliable way to tell if saving has completed.

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 )

• void set_normalmap_generator_override_begin_lod_index( int lod_index )

• void set_process_callback( int 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 Sep 12, 2023