Terrain3D

Inherits: Node3D

Description

Terrain3D is a high performance, editable terrain system for Godot 4. It provides a clipmap based terrain that supports terrains from 64x64m up to 65.5x65.5km with multiple LODs, 32 textures, and editor tools for importing or creating terrains.

This class handles mesh generation, and management of the whole system. See System Architecture for design details.

Properties

Terrain3DAssets	assets
RenderingServer.ShadowCastingSetting	cast_shadows	`1`
Terrain3DCollision	collision
`int`	collision_layer	`1`
`int`	collision_mask	`1`
CollisionMode	collision_mode	`1`
`float`	collision_priority	`1.0`
`int`	collision_radius	`64`
`int`	collision_shape_size	`16`
`float`	cull_margin	`0.0`
Terrain3DData	data
`String`	data_directory	`""`
DebugLevel	debug_level	`0`
`bool`	free_editor_textures	`true`
GeometryInstance3D.GIMode	gi_mode	`1`
Terrain3DInstancer	instancer
`float`	label_distance	`0.0`
`int`	label_size	`48`
Terrain3DMaterial	material
`int`	mesh_lods	`7`
`int`	mesh_size	`48`
`int`	mouse_layer	`32`
`PhysicsMaterial`	physics_material
RegionSize	region_size	`256`
`int`	render_layers	`2147483649`
`bool`	save_16_bit	`false`
`bool`	show_autoshader	`false`
`bool`	show_checkered	`false`
`bool`	show_colormap	`false`
`bool`	show_contours	`false`
`bool`	show_control_angle	`false`
`bool`	show_control_blend	`false`
`bool`	show_control_scale	`false`
`bool`	show_control_texture	`false`
`bool`	show_grey	`false`
`bool`	show_grid	`false`
`bool`	show_heightmap	`false`
`bool`	show_instancer_grid	`false`
`bool`	show_instances	`true`
`bool`	show_navigation	`false`
`bool`	show_region_grid	`false`
`bool`	show_roughmap	`false`
`bool`	show_texture_height	`false`
`bool`	show_texture_normal	`false`
`bool`	show_texture_rough	`false`
`bool`	show_vertex_grid	`false`
`String`	version	`"1.1.0-dev"`
`float`	vertex_spacing	`1.0`

Methods

`Mesh`	bake_mesh(lod: `int`, filter: HeightFilter = 0) const
`PackedVector3Array`	generate_nav_mesh_source_geometry(global_aabb: `AABB`, require_nav: `bool` = true) const
`Camera3D`	get_camera() const
Terrain3DEditor	get_editor() const
`Vector3`	get_intersection(src_pos: `Vector3`, direction: `Vector3`, gpu_mode: `bool` = false)
`EditorPlugin`	get_plugin() const
`Vector3`	get_snapped_position() const
void	set_camera(camera: `Camera3D`)
void	set_editor(editor: Terrain3DEditor)
void	set_plugin(plugin: `EditorPlugin`)

Signals

assets_changed() 🔗

Emitted when assets is changed.

material_changed() 🔗

Emitted when material is changed.

Enumerations

enum DebugLevel: 🔗

DebugLevel ERROR = 0

Errors and warnings always print.

DebugLevel INFO = 1

Typically every function call and other important informational messages.

DebugLevel DEBUG = 2

Detailed steps within functions.

DebugLevel EXTREME = 3

Messages for continuous operations like snapping and editing.

enum RegionSize: 🔗

RegionSize SIZE_64 = 64

The region size is 64 x 64 meters, vertices, and pixels on Image maps.

RegionSize SIZE_128 = 128

The region size is 128 x 128 meters, vertices, and pixels on Image maps.

RegionSize SIZE_256 = 256

The region size is 256 x 256 meters, vertices, and pixels on Image maps. (default)

RegionSize SIZE_512 = 512

The region size is 512 x 512 meters, vertices, and pixels on Image maps.

RegionSize SIZE_1024 = 1024

The region size is 1024 x 1024 meters, vertices, and pixels on Image maps.

RegionSize SIZE_2048 = 2048

The region size is 2048 x 2048 meters, vertices, and pixels on Image maps.

Property Descriptions

Terrain3DAssets assets 🔗

void set_assets(value: Terrain3DAssets)
Terrain3DAssets get_assets()

The list of texture and mesh assets used by Terrain3D. You can optionally save this as an external .tres text file if you wish to share it with Terrain3D nodes in other scenes.

RenderingServer.ShadowCastingSetting cast_shadows = 1 🔗

void set_cast_shadows(value: RenderingServer.ShadowCastingSetting)
RenderingServer.ShadowCastingSetting get_cast_shadows()

Tells the renderer how to cast shadows from the terrain onto other objects. This sets GeometryInstance3D.ShadowCastingSetting in the engine.

Terrain3DCollision collision 🔗

Terrain3DCollision get_collision()

The active Terrain3DCollision object.

int collision_layer = 1 🔗

void set_collision_layer(value: int)
int get_collision_layer()

Alias for Terrain3DCollision.layer.

int collision_mask = 1 🔗

void set_collision_mask(value: int)
int get_collision_mask()

Alias for Terrain3DCollision.mask.

CollisionMode collision_mode = 1 🔗

void set_collision_mode(value: CollisionMode)
CollisionMode get_collision_mode()

Alias for Terrain3DCollision.mode.

float collision_priority = 1.0 🔗

void set_collision_priority(value: float)
float get_collision_priority()

Alias for Terrain3DCollision.priority.

int collision_radius = 64 🔗

void set_collision_radius(value: int)
int get_collision_radius()

Alias for Terrain3DCollision.radius.

int collision_shape_size = 16 🔗

void set_collision_shape_size(value: int)
int get_collision_shape_size()

Alias for Terrain3DCollision.shape_size.

float cull_margin = 0.0 🔗

void set_cull_margin(value: float)
float get_cull_margin()

This margin is added to the vertical component of the terrain bounding box (AABB). The terrain already sets its AABB from Terrain3DData.get_height_range(), which is calculated while sculpting. This setting only needs to be used if the shader has expanded the terrain beyond the AABB and the terrain meshes are being culled at certain viewing angles. This might happen from using Terrain3DMaterial.world_background with NOISE and a height value larger than the terrain heights. This setting is similar to GeometryInstance3D.extra_cull_margin, but it only affects the Y axis.

Terrain3DData data 🔗

Terrain3DData get_data()

This class manages loading, saving, adding, and removing of Terrain3DRegions and access to their content.

String data_directory = "" 🔗

void set_data_directory(value: String)
String get_data_directory()

The directory where terrain data will be saved to and loaded from.

DebugLevel debug_level = 0 🔗

void set_debug_level(value: DebugLevel)
DebugLevel get_debug_level()

The verbosity of debug messages printed to the console. Errors and warnings are always printed. This can also be set via command line using --terrain3d-debug=LEVEL where LEVEL is one of ERROR, INFO, DEBUG, EXTREME. The last includes continuously recurring messages like position updates for the mesh as the camera moves around.

bool free_editor_textures = true 🔗

void set_free_editor_textures(value: bool)
bool get_free_editor_textures()

Frees ground textures used for editing at the start of the game. These textures are used to generate the TextureArrays, so if you don’t change any Terrain3DTextureAsset settings in game, this can be enabled. Calls Terrain3DAssets.clear_textures().

GeometryInstance3D.GIMode gi_mode = 1 🔗

void set_gi_mode(value: GeometryInstance3D.GIMode)
GeometryInstance3D.GIMode get_gi_mode()

Tells the renderer which global illumination mode to use for Terrain3D. This sets GeometryInstance3D.gi_mode in the engine.

Terrain3DInstancer instancer 🔗

Terrain3DInstancer get_instancer()

The active Terrain3DInstancer object.

float label_distance = 0.0 🔗

void set_label_distance(value: float)
float get_label_distance()

If label_distance is non-zero (try 1024-4096) it will generate and display region coordinates in the viewport so you can identify the exact region files you are editing. This setting is the visible distance of the labels.

int label_size = 48 🔗

void set_label_size(value: int)
int get_label_size()

Sets the font size for region labels. See label_distance.

Terrain3DMaterial material 🔗

void set_material(value: Terrain3DMaterial)
Terrain3DMaterial get_material()

A custom material for Terrain3D. You can optionally save this as an external .tres text file if you wish to share it with instances of Terrain3D in other scenes. See Terrain3DMaterial.

int mesh_lods = 7 🔗

void set_mesh_lods(value: int)
int get_mesh_lods()

The number of lods generated in the mesh. Enable wireframe mode in the viewport to see them.

int mesh_size = 48 🔗

void set_mesh_size(value: int)
int get_mesh_size()

The correlated size of the terrain meshes. Lod0 has 4*mesh_size + 2 quads per side. E.g. when mesh_size=8, lod0 has 34 quads to a side, including 2 quads for seams.

int mouse_layer = 32 🔗

void set_mouse_layer(value: int)
int get_mouse_layer()

Godot supports 32 render layers. For most objects, only layers 1-20 are available for selection in the inspector. 21-32 are settable via code, and are considered reserved for editor plugins.

This variable sets the editor render layer (21-32) to be used by get_intersection, which the mouse cursor uses.

You may place other objects on this layer, however get_intersection will report intersections with them. So either dedicate this layer to Terrain3D, or if you must use all 32 layers, dedicate this one during editing or when using get_intersection, and then you can use it during game play.

See get_intersection().

PhysicsMaterial physics_material 🔗

void set_physics_material(value: PhysicsMaterial)
PhysicsMaterial get_physics_material()

Alias for Terrain3DCollision.physics_material.

RegionSize region_size = 256 🔗

void change_region_size(value: RegionSize)
RegionSize get_region_size()

The number of vertices in each region, and the number of pixels for each map in Terrain3DRegion. 1 pixel always corresponds to 1 vertex. vertex_spacing laterally scales regions, but does not change the number of vertices or pixels in each.

There is no undo for this operation. However you can apply it again to reslice, as long as your data doesn’t hit the maximum boundaries.

int render_layers = 2147483649 🔗

void set_render_layers(value: int)
int get_render_layers()

The render layers the terrain is drawn on. This sets VisualInstance3D.layers in the engine. The defaults is layer 1 and 32 (for the mouse cursor). When you set this, make sure the layer for mouse_layer is included, or set that variable again after this so that the mouse cursor works.

bool save_16_bit = false 🔗

void set_save_16_bit(value: bool)
bool get_save_16_bit()

If enabled, heightmaps are saved as 16-bit half-precision to reduce file size. Files are always loaded in 32-bit for editing. Upon save, a copy of the heightmap is converted to 16-bit for writing. It does not change what is currently in memory.

This process is lossy. 16-bit precision gets increasingly worse with every power of 2. At a height of 256m, the precision interval is .25m. At 512m it is .5m. At 1024m it is 1m. Saving a height of 1024.4m will be rounded down to 1024m.

bool show_autoshader = false 🔗

void set_show_autoshader(value: bool)
bool get_show_autoshader()

Alias for Terrain3DMaterial.show_autoshader.

bool show_checkered = false 🔗

void set_show_checkered(value: bool)
bool get_show_checkered()

Alias for Terrain3DMaterial.show_checkered.

bool show_colormap = false 🔗

void set_show_colormap(value: bool)
bool get_show_colormap()

Alias for Terrain3DMaterial.show_colormap.

bool show_contours = false 🔗

void set_show_contours(value: bool)
bool get_show_contours()

Alias for Terrain3DMaterial.show_contours. Press 4 with the mouse in the viewport to toggle. Customize in the material.

bool show_control_angle = false 🔗

void set_show_control_angle(value: bool)
bool get_show_control_angle()

Alias for Terrain3DMaterial.show_control_angle.

bool show_control_blend = false 🔗

void set_show_control_blend(value: bool)
bool get_show_control_blend()

Alias for Terrain3DMaterial.show_control_blend.

bool show_control_scale = false 🔗

void set_show_control_scale(value: bool)
bool get_show_control_scale()

Alias for Terrain3DMaterial.show_control_scale.

bool show_control_texture = false 🔗

void set_show_control_texture(value: bool)
bool get_show_control_texture()

Alias for Terrain3DMaterial.show_control_texture.

bool show_grey = false 🔗

void set_show_grey(value: bool)
bool get_show_grey()

Alias for Terrain3DMaterial.show_grey.

bool show_grid = false 🔗

void set_show_region_grid(value: bool)
bool get_show_region_grid()

Alias for Terrain3DMaterial.show_region_grid. Press 1 with the mouse in the viewport to toggle.

bool show_heightmap = false 🔗

void set_show_heightmap(value: bool)
bool get_show_heightmap()

Alias for Terrain3DMaterial.show_heightmap.

bool show_instancer_grid = false 🔗

void set_show_instancer_grid(value: bool)
bool get_show_instancer_grid()

Alias for Terrain3DMaterial.show_instancer_grid. Press 2 with the mouse in the viewport to toggle.

bool show_instances = true 🔗

void set_show_instances(value: bool)
bool get_show_instances()

Shows or hides all instancer meshes.

bool show_navigation = false 🔗

void set_show_navigation(value: bool)
bool get_show_navigation()

Alias for Terrain3DMaterial.show_navigation.

bool show_region_grid = false 🔗

void set_show_region_grid(value: bool)
bool get_show_region_grid()

Alias for Terrain3DMaterial.show_region_grid. Press 1 with the mouse in the viewport to toggle.

bool show_roughmap = false 🔗

void set_show_roughmap(value: bool)
bool get_show_roughmap()

Alias for Terrain3DMaterial.show_autoshader.

bool show_texture_height = false 🔗

void set_show_texture_height(value: bool)
bool get_show_texture_height()

Alias for Terrain3DMaterial.show_texture_height.

bool show_texture_normal = false 🔗

void set_show_texture_normal(value: bool)
bool get_show_texture_normal()

Alias for Terrain3DMaterial.show_texture_normal.

bool show_texture_rough = false 🔗

void set_show_texture_rough(value: bool)
bool get_show_texture_rough()

Alias for Terrain3DMaterial.show_texture_rough.

bool show_vertex_grid = false 🔗

void set_show_vertex_grid(value: bool)
bool get_show_vertex_grid()

Alias for Terrain3DMaterial.show_vertex_grid. Press 3 with the mouse in the viewport to toggle.

String version = "1.1.0-dev" 🔗

String get_version()

The current version of Terrain3D.

float vertex_spacing = 1.0 🔗

void set_vertex_spacing(value: float)
float get_vertex_spacing()

The distance between vertices. Godot units are typically considered to be meters. This laterally scales the terrain on X and Z axes.

This variable changes the global position of landscape features. A mountain peak might be at (512, 512), but with a vertex spacing of 2.0 it is now located at (1024, 1024).

All Terrain3D functions with a global_position expect an absolute global value. If you would normally use Terrain3DData.import_images() to import an image in the region at (-1024, -1024), with a vertex_spacing of 2, you’ll need to import that image at (-2048, -2048) to place it in the same region.

To scale heights, export the height map and reimport it with a new height scale.

Method Descriptions

Mesh bake_mesh(lod: int, filter: HeightFilter = 0) const 🔗

Generates a static ArrayMesh for the terrain.

lod - Determines the granularity of the generated mesh. The range is 0-8. 4 is recommended.

filter - Controls how vertex Y coordinates are generated from the height map. See HeightFilter.

PackedVector3Array generate_nav_mesh_source_geometry(global_aabb: AABB, require_nav: bool = true) const 🔗

Generates source geometry faces for input to nav mesh baking. Geometry is only generated where there are no holes and the terrain has been painted as navigable.

global_aabb - If non-empty, geometry will be generated only within this AABB. If empty, geometry will be generated for the entire terrain.

require_nav - If true, this function will only generate geometry for terrain marked navigable. Otherwise, geometry is generated for the entire terrain within the AABB (which can be useful for dynamic and/or runtime nav mesh baking).

Camera3D get_camera() const 🔗

Returns the camera the terrain is currently snapping to.

Terrain3DEditor get_editor() const 🔗

Returns the current Terrain3DEditor instance, if it has been set.

Vector3 get_intersection(src_pos: Vector3, direction: Vector3, gpu_mode: bool = false) 🔗

Casts a ray from src_pos pointing towards direction, attempting to intersect the terrain. This operation is does not use physics, so enabling collision is unnecessary.

This function can operate in one of two modes defined by gpu_mode:

If gpu_mode is disabled (default), it raymarches from the camera until the terrain is intersected, up to 4000m away. This works with one function call, but only where regions exist. It is slower than gpu_mode and gets increasingly slower the farther away the terrain is, though you may not notice.
If gpu_mode is enabled, it uses the GPU to detect the mouse. This works wherever the terrain is visible, even outside of regions, but may need to be called twice.

GPU mode places a camera at the specified point and “looks” at the terrain. It uses the depth texture to determine how far away the intersection point is. It requires the use of an editor render layer (default 32) while using this function. See mouse_layer.

The main caveats of using this mode is that the call to get_intersection() requests a viewport be drawn, but cannot wait for it to finish as there is no “await” in C++ and no force draw function in Godot. So the return value is one frame behind, and invalid on the first call. This also means the function cannot be used more than once per frame. This mode works well when used continuously, once per frame, where one frame of difference won’t matter. The editor uses this mode to place the mouse cursor decal.

This mode can also be used by your plugins and games, such as a space ship firing lasers at the terrain and causing an explosion at the hit point. However if the calls aren’t continuous, eg driven by the mouse, you’ll need to call once to capture the viewport image, wait for it to be drawn, then call again to get the result:

var target_point = terrain.get_intersection(camera_pos, camera_dir, true)
await RenderingServer.frame_post_draw
target_point = terrain.get_intersection(camera_pos, camera_dir, true)

Possible return values:

If the terrain is hit, the intersection point is returned.
If there is no intersection, eg. the ray points towards the sky, it returns the maximum double float value Vector3(3.402823466e+38F,...). You can check this case with this code: if point.z > 3.4e38:
On error, it returns Vector3(NAN, NAN, NAN) and prints a message to the console.

EditorPlugin get_plugin() const 🔗

Returns the EditorPlugin connected to Terrain3D.

Vector3 get_snapped_position() const 🔗

Returns the last position the terrain was centered on.

void set_camera(camera: Camera3D) 🔗

Sets the camera the terrain snaps to.

void set_editor(editor: Terrain3DEditor) 🔗

Sets the current Terrain3DEditor instance.

void set_plugin(plugin: EditorPlugin) 🔗

Sets the EditorPlugin connected to Terrain3D.