Implementation:CARLA simulator Carla Navigation

Knowledge Sources	CARLA
Domains	Pedestrian Simulation, Navigation, AI
Last Updated	2026-02-15 05:00 GMT

Overview

Navigation is the core pedestrian navigation module in CARLA that uses the Recast & Detour library to manage crowd simulation, pathfinding, and obstacle avoidance for walkers in the simulated world.

Description

The Navigation class (defined in carla::nav) manages the entire lifecycle of pedestrian navigation within the CARLA simulator. It loads a precomputed navigation mesh (binary format with magic MSET), initializes Detour's dtNavMesh and dtNavMeshQuery for pathfinding, and creates a dtCrowd for real-time crowd simulation.

Key constants and configuration values include:

• MAX_AGENTS = 500 - Maximum number of concurrent crowd agents
• MAX_POLYS = 256 - Maximum polygon count for path queries
• MAX_QUERY_SEARCH_NODES = 2048 - Search depth for navigation queries
• AGENT_HEIGHT = 1.8f and AGENT_RADIUS = 0.3f - Default pedestrian dimensions matching the RecastBuilder settings
• AGENT_UNBLOCK_DISTANCE = 0.5f and AGENT_UNBLOCK_TIME = 4.0f - Parameters for detecting and resolving stuck agents
• AREA_GRASS_COST = 1.0f and AREA_ROAD_COST = 10.0f - Navigation area cost weights that make walkers prefer sidewalks and grass over roads

The class provides the following major capabilities:

• Mesh Loading: Load() accepts either a filename or a byte vector. It parses the binary navigation mesh format (header + tile data), initializes dtNavMesh, and sets up the dtNavMeshQuery for path queries.
• Crowd Management: CreateCrowd() initializes the Detour crowd with obstacle avoidance parameters. AddWalker() and RemoveAgent() manage individual pedestrian agents. UpdateVehicles() adds vehicle obstacles that walkers must avoid.
• Pathfinding: GetPath() and GetAgentRoute() compute navigation paths between two locations using Detour's polygon-based pathfinding with area type awareness.
• Crowd Update: UpdateCrowd() advances the crowd simulation by the episode delta time, updates agent positions, and handles stuck agent detection by comparing positions over time intervals.
• Walker Control: SetWalkerTarget(), SetWalkerMaxSpeed(), PauseAgent(), and SetWalkerLookAt() provide fine-grained control over individual pedestrians.
• Query Functions: GetWalkerTransform(), GetWalkerPosition(), GetWalkerSpeed(), GetRandomLocation(), HasVehicleNear(), and IsWalkerAlive() expose the current state of agents.

The class delegates route-level logic (waypoints, events, traffic lights) to the WalkerManager companion class.

Usage

Use Navigation on the client side to control pedestrian behavior in the simulation. It is instantiated as part of the client episode and receives the navigation mesh binary from the server. Typical usage involves loading the mesh, creating the crowd, adding walker agents, setting their destinations, and calling UpdateCrowd() every simulation tick.

Code Reference

Source Location

• Repository: CARLA
• File: LibCarla/source/carla/nav/Navigation.cpp
• Lines: 1-1249

Signature

namespace carla {
namespace nav {

  class Navigation : private NonCopyable {
  public:
    Navigation();
    ~Navigation();

    bool Load(const std::string &filename);
    bool Load(std::vector<uint8_t> content);
    bool GetPath(carla::geom::Location from, carla::geom::Location to,
                 dtQueryFilter *filter,
                 std::vector<carla::geom::Location> &path,
                 std::vector<unsigned char> &area);
    bool GetAgentRoute(ActorId id, carla::geom::Location from,
                       carla::geom::Location to,
                       std::vector<carla::geom::Location> &path,
                       std::vector<unsigned char> &area);

    void SetSimulator(std::weak_ptr<carla::client::detail::Simulator> simulator);
    void SetSeed(unsigned int seed);
    void CreateCrowd(void);
    bool AddWalker(ActorId id, carla::geom::Location from);
    bool AddOrUpdateVehicle(VehicleCollisionInfo &vehicle);
    bool RemoveAgent(ActorId id);
    bool UpdateVehicles(std::vector<VehicleCollisionInfo> vehicles);
    bool SetWalkerMaxSpeed(ActorId id, float max_speed);
    bool SetWalkerTarget(ActorId id, carla::geom::Location to);
    bool SetWalkerDirectTarget(ActorId id, carla::geom::Location to);
    bool GetWalkerTransform(ActorId id, carla::geom::Transform &trans);
    bool GetWalkerPosition(ActorId id, carla::geom::Location &location);
    float GetWalkerSpeed(ActorId id);
    void UpdateCrowd(const client::detail::EpisodeState &state);
    bool GetRandomLocation(carla::geom::Location &location,
                           dtQueryFilter *filter = nullptr) const;
    void SetPedestriansCrossFactor(float percentage);
    void PauseAgent(ActorId id, bool pause);
    bool HasVehicleNear(ActorId id, float distance, carla::geom::Location direction);
    bool SetWalkerLookAt(ActorId id, carla::geom::Location location);
    bool IsWalkerAlive(ActorId id, bool &alive);

    dtCrowd *GetCrowd();
    double GetDeltaSeconds();
  };

} // namespace nav
} // namespace carla

Import

#include "carla/nav/Navigation.h"

I/O Contract

Inputs

Name	Type	Required	Description
filename	std::string	Yes (for file load)	Path to the binary navigation mesh file
content	std::vector<uint8_t>	Yes (for memory load)	Binary navigation mesh data received from the server
id	ActorId	Yes	Unique identifier for a walker or vehicle agent
from / to	carla::geom::Location	Yes	Source and destination locations for pathfinding or agent placement
vehicles	std::vector<VehicleCollisionInfo>	Yes	Vehicle collision data for crowd obstacle avoidance
state	client::detail::EpisodeState	Yes	Current episode state containing delta time for crowd updates

Outputs

Name	Type	Description
path	std::vector<carla::geom::Location>	Computed navigation path as a sequence of waypoints
area	std::vector<unsigned char>	Area type for each path segment (sidewalk, crosswalk, road, grass)
trans	carla::geom::Transform	Current transform (position + rotation) of a walker agent
location	carla::geom::Location	Current or random location for a walker agent
return value	bool	Success or failure indicator for most operations

Usage Examples

Loading a Navigation Mesh and Creating Crowd

#include "carla/nav/Navigation.h"

carla::nav::Navigation nav;

// Load navigation mesh from binary data received from server
std::vector<uint8_t> nav_mesh_data = /* received from server */;
if (nav.Load(std::move(nav_mesh_data))) {
    nav.CreateCrowd();
}

Adding a Walker and Setting a Target

// Add a pedestrian agent at a spawn location
carla::geom::Location spawn{10.0f, 20.0f, 0.5f};
nav.AddWalker(walker_id, spawn);
nav.SetWalkerMaxSpeed(walker_id, 1.4f);

// Set a destination for the walker
carla::geom::Location destination{50.0f, 30.0f, 0.5f};
nav.SetWalkerTarget(walker_id, destination);

Updating the Crowd Each Tick

// In the simulation loop
nav.UpdateVehicles(vehicle_collision_data);
nav.UpdateCrowd(episode_state);

// Query updated walker position
carla::geom::Transform walker_transform;
nav.GetWalkerTransform(walker_id, walker_transform);

Related Pages

• CARLA_simulator_Carla_WalkerManager
• CARLA_simulator_Carla_Navigation_Interface