Add a documentation of the 3D terrain, grass and scattered models

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

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

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.
+
+![Blades of grass on a meadow of the island, with a path where no grass grows](grass-meadow.jpg)
+
+## 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).

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.
+
+![A hole made in a meadow: the water under the island is seen through it](hole-before-after.jpg)
+
+## 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.
+
+![The "Make a hole" brush, over a hole in a meadow](hole-brush.jpg)
+
+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.
+
+![The entrance of a tunnel, through a hole in the face of a hill](tunnel-entrance.jpg)
+
+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:
+
+![The tunnel of the 3D GTA with a map example, with the terrain hidden](tunnel-under-the-hill.jpg)
+
+!!! 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).
+
+![Driving inside the tunnel](tunnel-inside.jpg)
+
+## 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).

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...).
+
+![An island made with a 3D terrain, grass, trees and water](terrain-island.jpg)
+
+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.
+
+![A town, roads and hills made with a 3D terrain](terrain-town-hills.jpg)
+
+## 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 3D terrain, terrain grass and scattered models in the new object dialog](new-object-terrain.jpg)
+
+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:
+
+![A 3D terrain selected in the scene editor, with its tools](editor-terrain-selected.jpg)
+
+![The tools of the terrain: sculpt, paint layers, holes, tint and wetness, brush size and strength, undo](terrain-toolbar.png)
+
+- **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
+
+![The properties of a 3D terrain: layers, textures, normal maps and shape](terrain-properties.png){ 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)).
+
+<div style="clear: both;"></div>
+
+## 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.