Terrain3D Documentation

Terrain3D is a high-performance, editable terrain system designed for Godot 4. It is implemented as a C++ GDExtension, making it compatible with official Godot Engine builds. It can be used via GDScript, C#, or any other language supported by Godot.

Key Capabilities:

• Scale: Supports terrain regions ranging from 64x64m up to 65.5x65.5km (4295km^2) in non-contiguous and variable-sized configurations.
• Visuals: Supports up to 32 textures and up to 10 levels of detail (LOD) for the terrain mesh.
• Foliage: Includes foliage instancing with up to 10 levels of detail and shadow impostors.
• Editing: Features sculpting, hole creation, texture painting, texture detailing, color painting, and wetness painting.
• Importing: Supports heightmap imports from HTerrain, Gaea, World Creator, World Machine, Unity, Unreal, and any tool capable of exporting heightmaps.

The Terrain3DData class is the central manager for terrain data in Terrain3D. It handles the loading and unloading of regions, data retrieval, and data manipulation.

Terrain3D organizes data into regions arranged on a world grid (known as region locations). The actual map data is stored in Terrain3DRegion instances, which are saved to individual files. Terrain3DData coordinates these pieces to provide a unified interface for the terrain.

Terrain3D offers two distinct methods for rendering foliage and objects:

1. Particle Shader (particles): Uses the GPU to automatically generate meshes around the camera. This is ideal for high-density, procedurally generated meshes like grass. An example is available in extras/particle_example.

2. Terrain3DInstancer (instances): Uses Godot's MultiMesh class to optimally render hundreds of thousands of meshes that have been placed manually or via code. This is better for specific objects like rocks, trees, or debris.

Terrain3D is a vertex painter, not a pixel painter.

Performance vs. Precision:

• To maintain high performance, texel density is spread out. For example, 1024x1024 pixels might cover 1024m x 1024m.
• Each square meter is influenced by only 4 pixels of data at its corners.
• Limitation: Pixel-perfect painting is not practical. The system is designed for natural blending of quality textures between vertices rather than high-frequency pixel detail.
• Use Case: It is optimized for producing natural environments using sophisticated blending algorithms.

The Terrain3DTextureAsset is a Resource that contains a set of texture files and specific settings. These assets are intended to be added to a Terrain3DAssets resource.

Important: Textures must be prepared according to the project's specific texture preparation guidelines before use.

Terrain3D uses a Geomorphing Geometric Clipmap Mesh Terrain (similar to the system used in The Witcher 3).

Key characteristics:

• Automatic LOD: The terrain consists of several flat meshes with varying density; density is higher near the center (camera) and lower further away.
• LOD Blending: Levels of Detail (LODs) are blended together in a circular pattern.
• Camera-Centric: Meshes are centered on the camera to maintain high LODs near the player. While meshes move, the terrain appears stable because the underlying height data remains fixed in world space.

Terrain3D uses a vertex-based painting system rather than a pixel-based one. Texture codes are painted at each vertex (defaulting to 1m intervals) and represented as pixels on a Control map. The shader uses material parameters to interpolate and blend these values between vertices.

To inspect the generated shader code, you can enable shader_override_enabled in the material and leave the shader override slot empty. For a minimal implementation of terrain height without texturing, refer to addons/terrain_3D/extras/shaders/minimum.gdshader.

Terrain3D uses a geometry clipmap approach for terrain rendering rather than a traditional grid of mesh chunks.

Key characteristics:

• Mesh Generation: Mesh components are generated once at startup and periodically recentered on the camera location.
• LOD (Level of Detail): LODs are built into the initial mesh generation. Lower detail levels are automatically placed at a distance as mesh components recenter on the camera.
• Vertex Updates: Vertex heights are adjusted on each update via a GPU vertex shader that reads from the terrain heightmap.
• Memory Efficiency: The system allows for allocating regions for sculpting and texturing only where needed. This means you only pay VRAM and storage costs for used areas (e.g., islands in a large ocean), rather than the entire world bounds.

To begin using Terrain3D in your Godot 4 project, follow these steps:

1. Understand the System: Read the Introduction to learn how the terrain system operates.
2. Install the Addon: Follow the Installation & Upgrade instructions.
3. Learn via Tutorials: Watch the tutorial videos and consult the official documentation.
4. Get Support: If you encounter issues, refer to the Getting Help guide or join the Discord server.