Class reference

WorldScape3D

Inherits Node3D

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

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

int cast_shadows = 1

Tells the renderer how to cast shadows from the terrain onto other objects. This sets [code skip-lint]GeometryInstance3D.ShadowCastingSetting[/code] in the engine.

float cull_margin = 0.0

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 [code skip-lint]GeometryInstance3D.extra_cull_margin[/code], 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 = ""

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

int 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 [code skip-lint]--terrain-debug=LEVEL[/code] where [code skip-lint]LEVEL[/code] is one of [code skip-lint]ERROR, INFO, DEBUG, EXTREME[/code]. The last includes continuously recurring messages like position updates for the mesh as the camera moves around.

bool free_editor_textures = true

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

int gi_mode = 1

Tells the renderer which global illumination mode to use for WorldScape3D. This sets [code skip-lint]GeometryInstance3D.gi_mode[/code] in the engine.

float label_distance = 0.0

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.

WorldScape3DMaterial material

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

int mesh_lods = 7

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

int mesh_size = 48

The correlated size of the terrain meshes. Lod0 has [code skip-lint]4*mesh_size + 2[/code] 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

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 [code skip-lint]get_intersection[/code], which the mouse cursor uses. You may place other objects on this layer, however [code skip-lint]get_intersection[/code] 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 [code skip-lint]get_intersection[/code], and then you can use it during game play. See get_intersection().`

int 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. WorldScape3D.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

The render layers the terrain is drawn on. This sets [code skip-lint]VisualInstance3D.layers[/code] 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

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_instances = true

Shows or hides all instancer meshes.

float vertex_spacing = 1.0

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.

Methods

Mesh bake_mesh(int lod, int filter = 0) const

Generates a static ArrayMesh for the terrain. [code skip-lint]lod[/code] - Determines the granularity of the generated mesh. The range is 0-8. 4 is recommended. [code skip-lint]filter[/code] - Controls how vertex Y coordinates are generated from the height map. See WorldScape3DData.HeightFilter.

PackedVector3Array generate_nav_mesh_source_geometry(AABB global_aabb, bool require_nav = 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. [code skip-lint]global_aabb[/code] - If non-empty, geometry will be generated only within this AABB. If empty, geometry will be generated for the entire terrain. [code skip-lint]require_nav[/code] - 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(Vector3 src_pos, Vector3 direction, bool gpu_mode = false)

Casts a ray from [code skip-lint]src_pos[/code] pointing towards [code skip-lint]direction[/code], 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 [code skip-lint]gpu_mode[/code]: - 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 [code skip-lint]Vector3(3.402823466e+38F,...)[/code]. You can check this case with this code: [code skip-lint]if point.z > 3.4e38:[/code] - On error, it returns [code skip-lint]Vector3(NAN, NAN, NAN)[/code] and prints a message to the console.

Vector3 get_snapped_position() const

Returns the last position the terrain was centered on.

void set_camera(Camera3D camera)

Sets the camera the terrain snaps to.

Signals

assets_changed()

Emitted when assets is changed.

material_changed()

Emitted when material is changed.

Constants

ERROR = 0

Enum: DebugLevel

Errors and warnings always print.

INFO = 1

Enum: DebugLevel

Typically every function call and other important informational messages.

DEBUG = 2

Enum: DebugLevel

Detailed steps within functions.

EXTREME = 3

Enum: DebugLevel

Messages for continuous operations like snapping and editing.

SIZE_64 = 64

Enum: RegionSize

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

SIZE_128 = 128

Enum: RegionSize

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

SIZE_256 = 256

Enum: RegionSize

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

SIZE_512 = 512

Enum: RegionSize

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

SIZE_1024 = 1024

Enum: RegionSize

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

SIZE_2048 = 2048

Enum: RegionSize

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

SIZE_4096 = 4096

Enum: RegionSize

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

Source revision 5592dc3a7a61
Connection interrupted. Reload×

Rejoining the server...

Rejoin failed... trying again in seconds.

Failed to rejoin.
Please retry or reload the page.

The session has been paused by the server.

Failed to resume the session.
Please retry or reload the page.