Legacy Documentation: Version 5.3
NavMesh Agent
Off-Mesh Link

NavMesh Obstacle

Switch to Scripting

The NavMesh Obstacle component allows you to describe moving obstacles that the agents should avoid while navigating the world. A barrel or a crate controlled by the physics system is a good example of an obstacle. While the obstacle is moving the agents do their best to avoid it, but once the obstacle becomes stationary, it will carve a hole in the NavMesh so that the agents can change their paths to steer around it, or if the stationary obstacle blocked the pathway, the agents can find a different route.

Property Function
Shape The shape of the obstacle geometry: capsule or box
For box
   Center Center of the box relative to the transform position
   Size Size of the box
For capsule
   Center Center of the capsule relative to the transform position
   Radius Radius of the capsule
   Height Height of the capsule
Carve When turned on, the obstacle will carve hole in the NavMesh
When carving is turned on
   Move Threshold Threshold distance for updating a moving carved hole.
   Time To Stationary The time to wait until obstacle is treated as stationary.
   Carve Only Stationary When enabled, the obstacle will be carved only when it is stationary.


NavMesh Obstacles can be used to affect the agent’s navigation during the game in two ways:

  • Obstructing: when carving is not turned on, the default behavior of the obstacle is a lot like physics collider. The agents will try to avoid collisions with the obstacle, and when close they will collide with the obstacle. Obstacle avoidance is a very local operation, like trying to sense the environment with a stick. The agent may not find a way around in environment cluttered with obstacles. This mode is best used in cases where the obstacle is constantly moving, for example a vehicle, or even player character.
  • Carving: when carving is turned on, the obstacle will carve a hole in the NavMesh when stationary, and when moving it will be obstructing. When a hole is carved into the NavMesh, the path finder, which knows about the big picture, is able to navigate the agent around location cluttered with obstacles, or it can find another route if the current path gets blocked by an obstacle. You should turn on carving for obstacle like crates and barrels which generally block navigation, but can be moved by the player or other game events like explosions.

Moving Obstacle Logic

When the obstacle moves, the carved hole will also move but to reduce CPU overhead the hole is only recalculated when necessary. The recalculation logic has two options: 1) carve when stationary, 2) carve when moved.

  • Carve when stationary is the default behavior and is used when Carve Only Stationary is turned on. The obstacle is treated as moving when it has moved more than the distance set by Carving Move Threshold. At this time, the carved hole is removed. When the obstacle has stopped moving, and has been stationary more than Carving Time To Stationary seconds, the obstacles is treated stationary and carving is updated again. While the obstacle is moving, the agents will avoid it using the collision avoidance, but will not plan paths around it. This mode is generally the best choice in terms of performance. It is good match when the game object is controlled by physics (for example crates and barrels).
  • Carve when moved behavior is used when Carve Only Stationary is turned off. In this mode the carved hole is updated when the obstacle has moved more than the distance set by Carving Move Threshold. This mode is well suited for large slowly moving obstacles, for example a tank that is being avoided by infantry.

Further Reading

NavMesh Agent
Off-Mesh Link