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
_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 = 11
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. 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 VoxelLodTerrain.STREAMING_SYSTEM_LEGACY_OCTREE.
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 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_viewer_clipboxes = false¶
(This property has no documentation)
bool debug_draw_volume_bounds = 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 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.
For further control of LODs beyond 0, see VoxelLodTerrain.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.
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 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.
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 VoxelLodTerrain.streaming_system is set to VoxelLodTerrain.STREAMING_SYSTEM_CLIPBOX. In other cases, VoxelLodTerrain.lod_distance is used.
To control LOD 0, see VoxelLodTerrain.lod_distance.
int streaming_system = 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 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 )¶
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( int 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( int 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)
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( )¶
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( 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 Apr 06, 2024