Skip to content

Commit

Permalink
Merge pull request #61996 from smix8/navigation_bp_update_3.x
Browse files Browse the repository at this point in the history
[3.5] Update NavigationServer backport
  • Loading branch information
akien-mga authored Jun 15, 2022
2 parents 17e472f + 8bd7c61 commit 4e7363c
Show file tree
Hide file tree
Showing 60 changed files with 1,860 additions and 750 deletions.
2 changes: 2 additions & 0 deletions core/global_constants.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -592,8 +592,10 @@ void register_global_constants() {

BIND_GLOBAL_ENUM_CONSTANT(PROPERTY_HINT_LAYERS_2D_RENDER);
BIND_GLOBAL_ENUM_CONSTANT(PROPERTY_HINT_LAYERS_2D_PHYSICS);
BIND_GLOBAL_ENUM_CONSTANT(PROPERTY_HINT_LAYERS_2D_NAVIGATION);
BIND_GLOBAL_ENUM_CONSTANT(PROPERTY_HINT_LAYERS_3D_RENDER);
BIND_GLOBAL_ENUM_CONSTANT(PROPERTY_HINT_LAYERS_3D_PHYSICS);
BIND_GLOBAL_ENUM_CONSTANT(PROPERTY_HINT_LAYERS_3D_NAVIGATION);

BIND_GLOBAL_ENUM_CONSTANT(PROPERTY_HINT_FILE);
BIND_GLOBAL_ENUM_CONSTANT(PROPERTY_HINT_DIR);
Expand Down
2 changes: 2 additions & 0 deletions core/object.h
Original file line number Diff line number Diff line change
Expand Up @@ -67,8 +67,10 @@ enum PropertyHint {
PROPERTY_HINT_FLAGS, ///< hint_text= "flag1,flag2,etc" (as bit flags)
PROPERTY_HINT_LAYERS_2D_RENDER,
PROPERTY_HINT_LAYERS_2D_PHYSICS,
PROPERTY_HINT_LAYERS_2D_NAVIGATION,
PROPERTY_HINT_LAYERS_3D_RENDER,
PROPERTY_HINT_LAYERS_3D_PHYSICS,
PROPERTY_HINT_LAYERS_3D_NAVIGATION,
PROPERTY_HINT_FILE, ///< a file path must be passed, hint_text (optionally) is a filter "*.png,*.wav,*.doc,"
PROPERTY_HINT_DIR, ///< a directory path must be passed
PROPERTY_HINT_GLOBAL_FILE, ///< a file path must be passed, hint_text (optionally) is a filter "*.png,*.wav,*.doc,"
Expand Down
32 changes: 19 additions & 13 deletions doc/classes/@GlobalScope.xml
Original file line number Diff line number Diff line change
Expand Up @@ -1421,7 +1421,7 @@
Hints that an integer, float or string property is an enumerated value to pick in a list specified via a hint string.
The hint string is a comma separated list of names such as [code]"Hello,Something,Else"[/code]. For integer and float properties, the first name in the list has value 0, the next 1, and so on. Explicit values can also be specified by appending [code]:integer[/code] to the name, e.g. [code]"Zero,One,Three:3,Four,Six:6"[/code].
</constant>
<constant name="PROPERTY_HINT_ENUM_SUGGESTION" value="37" enum="PropertyHint">
<constant name="PROPERTY_HINT_ENUM_SUGGESTION" value="39" enum="PropertyHint">
Hints that a string property can be an enumerated value to pick in a list specified via a hint string such as [code]"Hello,Something,Else"[/code].
Unlike [constant PROPERTY_HINT_ENUM] a property with this hint still accepts arbitrary values and can be empty. The list of values serves to suggest possible values.
</constant>
Expand All @@ -1443,40 +1443,46 @@
<constant name="PROPERTY_HINT_LAYERS_2D_PHYSICS" value="10" enum="PropertyHint">
Hints that an integer property is a bitmask using the optionally named 2D physics layers.
</constant>
<constant name="PROPERTY_HINT_LAYERS_3D_RENDER" value="11" enum="PropertyHint">
<constant name="PROPERTY_HINT_LAYERS_2D_NAVIGATION" value="11" enum="PropertyHint">
Hints that an integer property is a bitmask using the optionally named 2D navigation layers.
</constant>
<constant name="PROPERTY_HINT_LAYERS_3D_RENDER" value="12" enum="PropertyHint">
Hints that an integer property is a bitmask using the optionally named 3D render layers.
</constant>
<constant name="PROPERTY_HINT_LAYERS_3D_PHYSICS" value="12" enum="PropertyHint">
<constant name="PROPERTY_HINT_LAYERS_3D_PHYSICS" value="13" enum="PropertyHint">
Hints that an integer property is a bitmask using the optionally named 3D physics layers.
</constant>
<constant name="PROPERTY_HINT_FILE" value="13" enum="PropertyHint">
<constant name="PROPERTY_HINT_LAYERS_3D_NAVIGATION" value="14" enum="PropertyHint">
Hints that an integer property is a bitmask using the optionally named 2D navigation layers.
</constant>
<constant name="PROPERTY_HINT_FILE" value="15" enum="PropertyHint">
Hints that a string property is a path to a file. Editing it will show a file dialog for picking the path. The hint string can be a set of filters with wildcards like [code]"*.png,*.jpg"[/code].
</constant>
<constant name="PROPERTY_HINT_DIR" value="14" enum="PropertyHint">
<constant name="PROPERTY_HINT_DIR" value="16" enum="PropertyHint">
Hints that a string property is a path to a directory. Editing it will show a file dialog for picking the path.
</constant>
<constant name="PROPERTY_HINT_GLOBAL_FILE" value="15" enum="PropertyHint">
<constant name="PROPERTY_HINT_GLOBAL_FILE" value="17" enum="PropertyHint">
Hints that a string property is an absolute path to a file outside the project folder. Editing it will show a file dialog for picking the path. The hint string can be a set of filters with wildcards like [code]"*.png,*.jpg"[/code].
</constant>
<constant name="PROPERTY_HINT_GLOBAL_DIR" value="16" enum="PropertyHint">
<constant name="PROPERTY_HINT_GLOBAL_DIR" value="18" enum="PropertyHint">
Hints that a string property is an absolute path to a directory outside the project folder. Editing it will show a file dialog for picking the path.
</constant>
<constant name="PROPERTY_HINT_RESOURCE_TYPE" value="17" enum="PropertyHint">
<constant name="PROPERTY_HINT_RESOURCE_TYPE" value="19" enum="PropertyHint">
Hints that a property is an instance of a [Resource]-derived type, optionally specified via the hint string (e.g. [code]"Texture"[/code]). Editing it will show a popup menu of valid resource types to instantiate.
</constant>
<constant name="PROPERTY_HINT_MULTILINE_TEXT" value="18" enum="PropertyHint">
<constant name="PROPERTY_HINT_MULTILINE_TEXT" value="20" enum="PropertyHint">
Hints that a string property is text with line breaks. Editing it will show a text input field where line breaks can be typed.
</constant>
<constant name="PROPERTY_HINT_PLACEHOLDER_TEXT" value="19" enum="PropertyHint">
<constant name="PROPERTY_HINT_PLACEHOLDER_TEXT" value="21" enum="PropertyHint">
Hints that a string property should have a placeholder text visible on its input field, whenever the property is empty. The hint string is the placeholder text to use.
</constant>
<constant name="PROPERTY_HINT_COLOR_NO_ALPHA" value="20" enum="PropertyHint">
<constant name="PROPERTY_HINT_COLOR_NO_ALPHA" value="22" enum="PropertyHint">
Hints that a color property should be edited without changing its alpha component, i.e. only R, G and B channels are edited.
</constant>
<constant name="PROPERTY_HINT_IMAGE_COMPRESS_LOSSY" value="21" enum="PropertyHint">
<constant name="PROPERTY_HINT_IMAGE_COMPRESS_LOSSY" value="23" enum="PropertyHint">
Hints that an image is compressed using lossy compression.
</constant>
<constant name="PROPERTY_HINT_IMAGE_COMPRESS_LOSSLESS" value="22" enum="PropertyHint">
<constant name="PROPERTY_HINT_IMAGE_COMPRESS_LOSSLESS" value="24" enum="PropertyHint">
Hints that an image is compressed using lossless compression.
</constant>
<constant name="PROPERTY_USAGE_STORAGE" value="1" enum="PropertyUsageFlags">
Expand Down
19 changes: 15 additions & 4 deletions doc/classes/Navigation.xml
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@
<method name="get_rid" qualifiers="const">
<return type="RID" />
<description>
Returns the object's [RID].
Returns the [RID] of the navigation map on the [NavigationServer].
</description>
</method>
<method name="get_simple_path" qualifiers="const">
Expand All @@ -57,19 +57,30 @@
</method>
</methods>
<members>
<member name="cell_height" type="float" setter="set_cell_height" getter="get_cell_height" default="0.2">
<member name="cell_height" type="float" setter="set_cell_height" getter="get_cell_height" default="0.25">
The cell height to use for fields.
</member>
<member name="cell_size" type="float" setter="set_cell_size" getter="get_cell_size" default="0.3">
<member name="cell_size" type="float" setter="set_cell_size" getter="get_cell_size" default="0.25">
The XZ plane cell size to use for fields.
</member>
<member name="edge_connection_margin" type="float" setter="set_edge_connection_margin" getter="get_edge_connection_margin" default="5.0">
<member name="edge_connection_margin" type="float" setter="set_edge_connection_margin" getter="get_edge_connection_margin" default="0.25">
This value is used to detect the near edges to connect compatible regions.
</member>
<member name="navigation_layers" type="int" setter="set_navigation_layers" getter="get_navigation_layers" default="1">
A bitfield determining all navigation map layers the navigation can use on a [method Navigation.get_simple_path] path query.
</member>
<member name="up_vector" type="Vector3" setter="set_up_vector" getter="get_up_vector" default="Vector3( 0, 1, 0 )">
Defines which direction is up. By default, this is [code](0, 1, 0)[/code], which is the world's "up" direction.
</member>
</members>
<signals>
<signal name="map_changed">
<argument index="0" name="map" type="RID" />
<description>
Emitted when a navigation map is updated, when a region moves or is modified.
</description>
</signal>
</signals>
<constants>
</constants>
</class>
3 changes: 3 additions & 0 deletions doc/classes/Navigation2D.xml
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,9 @@
<member name="edge_connection_margin" type="float" setter="set_edge_connection_margin" getter="get_edge_connection_margin" default="1.0">
This value is used to detect the near edges to connect compatible regions.
</member>
<member name="navigation_layers" type="int" setter="set_navigation_layers" getter="get_navigation_layers" default="1">
A bitfield determining all navigation map layers the navigation can use on a [method Navigation2D.get_simple_path] path query.
</member>
</members>
<constants>
</constants>
Expand Down
97 changes: 95 additions & 2 deletions doc/classes/Navigation2DServer.xml
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,8 @@
Navigation2DServer is the server responsible for all 2D navigation. It handles several objects, namely maps, regions and agents.
Maps are made up of regions, which are made of navigation polygons. Together, they define the navigable areas in the 2D world.
[b]Note:[/b] Most NavigationServer changes take effect after the next physics frame and not immediately. This includes all changes made to maps, regions or agents by navigation related Nodes in the SceneTree or made through scripts.
For two regions to be connected to each other, they must share a similar edge. An edge is considered connected to another if both of its two vertices are at a distance less than [member Navigation.edge_connection_margin] to the respective other edge's vertex.
For two regions to be connected to each other, they must share a similar edge. An edge is considered connected to another if both of its two vertices are at a distance less than navigation map [code]edge_connection_margin[/code] to the respective other edge's vertex.
You may assign navigation layers to regions with [method Navigation2DServer.region_set_navigation_layers], which then can be checked upon when requesting a path with [method Navigation2DServer.map_get_path]. This allows allowing or forbidding some areas to 2D objects.
To use the collision avoidance system, you may use agents. You can set an agent's target velocity, then the servers will emit a callback with a modified velocity.
[b]Note:[/b] The collision avoidance system ignores regions. Using the modified velocity as-is might lead to pushing and agent outside of a navigable area. This is a limitation of the collision avoidance system, any more complex situation may require the use of the physics engine.
This server keeps tracks of any call and executes them during the sync phase. This means that you can request any change to the map, using any thread, without worrying.
Expand Down Expand Up @@ -138,6 +139,13 @@
Returns all navigation agents [RID]s that are currently assigned to the requested navigation [code]map[/code].
</description>
</method>
<method name="map_get_cell_height" qualifiers="const">
<return type="float" />
<argument index="0" name="map" type="RID" />
<description>
Returns the map cell height. [b]Note:[/b] Currently not implemented.
</description>
</method>
<method name="map_get_cell_size" qualifiers="const">
<return type="float" />
<argument index="0" name="map" type="RID" />
Expand Down Expand Up @@ -174,8 +182,9 @@
<argument index="1" name="origin" type="Vector2" />
<argument index="2" name="destination" type="Vector2" />
<argument index="3" name="optimize" type="bool" />
<argument index="4" name="navigation_layers" type="int" default="1" />
<description>
Returns the navigation path to reach the destination from the origin.
Returns the navigation path to reach the destination from the origin. [code]navigation_layers[/code] is a bitmask of all region layers that are allowed to be in the path.
</description>
</method>
<method name="map_get_regions" qualifiers="const">
Expand All @@ -200,6 +209,14 @@
Sets the map active.
</description>
</method>
<method name="map_set_cell_height" qualifiers="const">
<return type="void" />
<argument index="0" name="map" type="RID" />
<argument index="1" name="cell_height" type="float" />
<description>
Set the map cell height used to weld the navigation mesh polygons. [b]Note:[/b] Currently not implemented.
</description>
</method>
<method name="map_set_cell_size" qualifiers="const">
<return type="void" />
<argument index="0" name="map" type="RID" />
Expand All @@ -222,13 +239,65 @@
Creates a new region.
</description>
</method>
<method name="region_get_connection_pathway_end" qualifiers="const">
<return type="Vector2" />
<argument index="0" name="region" type="RID" />
<argument index="1" name="connection" type="int" />
<description>
Returns the ending point of a connection door. [code]connection[/code] is an index between 0 and the return value of [method region_get_connections_count].
</description>
</method>
<method name="region_get_connection_pathway_start" qualifiers="const">
<return type="Vector2" />
<argument index="0" name="region" type="RID" />
<argument index="1" name="connection" type="int" />
<description>
Returns the starting point of a connection door. [code]connection[/code] is an index between 0 and the return value of [method region_get_connections_count].
</description>
</method>
<method name="region_get_connections_count" qualifiers="const">
<return type="int" />
<argument index="0" name="region" type="RID" />
<description>
Returns how many connections this [code]region[/code] has with other regions in the map.
</description>
</method>
<method name="region_get_enter_cost" qualifiers="const">
<return type="float" />
<argument index="0" name="region" type="RID" />
<description>
Returns the [code]enter_cost[/code] of this [code]region[/code].
</description>
</method>
<method name="region_get_map" qualifiers="const">
<return type="RID" />
<argument index="0" name="region" type="RID" />
<description>
Returns the navigation map [RID] the requested [code]region[/code] is currently assigned to.
</description>
</method>
<method name="region_get_navigation_layers" qualifiers="const">
<return type="int" />
<argument index="0" name="region" type="RID" />
<description>
Returns the region's navigation layers.
</description>
</method>
<method name="region_get_travel_cost" qualifiers="const">
<return type="float" />
<argument index="0" name="region" type="RID" />
<description>
Returns the [code]travel_cost[/code] of this [code]region[/code].
</description>
</method>
<method name="region_set_enter_cost" qualifiers="const">
<return type="void" />
<argument index="0" name="region" type="RID" />
<argument index="1" name="enter_cost" type="float" />
<description>
Sets the [code]enter_cost[/code] for this [code]region[/code].
</description>
</method>
<method name="region_set_map" qualifiers="const">
<return type="void" />
<argument index="0" name="region" type="RID" />
Expand All @@ -237,6 +306,14 @@
Sets the map for the region.
</description>
</method>
<method name="region_set_navigation_layers" qualifiers="const">
<return type="void" />
<argument index="0" name="region" type="RID" />
<argument index="1" name="navigation_layers" type="int" />
<description>
Set the region's navigation layers. This allows selecting regions from a path request (when using [method Navigation2DServer.map_get_path]).
</description>
</method>
<method name="region_set_navpoly" qualifiers="const">
<return type="void" />
<argument index="0" name="region" type="RID" />
Expand All @@ -253,7 +330,23 @@
Sets the global transformation for the region.
</description>
</method>
<method name="region_set_travel_cost" qualifiers="const">
<return type="void" />
<argument index="0" name="region" type="RID" />
<argument index="1" name="travel_cost" type="float" />
<description>
Sets the [code]travel_cost[/code] for this [code]region[/code].
</description>
</method>
</methods>
<signals>
<signal name="map_changed">
<argument index="0" name="map" type="RID" />
<description>
Emitted when a navigation map is updated, when a region moves or is modified.
</description>
</signal>
</signals>
<constants>
</constants>
</class>
5 changes: 4 additions & 1 deletion doc/classes/NavigationAgent.xml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
3D agent used in navigation for collision avoidance.
</brief_description>
<description>
3D agent that is used in navigation to reach a location while avoiding static and dynamic obstacles. The dynamic obstacles are avoided using RVO (Reciprocal Velocity Obstacles) collision avoidance. The agent needs navigation data to work correctly. This can be done by having the agent as a child of a [Navigation] node, or using [method set_navigation]. [NavigationAgent] is physics safe.
3D agent that is used in navigation to reach a location while avoiding static and dynamic obstacles. The dynamic obstacles are avoided using RVO (Reciprocal Velocity Obstacles) collision avoidance. The agent needs navigation data to work correctly. By default this node will register to the default [World] navigation map. If this node is a child of a [Navigation] node it will register to the navigation map of the navigation node or the function [method set_navigation] can be used to set the navigation node directly. [NavigationAgent] is physics safe.
[b]Note:[/b] After [method set_target_location] is used it is required to use the [method get_next_location] function once every physics frame to update the internal path logic of the NavigationAgent. The returned vector position from this function should be used as the next movement position for the agent's parent Node.
</description>
<tutorials>
Expand Down Expand Up @@ -114,6 +114,9 @@
<member name="max_speed" type="float" setter="set_max_speed" getter="get_max_speed" default="10.0">
The maximum speed that an agent can move.
</member>
<member name="navigation_layers" type="int" setter="set_navigation_layers" getter="get_navigation_layers" default="1">
A bitfield determining all navigation map layers the [NavigationAgent] belongs to. On path requests the agent will ignore navmeshes without at least one matching layer.
</member>
<member name="neighbor_dist" type="float" setter="set_neighbor_dist" getter="get_neighbor_dist" default="50.0">
The distance to search for other agents.
</member>
Expand Down
Loading

0 comments on commit 4e7363c

Please sign in to comment.