Implementation:CARLA simulator Carla TrafficManager Class

Knowledge Sources	CARLA
Domains	Traffic_Management, Autonomous_Driving
Last Updated	2026-02-15 05:00 GMT

Overview

The TrafficManager class is the top-level user-facing facade that integrates all traffic manager stages and provides the public API for controlling autonomous vehicle behavior in the CARLA simulator.

Description

TrafficManager serves as the singleton-like entry point for the entire Traffic Manager subsystem. It manages a static map of TrafficManagerBase instances (keyed by port number), supporting both local and remote traffic manager configurations. Key design aspects include:

Instance Management: The class maintains a static _tm_map (std::map<uint16_t, TrafficManagerBase*>) protected by a static mutex. When constructed with an EpisodeProxy and port, it either creates a TrafficManagerLocal instance (with an RPC server) or connects to a remote one via TrafficManagerClient.
Facade Pattern: Every public method (e.g., SetPercentageSpeedDifference, SetCollisionDetection, RegisterVehicles) delegates to the underlying TrafficManagerBase pointer retrieved via GetTM(port). This allows transparent switching between local and remote execution.
Lifecycle Methods: Release() destroys all TM instances, Reset() reinitializes them (e.g., after map changes), and Tick() provides manual synchronous advancement.
Port Validation: The IsValidPort() method ensures the port number is above 1023 to avoid reserved OS ports.

Delegated Methods (partial list):

RegisterVehicles / UnregisterVehicles: Add or remove vehicles from traffic management.
SetPercentageSpeedDifference / SetDesiredSpeed: Control vehicle speed.
SetLaneOffset / SetGlobalLaneOffset: Set lateral lane offsets.
SetCollisionDetection: Configure collision detection between specific vehicle pairs.
SetForceLaneChange / SetAutoLaneChange: Control lane change behavior.
SetDistanceToLeadingVehicle / SetGlobalDistanceToLeadingVehicle: Set following distance.
SetPercentageIgnoreWalkers / SetPercentageIgnoreVehicles: Set collision ignore probabilities.
SetPercentageRunningLight / SetPercentageRunningSign: Set traffic rule violation probabilities.
SetHybridPhysicsMode / SetHybridPhysicsRadius: Control hybrid physics optimization.
SetSynchronousMode / SynchronousTick: Control synchronous execution.
SetOSMMode: Enable Open Street Map routing mode.
SetCustomPath / SetImportedRoute: Import custom vehicle paths and routes.
SetRespawnDormantVehicles / SetBoundariesRespawnDormantVehicles: Control dormant vehicle management.
GetNextAction / GetActionBuffer: Query planned vehicle actions.

Usage

This is the primary class that CARLA Python/C++ clients interact with to configure and control autonomous traffic. Users create a TrafficManager instance from the CARLA world, register vehicles, and configure their behavior through the public API methods.

Code Reference

Source Location

Repository: CARLA
File: LibCarla/source/carla/trafficmanager/TrafficManager.h

Signature

class TrafficManager {
public:
  explicit TrafficManager(
    carla::client::detail::EpisodeProxy episode_proxy,
    uint16_t port = TM_DEFAULT_PORT);

  TrafficManager(const TrafficManager& other);
  TrafficManager();
  TrafficManager(TrafficManager &&) = default;
  TrafficManager &operator=(const TrafficManager &) = default;
  TrafficManager &operator=(TrafficManager &&) = default;

  static void Release();
  static void Reset();
  static void Tick();

  uint16_t Port() const;
  bool IsValidPort() const;

  void RegisterVehicles(const std::vector<ActorPtr> &actor_list);
  void UnregisterVehicles(const std::vector<ActorPtr> &actor_list);
  void SetPercentageSpeedDifference(const ActorPtr &actor, const float percentage);
  void SetDesiredSpeed(const ActorPtr &actor, const float value);
  void SetLaneOffset(const ActorPtr &actor, const float offset);
  void SetGlobalPercentageSpeedDifference(float const percentage);
  void SetGlobalLaneOffset(float const offset);
  void SetCollisionDetection(const ActorPtr &reference_actor, const ActorPtr &other_actor, const bool detect_collision);
  void SetForceLaneChange(const ActorPtr &actor, const bool direction);
  void SetAutoLaneChange(const ActorPtr &actor, const bool enable);
  void SetDistanceToLeadingVehicle(const ActorPtr &actor, const float distance);
  void SetGlobalDistanceToLeadingVehicle(const float distance);
  void SetHybridPhysicsMode(const bool mode_switch);
  void SetHybridPhysicsRadius(const float radius);
  void SetSynchronousMode(bool mode);
  bool SynchronousTick();
  void SetOSMMode(const bool mode_switch);
  void SetCustomPath(const ActorPtr &actor, const Path path, const bool empty_buffer);
  void SetImportedRoute(const ActorPtr &actor, const Route route, const bool empty_buffer);
  void SetRespawnDormantVehicles(const bool mode_switch);
  void SetRandomDeviceSeed(const uint64_t seed);
  void ShutDown();
  Action GetNextAction(const ActorId &actor_id);
  ActionBuffer GetActionBuffer(const ActorId &actor_id);
  // ... additional methods

private:
  void CreateTrafficManagerServer(carla::client::detail::EpisodeProxy episode_proxy, uint16_t port);
  bool CreateTrafficManagerClient(carla::client::detail::EpisodeProxy episode_proxy, uint16_t port);
  TrafficManagerBase* GetTM(uint16_t port) const;

  static std::map<uint16_t, TrafficManagerBase*> _tm_map;
  static std::mutex _mutex;
  uint16_t _port = 0;
};

Import

#include "carla/trafficmanager/TrafficManager.h"

I/O Contract

Inputs

Name	Type	Required	Description
episode_proxy	carla::client::detail::EpisodeProxy	Yes	Proxy to the current CARLA simulation episode
port	uint16_t	No	RPC port for the traffic manager (default: TM_DEFAULT_PORT)
actor / actor_list	ActorPtr / std::vector<ActorPtr>	Varies	Vehicle actor(s) for registration and per-vehicle configuration
percentage / value / distance	float	Varies	Numeric parameters for behavior configuration
mode_switch / enable	bool	Varies	Boolean toggles for mode switches

Outputs

Name	Type	Description
Port()	uint16_t	The port number this TrafficManager instance is bound to
IsValidPort()	bool	Whether the port is valid (above 1023)
SynchronousTick()	bool	Returns true when synchronous tick is successfully processed
GetNextAction()	Action	The next planned action (road option + waypoint) for a vehicle
GetActionBuffer()	ActionBuffer	The full buffer of planned actions for a vehicle

Usage Examples

// Create TrafficManager from a CARLA world:
auto world = client.GetWorld();
carla::traffic_manager::TrafficManager tm(world.GetEpisode(), 8000);

// Register vehicles:
std::vector<ActorPtr> vehicles = { vehicle1, vehicle2, vehicle3 };
tm.RegisterVehicles(vehicles);

// Configure behavior:
tm.SetPercentageSpeedDifference(vehicle1, -20.0f); // 20% faster than limit
tm.SetDesiredSpeed(vehicle2, 30.0f);               // exact 30 km/h
tm.SetDistanceToLeadingVehicle(vehicle1, 5.0f);
tm.SetAutoLaneChange(vehicle1, true);
tm.SetCollisionDetection(vehicle1, vehicle2, true);
tm.SetHybridPhysicsMode(true);
tm.SetHybridPhysicsRadius(50.0f);

// Synchronous mode:
tm.SetSynchronousMode(true);
bool success = tm.SynchronousTick();

// Cleanup:
tm.ShutDown();
TrafficManager::Release();

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment