diff --git a/docs/gdevelop5/objects/.pages b/docs/gdevelop5/objects/.pages
index f123f4a948..1bea87cbae 100644
--- a/docs/gdevelop5/objects/.pages
+++ b/docs/gdevelop5/objects/.pages
@@ -8,6 +8,7 @@ nav:
- 3D Box: 3d-box
- 3D Model: 3d-model
- 3D Light: 3d-light
+ - 3D Terrain: 3d-terrain
- ...
- External Tilemap (LDtk/Tiled): tilemap
- Custom Objects ("Prefabs"): custom-objects-prefab-template
diff --git a/docs/gdevelop5/objects/3d-terrain/.pages b/docs/gdevelop5/objects/3d-terrain/.pages
new file mode 100644
index 0000000000..489dfffae3
--- /dev/null
+++ b/docs/gdevelop5/objects/3d-terrain/.pages
@@ -0,0 +1,7 @@
+nav:
+ - index.md
+ - Sculpting and painting: sculpting-and-painting.md
+ - Grass: grass.md
+ - Forests, rocks and bushes: scattered-models.md
+ - Holes, tunnels and caves: holes-and-tunnels.md
+ - Tips and best practices: tips.md
diff --git a/docs/gdevelop5/objects/3d-terrain/editor-terrain-selected.jpg b/docs/gdevelop5/objects/3d-terrain/editor-terrain-selected.jpg
new file mode 100644
index 0000000000..148ed6c80c
Binary files /dev/null and b/docs/gdevelop5/objects/3d-terrain/editor-terrain-selected.jpg differ
diff --git a/docs/gdevelop5/objects/3d-terrain/forest.jpg b/docs/gdevelop5/objects/3d-terrain/forest.jpg
new file mode 100644
index 0000000000..d099d184ea
Binary files /dev/null and b/docs/gdevelop5/objects/3d-terrain/forest.jpg differ
diff --git a/docs/gdevelop5/objects/3d-terrain/grass-meadow.jpg b/docs/gdevelop5/objects/3d-terrain/grass-meadow.jpg
new file mode 100644
index 0000000000..b594e674f2
Binary files /dev/null and b/docs/gdevelop5/objects/3d-terrain/grass-meadow.jpg differ
diff --git a/docs/gdevelop5/objects/3d-terrain/grass.md b/docs/gdevelop5/objects/3d-terrain/grass.md
new file mode 100644
index 0000000000..824c7b747b
--- /dev/null
+++ b/docs/gdevelop5/objects/3d-terrain/grass.md
@@ -0,0 +1,39 @@
+---
+title: Terrain grass
+---
+# Terrain grass
+
+The **terrain grass** object covers the ground with thousands of blades of grass, swaying in the wind and pushed aside by the characters walking through them. It brings life to meadows, gardens or the sides of a road at a low cost.
+
+
+
+## Add grass
+
+Add a **Terrain grass** object (in the "New object from scratch" tab of the new object dialog) and put an instance over the [3D terrain](index.md). The width and height of the instance are the area where grass grows. Grass grows on the highest terrain at each point of the area (so one field of grass can cover several terrains side by side), or at the Z position of the instance where there is no terrain.
+
+The grass follows the ground: sculpt or paint the terrain, and the grass moves, appears or disappears with it.
+
+## Choose where grass grows
+
+- **Grows on terrain layer**: blades only grow where this layer is painted on the terrain (usually layer 1, the grass layer). Paint a path, a road or a beach with another layer, and no grass grows there.
+- **Maximum slope**: no grass grows on steeper ground, like cliffs.
+- There is no grass in the [holes](holes-and-tunnels.md) of the terrain.
+
+The blades take the [tint](sculpting-and-painting.md#tinting-the-ground) of the ground under them: tint a patch of the meadow in yellow and the grass is dry there too.
+
+## Make it look the way you want
+
+- **Density**, **Blade height** and **Blade width**: a dense lawn, a sparse steppe, or tall grass up to the knees.
+- **Base color** and **Tip color**: blades go from the base color at the ground to the tip color at their top. Use darker and more saturated colors at the base to give depth to the grass.
+- **Wind strength** and **Wind speed**: from a light breeze to a storm. Set the strength to 0 for grass that doesn't move.
+- **Object bending the grass**: the name of an object (usually the player) pushing the blades aside as it walks through them.
+
+## Performance
+
+Grass is drawn efficiently, but thousands of blades still have a cost, especially on phones:
+
+- Only put grass where the player can see it closely. Instead of a single grass object covering a whole world, use several instances on the meadows, gardens and roadsides where the player goes (the 3D GTA with a map example uses three).
+- **Fade distance**: blades become less dense with the distance to the camera, and are hidden after this distance. A lower fade distance is faster. Far away, the color of the grass layer of the terrain is enough to show grass.
+- Lower the **density** on mobile games, and compensate with taller or wider blades.
+
+See also [Tips and best practices](tips.md).
diff --git a/docs/gdevelop5/objects/3d-terrain/hole-before-after.jpg b/docs/gdevelop5/objects/3d-terrain/hole-before-after.jpg
new file mode 100644
index 0000000000..bd2b8febf8
Binary files /dev/null and b/docs/gdevelop5/objects/3d-terrain/hole-before-after.jpg differ
diff --git a/docs/gdevelop5/objects/3d-terrain/hole-brush.jpg b/docs/gdevelop5/objects/3d-terrain/hole-brush.jpg
new file mode 100644
index 0000000000..b317c87e08
Binary files /dev/null and b/docs/gdevelop5/objects/3d-terrain/hole-brush.jpg differ
diff --git a/docs/gdevelop5/objects/3d-terrain/holes-and-tunnels.md b/docs/gdevelop5/objects/3d-terrain/holes-and-tunnels.md
new file mode 100644
index 0000000000..cd92d00636
--- /dev/null
+++ b/docs/gdevelop5/objects/3d-terrain/holes-and-tunnels.md
@@ -0,0 +1,62 @@
+---
+title: Holes, tunnels and caves
+---
+# Holes, tunnels and caves
+
+A [3D terrain](index.md) can have **holes**: there is no ground there, nothing is drawn, characters and objects fall through them, and the [grass](grass.md) and [scattered models](scattered-models.md) don't grow there. Holes are the entrances of tunnels, caves, wells or mines, and can also be dug during the game.
+
+
+
+## Make and fill holes in the scene editor
+
+Select the terrain, then:
+
+- **Make a hole** removes the ground in the brush circle.
+- **Fill holes** brings back the ground in the brush circle. Holes are filled with the layers of the ground around them, so a hole in grass is filled with grass.
+
+
+
+Like the other brushes, use **Undo** to remove the last strokes. Holes can also be written in the **Edits** property of the terrain (the `hole` and `fill` tools), see [The "Edits" property](sculpting-and-painting.md#the-edits-property-a-terrain-described-in-text).
+
+!!! note
+
+ A height field can't go under itself: a hole is only an opening in the ground. What's under the ground (the tunnel, the cave, the bottom of the well) is made with 3D models, as explained below.
+
+## Make a tunnel
+
+A tunnel through a hill is made of a few parts:
+
+1. **A 3D model of the tunnel**: a tube with a road inside, made in a 3D modeling software (like Blender) or found in an asset pack, and added as a [3D model object](/gdevelop5/objects/3d-model). Place it under the hill, with its ends at the faces of the hill.
+1. **Collisions inside the tunnel**: add the [3D physics behavior](/gdevelop5/behaviors/physics3d) to the tunnel, with the "Static" type and the "Mesh" shape: characters and cars drive on its road and are stopped by its walls.
+1. **Roads to the entrances**: flatten the ground in front of each entrance down to the floor of the tunnel, and paint the road.
+1. **Holes at the entrances**: make holes where the ground would be inside the tunnel, near its ends. Keep the ground above the rest of the tunnel: the player never sees the outside of the tube.
+
+
+
+Here is what's hidden under the hill of the "3D GTA with a map" example. The tunnel is a 3D model, with big concrete blocks around each entrance (the portals). They fill the space between the tube and the ground, so that only the tunnel is seen through the holes, whatever the angle of the camera:
+
+
+
+!!! tip
+
+ Make the ends of your tunnel model a bit larger than the holes, and make the holes a bit smaller than the inside of the tunnel. The edge of a hole always looks smooth, but collisions are removed for whole cells of the terrain, so the hole in the collisions can be up to one cell larger than the hole drawn. A tunnel model going a bit further than the hole covers the difference. Rocks or bushes around an entrance are another good way to hide the edges.
+
+Inside the tunnel, a camera following the player from far away could end up in the hill. Bring it closer while the player is under the ground: the "3D GTA with a map" example does it by comparing the Z position of the car with the **ground Z position** of the terrain above it, and changing the distance of its [third person camera](/gdevelop5/extensions/third-person-camera).
+
+
+
+## Caves, wells and mines
+
+The same recipe works for other places under the ground:
+
+- **A cave**: a hole in the side of a mountain, in front of a 3D model of the cave, with a mesh collision shape.
+- **A well or a pit**: a hole in flat ground, above a 3D model of the shaft (a cylinder open at the top).
+- **A mine with several entrances**: one model for the galleries, and a hole at each entrance.
+
+The **Carve an entrance** action makes the entrance of a tunnel or a cave on a slope, in one step: it flattens the ground in front of the entrance to the floor of the tunnel, and makes the hole.
+
+## Holes during the game
+
+Holes can be made and filled with actions during the game: dig into the ground, open a trap door in the floor, collapse the ground under a heavy object, or reveal the entrance of a secret cave when the player finds a key. Collisions are updated: objects above a new hole fall in it.
+
+To know if there is a hole at a position, use the **Hole** condition. The **Ground Z position, with holes** expression gives the height of the ground, or a value of your choice where there is a hole (for example a value far under the ground), to place objects only where there is ground. All the actions, conditions and expressions are listed in the [reference of the 3D terrain extension](/gdevelop5/extensions/terrain3d).
diff --git a/docs/gdevelop5/objects/3d-terrain/index.md b/docs/gdevelop5/objects/3d-terrain/index.md
new file mode 100644
index 0000000000..da958f8b44
--- /dev/null
+++ b/docs/gdevelop5/objects/3d-terrain/index.md
@@ -0,0 +1,109 @@
+---
+title: 3D Terrain
+---
+# 3D Terrain
+
+The **3D terrain** object is the ground of open worlds, adventure games, racing games or any 3D game that needs more than a flat floor: hills, mountains, valleys, islands, roads and paths. You shape it directly in the scene editor with brushes, like in a painting software, and paint it with up to 4 layers of textures (grass, dirt, rock, sand...).
+
+
+
+The terrain comes with two companion objects, which follow its shape automatically:
+
+- **Terrain grass**: thousands of blades of grass swaying in the wind, growing where the ground is painted with grass. See [Grass](grass.md).
+- **Scattered models**: forests, rocks, bushes or flowers made of hundreds or thousands of copies of a 3D model, drawn much faster than an object for each tree. See [Forests, rocks and bushes](scattered-models.md).
+
+The terrain can also have holes for the entrances of [tunnels and caves](holes-and-tunnels.md), and be tinted or made wet (see [Sculpting and painting](sculpting-and-painting.md)).
+
+!!! tip
+
+ Open the **3D GTA with a map** and **3D island terrain** examples from the home page of GDevelop to see a terrain with roads, forests, a tunnel, a beach and water, and to try the tools of this page on them.
+
+
+
+## Add a terrain to a scene
+
+In the objects list, add a new object and choose **3D terrain** in the "New object from scratch" tab. The grass and the scattered models are listed next to it.
+
+
+
+The terrain objects are in an extension of the community: if they are not listed, click the menu at the right of the search bar and choose to show experimental objects, or search for "terrain" in the extensions. Ready-to-use terrains (green hills, a tropical island, snowy mountains, desert dunes...) are also available in the asset store: search for "3D terrains".
+
+Put an instance of the terrain in the scene: its **width** and **height** are the size of the ground, and its **depth** is the height of the highest mountains. The **Z** position of the instance is the lowest point of the ground.
+
+!!! note
+
+ A terrain is often much bigger than the screen. A size of 4096 x 4096 is a good start for an island or a level, and 8192 x 8192 or more for an open world. For bigger worlds, put several terrains side by side.
+
+## Edit the terrain in the scene editor
+
+Select the terrain in the scene editor (click on the ground) to show its tools at the top of the 3D view:
+
+
+
+
+
+- **Sculpt**: raise, lower, smooth or flatten the ground.
+- **Paint layers**: paint one of the 4 layers (shown with their color).
+- **Holes**: make holes in the ground, or fill them again.
+- **Tint and wetness**: change the color of the ground, or make it wet.
+- **Brush size and strength**, and **Undo** for the last strokes.
+
+Choose a tool, then drag on the terrain to use it. Click again on the tool to stop using it and select other objects. Everything is explained in [Sculpting and painting](sculpting-and-painting.md).
+
+Your strokes are saved in the project when you release the mouse button. They are kept on top of the starting shape of the terrain (see below), so you can still change it afterwards.
+
+## Start from a relief or a heightmap
+
+Instead of sculpting everything by hand, start from a shape given in the properties of the object, in the **Shape** group:
+
+- **Relief**: flat, hills, mountains or an island. Change the **Seed** to get another terrain with the same kind of relief.
+- **Heightmap image**: a grayscale image where black is the lowest ground and white the highest (at the depth of the instance). Use it to import a terrain made in another software, or a real place.
+- **Resolution**: the number of cells on each side of the terrain. A higher resolution allows smaller details (like a narrow path or a small ditch), but takes more memory and time to load. Use the lowest resolution that keeps the details you need.
+
+The tools of the scene editor change the terrain on top of this shape.
+
+## Layers and textures
+
+{ align=right width=280 }
+
+A terrain has 4 layers, usually grass, dirt, rock and sand. Each layer has a **color** and, optionally, a **texture** (tinted by the color) and a **normal map** to show the bumps of the texture under the lights. Textures from ambientCG (with their "Color" and "NormalGL" images) work great.
+
+A few properties make the ground look more natural:
+
+- **Layer on steep slopes** and **Steep slope angle**: the slopes steeper than this angle automatically show a layer (usually rock), whatever is painted there. Sculpt a hill and its sides become rocky.
+- **Height blending**: where two layers meet, the stones or tufts of a texture cover the gaps of the other instead of fading into it.
+- **Texture variation**: makes the repetition of textures less visible.
+- **Texture size**: the size of one repetition of the textures in the scene.
+
+A new terrain is fully painted with the first layer: paint the other layers where you need them (see [Painting the layers](sculpting-and-painting.md#painting-the-layers)).
+
+
+
+## Lights and shadows
+
+Like other 3D objects, the terrain is lit by the lights of the layer: a directional light (the sun) and a hemisphere or ambient light are recommended. The terrain can cast and receive shadows: hills cast shadows on valleys, and trees, characters and buildings cast shadows on the ground. See [3D lights](/gdevelop5/objects/3d-light).
+
+## Collisions with characters, cars and objects
+
+Add the **[3D physics behavior](/gdevelop5/behaviors/physics3d)** to the terrain: characters (with the 3D physics character behavior), cars and other objects will walk, drive or roll on it, exactly following its shape. The terrain is always static: it's never moved by the physics engine, but its collisions are updated when it's changed during the game.
+
+For characters controlled by the computer, add the **floor/obstacle for pathfinding (navmesh based)** behavior to the terrain: characters with the [navmesh pathfinding behavior](/gdevelop5/behaviors/nav-mesh-pathfinding) will find their way on its hills and around its cliffs.
+
+## Use the terrain in events
+
+The terrain can be read and changed during the game with events. Some examples:
+
+- Put objects on the ground: the **Put objects on the ground** action places objects (or a group of objects) at the height of the ground under them. It's useful for objects created during the game, like collectibles or enemies.
+- Read the **ground Z position**, **slope** or **painted layer** at a position: to know if a character walks on sand or on a road (to play other footstep sounds, or slow down a car on grass), or to spawn objects only on flat ground.
+- Raise, lower, flatten, smooth and paint the ground: craters after an explosion, footprints, a road built by the player, terraforming... Raising and painting also work along a line, for paths, rivers or the trail of a vehicle.
+- Generate a new relief with a seed, or load a heightmap, for worlds made at random or loaded from levels.
+
+All the actions, conditions and expressions are listed in the [reference of the 3D terrain extension](/gdevelop5/extensions/terrain3d).
+
+## Learn more
+
+- [Sculpting and painting](sculpting-and-painting.md): the brushes, painting layers, tint and wetness, and the "Edits" property.
+- [Grass](grass.md): fields of grass swaying in the wind.
+- [Forests, rocks and bushes](scattered-models.md): scattered models.
+- [Holes and tunnels](holes-and-tunnels.md): tunnels, caves and wells.
+- [Tips and best practices](tips.md): performance, mobile games, big worlds and common problems.
diff --git a/docs/gdevelop5/objects/3d-terrain/new-object-terrain.jpg b/docs/gdevelop5/objects/3d-terrain/new-object-terrain.jpg
new file mode 100644
index 0000000000..0a08758118
Binary files /dev/null and b/docs/gdevelop5/objects/3d-terrain/new-object-terrain.jpg differ
diff --git a/docs/gdevelop5/objects/3d-terrain/paint-path.jpg b/docs/gdevelop5/objects/3d-terrain/paint-path.jpg
new file mode 100644
index 0000000000..e2d9ac8c40
Binary files /dev/null and b/docs/gdevelop5/objects/3d-terrain/paint-path.jpg differ
diff --git a/docs/gdevelop5/objects/3d-terrain/scattered-models-erase.jpg b/docs/gdevelop5/objects/3d-terrain/scattered-models-erase.jpg
new file mode 100644
index 0000000000..c803333aa0
Binary files /dev/null and b/docs/gdevelop5/objects/3d-terrain/scattered-models-erase.jpg differ
diff --git a/docs/gdevelop5/objects/3d-terrain/scattered-models-pack.jpg b/docs/gdevelop5/objects/3d-terrain/scattered-models-pack.jpg
new file mode 100644
index 0000000000..12b46f3f51
Binary files /dev/null and b/docs/gdevelop5/objects/3d-terrain/scattered-models-pack.jpg differ
diff --git a/docs/gdevelop5/objects/3d-terrain/scattered-models.md b/docs/gdevelop5/objects/3d-terrain/scattered-models.md
new file mode 100644
index 0000000000..38fd0c3d63
--- /dev/null
+++ b/docs/gdevelop5/objects/3d-terrain/scattered-models.md
@@ -0,0 +1,86 @@
+---
+title: Forests, rocks and bushes (scattered models)
+---
+# Forests, rocks and bushes (scattered models)
+
+A **scattered models** object places hundreds or thousands of copies of a 3D model on the ground: trees of a forest, rocks, bushes, flowers, mushrooms, tree stumps... All the copies are drawn at once, which is much faster than an object for each tree, including on phones. The copies follow the [3D terrain](index.md) when it's sculpted.
+
+
+
+## Add a forest
+
+The quickest way is to start from a ready-to-use forest: in the new object dialog, choose **Scattered models** in the "New object from scratch" tab. The assets of the "3D Scattered Models" pack are shown: forests of pines, leafy trees, birches, palm trees, rocks, bushes, flowers, cacti... Each one is already set up with a model, a size, a density and the slopes where it grows. Choose "Skip and create from scratch" to use your own 3D model (a .glb file).
+
+
+
+Put an instance of the object over the terrain: copies grow in the **area of the instance** (its width and height), on the highest terrain at each point, or at the Z position of the instance where there is no terrain. To cover a whole terrain, give the instance the same position and size as the terrain.
+
+Use one object for each kind of model: a pine forest, a leafy forest, bushes and rocks are four objects, which can cover the same area.
+
+## Choose where copies grow
+
+In the properties of the object:
+
+- **Copies grow**: **everywhere** in the area, or only where they are **painted** with the brushes or the edits (see below). Painted is best for forests with clearings, groves along roads, or rocks at the foot of cliffs.
+- **Grows on terrain layer**: copies only grow on this layer of the terrain, away from its borders. Paint roads and paths with another layer, and trees never stand on them.
+- **Maximum slope**: no copies on steeper ground. Use a low value for trees, and a higher one for rocks.
+- **Minimum ground Z** and **Maximum ground Z**: no copies under the water level (set the minimum to the Z of the water) or above the tree line on mountains (set the maximum).
+- **Density**: the number of copies in a square of 100 x 100 pixels. Copies are placed at random in a grid, so they never pile up on each other.
+- **Seed**: changes where the copies are, for another forest with the same density.
+
+## Paint and erase copies in the scene editor
+
+Click on a copy (like a tree) in the scene editor to select its object, and show its brushes above the 3D view:
+
+- **Add copies** paints where copies grow (when "Copies grow" is "painted"). With "everywhere", it brings back copies that were erased.
+- **Erase copies** removes copies: for clearings, the space around houses, or a path through a forest.
+- The **size** and **strength** of the brush, and **Undo**.
+
+
+
+!!! tip
+
+ When the terrain is selected, clicks on the ground are used by the brushes of the terrain. Choose another tool, or click again on the tool to stop using it, then click on a tree to select the forest.
+
+Like for the terrain, an **Edits** property (click "Show more" in the properties) lists the places where copies are added or erased, in a JSON format that can be changed by hand or by an AI. The brushes save their changes in the **Painted data** property: clear it to remove them.
+
+## Make the copies look natural
+
+- **3D model** and **Height of a copy**: copies keep the proportions of the model. Models made standing on the Y axis, like most models of the asset store, are stood up automatically.
+- **Smallest** and **largest random scale**: each copy gets a random scale between them, for trees of different ages.
+- **Random rotation**: turns each copy around the vertical axis, so that they don't all look the same.
+- **Random tint**: each copy is tinted between white and this color, for slightly different shades of leaves (white for no tint).
+
+## Collisions: trees that stop the player
+
+Rocks and trees should usually stop characters and cars, while bushes, flowers and grass tufts should not:
+
+1. Enable **Trunk collisions** in the properties of the object, and set the **Trunk diameter**: each copy gets a collision shape around its trunk (or around the rock), scaled with the copy.
+1. Add the **[3D physics behavior](/gdevelop5/behaviors/physics3d)** to the object, with the "Static" type.
+
+Characters and cars then bump into trees, while still walking under their branches. For characters controlled by the computer, add the **floor/obstacle for pathfinding (navmesh based)** behavior to the object too: they will walk around the trunks.
+
+Without trunk collisions, these behaviors have no effect on the object: characters walk through the copies.
+
+## Use copies in events
+
+The copies are not objects: they can't have their own variables or behaviors, but the object has actions, conditions and expressions to use them:
+
+- **Cut trees, break rocks, harvest bushes**: get the position of the nearest copy to the player (with the "X/Y position of the nearest copy" expressions), check the distance to it, then use the **Erase copies** action at this position, with a small radius. Create a falling tree (a 3D model object) at the same place for an animation.
+- **Plant trees** with the **Add copies** action.
+- Count the copies, for example to know how many trees are left in a forest.
+
+All the actions, conditions and expressions are listed in the [reference of the 3D terrain extension](/gdevelop5/extensions/terrain3d).
+
+!!! tip
+
+ Use regular [3D model objects](/gdevelop5/objects/3d-model) for the few trees or rocks that need their own behaviors or animations, like a tree that falls or a rock hiding a treasure, and scattered models for all the others.
+
+## Performance
+
+- **Draw distance**: copies shrink and disappear at this distance from the camera. Use a short distance for small plants (flowers, grass tufts, mushrooms), and a longer one for trees, which are seen from far.
+- **Cast shadows**: disable it for small plants and rocks. Shadows of trees look great, but cost more.
+- A lower **density** is faster, and often looks better: a forest doesn't need to be dense everywhere. Paint dense groves and keep sparse trees elsewhere.
+- Models with fewer triangles are faster: low poly models, like the ones of the asset store, are a good fit.
+
+See also [Tips and best practices](tips.md).
diff --git a/docs/gdevelop5/objects/3d-terrain/sculpt-brush.jpg b/docs/gdevelop5/objects/3d-terrain/sculpt-brush.jpg
new file mode 100644
index 0000000000..f77a45f4e6
Binary files /dev/null and b/docs/gdevelop5/objects/3d-terrain/sculpt-brush.jpg differ
diff --git a/docs/gdevelop5/objects/3d-terrain/sculpt-raise-before-after.jpg b/docs/gdevelop5/objects/3d-terrain/sculpt-raise-before-after.jpg
new file mode 100644
index 0000000000..a401654391
Binary files /dev/null and b/docs/gdevelop5/objects/3d-terrain/sculpt-raise-before-after.jpg differ
diff --git a/docs/gdevelop5/objects/3d-terrain/sculpting-and-painting.md b/docs/gdevelop5/objects/3d-terrain/sculpting-and-painting.md
new file mode 100644
index 0000000000..5c264d58c0
--- /dev/null
+++ b/docs/gdevelop5/objects/3d-terrain/sculpting-and-painting.md
@@ -0,0 +1,87 @@
+---
+title: Sculpting and painting a 3D terrain
+---
+# Sculpting and painting a 3D terrain
+
+Select a [3D terrain](index.md) in the scene editor to show its tools above the 3D view. Choose a tool, then drag on the terrain: a circle shows where the brush is. Click again on the tool to stop using it.
+
+
+
+The **brush size** and **brush strength** sliders change all the brushes. Use a big brush with a low strength for the large shapes (hills, valleys), then a smaller brush for the details. **Undo** removes the last strokes made on the terrain.
+
+## Sculpting
+
+- **Raise** and **Lower**: build hills and mountains, or dig valleys, lakes and riverbeds. The longer you hold the mouse button, the higher or deeper the ground goes.
+- **Smooth**: softens bumps and sharp edges. Use it after raising or lowering to get natural slopes.
+- **Flatten**: brings the ground to the height where the drag starts. Use it for plateaus, the ground under buildings, and the bed of roads: start the drag on the road, then drag along it.
+
+
+
+The sides of the hill above became rocky by themselves: the slopes steeper than the **Steep slope angle** show the **Layer on steep slopes**, whatever is painted there. Raise the angle to keep more grass on slopes, or lower it for a more rocky landscape.
+
+!!! tip
+
+ Objects placed on the terrain (trees, buildings, characters) don't move when you sculpt under them. Sculpt the terrain first, then place objects. The [grass](grass.md) and [scattered models](scattered-models.md) always follow the ground.
+
+## Painting the layers
+
+The 4 layer buttons (shown with the color of each layer) paint a layer: dirt for paths, sand for beaches, rock for cliffs, or any texture you've set in the properties of the terrain (see [Layers and textures](index.md#layers-and-textures)). The strength of the brush makes the layer cover the others more or less quickly, for soft or sharp borders.
+
+
+
+Painting is also how you choose where the [grass](grass.md) and the [scattered models](scattered-models.md) grow: they only grow on the layer given in their properties. In the image above, the grass doesn't grow on the dirt path. Paint roads with their own layer and trees will never stand in the middle of them.
+
+!!! tip
+
+ Use a texture with a normal map for each layer: the light of the sun makes the stones, cracks and tufts of the textures stand out. The ambientCG website has free textures for grass, dirt, rock, sand, snow, asphalt or tiles, with their normal maps ("NormalGL").
+
+## Tinting the ground
+
+The **Tint** tool multiplies the color of the ground by a color, without changing the painted layers. Use it for variety: dry or yellow patches in a meadow, burnt ground, darker soil under trees, autumn colors, or a reddish sand. Painting with white removes the tint.
+
+
+
+Choose the color of the brush in the toolbar after selecting the tool. The blades of the [terrain grass](grass.md) take the tint of the ground under them, so a dry patch also has dry grass.
+
+## Wet ground
+
+The **Wetness** tool makes the ground darker and shinier, like wet soil or sand. A slider next to it sets the wetness of the brush: all the way to the right for soaked ground, all the way to the left to dry the ground again.
+
+
+
+Use it for puddles on a path, a muddy riverbank, or the ground around a fountain. For the sand of a beach, there is no need to paint: in the **Wetness** group of the properties, enable **Wet shore** and set **Wet below Z** to the height of the water. The ground is wet under this height, and dries progressively over the height given in **Wet shore fade**.
+
+
+
+!!! tip
+
+ Set "Wet below Z" a bit above the Z position of your water object: the sand just above the water is wet too, as if the waves had just retreated.
+
+## The "Edits" property: a terrain described in text
+
+{ align=right width=300 }
+
+In the **Shape** group of the properties (click "Show more"), the **Edits** property describes changes of the terrain as a list of strokes written in JSON: raise, flatten, smooth, paint, tint, wetness, hole and fill. They are applied in order on top of the relief or the heightmap.
+
+Edits are useful because they can be read and changed: copy a road from a terrain to another, move a hill by changing its position, or ask the AI of GDevelop to shape the terrain ("add a lake in the north", "make a road from the town to the hill"). Strokes can follow a line (with `toX` and `toY`), and a flattened road can go up or down a slope (with `toZ`).
+
+Positions and sizes are fractions of the size of the terrain (0 is the left or top border, 1 the right or bottom border), and heights are fractions of its depth, so edits stay at the same place if the terrain is resized. For example, this flattens a road going up from the left of the terrain to its center, then paints it with the second layer:
+
+```json
+[
+ {"tool": "flatten", "x": 0.1, "y": 0.5, "toX": 0.5, "toY": 0.5, "radius": 0.02, "z": 0.05, "toZ": 0.2},
+ {"tool": "paint", "x": 0.1, "y": 0.5, "toX": 0.5, "toY": 0.5, "radius": 0.015, "layer": 2}
+]
+```
+
+The description of the property, shown in the editor, lists all the tools and their parameters.
+
+
+
+The brushes of the scene editor don't write in the edits: they save their changes in the **Sculpted and painted data** property, in a compact format that is not meant to be read. Clear this property to remove all the changes made with the brushes and go back to the relief, the heightmap and the edits.
+
+## Changing the terrain during the game
+
+The same tools are available as actions in the events: raise, lower, flatten, smooth, paint, tint, change the wetness, make or fill holes. They can be used for craters after an explosion, a road that the player builds, footprints in the snow, a puddle growing when it rains, or wet ground drying in the sun. Collisions are updated with the ground.
+
+These changes only exist during the game: they are not saved in the project. All the actions, conditions and expressions are listed in the [reference of the 3D terrain extension](/gdevelop5/extensions/terrain3d).
diff --git a/docs/gdevelop5/objects/3d-terrain/terrain-edits-property.png b/docs/gdevelop5/objects/3d-terrain/terrain-edits-property.png
new file mode 100644
index 0000000000..a4bc6e59f5
Binary files /dev/null and b/docs/gdevelop5/objects/3d-terrain/terrain-edits-property.png differ
diff --git a/docs/gdevelop5/objects/3d-terrain/terrain-island.jpg b/docs/gdevelop5/objects/3d-terrain/terrain-island.jpg
new file mode 100644
index 0000000000..303e9b70ab
Binary files /dev/null and b/docs/gdevelop5/objects/3d-terrain/terrain-island.jpg differ
diff --git a/docs/gdevelop5/objects/3d-terrain/terrain-properties.png b/docs/gdevelop5/objects/3d-terrain/terrain-properties.png
new file mode 100644
index 0000000000..78f2a373a8
Binary files /dev/null and b/docs/gdevelop5/objects/3d-terrain/terrain-properties.png differ
diff --git a/docs/gdevelop5/objects/3d-terrain/terrain-toolbar.png b/docs/gdevelop5/objects/3d-terrain/terrain-toolbar.png
new file mode 100644
index 0000000000..0aad7d2f31
Binary files /dev/null and b/docs/gdevelop5/objects/3d-terrain/terrain-toolbar.png differ
diff --git a/docs/gdevelop5/objects/3d-terrain/terrain-town-hills.jpg b/docs/gdevelop5/objects/3d-terrain/terrain-town-hills.jpg
new file mode 100644
index 0000000000..d36d4c06c0
Binary files /dev/null and b/docs/gdevelop5/objects/3d-terrain/terrain-town-hills.jpg differ
diff --git a/docs/gdevelop5/objects/3d-terrain/tint-tool.jpg b/docs/gdevelop5/objects/3d-terrain/tint-tool.jpg
new file mode 100644
index 0000000000..67553eca40
Binary files /dev/null and b/docs/gdevelop5/objects/3d-terrain/tint-tool.jpg differ
diff --git a/docs/gdevelop5/objects/3d-terrain/tips.md b/docs/gdevelop5/objects/3d-terrain/tips.md
new file mode 100644
index 0000000000..0568fb9cf6
--- /dev/null
+++ b/docs/gdevelop5/objects/3d-terrain/tips.md
@@ -0,0 +1,78 @@
+---
+title: 3D terrain tips and best practices
+---
+# 3D terrain tips and best practices
+
+## A good workflow
+
+1. **Start from a shape**: choose a relief (hills, mountains, island) and try a few seeds, or import a heightmap. It's faster than sculpting everything from a flat ground.
+1. **Sculpt the big shapes first**, with a big brush and a low strength: hills, valleys, the coast of an island. Then add the details with smaller brushes.
+1. **Prepare the places for buildings and roads**: flatten the ground under buildings, and flatten the bed of roads before painting them.
+1. **Paint the layers**: roads and paths with their own layer, sand on beaches, dirt under trees. Grass and trees only grow on the layers you choose, so painting also decides where they grow.
+1. **Add grass, forests and rocks**, then erase them where they are not wanted (around houses, on the paths of the player).
+1. **Place the other objects last**: objects placed on the terrain don't follow the ground when you sculpt under them.
+
+!!! tip
+
+ Surround the playable area with high mountains, cliffs or water. It hides the end of the terrain, and it's easier than making a world without borders.
+
+## Size and resolution
+
+The **resolution** of a terrain is the number of cells on each side. The size of a cell is the size of the terrain divided by the resolution: it's the size of the smallest details that can be sculpted (a narrow path, a ditch, the edge of a hole).
+
+- Small cells (16 to 32 pixels) for terrains where the player walks and drives closely: roads, paths and holes have sharp edges.
+- Bigger cells for backgrounds, mountains seen from far, or the sea floor.
+- A higher resolution takes more memory and more time to load, and makes changes during the game slower. Use the lowest resolution that keeps the details you need.
+
+The resolution can be changed after sculpting: the changes made with the brushes are kept, with more or less details.
+
+For very big worlds, put several terrains side by side rather than one huge terrain with a high resolution. Grass and scattered models can cover several terrains with a single object.
+
+## Performance and mobile games
+
+Terrains are made for big worlds: the parts out of the screen are not drawn, and the far away parts are simplified. To keep a game smooth, especially on phones:
+
+- Use a terrain resolution that fits the size of the world (see above).
+- Grass: put it only where the player can see it closely, lower its **fade distance** and its **density**. See [Grass](grass.md#performance).
+- Scattered models: lower the **draw distance** of small plants and rocks, and disable the shadows of small things. See [Forests, rocks and bushes](scattered-models.md#performance).
+- Shadows are one of the most expensive parts of a 3D scene: lower the **Shadow quality** or the **Shadow distance** of the directional light, or disable shadows on the objects that don't need them.
+- Layer effects like ambient occlusion, depth of field or bloom look great but are expensive: try your game on a phone and keep the ones that matter.
+- Holes make the terrain a bit slower to draw: only the terrains with holes pay this cost.
+
+See also [how to improve the performance of a game](/gdevelop5/tutorials/how-to-debug-poor-performance).
+
+## Characters, cars and physics
+
+- Add the [3D physics behavior](/gdevelop5/behaviors/physics3d) to the terrain, with a 3D physics character behavior on the player: it walks on slopes, and is stopped by slopes too steep to climb.
+- Cars (with the 3D physics car behavior) follow the ground exactly: smooth the roads to avoid bumps, and keep their slopes reasonable.
+- Objects created during the game can be put on the ground with the **Put objects on the ground** action, or with their Z position set to the **ground Z position** expression.
+- When the ground changes during the game (a crater, a hole), the collisions are updated and objects on the ground fall or roll accordingly.
+
+## Common problems
+
+**The terrain objects are not in the new object dialog.**
+They are in an extension made by the community. Click the menu at the right of the search bar of the "New object from scratch" tab, and choose to show experimental objects.
+
+**I can't select a tree or another object: clicks paint the terrain.**
+A brush of the terrain is still in use. Click again on the tool in the toolbar to stop using it, then click on the object.
+
+**Objects float above the ground or are buried after sculpting.**
+Objects placed in the scene don't follow the ground. Move them, or use the **Put objects on the ground** action at the beginning of the scene for the objects that must stand on the ground.
+
+**Grass or trees grow on a road.**
+Paint the road with a layer that is not the "Grows on terrain layer" of the grass and of the scattered models. Erase the remaining trees with the "Erase copies" brush.
+
+**The player walks through the trees.**
+Enable **Trunk collisions** on the scattered models, and add the 3D physics behavior to them, with the "Static" type. See [Collisions](scattered-models.md#collisions-trees-that-stop-the-player).
+
+**The textures of the ground look blurry or repetitive.**
+Lower the **Texture size** for sharper textures, raise the **Texture variation** to hide the repetition, and add normal maps to the layers.
+
+**The outside of a tunnel or the sky is seen through the edge of a hole.**
+Make the hole smaller than the inside of the tunnel, and make the ends of the tunnel model bigger. Look at the entrances from all the angles the camera can take in the game. See [Make a tunnel](holes-and-tunnels.md#make-a-tunnel).
+
+**An object falls into a hole a bit before reaching its edge.**
+Collisions are removed for whole cells of the terrain: a higher resolution makes the difference smaller. Make the 3D model under the hole go a bit further than the hole.
+
+**Changes made with actions are lost when the game restarts.**
+Actions only change the terrain during the game. Use the brushes of the scene editor, or the **Edits** property, to change the terrain of the project.
diff --git a/docs/gdevelop5/objects/3d-terrain/tunnel-entrance.jpg b/docs/gdevelop5/objects/3d-terrain/tunnel-entrance.jpg
new file mode 100644
index 0000000000..60d232bde0
Binary files /dev/null and b/docs/gdevelop5/objects/3d-terrain/tunnel-entrance.jpg differ
diff --git a/docs/gdevelop5/objects/3d-terrain/tunnel-inside.jpg b/docs/gdevelop5/objects/3d-terrain/tunnel-inside.jpg
new file mode 100644
index 0000000000..dbe43f18f3
Binary files /dev/null and b/docs/gdevelop5/objects/3d-terrain/tunnel-inside.jpg differ
diff --git a/docs/gdevelop5/objects/3d-terrain/tunnel-under-the-hill.jpg b/docs/gdevelop5/objects/3d-terrain/tunnel-under-the-hill.jpg
new file mode 100644
index 0000000000..f94304cdc0
Binary files /dev/null and b/docs/gdevelop5/objects/3d-terrain/tunnel-under-the-hill.jpg differ
diff --git a/docs/gdevelop5/objects/3d-terrain/wet-shore.jpg b/docs/gdevelop5/objects/3d-terrain/wet-shore.jpg
new file mode 100644
index 0000000000..58ca9cae7e
Binary files /dev/null and b/docs/gdevelop5/objects/3d-terrain/wet-shore.jpg differ
diff --git a/docs/gdevelop5/objects/3d-terrain/wetness-toolbar.png b/docs/gdevelop5/objects/3d-terrain/wetness-toolbar.png
new file mode 100644
index 0000000000..3354eff7af
Binary files /dev/null and b/docs/gdevelop5/objects/3d-terrain/wetness-toolbar.png differ