Home Explore Help
Sign In
godotengine
/
godot-docs
mirror of https://github.com/godotengine/godot-docs
Watch 1
Star 1
Fork 0
Files
Tree: 9ffd5f53c4
Branches Tags
godot-docs
/
classes
/
class_navigationmeshgenerator.rst

class_navigationmeshgenerator.rst 12 KB
History Raw

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126 
  1. :github_url: hide
    2. 

  2. 

  3. .. DO NOT EDIT THIS FILE!!!
    4. 

  4. .. Generated automatically from Godot engine sources.
    5. 

  5. .. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py.
    6. 

  6. .. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/NavigationMeshGenerator.xml.
    7. 

  7. 

  8. .. _class_NavigationMeshGenerator:
    9. 

  9. 

  10. NavigationMeshGenerator
    11. 

  11. =======================
    12. 

  12. 

  13. **Deprecated:** This class may be changed or removed in future versions.
    14. 

  14. 

  15. **Inherits:** :ref:`Object<class_Object>`
    16. 

  16. 

  17. Helper class for creating and clearing navigation meshes.
    18. 

  18. 

  19. .. rst-class:: classref-introduction-group
    20. 

  20. 

  21. Description
    22. 

  22. -----------
    23. 

  23. 

  24. This class is responsible for creating and clearing 3D navigation meshes used as :ref:`NavigationMesh<class_NavigationMesh>` resources inside :ref:`NavigationRegion3D<class_NavigationRegion3D>`. The **NavigationMeshGenerator** has very limited to no use for 2D as the navigation mesh baking process expects 3D node types and 3D source geometry to parse.
    25. 

  25. 

  26. The entire navigation mesh baking is best done in a separate thread as the voxelization, collision tests and mesh optimization steps involved are very slow and performance-intensive operations.
    27. 

  27. 

  28. Navigation mesh baking happens in multiple steps and the result depends on 3D source geometry and properties of the :ref:`NavigationMesh<class_NavigationMesh>` resource. In the first step, starting from a root node and depending on :ref:`NavigationMesh<class_NavigationMesh>` properties all valid 3D source geometry nodes are collected from the :ref:`SceneTree<class_SceneTree>`. Second, all collected nodes are parsed for their relevant 3D geometry data and a combined 3D mesh is build. Due to the many different types of parsable objects, from normal :ref:`MeshInstance3D<class_MeshInstance3D>`\ s to :ref:`CSGShape3D<class_CSGShape3D>`\ s or various :ref:`CollisionObject3D<class_CollisionObject3D>`\ s, some operations to collect geometry data can trigger :ref:`RenderingServer<class_RenderingServer>` and :ref:`PhysicsServer3D<class_PhysicsServer3D>` synchronizations. Server synchronization can have a negative effect on baking time or framerate as it often involves :ref:`Mutex<class_Mutex>` locking for thread security. Many parsable objects and the continuous synchronization with other threaded Servers can increase the baking time significantly. On the other hand only a few but very large and complex objects will take some time to prepare for the Servers which can noticeably stall the next frame render. As a general rule the total number of parsable objects and their individual size and complexity should be balanced to avoid framerate issues or very long baking times. The combined mesh is then passed to the Recast Navigation Object to test the source geometry for walkable terrain suitable to :ref:`NavigationMesh<class_NavigationMesh>` agent properties by creating a voxel world around the meshes bounding area.
    29. 

  29. 

  30. The finalized navigation mesh is then returned and stored inside the :ref:`NavigationMesh<class_NavigationMesh>` for use as a resource inside :ref:`NavigationRegion3D<class_NavigationRegion3D>` nodes.
    31. 

  31. 

  32. \ **Note:** Using meshes to not only define walkable surfaces but also obstruct navigation baking does not always work. The navigation baking has no concept of what is a geometry "inside" when dealing with mesh source geometry and this is intentional. Depending on current baking parameters, as soon as the obstructing mesh is large enough to fit a navigation mesh area inside, the baking will generate navigation mesh areas that are inside the obstructing source geometry mesh.
    33. 

  33. 

  34. .. rst-class:: classref-introduction-group
    35. 

  35. 

  36. Tutorials
    37. 

  37. ---------
    38. 

  38. 

  39. - :doc:`Using NavigationMeshes <../tutorials/navigation/navigation_using_navigationmeshes>`
    40. 

  40. 

  41. .. rst-class:: classref-reftable-group
    42. 

  42. 

  43. Methods
    44. 

  44. -------
    45. 

  45. 

  46. .. table::
    47. 

  47.    :widths: auto
    48. 

  48. 

  49.    +--------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
    50. 

  50.    | |void| | :ref:`bake<class_NavigationMeshGenerator_method_bake>`\ (\ navigation_mesh\: :ref:`NavigationMesh<class_NavigationMesh>`, root_node\: :ref:`Node<class_Node>`\ )                                                                                                                                                                                                                  |
    51. 

  51.    +--------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
    52. 

  52.    | |void| | :ref:`bake_from_source_geometry_data<class_NavigationMeshGenerator_method_bake_from_source_geometry_data>`\ (\ navigation_mesh\: :ref:`NavigationMesh<class_NavigationMesh>`, source_geometry_data\: :ref:`NavigationMeshSourceGeometryData3D<class_NavigationMeshSourceGeometryData3D>`, callback\: :ref:`Callable<class_Callable>` = Callable()\ )                              |
    53. 

  53.    +--------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
    54. 

  54.    | |void| | :ref:`clear<class_NavigationMeshGenerator_method_clear>`\ (\ navigation_mesh\: :ref:`NavigationMesh<class_NavigationMesh>`\ )                                                                                                                                                                                                                                                     |
    55. 

  55.    +--------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
    56. 

  56.    | |void| | :ref:`parse_source_geometry_data<class_NavigationMeshGenerator_method_parse_source_geometry_data>`\ (\ navigation_mesh\: :ref:`NavigationMesh<class_NavigationMesh>`, source_geometry_data\: :ref:`NavigationMeshSourceGeometryData3D<class_NavigationMeshSourceGeometryData3D>`, root_node\: :ref:`Node<class_Node>`, callback\: :ref:`Callable<class_Callable>` = Callable()\ ) |
    57. 

  57.    +--------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
    58. 

  58. 

  59. .. rst-class:: classref-section-separator
    60. 

  60. 

  61. ----
    62. 

  62. 

  63. .. rst-class:: classref-descriptions-group
    64. 

  64. 

  65. Method Descriptions
    66. 

  66. -------------------
    67. 

  67. 

  68. .. _class_NavigationMeshGenerator_method_bake:
    69. 

  69. 

  70. .. rst-class:: classref-method
    71. 

  71. 

  72. |void| **bake**\ (\ navigation_mesh\: :ref:`NavigationMesh<class_NavigationMesh>`, root_node\: :ref:`Node<class_Node>`\ ) :ref:`🔗<class_NavigationMeshGenerator_method_bake>`
    73. 

  73. 

  74. **Deprecated:** This method is deprecated due to core threading changes. To upgrade existing code, first create a :ref:`NavigationMeshSourceGeometryData3D<class_NavigationMeshSourceGeometryData3D>` resource. Use this resource with :ref:`parse_source_geometry_data<class_NavigationMeshGenerator_method_parse_source_geometry_data>` to parse the :ref:`SceneTree<class_SceneTree>` for nodes that should contribute to the navigation mesh baking. The :ref:`SceneTree<class_SceneTree>` parsing needs to happen on the main thread. After the parsing is finished use the resource with :ref:`bake_from_source_geometry_data<class_NavigationMeshGenerator_method_bake_from_source_geometry_data>` to bake a navigation mesh.
    75. 

  75. 

  76. Bakes the ``navigation_mesh`` with source geometry collected starting from the ``root_node``.
    77. 

  77. 

  78. .. rst-class:: classref-item-separator
    79. 

  79. 

  80. ----
    81. 

  81. 

  82. .. _class_NavigationMeshGenerator_method_bake_from_source_geometry_data:
    83. 

  83. 

  84. .. rst-class:: classref-method
    85. 

  85. 

  86. |void| **bake_from_source_geometry_data**\ (\ navigation_mesh\: :ref:`NavigationMesh<class_NavigationMesh>`, source_geometry_data\: :ref:`NavigationMeshSourceGeometryData3D<class_NavigationMeshSourceGeometryData3D>`, callback\: :ref:`Callable<class_Callable>` = Callable()\ ) :ref:`🔗<class_NavigationMeshGenerator_method_bake_from_source_geometry_data>`
    87. 

  87. 

  88. Bakes the provided ``navigation_mesh`` with the data from the provided ``source_geometry_data``. After the process is finished the optional ``callback`` will be called.
    89. 

  89. 

  90. .. rst-class:: classref-item-separator
    91. 

  91. 

  92. ----
    93. 

  93. 

  94. .. _class_NavigationMeshGenerator_method_clear:
    95. 

  95. 

  96. .. rst-class:: classref-method
    97. 

  97. 

  98. |void| **clear**\ (\ navigation_mesh\: :ref:`NavigationMesh<class_NavigationMesh>`\ ) :ref:`🔗<class_NavigationMeshGenerator_method_clear>`
    99. 

  99. 

  100. Removes all polygons and vertices from the provided ``navigation_mesh`` resource.
    101. 

  101. 

  102. .. rst-class:: classref-item-separator
    103. 

  103. 

  104. ----
    105. 

  105. 

  106. .. _class_NavigationMeshGenerator_method_parse_source_geometry_data:
    107. 

  107. 

  108. .. rst-class:: classref-method
    109. 

  109. 

  110. |void| **parse_source_geometry_data**\ (\ navigation_mesh\: :ref:`NavigationMesh<class_NavigationMesh>`, source_geometry_data\: :ref:`NavigationMeshSourceGeometryData3D<class_NavigationMeshSourceGeometryData3D>`, root_node\: :ref:`Node<class_Node>`, callback\: :ref:`Callable<class_Callable>` = Callable()\ ) :ref:`🔗<class_NavigationMeshGenerator_method_parse_source_geometry_data>`
    111. 

  111. 

  112. Parses the :ref:`SceneTree<class_SceneTree>` for source geometry according to the properties of ``navigation_mesh``. Updates the provided ``source_geometry_data`` resource with the resulting data. The resource can then be used to bake a navigation mesh with :ref:`bake_from_source_geometry_data<class_NavigationMeshGenerator_method_bake_from_source_geometry_data>`. After the process is finished the optional ``callback`` will be called.
    113. 

  113. 

  114. \ **Note:** This function needs to run on the main thread or with a deferred call as the SceneTree is not thread-safe.
    115. 

  115. 

  116. \ **Performance:** While convenient, reading data arrays from :ref:`Mesh<class_Mesh>` resources can affect the frame rate negatively. The data needs to be received from the GPU, stalling the :ref:`RenderingServer<class_RenderingServer>` in the process. For performance prefer the use of e.g. collision shapes or creating the data arrays entirely in code.
    117. 

  117. 

  118. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
    119. 

  119. .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
    120. 

  120. .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`
    121. 

  121. .. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)`
    122. 

  122. .. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)`
    123. 

  123. .. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)`
    124. 

  124. .. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)`
    125. 

  125. .. |void| replace:: :abbr:`void (No return value.)`
    126. 

  126.