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 [url=https://terrain3d.readthedocs.io/en/stable/docs/system_architecture.html]System Architecture[/url] for design details. 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 [enum Terrain3DData.HeightFilter]. 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). Returns the camera the terrain is currently tracking for position, if not overridden by [member clipmap_target]. See [method set_camera]. Returns the position on which the terrain mesh is centered, which may be the camera or a target node. See [member clipmap_target]. Returns the position on which the terrain collision is centered, which may be the camera or a target node. See [member collision_target]. Returns the current Terrain3DEditor instance, if it has been set. 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 and is not a typical raycast, so enabling collision is unnecessary. This function likely won't work if src_pos is below the terrain. This function can operate in one of two modes selected by [code skip-lint]gpu_mode[/code]: - If gpu_mode is disabled (default), it raymarches from src_pos until the terrain is intersected, up to 4000m away. This works with one function call, and can only intersect the terrain 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, set with [member mouse_layer]) while using this function. 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: [codeblock] 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) [/codeblock] 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. Also see [method get_raycast_result] and [method Terrain3DData.get_height] for alternative functions. Returns the EditorPlugin Object connected to Terrain3D. This is a helper function that creates a general physics-based raycast and returns the resulting dictionary; it's not limited to terrain use. Raycasts can only detect collision. It is used by our editor using the `on_collision` option to instance on non-terrain meshes. Direction is added to src_pos and includes magnitude. So to run a raycast from (100, 100, 100) to the ground 100m below, direction would be (0, -110, 0) with margin. Collision_mask has the physics layers the query will detect as a bitmask. By default, all collision layers are detected. See [url=https://docs.godotengine.org/en/stable/classes/class_physicsdirectspacestate3d.html#class-physicsdirectspacestate3d-method-intersect-ray]PhysicsDirectSpaceState3D.intersect_ray[/url] for how to interpret the resulting dictionary. Also see [method get_intersection] and [method Terrain3DData.get_height] for alternative functions. Specifies the camera on which the terrain centers. It attempts to aquire the camera from the active viewport. If the camera is instanced in a sub scene or by code, Terrain3D might not be able to find it, will issue an error, and the terrain will center at (0,0,0) causing LODs to not update until a trackable node is set. Either specify the camera, or specify the clipmap and/or collision targets. It will use the targets first and fall back to the camera if they are null. See [member clipmap_target] and [member collision_target]. Sets the current Terrain3DEditor instance. Sets the EditorPlugin Object connected to Terrain3D. Queues the terrain mesh and collision to snap their positions to the target nodes on the next physics frame. Typically this only happens if the targets have moved sufficiently far. See [member clipmap_target] and [member collision_target]. The list of texture and mesh assets used by Terrain3D. You can optionally save this as an external [code skip-lint].tres[/code] text file if you wish to share it with Terrain3D nodes in other scenes. Tells the renderer how to cast shadows from the terrain onto other objects. This sets [code skip-lint]GeometryInstance3D.ShadowCastingSetting[/code] in the engine. The terrain mesh will center itself at the position of this node. If null, it will fall back to the camera position. See [method set_camera]. The active [Terrain3DCollision] object. The physics layers the terrain lives on. Sets [code skip-lint]CollisionObject3D.collision_layer[/code]. Alias for [member Terrain3DCollision.layer]. Also see [member collision_mask]. The physics layers the physics body scans for colliding objects. Sets [code skip-lint]CollisionObject3D.collision_mask[/code]. Alias for [member Terrain3DCollision.mask]. Also see [member collision_layer]. The selected mode determines if collision is generated and how. See [enum Terrain3DCollision.CollisionMode] for details. Alias for [member Terrain3DCollision.mode]. The priority with which the physics server uses to solve collisions. The higher the priority, the lower the penetration of a colliding object. Sets [code skip-lint]CollisionObject3D.collision_priority[/code]. Alias for [member Terrain3DCollision.priority]. If [member collision_mode] is Dynamic, this is the distance range within which collision shapes will be generated. Alias for [member Terrain3DCollision.radius]. If [member collision_mode] is Dynamic, this is the size of each collision shape. Alias for [member Terrain3DCollision.shape_size]. In dynamic mode, the terrain collision will center itself at the position of this node. If null, it will fall back to the [member clipmap_target] position and failing that will use the camera position. See [method set_camera]. This margin is added to the vertical component of the terrain mesh bounding boxes (AABB). The terrain already sets its AABB from [method 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 [member Terrain3DMaterial.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. This class manages loading, saving, adding, and removing of Terrain3DRegions and access to their content. The directory where terrain data will be saved to and loaded from. 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]--terrain3d-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. A global multiplier for all displaced textures. This is the maximum distance that 2 adjacent verticies can be vertically seperated by. Setting this 1.0 would mean a maximum of + 0.5m, and -0.5m deviation from the collision mesh. Alias for [member Terrain3DMaterial.displacement_scale]. Adjusts the transition between textures. When set at `1.0`, the blending of displacment between textures will match the aldebo/normal blend sharpness exactly. Lower values will have a softer transition, avoiding harsh shapes, without compromising the abldeo and normal blend sharpness. If set at or very near to `0.0`, it is possible that more displaced textures can affect less displaced textures at low blend values even if not visible. Alias for [member Terrain3DMaterial.displacement_sharpness]. Frees ground textures used for editing in _ready(). These textures are used to generate the TextureArrays, so if you don't change any [Terrain3DTextureAsset] 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 [method Terrain3DAssets.clear_textures]. Tells the renderer which global illumination mode to use for the terrain mesh. This sets [code skip-lint]GeometryInstance3D.gi_mode[/code] in the engine. The active [Terrain3DInstancer] object. Normal - Generates MultiMeshInstance3Ds and renders all instances as normal. Disabled - prevents the instancer from creating any MultiMeshInstance3Ds. Alias for [member Terrain3DInstancer.mode]. 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. Sets the font size for region labels. See [member label_distance]. A custom material for Terrain3D. You can optionally save this as an external [code skip-lint].tres[/code] text file if you wish to share it with instances of Terrain3D in other scenes. See [Terrain3DMaterial]. The number of lods generated for the terrain meshes. Enable wireframe mode in the viewport to see them. 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. 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 [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 Terrain3D, 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 [method get_intersection]. Tells the renderer how to cast shadows from the ocean onto other objects. This sets [code skip-lint]GeometryInstance3D.ShadowCastingSetting[/code] in the engine. This margin is added to the vertical component of the ocean mesh bounding boxes (AABB). When you set the height of your waves in the shader, this margin should be adjusted. If it's too small, the meshes will clip at certain camera angles. If you set it too large, the renderer may have slightly more work to do. This setting is similar to [code skip-lint]GeometryInstance3D.extra_cull_margin[/code], but it only affects the Y axis. Generates another clipmap mesh, which you can apply an ocean shader to and configure independently of the terrain mesh. Tells the renderer which global illumination mode to use for the ocean mesh. This sets [code skip-lint]GeometryInstance3D.gi_mode[/code] in the engine. This sets the _light_direction and _light_color uniforms in the ocean shader, if they are present. You can use this for light scattering, detecting if the light is above the horizon, albedo coloring, etc. You can assign a [code skip-lint]StandardMaterial[/code] here for testing, but you really need a [code skip-lint]ShaderMaterial[/code]. Start with the example in [code skip-lint]addons/terrain_3d/extras/shaders/M_ocean.tres[/code], which you can build on. Or use any of the ocean shaders available around the internet, provided you set `skip_vertex_transform` and copy the geomorphing code from our `vertex()` shader, which will properly handle the LOD transitions on the clipmap. The number of lods generated for the ocean meshes. Enable wireframe mode in the viewport to see them. The correlated size of the ocean meshes. Lod0 has [code skip-lint]4*ocean_mesh_size + 2[/code] quads per side. E.g. when ocean_mesh_size=8, lod0 has 34 quads to a side, including 2 quads for seams. The render layers the ocean is drawn on. This sets [code skip-lint]VisualInstance3D.layers[/code] in the engine. This setting creates up to 6 additional subdivisions of the ocean mesh below LOD0, which provides more vertices for the vertex shader if desired. You can see it in wireframe mode. The distance between vertices, settable up to 100. Godot units are typically considered to be meters. This laterally scales the ocean vertices on X and Z axes, but does not scale wave height. Applies a [code skip-lint]PhysicsMaterial[/code] override to the entire terrain StaticBody. Alias for [member Terrain3DCollision.physics_material] See that entry for details. The number of vertices in each region, and the number of pixels for each map in [Terrain3DRegion]. 1 pixel always corresponds to 1 vertex. [member Terrain3D.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. 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 via code, make sure the layer for [member mouse_layer] is included, or set that variable again after this so that the mouse cursor and [method get_intersection] work. 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. Displays the area designated for use by the autoshader, which shows materials based upon slope. Alias for [member Terrain3DMaterial.show_autoshader]. Shows a checkerboard display using a shader rendered pattern. This is turned on if the Texture List is empty. Note that when a blank texture slot is created, a 1k checkerboard texture is generated and stored in the texture slot. That takes VRAM. The two patterns have a slightly different scale. Alias for [member Terrain3DMaterial.show_checkered]. Shows the color map in the albedo channel. Alias for [member Terrain3DMaterial.show_colormap]. Overlays contour lines on the terrain. Customize the options in the material when enabled. Press `4` with the mouse in the viewport to toggle. Alias for [member Terrain3DMaterial.show_contours]. Albedo shows the painted angle. Orange means 0°, Yellow 270°, Cyan 180°, Violet 90°. Or warm colors towards -Z, cool colors +Z, greens/yellows +X, reds/blues -X. Draw all angles coming from the center of a circle for a better understanding. Alias for [member Terrain3DMaterial.show_control_angle]. Displays the values used to blend the textures. Blue shows the autoshader blending, red shows manually painted blending. Alias for [member Terrain3DMaterial.show_control_blend]. Albedo shows the painted scale. Larger scales are more red, smaller scales are more blue. 0.5 middle grey is the default 100% scale. Alias for [member Terrain3DMaterial.show_control_scale]. Albedo shows the base and overlay texture indices defined by the control map. Red pixels indicate the base texture, with brightness showing texture ids 0 to 31. Green pixels indicate the overlay texture. Yellow indicates both. Alias for [member Terrain3DMaterial.show_control_texture]. Alias for [member Terrain3DMaterial.show_displacement_buffer]. Albedo is set to 0.2 grey. Alias for [member Terrain3DMaterial.show_grey]. Alias for [member Terrain3DMaterial.show_region_grid]. Press `1` with the mouse in the viewport to toggle. Albedo is a white to black gradient depending on height. The gradient is scaled to a height of 300, so above that or far below 0 will be all white or black. Alias for [member Terrain3DMaterial.show_heightmap]. Overlays the 32x32m instancer grid on the terrain, which shows how the instancer data is partitioned. Press `2` with the mouse in the viewport to toggle. Alias for [member Terrain3DMaterial.show_instancer_grid]. Highlights non-smooth areas of the terrain. Jagged peaks, troughs, or edges that are a bit rough with sharp angles between vertices. Alias for [member Terrain3DMaterial.show_jaggedness]. Displays the area designated for generating the navigation mesh. Alias for [member Terrain3DMaterial.show_navigation]. Overlays the region grid on the terrain. This is more accurate than the region grid gizmo for determining where the region border is when editing. Press `1` with the mouse in the viewport to toggle. Alias for [member Terrain3DMaterial.show_region_grid]. Albedo is set to the roughness modification map as grey scale. Middle grey, 0.5 means no roughness modification. Black would be high gloss while white is very rough. Alias for [member Terrain3DMaterial.show_roughmap]. Albedo textures are shown only. Other channels are excluded. Alias for [member Terrain3DMaterial.show_texture_albedo]. Albedo is set to the painted Ambient Occlusion textures. Alias for [member Terrain3DMaterial.show_texture_ao]. Albedo is set to the painted Height textures. Alias for [member Terrain3DMaterial.show_texture_height]. Albedo is set to the painted Normal textures. Alias for [member Terrain3DMaterial.show_texture_normal]. Albedo is set to the painted Roughness textures. This is different from the roughness modification map above. Alias for [member Terrain3DMaterial.show_texture_rough]. Overlays the vertex grid on the terrain, showing where each vertex is. Press `3` with the mouse in the viewport to toggle. Alias for [member Terrain3DMaterial.show_vertex_grid]. Enables displacement using texture heights for additional mesh detail when set above 0. This creates up to 6 additional subdivisions of the terrain mesh below LOD0, and adds a displacement buffer configurable in the material. You can see this in wireframe mode. Set to 0 to disable displacement. See [member Terrain3DMaterial.show_displacement_buffer] and look at the Displacement Buffer debug view. The current version of Terrain3D. The distance between vertices, settable up to 100. 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). It retains the same height. All Terrain3D functions with a global_position expect an absolute global value. If you would normally use [method 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. Emitted when [member assets] is changed. Emitted when [member material] is changed. Errors and warnings always print. Typically every function call and other important informational messages. Detailed steps within functions. Messages for continuous operations like snapping and editing. The region size is 64 x 64 meters, vertices, and pixels on Image maps. The region size is 128 x 128 meters, vertices, and pixels on Image maps. The region size is 256 x 256 meters, vertices, and pixels on Image maps. (default) The region size is 512 x 512 meters, vertices, and pixels on Image maps. The region size is 1024 x 1024 meters, vertices, and pixels on Image maps. The region size is 2048 x 2048 meters, vertices, and pixels on Image maps.

Files

Loading code snippet…