Skip to content

Latest commit

 

History

History
1218 lines (691 loc) · 53.6 KB

class_terrain3d.rst

File metadata and controls

1218 lines (691 loc) · 53.6 KB
github_url:hide

Terrain3D

Inherits: Node3D

.. rst-class:: classref-introduction-group

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.

.. rst-class:: classref-reftable-group

Properties

:ref:`Terrain3DAssets<class_Terrain3DAssets>` :ref:`assets<class_Terrain3D_property_assets>`  
RenderingServer.ShadowCastingSetting :ref:`cast_shadows<class_Terrain3D_property_cast_shadows>` 1
:ref:`Terrain3DCollision<class_Terrain3DCollision>` :ref:`collision<class_Terrain3D_property_collision>`  
int :ref:`collision_layer<class_Terrain3D_property_collision_layer>` 1
int :ref:`collision_mask<class_Terrain3D_property_collision_mask>` 1
:ref:`CollisionMode<enum_Terrain3DCollision_CollisionMode>` :ref:`collision_mode<class_Terrain3D_property_collision_mode>` 1
float :ref:`collision_priority<class_Terrain3D_property_collision_priority>` 1.0
int :ref:`collision_radius<class_Terrain3D_property_collision_radius>` 64
int :ref:`collision_shape_size<class_Terrain3D_property_collision_shape_size>` 16
float :ref:`cull_margin<class_Terrain3D_property_cull_margin>` 0.0
:ref:`Terrain3DData<class_Terrain3DData>` :ref:`data<class_Terrain3D_property_data>`  
String :ref:`data_directory<class_Terrain3D_property_data_directory>` ""
int :ref:`debug_level<class_Terrain3D_property_debug_level>` 0
GeometryInstance3D.GIMode :ref:`gi_mode<class_Terrain3D_property_gi_mode>` 1
:ref:`Terrain3DInstancer<class_Terrain3DInstancer>` :ref:`instancer<class_Terrain3D_property_instancer>`  
float :ref:`label_distance<class_Terrain3D_property_label_distance>` 0.0
int :ref:`label_size<class_Terrain3D_property_label_size>` 48
:ref:`Terrain3DMaterial<class_Terrain3DMaterial>` :ref:`material<class_Terrain3D_property_material>`  
int :ref:`mesh_lods<class_Terrain3D_property_mesh_lods>` 7
int :ref:`mesh_size<class_Terrain3D_property_mesh_size>` 48
int :ref:`mouse_layer<class_Terrain3D_property_mouse_layer>` 32
:ref:`RegionSize<enum_Terrain3D_RegionSize>` :ref:`region_size<class_Terrain3D_property_region_size>` 256
int :ref:`render_layers<class_Terrain3D_property_render_layers>` 2147483649
bool :ref:`save_16_bit<class_Terrain3D_property_save_16_bit>` false
bool :ref:`show_autoshader<class_Terrain3D_property_show_autoshader>` false
bool :ref:`show_checkered<class_Terrain3D_property_show_checkered>` false
bool :ref:`show_colormap<class_Terrain3D_property_show_colormap>` false
bool :ref:`show_control_angle<class_Terrain3D_property_show_control_angle>` false
bool :ref:`show_control_blend<class_Terrain3D_property_show_control_blend>` false
bool :ref:`show_control_scale<class_Terrain3D_property_show_control_scale>` false
bool :ref:`show_control_texture<class_Terrain3D_property_show_control_texture>` false
bool :ref:`show_grey<class_Terrain3D_property_show_grey>` false
bool :ref:`show_grid<class_Terrain3D_property_show_grid>` false
bool :ref:`show_heightmap<class_Terrain3D_property_show_heightmap>` false
bool :ref:`show_instancer_grid<class_Terrain3D_property_show_instancer_grid>` false
bool :ref:`show_instances<class_Terrain3D_property_show_instances>` true
bool :ref:`show_navigation<class_Terrain3D_property_show_navigation>` false
bool :ref:`show_region_grid<class_Terrain3D_property_show_region_grid>` false
bool :ref:`show_roughmap<class_Terrain3D_property_show_roughmap>` false
bool :ref:`show_texture_height<class_Terrain3D_property_show_texture_height>` false
bool :ref:`show_texture_normal<class_Terrain3D_property_show_texture_normal>` false
bool :ref:`show_texture_rough<class_Terrain3D_property_show_texture_rough>` false
bool :ref:`show_vertex_grid<class_Terrain3D_property_show_vertex_grid>` false
String :ref:`version<class_Terrain3D_property_version>` "1.0.0-dev"
float :ref:`vertex_spacing<class_Terrain3D_property_vertex_spacing>` 1.0 
.. rst-class:: classref-reftable-group

Methods

Mesh :ref:`bake_mesh<class_Terrain3D_method_bake_mesh>`(lod: int, filter: :ref:`HeightFilter<enum_Terrain3DData_HeightFilter>`) |const|
PackedVector3Array :ref:`generate_nav_mesh_source_geometry<class_Terrain3D_method_generate_nav_mesh_source_geometry>`(global_aabb: AABB, require_nav: bool = true) |const|
Camera3D :ref:`get_camera<class_Terrain3D_method_get_camera>`() |const|
:ref:`Terrain3DEditor<class_Terrain3DEditor>` :ref:`get_editor<class_Terrain3D_method_get_editor>`() |const|
Vector3 :ref:`get_intersection<class_Terrain3D_method_get_intersection>`(src_pos: Vector3, direction: Vector3, gpu_mode: bool = false)
EditorPlugin :ref:`get_plugin<class_Terrain3D_method_get_plugin>`() |const|
Vector3 :ref:`get_snapped_position<class_Terrain3D_method_get_snapped_position>`() |const|
bool :ref:`is_compatibility_mode<class_Terrain3D_method_is_compatibility_mode>`() |const|
|void| :ref:`set_camera<class_Terrain3D_method_set_camera>`(camera: Camera3D)
|void| :ref:`set_editor<class_Terrain3D_method_set_editor>`(editor: :ref:`Terrain3DEditor<class_Terrain3DEditor>`)
|void| :ref:`set_plugin<class_Terrain3D_method_set_plugin>`(plugin: EditorPlugin) 
.. rst-class:: classref-section-separator


.. rst-class:: classref-descriptions-group

Signals

.. rst-class:: classref-signal

assets_changed() :ref:`🔗<class_Terrain3D_signal_assets_changed>`

Emitted when :ref:`assets<class_Terrain3D_property_assets>` is changed.

.. rst-class:: classref-item-separator


.. rst-class:: classref-signal

material_changed() :ref:`🔗<class_Terrain3D_signal_material_changed>`

Emitted when :ref:`material<class_Terrain3D_property_material>` is changed.

.. rst-class:: classref-section-separator


.. rst-class:: classref-descriptions-group

Enumerations

.. rst-class:: classref-enumeration

enum RegionSize: :ref:`🔗<enum_Terrain3D_RegionSize>`

.. rst-class:: classref-enumeration-constant

:ref:`RegionSize<enum_Terrain3D_RegionSize>` SIZE_64 = 64

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

.. rst-class:: classref-enumeration-constant

:ref:`RegionSize<enum_Terrain3D_RegionSize>` SIZE_128 = 128

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

.. rst-class:: classref-enumeration-constant

:ref:`RegionSize<enum_Terrain3D_RegionSize>` SIZE_256 = 256

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

.. rst-class:: classref-enumeration-constant

:ref:`RegionSize<enum_Terrain3D_RegionSize>` SIZE_512 = 512

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

.. rst-class:: classref-enumeration-constant

:ref:`RegionSize<enum_Terrain3D_RegionSize>` SIZE_1024 = 1024

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

.. rst-class:: classref-enumeration-constant

:ref:`RegionSize<enum_Terrain3D_RegionSize>` SIZE_2048 = 2048

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

.. rst-class:: classref-section-separator


.. rst-class:: classref-descriptions-group

Property Descriptions

.. rst-class:: classref-property

:ref:`Terrain3DAssets<class_Terrain3DAssets>` assets :ref:`🔗<class_Terrain3D_property_assets>`

.. rst-class:: classref-property-setget

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.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

RenderingServer.ShadowCastingSetting cast_shadows = 1 :ref:`🔗<class_Terrain3D_property_cast_shadows>`

.. rst-class:: classref-property-setget
  • |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.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

:ref:`Terrain3DCollision<class_Terrain3DCollision>` collision :ref:`🔗<class_Terrain3D_property_collision>`

.. rst-class:: classref-property-setget

The active :ref:`Terrain3DCollision<class_Terrain3DCollision>` object.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

int collision_layer = 1 :ref:`🔗<class_Terrain3D_property_collision_layer>`

.. rst-class:: classref-property-setget
  • |void| set_collision_layer(value: int)
  • int get_collision_layer()

Alias for :ref:`Terrain3DCollision.layer<class_Terrain3DCollision_property_layer>`.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

int collision_mask = 1 :ref:`🔗<class_Terrain3D_property_collision_mask>`

.. rst-class:: classref-property-setget
  • |void| set_collision_mask(value: int)
  • int get_collision_mask()

Alias for :ref:`Terrain3DCollision.mask<class_Terrain3DCollision_property_mask>`.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

:ref:`CollisionMode<enum_Terrain3DCollision_CollisionMode>` collision_mode = 1 :ref:`🔗<class_Terrain3D_property_collision_mode>`

.. rst-class:: classref-property-setget

Alias for :ref:`Terrain3DCollision.mode<class_Terrain3DCollision_property_mode>`.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

float collision_priority = 1.0 :ref:`🔗<class_Terrain3D_property_collision_priority>`

.. rst-class:: classref-property-setget
  • |void| set_collision_priority(value: float)
  • float get_collision_priority()

Alias for :ref:`Terrain3DCollision.priority<class_Terrain3DCollision_property_priority>`.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

int collision_radius = 64 :ref:`🔗<class_Terrain3D_property_collision_radius>`

.. rst-class:: classref-property-setget
  • |void| set_collision_radius(value: int)
  • int get_collision_radius()

Alias for :ref:`Terrain3DCollision.radius<class_Terrain3DCollision_property_radius>`.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

int collision_shape_size = 16 :ref:`🔗<class_Terrain3D_property_collision_shape_size>`

.. rst-class:: classref-property-setget
  • |void| set_collision_shape_size(value: int)
  • int get_collision_shape_size()

Alias for :ref:`Terrain3DCollision.shape_size<class_Terrain3DCollision_property_shape_size>`.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

float cull_margin = 0.0 :ref:`🔗<class_Terrain3D_property_cull_margin>`

.. rst-class:: classref-property-setget
  • |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 :ref:`Terrain3DData.get_height_range<class_Terrain3DData_method_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 :ref:`Terrain3DMaterial.world_background<class_Terrain3DMaterial_property_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.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

:ref:`Terrain3DData<class_Terrain3DData>` data :ref:`🔗<class_Terrain3D_property_data>`

.. rst-class:: classref-property-setget

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

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

String data_directory = "" :ref:`🔗<class_Terrain3D_property_data_directory>`

.. rst-class:: classref-property-setget
  • |void| set_data_directory(value: String)
  • String get_data_directory()

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

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

int debug_level = 0 :ref:`🔗<class_Terrain3D_property_debug_level>`

.. rst-class:: classref-property-setget
  • |void| set_debug_level(value: int)
  • int 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.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

GeometryInstance3D.GIMode gi_mode = 1 :ref:`🔗<class_Terrain3D_property_gi_mode>`

.. rst-class:: classref-property-setget
  • |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.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

:ref:`Terrain3DInstancer<class_Terrain3DInstancer>` instancer :ref:`🔗<class_Terrain3D_property_instancer>`

.. rst-class:: classref-property-setget

The active :ref:`Terrain3DInstancer<class_Terrain3DInstancer>` object.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

float label_distance = 0.0 :ref:`🔗<class_Terrain3D_property_label_distance>`

.. rst-class:: classref-property-setget
  • |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.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

int label_size = 48 :ref:`🔗<class_Terrain3D_property_label_size>`

.. rst-class:: classref-property-setget
  • |void| set_label_size(value: int)
  • int get_label_size()

Sets the font size for region labels. See :ref:`label_distance<class_Terrain3D_property_label_distance>`.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

:ref:`Terrain3DMaterial<class_Terrain3DMaterial>` material :ref:`🔗<class_Terrain3D_property_material>`

.. rst-class:: classref-property-setget

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 :ref:`Terrain3DMaterial<class_Terrain3DMaterial>`.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

int mesh_lods = 7 :ref:`🔗<class_Terrain3D_property_mesh_lods>`

.. rst-class:: classref-property-setget
  • |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.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

int mesh_size = 48 :ref:`🔗<class_Terrain3D_property_mesh_size>`

.. rst-class:: classref-property-setget
  • |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.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

int mouse_layer = 32 :ref:`🔗<class_Terrain3D_property_mouse_layer>`

.. rst-class:: classref-property-setget
  • |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 :ref:`get_intersection<class_Terrain3D_method_get_intersection>`.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

:ref:`RegionSize<enum_Terrain3D_RegionSize>` region_size = 256 :ref:`🔗<class_Terrain3D_property_region_size>`

.. rst-class:: classref-property-setget

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

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

int render_layers = 2147483649 :ref:`🔗<class_Terrain3D_property_render_layers>`

.. rst-class:: classref-property-setget
  • |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 :ref:`mouse_layer<class_Terrain3D_property_mouse_layer>` is included, or set that variable again after this so that the mouse cursor works.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

bool save_16_bit = false :ref:`🔗<class_Terrain3D_property_save_16_bit>`

.. rst-class:: classref-property-setget
  • |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.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

bool show_autoshader = false :ref:`🔗<class_Terrain3D_property_show_autoshader>`

.. rst-class:: classref-property-setget
  • |void| set_show_autoshader(value: bool)
  • bool get_show_autoshader()

Alias for :ref:`Terrain3DMaterial.show_autoshader<class_Terrain3DMaterial_property_show_autoshader>`.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

bool show_checkered = false :ref:`🔗<class_Terrain3D_property_show_checkered>`

.. rst-class:: classref-property-setget
  • |void| set_show_checkered(value: bool)
  • bool get_show_checkered()

Alias for :ref:`Terrain3DMaterial.show_checkered<class_Terrain3DMaterial_property_show_checkered>`.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

bool show_colormap = false :ref:`🔗<class_Terrain3D_property_show_colormap>`

.. rst-class:: classref-property-setget
  • |void| set_show_colormap(value: bool)
  • bool get_show_colormap()

Alias for :ref:`Terrain3DMaterial.show_colormap<class_Terrain3DMaterial_property_show_colormap>`.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

bool show_control_angle = false :ref:`🔗<class_Terrain3D_property_show_control_angle>`

.. rst-class:: classref-property-setget
  • |void| set_show_control_angle(value: bool)
  • bool get_show_control_angle()

Alias for :ref:`Terrain3DMaterial.show_control_angle<class_Terrain3DMaterial_property_show_control_angle>`.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

bool show_control_blend = false :ref:`🔗<class_Terrain3D_property_show_control_blend>`

.. rst-class:: classref-property-setget
  • |void| set_show_control_blend(value: bool)
  • bool get_show_control_blend()

Alias for :ref:`Terrain3DMaterial.show_control_blend<class_Terrain3DMaterial_property_show_control_blend>`.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

bool show_control_scale = false :ref:`🔗<class_Terrain3D_property_show_control_scale>`

.. rst-class:: classref-property-setget
  • |void| set_show_control_scale(value: bool)
  • bool get_show_control_scale()

Alias for :ref:`Terrain3DMaterial.show_control_scale<class_Terrain3DMaterial_property_show_control_scale>`.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

bool show_control_texture = false :ref:`🔗<class_Terrain3D_property_show_control_texture>`

.. rst-class:: classref-property-setget
  • |void| set_show_control_texture(value: bool)
  • bool get_show_control_texture()

Alias for :ref:`Terrain3DMaterial.show_control_texture<class_Terrain3DMaterial_property_show_control_texture>`.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

bool show_grey = false :ref:`🔗<class_Terrain3D_property_show_grey>`

.. rst-class:: classref-property-setget
  • |void| set_show_grey(value: bool)
  • bool get_show_grey()

Alias for :ref:`Terrain3DMaterial.show_grey<class_Terrain3DMaterial_property_show_grey>`.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

bool show_grid = false :ref:`🔗<class_Terrain3D_property_show_grid>`

.. rst-class:: classref-property-setget
  • |void| set_show_region_grid(value: bool)
  • bool get_show_region_grid()

Alias for :ref:`Terrain3DMaterial.show_region_grid<class_Terrain3DMaterial_property_show_region_grid>`.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

bool show_heightmap = false :ref:`🔗<class_Terrain3D_property_show_heightmap>`

.. rst-class:: classref-property-setget
  • |void| set_show_heightmap(value: bool)
  • bool get_show_heightmap()

Alias for :ref:`Terrain3DMaterial.show_heightmap<class_Terrain3DMaterial_property_show_heightmap>`.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

bool show_instancer_grid = false :ref:`🔗<class_Terrain3D_property_show_instancer_grid>`

.. rst-class:: classref-property-setget
  • |void| set_show_instancer_grid(value: bool)
  • bool get_show_instancer_grid()

Alias for :ref:`Terrain3DMaterial.show_instancer_grid<class_Terrain3DMaterial_property_show_instancer_grid>`.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

bool show_instances = true :ref:`🔗<class_Terrain3D_property_show_instances>`

.. rst-class:: classref-property-setget
  • |void| set_show_instances(value: bool)
  • bool get_show_instances()

Shows or hides all instancer meshes.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

bool show_navigation = false :ref:`🔗<class_Terrain3D_property_show_navigation>`

.. rst-class:: classref-property-setget
  • |void| set_show_navigation(value: bool)
  • bool get_show_navigation()

Alias for :ref:`Terrain3DMaterial.show_navigation<class_Terrain3DMaterial_property_show_navigation>`.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

bool show_region_grid = false :ref:`🔗<class_Terrain3D_property_show_region_grid>`

.. rst-class:: classref-property-setget
  • |void| set_show_region_grid(value: bool)
  • bool get_show_region_grid()

Alias for :ref:`Terrain3DMaterial.show_region_grid<class_Terrain3DMaterial_property_show_region_grid>`.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

bool show_roughmap = false :ref:`🔗<class_Terrain3D_property_show_roughmap>`

.. rst-class:: classref-property-setget
  • |void| set_show_roughmap(value: bool)
  • bool get_show_roughmap()

Alias for :ref:`Terrain3DMaterial.show_autoshader<class_Terrain3DMaterial_property_show_autoshader>`.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

bool show_texture_height = false :ref:`🔗<class_Terrain3D_property_show_texture_height>`

.. rst-class:: classref-property-setget
  • |void| set_show_texture_height(value: bool)
  • bool get_show_texture_height()

Alias for :ref:`Terrain3DMaterial.show_texture_height<class_Terrain3DMaterial_property_show_texture_height>`.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

bool show_texture_normal = false :ref:`🔗<class_Terrain3D_property_show_texture_normal>`

.. rst-class:: classref-property-setget
  • |void| set_show_texture_normal(value: bool)
  • bool get_show_texture_normal()

Alias for :ref:`Terrain3DMaterial.show_texture_normal<class_Terrain3DMaterial_property_show_texture_normal>`.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

bool show_texture_rough = false :ref:`🔗<class_Terrain3D_property_show_texture_rough>`

.. rst-class:: classref-property-setget
  • |void| set_show_texture_rough(value: bool)
  • bool get_show_texture_rough()

Alias for :ref:`Terrain3DMaterial.show_texture_rough<class_Terrain3DMaterial_property_show_texture_rough>`.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

bool show_vertex_grid = false :ref:`🔗<class_Terrain3D_property_show_vertex_grid>`

.. rst-class:: classref-property-setget
  • |void| set_show_vertex_grid(value: bool)
  • bool get_show_vertex_grid()

Alias for :ref:`Terrain3DMaterial.show_vertex_grid<class_Terrain3DMaterial_property_show_vertex_grid>`.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

String version = "1.0.0-dev" :ref:`🔗<class_Terrain3D_property_version>`

.. rst-class:: classref-property-setget
  • String get_version()

The current version of Terrain3D.

.. rst-class:: classref-item-separator


.. rst-class:: classref-property

float vertex_spacing = 1.0 :ref:`🔗<class_Terrain3D_property_vertex_spacing>`

.. rst-class:: classref-property-setget
  • |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 :ref:`Terrain3DData.import_images<class_Terrain3DData_method_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.

.. rst-class:: classref-section-separator


.. rst-class:: classref-descriptions-group

Method Descriptions

.. rst-class:: classref-method

Mesh bake_mesh(lod: int, filter: :ref:`HeightFilter<enum_Terrain3DData_HeightFilter>`) |const| :ref:`🔗<class_Terrain3D_method_bake_mesh>`

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 :ref:`HeightFilter<enum_Terrain3DData_HeightFilter>`.

.. rst-class:: classref-item-separator


.. rst-class:: classref-method

PackedVector3Array generate_nav_mesh_source_geometry(global_aabb: AABB, require_nav: bool = true) |const| :ref:`🔗<class_Terrain3D_method_generate_nav_mesh_source_geometry>`

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

.. rst-class:: classref-item-separator


.. rst-class:: classref-method

Camera3D get_camera() |const| :ref:`🔗<class_Terrain3D_method_get_camera>`

Returns the camera the terrain is currently snapping to.

.. rst-class:: classref-item-separator


.. rst-class:: classref-method

:ref:`Terrain3DEditor<class_Terrain3DEditor>` get_editor() |const| :ref:`🔗<class_Terrain3D_method_get_editor>`

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

.. rst-class:: classref-item-separator


.. rst-class:: classref-method

Vector3 get_intersection(src_pos: Vector3, direction: Vector3, gpu_mode: bool = false) :ref:`🔗<class_Terrain3D_method_get_intersection>`

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 :ref:`mouse_layer<class_Terrain3D_property_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.
.. rst-class:: classref-item-separator


.. rst-class:: classref-method

EditorPlugin get_plugin() |const| :ref:`🔗<class_Terrain3D_method_get_plugin>`

Returns the EditorPlugin connected to Terrain3D.

.. rst-class:: classref-item-separator


.. rst-class:: classref-method

Vector3 get_snapped_position() |const| :ref:`🔗<class_Terrain3D_method_get_snapped_position>`

Returns the last position the terrain was centered on.

.. rst-class:: classref-item-separator


.. rst-class:: classref-method

bool is_compatibility_mode() |const| :ref:`🔗<class_Terrain3D_method_is_compatibility_mode>`

Returns true if Terrain3D has detected that the Compatibility renderer is in use.

.. rst-class:: classref-item-separator


.. rst-class:: classref-method

|void| set_camera(camera: Camera3D) :ref:`🔗<class_Terrain3D_method_set_camera>`

Sets the camera the terrain snaps to.

.. rst-class:: classref-item-separator


.. rst-class:: classref-method

|void| set_editor(editor: :ref:`Terrain3DEditor<class_Terrain3DEditor>`) :ref:`🔗<class_Terrain3D_method_set_editor>`

Sets the current Terrain3DEditor instance.

.. rst-class:: classref-item-separator


.. rst-class:: classref-method

|void| set_plugin(plugin: EditorPlugin) :ref:`🔗<class_Terrain3D_method_set_plugin>`

Sets the EditorPlugin connected to Terrain3D.