使用 NavigationAgent

NavigationAgent 即导航代理，是一种辅助节点，能够为继承自 Node2D/3D 的父节点提供寻路、路径跟随、代理躲避等功能。这类节点会代替父级角色节点对 NavigationServer API 进行常见的调用，针对初学者进行了优化。

2D 和 3D 版本的 NavigationAgent 分别是 NavigationAgent2D 和 NavigationAgent3D。

新建的 NavigationAgent 节点会自动加入 World2D/World3D 的默认导航地图。

NavigationsAgent 节点是可选的，不是使用导航系统的硬性要求。对应的功能都可以用脚本代替，替换为对 NavigationServer API 的直接调用。

NavigationAgent 寻路

NavigationAgents query a new navigation path on their current navigation map when their target_position is set with a global position.

匀速遍历, 然后, 可以用下面的伪代码。

  • The navigation_layers bitmask can be used to limit the navigation meshes that the agent can use.

  • The pathfinding_algorithm controls how the pathfinding travels through the navigation mesh polygons in the path search.

  • The path_postprocessing sets if or how the raw path corridor found by the pathfinding is altered before it is returned.

  • The path_metadata_flags enable the collection of additional path point meta data returned by the path.

警告

Disabling path meta flags will disable related signal emissions on the agent.

NavigationAgent 路径跟随

After a target_position has been set for the agent, the next position to follow in the path can be retrieved with the get_next_path_position() function.

Once the next path position is received move the parent actor node of the agent towards this path position with your own movement code.

备注

The navigation system never moves the parent node of a NavigationAgent. The movement is entirely in the hands of users and their custom scripts.

NavigationAgents have their own internal logic to proceed with the current path and call for updates.

The get_next_path_position() function is responsible for updating many of the agent’s internal states and properties. The function should be repeatedly called once every physics_process until is_navigation_finished() tells that the path is finished. The function should not be called after the target position or path end has been reached as it can make the agent jitter in place due to the repeated path updates. Always check very early in script with is_navigation_finished() if the path is already finished.

这个节点有如下属性可供设置。

  • The path_desired_distance defines the distance at which the agent advances its internal path index to the next path position.

  • The target_desired_distance defines the distance at which the agent considers the target position to be reached and the path at its end.

  • The path_max_distance defines when an agent requests a new path cause it was moved too far away from the current path point segment.

The important updates are all triggered with the get_next_path_position() function when called in _physics_process().

NavigationAgents can be used with process but are still limited to a single update that happens in physics_process.

Script examples for various nodes commonly used with NavigationAgents can be found further below.

运行以下命令

There are some common user problems and important caveats to consider when writing agent movement scripts.

  • The path is returned empty

    If an agent queries a path before the navigation map synchronisation, e.g. in a _ready() function, the path might return empty. In this case the get_next_path_position() function will return the same position as the agent parent node and the agent will consider the path end reached. This is fixed by making a deferred call or using a callback e.g. waiting for the navigation map changed signal.

  • The agent is stuck dancing between two positions

    This is usually caused by very frequent path updates every single frame, either deliberate or by accident (e.g. max path distance set too short). The pathfinding needs to find the closest position that are valid on navigation mesh. If a new path is requested every single frame the first path positions might end up switching constantly in front and behind the agent’s current position, causing it to dance between the two positions.

  • The agent is backtracking sometimes

    If an agent moves very fast it might overshoot the path_desired_distance check without ever advancing the path index. This can lead to the agent backtracking to the path point now behind it until it passes the distance check to increase the path index. Increase the desired distances accordingly for your agent speed and update rate usually fixes this as well as a more balanced navigation mesh polygon layout with not too many polygon edges cramped together in small spaces.

  • The agent is sometimes looking backwards for a frame

    Same as with stuck dancing agents between two positions, this is usually caused by very frequent path updates every single frame. Depending on your navigation mesh layout, and especially when an agent is directly placed over a navigation mesh edge or edge connection, expect path positions to be sometimes slightly “behind” your actors current orientation. This happens due to precision issues and can not always be avoided. This is usually only a visible problem if actors are instantly rotated to face the current path position.

NavigationAgent 避障

This section explains how to use the navigation avoidance specific to NavigationAgents.

In order for NavigationAgents to use the avoidance feature the enable_avoidance property must be set to true.

../../_images/agent_avoidance_enabled.png

The velocity_computed signal of the NavigationAgent node must be connected to receive the safe velocity calculation result.

../../_images/agent_safevelocity_signal.png

Use set_velocity() on the NavigationAgent node in _physics_process() to update the agent with the current velocity of the agent’s parent node.

While avoidance is enabled on the agent the safe_velocity vector will be received with the velocity_computed signal every physics frame. This velocity vector should be used to move the NavigationAgent’s parent node in order to avoidance collision with other avoidance using agents or avoidance obstacles.

备注

Only other agents on the same map that are registered for avoidance themself will be considered in the avoidance calculation.

The following NavigationAgent properties are relevant for avoidance:

  • The property height is available in 3D only. The height together with the current global y-axis position of the agent determines the vertical placement of the agent in the avoidance simulation. Agents using the 2D avoidance will automatically ignore other agents or obstacles that are below or above them.

  • The property radius controls the size of the avoidance circle, or in case of 3D sphere, around the agent. This area describes the agents body and not the avoidance maneuver distance.

  • The property neighbor_distance controls the search radius of the agent when searching for other agents that should be avoided. A lower value reduces processing cost.

  • The property max_neighbors controls how many other agents are considered in the avoidance calculation if they all have overlapping radius. A lower value reduces processing cost but a too low value may result in agents ignoring the avoidance.

  • The properties time_horizon_agents and time_horizon_obstacles control the avoidance prediction time for other agents or obstacles in seconds. When agents calculate their safe velocities they choose velocities that can be kept for this amount of seconds without colliding with another avoidance object. The prediction time should be kept as low as possible as agents will slow down their velocities to avoid collision in that timeframe.

  • The property max_speed controls the maximum velocity allowed for the agents avoidance calculation. If the agents parents moves faster than this value the avoidance safe_velocity might not be accurate enough to avoid collision.

  • The property use_3d_avoidance switches the agent between the 2D avoidance (xz axis) and the 3D avoidance (xyz axis) on the next update. Note that 2D avoidance and 3D avoidance run in separate avoidance simulations so agents split between them do not affect each other.

  • The properties avoidance_layers and avoidance_mask are bitmasks similar to e.g. physics layers. Agents will only avoid other avoidance objects that are on an avoidance layer that matches at least one of their own avoidance mask bits.

  • The avoidance_priority makes agents with a higher priority ignore agents with a lower priority. This can be used to give certain agents more importance in the avoidance simulation, e.g. important npcs characters, without constantly changing their entire avoidance layers or mask.

Avoidance exists in its own space and has no information from navigation meshes or physics collision. Behind the scene avoidance agents are just circles with different radius on a flat 2D plane or spheres in an otherwise empty 3D space. NavigationObstacles can be used to add some environment constrains to the avoidance simulation, see 使用 NavigationObstacle.

备注

Avoidance does not affect the pathfinding. It should be seen as an additional option for constantly moving objects that cannot be (re)baked to a navigation mesh efficiently in order to move around them.

Using the NavigationAgent enable_avoidance property is the preferred option to toggle avoidance. The following code snippets can be used to toggle avoidance on agents, create or delete avoidance callbacks or switch avoidance modes.

GDScript

  1. extends NavigationAgent2D
  3. var agent: RID = get_rid()
  4. # Enable avoidance
  5. NavigationServer2D.agent_set_avoidance_enabled(agent, true)
  6. # Create avoidance callback
  7. NavigationServer2D.agent_set_avoidance_callback(agent, Callable(self, "_avoidance_done"))
  9. # Disable avoidance
  10. NavigationServer2D.agent_set_avoidance_enabled(agent, false)
  11. # Delete avoidance callback
  12. NavigationServer2D.agent_set_avoidance_callback(agent, Callable())

GDScript

  1. extends NavigationAgent3D
  3. var agent: RID = get_rid()
  4. # Enable avoidance
  5. NavigationServer3D.agent_set_avoidance_enabled(agent, true)
  6. # Create avoidance callback
  7. NavigationServer3D.agent_set_avoidance_callback(agent, Callable(self, "_avoidance_done"))
  8. # Switch to 3D avoidance
  9. NavigationServer3D.agent_set_use_3d_avoidance(agent, true)
  11. # Disable avoidance
  12. NavigationServer3D.agent_set_avoidance_enabled(agent, false)
  13. # Delete avoidance callback
  14. NavigationServer3D.agent_set_avoidance_callback(agent, Callable())
  15. # Switch to 2D avoidance
  16. NavigationServer3D.agent_set_use_3d_avoidance(agent, false)

NavigationAgent 脚本模板

The following sections provides script templates for nodes commonly used with NavigationAgents.

角色为 Node3D

This script adds basic navigation movement to a Node3D with a NavigationAgent3D child node.

GDScript

  1. extends Node3D
  3. @export var movement_speed: float = 4.0
  4. @onready var navigation_agent: NavigationAgent3D = get_node("NavigationAgent3D")
  5. var movement_delta: float
  7. func _ready() -> void:
  8.     navigation_agent.velocity_computed.connect(Callable(_on_velocity_computed))
  10. func set_movement_target(movement_target: Vector3):
  11.     navigation_agent.set_target_position(movement_target)
  13. func _physics_process(delta):
  14.     if navigation_agent.is_navigation_finished():
  15.         return
  17.     movement_delta = movement_speed * delta
  18.     var next_path_position: Vector3 = navigation_agent.get_next_path_position()
  19.     var new_velocity: Vector3 = global_position.direction_to(next_path_position) * movement_delta
  20.     if navigation_agent.avoidance_enabled:
  21.         navigation_agent.set_velocity(new_velocity)
  22.     else:
  23.         _on_velocity_computed(new_velocity)
  25. func _on_velocity_computed(safe_velocity: Vector3) -> void:
  26.     global_position = global_position.move_toward(global_position + safe_velocity, movement_delta)

角色为 CharacterBody3D

This script adds basic navigation movement to a CharacterBody3D with a NavigationAgent3D child node.

GDScript

  1. extends CharacterBody3D
  3. @export var movement_speed: float = 4.0
  4. @onready var navigation_agent: NavigationAgent3D = get_node("NavigationAgent3D")
  6. func _ready() -> void:
  7.     navigation_agent.velocity_computed.connect(Callable(_on_velocity_computed))
  9. func set_movement_target(movement_target: Vector3):
  10.     navigation_agent.set_target_position(movement_target)
  12. func _physics_process(delta):
  13.     if navigation_agent.is_navigation_finished():
  14.         return
  16.     var next_path_position: Vector3 = navigation_agent.get_next_path_position()
  17.     var new_velocity: Vector3 = global_position.direction_to(next_path_position) * movement_speed
  18.     if navigation_agent.avoidance_enabled:
  19.         navigation_agent.set_velocity(new_velocity)
  20.     else:
  21.         _on_velocity_computed(new_velocity)
  23. func _on_velocity_computed(safe_velocity: Vector3):
  24.     velocity = safe_velocity
  25.     move_and_slide()

角色为 RigidBody3D

This script adds basic navigation movement to a RigidBody3D with a NavigationAgent3D child node.

GDScript

  1. extends RigidBody3D
  3. @export var movement_speed: float = 4.0
  4. @onready var navigation_agent: NavigationAgent3D = get_node("NavigationAgent3D")
  6. func _ready() -> void:
  7.     navigation_agent.velocity_computed.connect(Callable(_on_velocity_computed))
  9. func set_movement_target(movement_target: Vector3):
  10.     navigation_agent.set_target_position(movement_target)
  12. func _physics_process(delta):
  13.     if navigation_agent.is_navigation_finished():
  14.         return
  16.     var next_path_position: Vector3 = navigation_agent.get_next_path_position()
  17.     var new_velocity: Vector3 = global_position.direction_to(next_path_position) * movement_speed
  18.     if navigation_agent.avoidance_enabled:
  19.         navigation_agent.set_velocity(new_velocity)
  20.     else:
  21.         _on_velocity_computed(new_velocity)
  23. func _on_velocity_computed(safe_velocity: Vector3):
  24.     linear_velocity = safe_velocity

Previous Next

© 版权所有 2014-present Juan Linietsky, Ariel Manzur and the Godot community (CC BY 3.0). Revision b1c660f7.

Built with Sphinx using a theme provided by Read the Docs.