VoxelNode¶
Inherits: Node3D
Inherited by: VoxelLodTerrain, VoxelTerrain
Base class for voxel volumes.
Properties:¶
| Type | Name | Default |
|---|---|---|
| ShadowCastingSetting | cast_shadow | 1 |
| VoxelFormat | format | |
| VoxelGenerator | generator | |
| GIMode | gi_mode | 0 |
| VoxelMesher | mesher | |
| int | render_layers_mask | 1 |
| VoxelStream | stream |
Methods:¶
| Return | Signature |
|---|---|
| Node3D | convert_to_nodes ( NodeConversionFlags flags ) const |
Enumerations:¶
enum NodeConversionFlags:
- NODE_CONVERSION_INCLUDE_INSTANCER = 1 --- If the terrain has a VoxelInstancer, instances spawned by it will be included in the result as a MultiMeshInstance per chunk.
- NODE_CONVERSION_INCLUDE_INVISIBLE_BLOCKS = 2 --- Some chunks are internally hidden by the terrain system, notably as part of the LOD system. If this flag is provided, these chunks will be included in the output.
- NODE_CONVERSION_INCLUDE_MATERIAL_OVERRIDES = 4 --- Specifies that material overrides present on the terrain should be applied to chunks of the result.
Property Descriptions¶
ShadowCastingSetting cast_shadow = 1¶
Sets the shadow casting mode that meshes of the terrain will use.
VoxelFormat format¶
Overrides the default format of voxels.
WARNING: changing this will reload the terrain. If it has a stream attached with data saved with a different format, it might load improperly.
VoxelGenerator generator¶
Procedural generator used to load voxel blocks when not present in the stream.
GIMode gi_mode = 0¶
Sets the Global Illumination mode meshes of the terrain will use.
VoxelMesher mesher¶
Defines how voxels are transformed into visible meshes.
int render_layers_mask = 1¶
Sets the render layers meshes of the terrain will use.
VoxelStream stream¶
Primary source of persistent voxel data. If left unassigned, the whole volume will use the generator.
Method Descriptions¶
Node3D convert_to_nodes( NodeConversionFlags flags )¶
Generates a tree representing the terrain at the time of calling, only using Godot vanilla nodes.
This method can be used as a way to produce a snapshot of the terrain as a vanilla scene that can be opened with standard Godot versions without plugins. It could also be used for debug purposes, or as a way to workaround Godot features that expect mesh instance nodes (such as some GI baking options, navigation generation or GLTF export).
The returned root is not added to the scene tree. It is up to you to decide what to do with it. If you want it to be present in the scene, you should add it as child of an existing node. Otherwise, don't forget to free it.
Output structure: every chunk of the terrain will create its own MeshInstance3D, with a unique ArrayMesh resource attached to it. Meshes and/or mesh instances may also have materials attached to them. Depending on how the terrain is configured, these materials can be unique per chunk. If the terrain has LODs, chunks will be stored under a corresponding LOD node. If the terrain has an instancer, multimesh chunks can be included. See NodeConversionFlags for options.
Resources: unless specified, resources attached to nodes of the tree will be direct references to those actually used by the terrain system. Careful, depending on configuration, it is possible that they get altered when the terrain runs its next process cycle (for example, materials with per-chunk parameters are pooled, so when chunks get unloaded, those referenced in the nodes might drastically change as new chunks re-use them).
Performance: this can be an expensive operation. It might slow down your game.
Packing to scene file: it is possible to save the output as a PackedScene, by assigning Node.owner (see Godot's documentation). It contains a lot of unique meshes so the saved scenes can be very large. Prefer saving as binary .scn if it's a problem. If the terrain uses a ShaderMaterial with detail rendering, chunks will also have unique textures, further increasing size.
GLTF: if your terrain uses ShaderMaterial and you want to convert the terrain to a GLTFDocument, these materials won't carry over because GLTF does not support it. That also means if you use VoxelMesherTransvoxel with LOD, meshes in your GLTF document will have unwanted extra geometry and cracks at the seams (which would normally be handled by shader).
LOD: if your terrain has LOD, you will only get a snapshot of which LODs are currently active. Detailed meshes will be centered around viewers, and have less and less details further away.
Generated on Jan 26, 2026