Update documentation with Navigation and other updates

.gitattributes

@@ -5,3 +5,5 @@
 *.glb filter=lfs diff=lfs merge=lfs -text
 *.occ filter=lfs diff=lfs merge=lfs -text
 *.dds filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.mp4 filter=lfs diff=lfs merge=lfs -text

Terrain3D.vcxproj

@@ -186,6 +186,7 @@
     <None Include="SConstruct" />
     <None Include="src\shaders\debug_views.glsl" />
     <None Include="src\shaders\main.glsl" />
+    <None Include="src\shaders\uniforms.glsl" />
     <None Include="src\shaders\world_noise.glsl" />
     <None Include="src\shaders\editor_functions.glsl" />
     <None Include="src\shaders\dual_scaling.glsl" />
@@ -210,6 +211,7 @@
     <Text Include="doc\docs\building_from_source.md" />
     <Text Include="doc\_static\theme_overrides.css" />
     <Text Include="LICENSE.txt" />
+    <Text Include="doc\docs\navigation.md" />
   </ItemGroup>
   <ItemGroup>
     <Xml Include="doc\classes\Terrain3D.xml" />

doc/api/class_terrain3dtexturelist.rst

@@ -41,6 +41,8 @@ Methods
    +-------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
    | :ref:`int<class_int>`                           | :ref:`get_texture_count<class_Terrain3DTextureList_method_get_texture_count>` **(** **)**                                                                          |
    +-------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+   | void                                            | :ref:`save<class_Terrain3DTextureList_method_save>` **(** **)**                                                                                                    |
+   +-------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
    | void                                            | :ref:`set_texture<class_Terrain3DTextureList_method_set_texture>` **(** :ref:`int<class_int>` index, :ref:`Terrain3DTexture<class_Terrain3DTexture>` texture **)** |
    +-------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 
@@ -141,6 +143,20 @@ Method Descriptions
 
 ----
 
+.. _class_Terrain3DTextureList_method_save:
+
+.. rst-class:: classref-method
+
+void **save** **(** **)**
+
+.. container:: contribute
+
+	There is currently no description for this method. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!
+
+.. rst-class:: classref-item-separator
+
+----
+
 .. _class_Terrain3DTextureList_method_set_texture:
 
 .. rst-class:: classref-method

doc/classes/Terrain3D.xml

@@ -15,6 +15,13 @@
 			<description>
 			</description>
 		</method>
+		<method name="generate_nav_mesh_source_geometry">
+			<return type="PackedVector3Array" />
+			<param index="0" name="global_aabb" type="AABB" />
+			<param index="1" name="require_nav" type="bool" default="true" />
+			<description>
+			</description>
+		</method>
 		<method name="get_camera">
 			<return type="Camera3D" />
 			<description>
@@ -73,10 +80,6 @@
 		</method>
 	</methods>
 	<members>
-		<member name="clipmap_levels" type="int" setter="set_clipmap_levels" getter="get_clipmap_levels" default="7">
-		</member>
-		<member name="clipmap_size" type="int" setter="set_clipmap_size" getter="get_clipmap_size" default="48">
-		</member>
 		<member name="collision_enabled" type="bool" setter="set_collision_enabled" getter="get_collision_enabled" default="true">
 		</member>
 		<member name="collision_layer" type="int" setter="set_collision_layer" getter="get_collision_layer" default="1">
@@ -91,6 +94,10 @@
 		</member>
 		<member name="material" type="Terrain3DMaterial" setter="set_material" getter="get_material">
 		</member>
+		<member name="mesh_lods" type="int" setter="set_mesh_lods" getter="get_mesh_lods" default="7">
+		</member>
+		<member name="mesh_size" type="int" setter="set_mesh_size" getter="get_mesh_size" default="48">
+		</member>
 		<member name="render_cast_shadows" type="int" setter="set_cast_shadows" getter="get_cast_shadows" enum="GeometryInstance3D.ShadowCastingSetting" default="1">
 		</member>
 		<member name="render_cull_margin" type="float" setter="set_cull_margin" getter="get_cull_margin" default="0.0">

doc/classes/Terrain3DMaterial.xml

@@ -36,6 +36,11 @@
 				Returns the RID of the built in shader used with the Rendering Server. This is different from any shader override which has its own RID.
 			</description>
 		</method>
+		<method name="save">
+			<return type="void" />
+			<description>
+			</description>
+		</method>
 		<method name="set_shader_param">
 			<return type="void" />
 			<param index="0" name="name" type="StringName" />
@@ -48,6 +53,10 @@
 	<members>
 		<member name="_shader_parameters" type="Dictionary" setter="_set_shader_parameters" getter="_get_shader_parameters" default="{}">
 		</member>
+		<member name="auto_shader" type="bool" setter="set_auto_shader" getter="get_auto_shader" default="true">
+		</member>
+		<member name="dual_scaling" type="bool" setter="set_dual_scaling" getter="get_dual_scaling" default="true">
+		</member>
 		<member name="shader_override" type="Shader" setter="set_shader_override" getter="get_shader_override">
 			If shader_override_enabled is true and this Shader is valid, the material will use this custom shader code. If this is blank when you enable the override, the system will generate a shader with the current settings. So if you have a debug view enabled, the generated shader will have all of that code. A visual shader will also work here. However we only generate a text based shader so currently a visual shader needs to be constructed with the base code before it can work.
 		</member>
@@ -94,6 +103,8 @@
 		<member name="show_vertex_grid" type="bool" setter="set_show_vertex_grid" getter="get_show_vertex_grid" default="false">
 			Show a grid on the vertices, overlaying any above shader.
 		</member>
+		<member name="texture_filtering" type="int" setter="set_texture_filtering" getter="get_texture_filtering" enum="Terrain3DMaterial.TextureFiltering" default="0">
+		</member>
 		<member name="world_background" type="int" setter="set_world_background" getter="get_world_background" enum="Terrain3DMaterial.WorldBackground" default="1">
 			See the [enum WorldBackground] for options.
 		</member>
@@ -108,5 +119,9 @@
 		<constant name="NOISE" value="2" enum="WorldBackground">
 			Outside of the defined regions, generate visual-only hills.
 		</constant>
+		<constant name="LINEAR" value="0" enum="TextureFiltering">
+		</constant>
+		<constant name="NEAREST" value="1" enum="TextureFiltering">
+		</constant>
 	</constants>
 </class>

doc/classes/Terrain3DTextureList.xml

@@ -18,6 +18,11 @@
 			<description>
 			</description>
 		</method>
+		<method name="save">
+			<return type="void" />
+			<description>
+			</description>
+		</method>
 		<method name="set_texture">
 			<return type="void" />
 			<param index="0" name="index" type="int" />

doc/docs/building_from_source.md

@@ -46,6 +46,12 @@ remote: Total 125 (delta 56), reused 94 (delta 36), pack-reused 0
 Receiving objects: 100% (125/125), 42.20 KiB | 194.00 KiB/s, done.
 Resolving deltas: 100% (56/56), done.
 
+$ git lfs install
+Updated Git hooks.
+Git LFS initialized.
+
+$ git lfs pull
+
 $ cd Terrain3D
 
 Terrain3D$ git submodule init

doc/docs/import_export.md

@@ -32,7 +32,7 @@ Currently importing and exporting is possible via code or our import tool. We wi
 
 7) Click `Run Import` and wait 10-30 seconds. Look at the console for activity or errors. If the `Terrain3D.debug_level` is set to `debug`, you'll also see progress.
 
-8) When you are happy with the import, scroll down in the inspector (half of it is hidden by the `Surfaces` panel) until you see `Terrain3D, Storage`.
+8) When you are happy with the import, scroll down in the inspector (half of it is hidden by the `Textures` panel) until you see `Terrain3D, Storage`.
 
 9) Click the right arrow next to the Terrain3DStorage file and save the file wherever you wish. Make sure to save it as `.res` which is a binary Godot resource file. 
 
@@ -47,7 +47,7 @@ You can now load this `res` file into a Terrain3D in any of your scenes. You can
 We can import raw plus any supported image format Godot can read into any of the map types. These include:
 * [Image formats for external files](https://docs.godotengine.org/en/stable/tutorials/assets_pipeline/importing_images.html#supported-image-formats): `bmp`, `dds`, `exr`, `hdr`, `jpg`, `jpeg`, `png`, `tga`, `svg`, `webp`
 * [Image formats stored in a Godot resource file](https://docs.godotengine.org/en/stable/classes/class_image.html#enum-image-format): `tres`, `res`
-* R16 Height map aka RAW: For 16-bit heightmaps read/writable by World Machine, Unity, Krita, Photoshop, etc. The extension should be `r16` or `raw`. Min/Max heights and image size are not stored in the file, so you must keep track of them elsewhere (such as in the name)
+* R16 Height map aka RAW: For 16-bit heightmaps read/writable by World Machine, Unity, Krita, etc. The extension should be `r16` or `raw`. Min/Max heights and image size are not stored in the file, so you must keep track of them elsewhere (such as in the name). `Photoshop Raw` is a different format. Use [exr](https://www.exr-io.com/) for photoshop.
 
 Only `exr` or `r16/raw` are recommended for heightmaps. Godot PNG only supports 8-bit per channel, so don't use it for heightmaps. It is fine for external editing of control and color maps which are RGBA. See [Terrain3DStorage](../api/class_terrain3dstorage.rst) for details on internal storage.
 
@@ -88,7 +88,7 @@ Notes:
 We can export raw plus any supported image format Godot can write. These include:
 * [Image save functions for external files](https://docs.godotengine.org/en/stable/classes/class_image.html#class-image-method-save-exr): `exr`, `png`, `jpg`, `webp`
 * Images stored in a Godot resource file: `tres` for text, `res` for binary (with `ResourceSaver::FLAG_COMPRESS` enabled)
-* R16 Height map aka RAW: For 16-bit heightmaps read/writable by World Machine, Unity, Krita, Photoshop, etc. Save with the extension `r16` or `raw`. Min/Max heights and image size are not stored in the file, so you must keep track of them elsewhere. See below to acquire the dimensions.
+* R16 Height map aka RAW: For 16-bit heightmaps read/writable by World Machine, Unity, Krita, etc. Save with the extension `r16` or `raw`. Min/Max heights and image size are not stored in the file, so you must keep track of them elsewhere. See below to acquire the dimensions. `Photoshop Raw` is a different format. Use [exr](https://www.exr-io.com/) for photoshop.
 
 For heightmaps, use `exr` or `r16/raw` for external tools, or `res` for Godot only use. Godot PNG only supports 8-bit per channel, so it will give you blocky heightmaps.
 

doc/docs/navigation.md

@@ -0,0 +1,102 @@
+# Navigation
+
+Navigation in games is quite a broad and sometimes complex topic. A full description can't be provided here, so it's recommended to familiarize yourself with the basic concepts in the [official Godot documentation](https://docs.godotengine.org/en/stable/tutorials/navigation/navigation_introduction_3d.html) first.
+
+This page describes how to bake a nav mesh (navigation mesh) for your terrain.
+
+
+## Setting Up Navigation
+
+Nav meshes take a long time to bake, and in most games, it would be wasteful to generate vast amounts of navigation data for areas that navigation agents aren't going to use. So by default, all terrain is un-navigable. To make parts of it navigable, you must use the Navigable terrain tool. Navigable areas appear in dark magenta when this tool is selected.
+
+```{image} images/nav_painting.png
+:target: ../_images/nav_painting.png
+```
+
+Next, you will need a `NavigationRegion3D` node. If you don't already have one, Terrain3D provides a convenient tool to set one up for you. Select your `Terrain3D` node, then in the `Terrain3D Tools` menu on top, click `Set up Navigation`.
+
+```{image} images/terrain3d_tools.png
+:target: ../_images/terrain3d_tools.png
+```
+
+The same steps can be performed manually if you prefer:
+
+1. Create a `NavigationRegion3D` node.
+2. Assign it a blank `NavigationMesh` resource. Review and adjust the settings on it if you need to.
+3. If using the default source geometry mode, move the `Terrain3D` node to be a child of the new `NavigationRegion3D` node. Otherwise, if you selected one of the group-based modes, add the Terrain3D node to the group.
+
+
+## Baking a Nav Mesh
+
+Once navigation has been set up, baking and re-baking it is straight-forward:
+
+1. Select the `Terrain3D` node.
+2. In Terrain3D Tools, click `Bake NavMesh`. This can take a long time to complete.
+
+Note that the standard `Bake NavMesh` button that `NavigationRegion3D` provides will not generate a nav mesh for Terrain3D (see [godot-proposals#5138](https://github.com/godotengine/godot-proposals/issues/5138)). Only use the Terrain3D Tools baker, which appears whenever you click the `Terrain3D` node or any `NavigationRegion3D` nodes.
+
+```{image} images/nav_baking.png
+:target: ../_images/nav_baking.png
+```
+
+If this is your first time setting up and baking a nav mesh, the only thing left to do is add your navigation agents. See [Godot's very clear and thorough documentation on navigation agents](https://docs.godotengine.org/en/stable/tutorials/navigation/navigation_using_navigationagents.html), which provides several handy template scripts you can use.
+
+You can also play with the NavigationDemo.tscn and CodeGenerated.tscn scenes which both demonstrate navigation.
+
+<figure class="video_container">
+ <video width="600px" controls="true" allowfullscreen="true">
+ <source src="../_static/video/nav_demo.mp4" type="video/mp4">
+ </video>
+</figure>
+
+
+## Tips
+
+### Save NavigationMesh resources to disk
+
+NavigationMesh resources can bloat the size of your scene. It's recommended to save these resources to disk in binary format with the `.res` extension.
+
+### Use multiple nav meshes in large scenes
+
+As mentioned, in many games, large areas of terrain are generally unreachable to agents. The 'Navigable Areas' tool is used to reduce the amount of geometry coming from the `Terrain3D` node, however having lots of other meshes in unreachable areas can also lead to long bake times.
+
+If you have a very large scene in, for example, an open world RPG, it's better to have multiple small nav meshes that cover only what you need, rather than one giant one covering the entire world. In said example, each RPG town could have its own nav mesh. To do this, you would need to:
+
+1. Create a NavigationRegion3D node for each town, each with their own NavigationMesh resources (i.e. unique, not shared).
+2. Define the [`filter_baking_aabb`](https://docs.godotengine.org/en/stable/classes/class_navigationmesh.html#class-navigationmesh-property-filter-baking-aabb) on each nav mesh, so that it only bakes objects within its own area.
+3. To use the same Terrain3D node with multiple NavigationRegion3D, set up the nav meshes to use one of the [`SOURCE_GEOMETRY_GROUPS_*` modes](https://docs.godotengine.org/en/stable/classes/class_navigationmesh.html#class-navigationmesh-property-geometry-source-geometry-mode) instead of the default `SOURCE_GEOMETRY_ROOT_NODE_CHILDREN`, and add the Terrain3D node to the group.
+
+
+## Common Issues
+
+### NavigationMeshSourceGeometryData3D is empty. Parse source geometry first.
+
+The engine produces this error if there's nothing for a NavigationRegion3D to generate a nav mesh from. The most likely cause, if you're using Terrain3D, is that you haven't painted any parts of the terrain as navigable.
+
+### Navigation map synchronization error
+
+`Navigation map synchronization error. Attempted to merge a navigation mesh polygon edge with another already-merged edge. This is usually caused by crossing edges, overlapping polygons, or a mismatch of the NavigationMesh / NavigationPolygon baked 'cell_size' and navigation map 'cell_size'`
+
+There are several possible causes for this. If the `cell_size` of your nav mesh matches the `cell_size` in your project settings, it's currently believed to be caused by [an engine bug](https://github.com/godotengine/godot/issues/85548). This error message shouldn't affect the usability of your nav meshes.
+
+### Agents get stuck on collisions, run in circles, go off the nav mesh, or fail to find obvious paths
+
+Developing good path-following behaviors is a very complex topic, far beyond the scope of this article. In general, make sure your NavigationMesh settings, NavigationAgent3D settings, and collisions are all consistent with each other. If a NavigationAgent3D is using a NavigationMesh that was baked for smaller agents than itself, for instance, then it's going to get stuck.
+
+You can try repainting an area and regenerating the nav mesh.
+
+Making reasonable fallback behaviors, when you're able to detect in a script that something has gone awry, can also help.
+
+
+## Baking a Nav Mesh at Runtime
+
+If your project has dynamic, or generated terrain, or if the traversable area of your terrain is so gigantic that it can't be baked in the editor, then you might need to use runtime navmesh baking.
+
+Terrain3D contains an example script that shows how to bake terrain nav meshes at runtime, which you can find in the `CodeGenerated.tscn` demo scene. The script periodically re-bakes a nav mesh in the area around the player as they move through the scene.
+
+<figure class="video_container">
+ <video width="600px" controls="true" allowfullscreen="true">
+ <source src="../_static/video/nav_code_demo.mp4" type="video/mp4">
+ </video>
+</figure>
+

doc/docs/occlusion_culling.md

@@ -15,10 +15,11 @@ First, enable `use_occlusion_culling` in the project settings.
 Then in the editor:
 
 * Select Terrain3D.
-* Click `Bake Occluder3D` in the top menu. On the popup window accept the default, LOD 4.
+* Click `Terrain3D Tools`, then `Bake Occluder3D` in the top menu. 
+* On the popup window accept the default, LOD 4.
 
-```{image} images/oc_t3d_menu.png
-:target: ../_images/oc_t3d_menu.png
+```{image} images/terrain3d_tools.png
+:target: ../_images/terrain3d_tools.png
 ```
 
 * Select the OccluderInstance3D child node.