TerraBrush

TerraBrush

A simple GDExtension Terrain heightmap editor for Godot engine 4.5+

Disclaimer

This project has been made mainly for my own project.

I'm happy to share it with the community but it's possible that some features that you would expect are not there.

I'm gonna be happy to accept PR for new features if it fits.

Godot 4.4 and lower (4.x)

The demo scene was made for a previous version of the addon. A new one has been made to work with the new version.

Live demo

A live demo has been created to let you try the addon without the need of having Godot installed. It runs in the browser, hosted on itch.io :

Key Features

• Sculpt - Sculpt your terrain with a heightmap
  • Increase the terrain
  • Decrease the terrain
  • Smooth the terrain
  • Flatten the terrain
  • Set height (paint to a specific height)
  • Set angle (paint from a starting point with a specific angle)
• Paint color - Add colors to your terrain
• Paint textures - Add textures to your terrain with the painting tool
  • Normal map and roughness texture are supported
  • Automatic slope based texturing
• Foliage - Add foliage to your terrain (ex. Grass)
  • The foliage follows the main camera with a given maximum distance
• Packed scenes - Scatter packed scenes to the terrain
  • Multiple objects can be scattered with one brush
  • Random rotation is supported
  • The packed scenes will always follow the terrain
  • Live adjustment of the position while the terrain is sculpting
• Water - Add water to your terrain
  • The water will make the terrain go lower for the painted area
  • The packed scenes and the foliage will also get lower with the water
  • Support for custom shader
• Water flow - Paint the direction of the water
• Snow - Add thick snow to your terrain
  • The texture of the snow is configurable so it's easy to make something like sand
  • Support for custom shader
• Hole - Paint hole. Useful to create cave or juste to make a terrain that is not square.
• Multiple brushes
  • Custom brushes are also available
• Slope painting limit - Limit the painting with slope angles for ALL the tools
• Pie menu
• Shortcuts
  • The plugin has been made so it's really easy to use. A lot of shortcuts are available.
    • LShift - Reverse the tool. Usually, this option will go from "Add" to "Remove". For the sculpting option, this does the "Smooth" option.
    • V - Show the PieMenu for the current tool
    • B - Show the PieMenu for the current brush
    • N - Show the options for the current tool (ex. While painting the textures, the PieMenu will show textures)
    • G - Show a quick select for the brush size
    • J - Show a quick select for the brush strength
    • K - Toggle "Auto add zones"
    • X - Lock on X axis
    • Z - Lock on Z axis
  • Shortcuts can be Re-Assigned. To Access them, Goto 'Project->Tools->TerraBrush Key bindings' to access the keymap, and ability to re-assign keys. - Implemented by @eumario
• Settings - Some settings are available in the "ProjectSettings->TerraBrush" (ex. The decal color)
• LOD - The terrain is created using a custom clipmap mesh so less vertices are needed. https://youtu.be/BardvKC0HF0
• MultiZones - The terrain supports multiple zones (or chunks or regions) to improve performances on bigger terrain. https://youtu.be/X_klfk-kdSE
• Heightmap based blending - Textures can be blended with heightmaps/bumpmaps with custom intensity. - Implemented by @ZaPx64
• Paint locked areas - Areas on the terrain can be locked so you don't modify completed parts
• Paint meta info - Define meta info on parts of the terrain. This can be retrieved using the GetPositionInformation function.
• Import and Export - Import and export terrain from/to various images.
• In game editor - TerraBrush supports In game editing from the node TerraBrushEditor, perfect to make custom maps from your game (experimental)
• Web Export - The TerraBrush node and the TerraBrushEditor node both works with Web Exports (experimental)

GDExtension

[!NOTE] TerraBrush used to be a C# addon, it's not the case anymore!!! (https://youtu.be/m3Iq8OZ3XZk)

The whole project has be rewritten in C++ as a GDExtension, to make it work with more systems (Web Exports, Godot without .Net, etc.)

Starting from the version 0.14.0-alpha, C# is not required anymore.

[!IMPORTANT] Since everything has been rewritten, from C# to C++, I could not make it work automatically with previously created terrain (before 0.14.0-alpha).

Using a terrain created with the C# version

As I said, I cannot make the old terrain from C# work as is. But! I made a script that let you convert a terrain from the old C# version.

The script is available here : https://github.com/spimort/TerraBrush/blob/main/demo/terra_brush_legacy_converter.gd

• Just create a scene, with a node.
• Set the script to the node.
• Set the property for the existing scene that has a TerraBrush node in it, and the folder of the Data (from DataPath).
• Hit that convert button.

The script will try its best to cover the conversion but it might not be perfect. Feel free to adapt the script to your needs.

TerraBrushEditor Node

The addon includes a node called TerraBrushEditor that let you paint your terrain in game. This can be useful to allow your community to help you build your terrain.

This feature is still a work in progress so expect some changes on it in the future.

WebExport

The web export works just fine with TerraBrush (and with the TerraBrushEditor node). Since the web uses the compatibility renderer (OpenGL), you could see some noticable visual differences.

The web export is still experimental and could change in the future.

How To Use

Watch the tutorial video (it was made for the C# version but most of the stuff are about the same, until a new video is created for the new version) ! https://youtu.be/n5WeAqeea1c

Download one of the release from https://github.com/spimort/TerraBrush/releases.

Extract the downloaded zip file into your project. The zip file should have an addons folder with the TerraBrush content.

[!IMPORTANT] If Godot was open when you extrated the addon to the project, sometimes, Godot just closes. Just reopen it, it should be fine.

[!NOTE] You don't need to enable/disable the plugin, just having it present in the project under addons is enough to enable it.

Add the node - To add a terrain node, in the "Add node" screen, search for "Node3D->TerraBrush" ()

Create the terrain

To create the terrain, there is a popup menu called "Terrain" with some options to create/update/remove, located in the tool menu of Godot (close to your viewport options). Make sure you have a DataPath set for your terrain before to create it. This DataPath should be unique per terrain.

Update the terrain

Some properties of the node require the terrain to refresh (mainly for the shaders and stuff). If something does not refresh, hit that "UpdateTerrain" button!

For example, if you add a new texture, add foliage, add an object, add a water definition or add snow, you'll have to hit the "UpdateTerrain" button.

This was designed this way to avoid spamming the properties of the terrain to update too often. This let you play with the settings before to force the terrain to recreate itself.

Node properties

Property	Description
Terrain Settings
Zones Size	This is the size of the zones (in meters). By default, it will be 256m. There is no limit for this value but having a really high value will decrease the performance. Each zone will be created with this size.
Resolution	This determines the terrain resolution. By default, the resolution is 1. For each pixel in the heightmap image, 1m of terrain is calculated (1px = 1m). Increasing the resolution means each pixel will cover more terrain: a resolution of 2 covers 2m per pixel, and a resolution of 4 covers 4m per pixel. This helps reduce the heightmap file size and create a terrain with fewer polygons.

The resolution applies only to components affecting the terrain shape (Heightmap, Water, Snow). All other components maintain a resolution of 1 for precision painting. The resolution must be either 1 or a power of 2. When using a resolution higher than 1, the ZonesSize must be a power of 2 plus 1 (e.g., 257). It is also recommended to set the LODInitialCellWidth to match the resolution.| |Data Path|In order to work, TerraBrush needs to have somewhere to store some files. Make sure the option for "Data Path" is filled. If possible, the tool will fill in information by itself.| |Collision Only|This option is useful for running for example a Game Server. This will only create the collisions of the terrain (the packed scenes will also be created since they could have a collision shape)| |Visual Instance Layers|The godot layer on which the terrain will be displayed.| |Custom Shader|Allow you to use a custom shader for the terrain.| |Create Terrain|Create the terrain with the current settings (everything that has been done will be cleared).| |Update Terrain|Update the terrain with the current settings (it will keep everything that has been painted). This option is useful if you modify something that has a direct impact on the map (ex. Add a new texture, foliage, packed scenes, etc.).| |Remove Terrain|Remove the current terrain (everything that has been done will be cleared).| |Lock all terrain|Lock all parts of the current Terrain.| |Unlock all terrain|Unlock all parts of the current Terrain.| |Import Terrain|Import terrain components from various images.| |Export Terrain|Export all components of the terrain to images.| |LOD|| |Chunk Mesh|Whether or not the clipmap is chunked (chunked means more draw calls but better frustum culling so might get you better perfs).| |Chunk AABB Height|Control the AABB height of each chunk. If left to -1 (default value), the zone size will be used as the height (ex. 256).| |LOD Levels|The number of levels the clipmap will be made of. The default value is 5.| |LOD Rows Per Level|The number of rows per level. This is a base number, depending on the level, there might be more rows (ex. the first level is a little bit different so it has more cells). The default value is 101.| |LOD Initial Cell Width|The initial size of the cell. Each level will double the size of the previous level cell' size. the default value is 1.0 (1 meter)| |Collisions|| |Create Collision In Thread|Create the collision shape in a thread. This helps a lot when editing the terrain. This also means that the collision could appear late compared to the terrain. The default value is true.| |Collision Layers|The terrain collision layers| |Collision Mask| The terrain collision mask| |Textures|| |Texture Sets|Let you define the textures of the terrain. Be aware, that all the textures must be in the same format (ex. Mipmaps, compression mode, etc.). Make sure to hit the update terrain button when you modify this and the terrain has already been created. You should create a TextureSetsResource which holds several TextureSetResource. A set will accept an Albedo, Normal and Roughness texture. You can create a resource file with the TextureSetsResource so you can reuse your textures with other terrain.| |TextureSetResource[x].Name|The name of the texture. This information is useful when you want to query the terrain to know the texture at a specific position.| |TextureSetResource[x].AlbedoTexture|The albedo texure of the set.| |TextureSetResource[x].AlbedoColorMapTexture|Not working with the compatibility renderer. Apply a gradient color map to the albedo texture (Gray scaled albedo texture works best).| |TextureSetResource[x].AlbedoCurveTexture|Not working with the compatibility renderer. **Only available when usi