Attention: Here be dragons (unstable version)

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Redot.

Checking the stable version of the documentation...

WorldScape3D

Inherits: Node3D < Node < Object

Description

WorldScape3D is a clipmap based terrain system that supports terrains from 64x64m up to 65.5x65.5km with multiple LODs, 32 textures, with imported or locally created terrains.

This class handles mesh generation, and management of the whole system.

Properties

WorldScape3DAssets

assets

ShadowCastingSetting

cast_shadows

1

WorldScape3DCollision

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

WorldScape3DData

data

String

data_directory

""

DebugLevel

debug_level

0

bool

free_editor_textures

true

GIMode

gi_mode

1

WorldScape3DInstancer

instancer

float

label_distance

0.0

int

label_size

48

WorldScape3DMaterial

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_jaggedness

false

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

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

Vector3

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

Vector3

get_snapped_position() const

void

set_camera(camera: Camera3D)

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.

RegionSize SIZE_4096 = 4096

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

Property Descriptions

WorldScape3DAssets assets 🔗

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

ShadowCastingSetting cast_shadows = 1 🔗

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

WorldScape3DCollision collision 🔗

The active WorldScape3DCollision object.

int collision_layer = 1 🔗

  • void set_collision_layer(value: int)

  • int get_collision_layer()

Alias for WorldScape3DCollision.layer.

int collision_mask = 1 🔗

  • void set_collision_mask(value: int)

  • int get_collision_mask()

Alias for WorldScape3DCollision.mask.

CollisionMode collision_mode = 1 🔗

Alias for WorldScape3DCollision.mode.

float collision_priority = 1.0 🔗

  • void set_collision_priority(value: float)

  • float get_collision_priority()

Alias for WorldScape3DCollision.priority.

int collision_radius = 64 🔗

  • void set_collision_radius(value: int)

  • int get_collision_radius()

Alias for WorldScape3DCollision.radius.

int collision_shape_size = 16 🔗

  • void set_collision_shape_size(value: int)

  • int get_collision_shape_size()

Alias for WorldScape3DCollision.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 WorldScape3DData.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 WorldScape3DMaterial.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.

WorldScape3DData data 🔗

This class manages loading, saving, adding, and removing of WorldScape3DRegions 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 🔗

The verbosity of debug messages printed to the console. Errors and warnings are always printed. This can also be set via command line using --terrain-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 in _ready(). These textures are used to generate the TextureArrays, so if you don't change any WorldScape3DTextureAsset settings in game, this can be enabled. Also reloads the texture asset list in _enter_tree() in case you load scenes via code and need the textures again. Calls WorldScape3DAssets.clear_textures().

GIMode gi_mode = 1 🔗

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

WorldScape3DInstancer instancer 🔗

The active WorldScape3DInstancer 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.

WorldScape3DMaterial material 🔗

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

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

Redot 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 WorldScape3D, 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 🔗

Alias for WorldScape3DCollision.physics_material.

RegionSize region_size = 256 🔗

The number of vertices in each region, and the number of pixels for each map in WorldScape3DRegion. 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 WorldScape3DMaterial.show_autoshader.

bool show_checkered = false 🔗

  • void set_show_checkered(value: bool)

  • bool get_show_checkered()

Alias for WorldScape3DMaterial.show_checkered.

bool show_colormap = false 🔗

  • void set_show_colormap(value: bool)

  • bool get_show_colormap()

Alias for WorldScape3DMaterial.show_colormap.

bool show_contours = false 🔗

  • void set_show_contours(value: bool)

  • bool get_show_contours()

Alias for WorldScape3DMaterial.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 WorldScape3DMaterial.show_control_angle.

bool show_control_blend = false 🔗

  • void set_show_control_blend(value: bool)

  • bool get_show_control_blend()

Alias for WorldScape3DMaterial.show_control_blend.

bool show_control_scale = false 🔗

  • void set_show_control_scale(value: bool)

  • bool get_show_control_scale()

Alias for WorldScape3DMaterial.show_control_scale.

bool show_control_texture = false 🔗

  • void set_show_control_texture(value: bool)

  • bool get_show_control_texture()

Alias for WorldScape3DMaterial.show_control_texture.

bool show_grey = false 🔗

  • void set_show_grey(value: bool)

  • bool get_show_grey()

Alias for WorldScape3DMaterial.show_grey.

bool show_grid = false 🔗

  • void set_show_region_grid(value: bool)

  • bool get_show_region_grid()

Alias for WorldScape3DMaterial.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 WorldScape3DMaterial.show_heightmap.

bool show_instancer_grid = false 🔗

  • void set_show_instancer_grid(value: bool)

  • bool get_show_instancer_grid()

Alias for WorldScape3DMaterial.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_jaggedness = false 🔗

  • void set_show_jaggedness(value: bool)

  • bool get_show_jaggedness()

Alias for WorldScape3DMaterial.show_jaggedness.

bool show_navigation = false 🔗

  • void set_show_navigation(value: bool)

  • bool get_show_navigation()

Alias for WorldScape3DMaterial.show_navigation.

bool show_region_grid = false 🔗

  • void set_show_region_grid(value: bool)

  • bool get_show_region_grid()

Alias for WorldScape3DMaterial.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 WorldScape3DMaterial.show_roughmap.

bool show_texture_height = false 🔗

  • void set_show_texture_height(value: bool)

  • bool get_show_texture_height()

Alias for WorldScape3DMaterial.show_texture_height.

bool show_texture_normal = false 🔗

  • void set_show_texture_normal(value: bool)

  • bool get_show_texture_normal()

Alias for WorldScape3DMaterial.show_texture_normal.

bool show_texture_rough = false 🔗

  • void set_show_texture_rough(value: bool)

  • bool get_show_texture_rough()

Alias for WorldScape3DMaterial.show_texture_rough.

bool show_vertex_grid = false 🔗

  • void set_show_vertex_grid(value: bool)

  • bool get_show_vertex_grid()

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

float vertex_spacing = 1.0 🔗

  • void set_vertex_spacing(value: float)

  • float get_vertex_spacing()

The distance between vertices. Redot 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 WorldScape3D functions with a global_position expect an absolute global value. If you would normally use WorldScape3DData.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.

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 Redot currently does not support co-routines nor forcing redraw in C++. 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.

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.