Implementation:CARLA simulator Carla TrafficLight Class

Knowledge Sources	CARLA
Domains	Client Library, Traffic Control, Simulation
Last Updated	2026-02-15 05:00 GMT

Overview

TrafficLight is a client-side class representing a traffic light actor in CARLA, providing methods to control and query its state, timing, grouping, and associated road infrastructure.

Description

The TrafficLight class in the carla::client namespace extends TrafficSign (which itself extends Actor) and provides traffic light-specific functionality.

State Management

• SetState(state) -- Sets the traffic light to a specific rpc::TrafficLightState (Red, Yellow, Green, Off, Unknown).
• GetState() -- Returns the current state from the last tick without calling the simulator.

Timing Control

• SetGreenTime(green_time) / GetGreenTime() -- Set/get the duration of the green phase.
• SetYellowTime(yellow_time) / GetYellowTime() -- Set/get the duration of the yellow phase.
• SetRedTime(red_time) / GetRedTime() -- Set/get the duration of the red phase.
• GetElapsedTime() -- Returns the elapsed time in the current phase from the last tick.
• Freeze(freeze) / IsFrozen() -- Freeze or unfreeze the traffic light timer.

Group Operations

• GetPoleIndex() -- Returns the index of this pole within its traffic light group.
• GetGroupTrafficLights() -- Returns all traffic lights in the group this one belongs to. This method does call the simulator.
• ResetGroup() -- Resets the timers and states of all groups.

Road Infrastructure

• GetAffectedLaneWaypoints() -- Returns waypoints of lanes affected by this traffic light.
• GetLightBoxes() -- Returns bounding boxes of the traffic light geometry.
• GetOpenDRIVEID() -- Returns the OpenDRIVE signal ID as road::SignId.
• GetStopWaypoints() -- Returns the waypoints where vehicles should stop for this light.

Usage

Traffic lights are typically retrieved from the simulation world via actor queries or from the Vehicle::GetTrafficLight() method. They can be programmatically controlled for testing traffic scenarios or frozen to create specific test conditions.

Code Reference

Source Location

• Repository: CARLA
• File: LibCarla/source/carla/client/TrafficLight.h (82 lines)

Signature

namespace carla {
namespace client {

class TrafficLight : public TrafficSign {
public:
  explicit TrafficLight(ActorInitializer init);

  void SetState(rpc::TrafficLightState state);
  rpc::TrafficLightState GetState() const;

  void SetGreenTime(float green_time);
  float GetGreenTime() const;
  void SetYellowTime(float yellow_time);
  float GetYellowTime() const;
  void SetRedTime(float red_time);
  float GetRedTime() const;
  float GetElapsedTime() const;

  void Freeze(bool freeze);
  bool IsFrozen() const;

  uint32_t GetPoleIndex();
  std::vector<SharedPtr<TrafficLight>> GetGroupTrafficLights();
  void ResetGroup();

  std::vector<SharedPtr<Waypoint>> GetAffectedLaneWaypoints() const;
  std::vector<geom::BoundingBox> GetLightBoxes() const;
  road::SignId GetOpenDRIVEID() const;
  std::vector<SharedPtr<Waypoint>> GetStopWaypoints() const;
};

} // namespace client
} // namespace carla

Import

#include "carla/client/TrafficLight.h"

I/O Contract

Inputs

Name	Type	Required	Description
init	ActorInitializer	Yes	Actor initialization data
state	rpc::TrafficLightState	No	Target traffic light state (Red, Yellow, Green, Off, Unknown)
green_time	float	No	Duration of green phase in seconds
yellow_time	float	No	Duration of yellow phase in seconds
red_time	float	No	Duration of red phase in seconds
freeze	bool	No	Whether to freeze the traffic light timer

Outputs

Name	Type	Description
state	rpc::TrafficLightState	Current traffic light state
time values	float	Green, yellow, red, or elapsed time in seconds
is_frozen	bool	Whether the traffic light is currently frozen
group_lights	std::vector<SharedPtr<TrafficLight>>	All traffic lights in the same group
waypoints	std::vector<SharedPtr<Waypoint>>	Affected lane or stop waypoints
light_boxes	std::vector<geom::BoundingBox>	Bounding boxes of light geometry
opendrive_id	road::SignId	OpenDRIVE signal identifier

Usage Examples

// Get a traffic light from the world
auto traffic_lights = world.GetActors()->Filter("traffic.traffic_light");
auto tl = std::static_pointer_cast<carla::client::TrafficLight>(traffic_lights->at(0));

// Set to red and freeze
tl->SetState(carla::rpc::TrafficLightState::Red);
tl->Freeze(true);

// Configure timing
tl->SetGreenTime(15.0f);
tl->SetYellowTime(3.0f);
tl->SetRedTime(20.0f);

// Get group information
auto group = tl->GetGroupTrafficLights();
auto stop_waypoints = tl->GetStopWaypoints();

Related Pages

• Environment:CARLA_simulator_Carla_Simulation_Runtime
• CARLA_simulator_Carla_Actor_Class - Base Actor class
• CARLA_simulator_Carla_Vehicle_Class - Vehicle class that interacts with traffic lights
• CARLA_simulator_Carla_RssCheck - RSS check that considers traffic light states