Traffic lights are used at urban street intersections. They are visual indicators of the traffic control regulations.

Traffic lights are configurated in a .lua file in the res/config/traffic_light/ folder. It's content is:

function data()
  return {
    yearFrom = 1980,
    tryOpposite = true,
    modelFn = function,
  }
end

There are three properties that are returned:

• yearFrom is the year from when the configuration is available. The game will pick the newest one available.
• tryOpposite is a boolean value. If set to true, it is tried to build the traffic lights on the opposite side of the intersection, like it is common in the USA. If there is no opposite street, the lights are placed before the intersection like if tryOpposite would be false.
• modelFn is the function that actually returns the models to be built for each street at the intersection. See below.

The modelFn is a function that is called for every incoming street at an intersection to compute the traffic lights models. It gets several parameters in a data struct:

The expected return data struct contains a list with n nested lists where n is the number of lanes with needsLight == true. Each of the nested lists contains pairs with id and transf where

• id is the reference to a .mdl file relative to res/models/model/.
• transf is the global transformation matrix for this model.

An exemplaric result data struct for a one-way street with one car lane could look like this:

{
  { -- sidewalk right
    { id = "street/traffic_light_eu_c/pedestrian_light.mdl", transf = { ... } } 
  }, 
  { --car lane
    { id = "street/traffic_light_eu_c/traffic_light_1.mdl", transf = { ... } }, 
    { id = "street/traffic_light_eu_c/pole.mdl", transf = { ... } }
  }, 
  { --sidewalk left
    { id = "street/traffic_light_eu_c/pedestrian_light.mdl", transf = { ... } }, 
    { id = "street/traffic_light_eu_c/pedestrian_pole.mdl", transf = { ... } }
  }
}

There is a prebuilt modelFn function available in the res/scripts/trafficlightutil.lua script. It requires a data struct with several properties:

local input = {
  models = {
    trafficLightPole = "street/traffic_light_us_c/pole.mdl",
    pedestrianPole = "street/traffic_light_us_c/pedestrian_pole.mdl",
    beam = {
      "street/traffic_light_us_c/beam_1.mdl",
      "street/traffic_light_us_c/beam_2.mdl",
      "street/traffic_light_us_c/beam_r.mdl",
      -- last model is repeated
    },
    trafficLight = {
      "street/traffic_light_us_c/traffic_light_1.mdl",
      "street/traffic_light_us_c/traffic_light_r.mdl",
      -- last model is repeated
    },
    pedestrianLight = "street/traffic_light_us_c/pedestrian_light.mdl",
  },
  params = {
    offset = -0.25,
    beamWidth = { 4 + .25, 4, 4 }, -- on model repetition last entry is used
    lightOffset = { 2, 2 }, -- offset is relative to beam -- on model repetition last entry is used
    poleTrafficLight = false
  }
}
 
...
 
  modelFn = trafficlightutil.standardLights(input),

The models that should be used by the script are provided in the models block:

• trafficLightPole is the pole model for traffic lights and pedestriant lights on the right side of the car lanes.
• pedestrianPoleis the pole model for pedestriant lights where they are not attached to a traffic light pole, e.g. on the left side of the street.
• beam is a list of beam models. The first one is used on the right, usually to extend the traffic light pole. The last one is repeated if needed.
• trafficLight is a list of trafficLight models. The first one is used on the right side. The last one is repeated if needed.
• pedestrianLight is the model for the pedestrian lights.

Additional parameters are provided in the params block:

• offset is a offset orthogonal to street direction.
• beamWidth is a list of n floats where n is the number of entries in the beam list above. Each value is the width of the respective beam model.
• lightOffset is a list of offsets from the mid of the lane in orthogonal direction for each traffic light from the trafficLight list above.
• poleTrafficLight is a boolean option that determines if the traffic light of the rightmost lane should be mounted at the traffic pole instead of the beam above.

The traffic light models as well as the pedestriant light models can use the following events:

• idle_red animation is used as a loop while the light is in 'red' state.
• green animation is used when the light switches from 'red' to 'green'.
• idle_green animation is used as a loop while the light is in 'green' state.
• red animation is used when the light switches from 'green' to 'red'.

Usually a traffic light is in red state and the idle_red animation is performed. As soon as it switches to green, green is performed once. Then idle_green is looped as long as the traffic light stays green. When the traffic light turns back to red, red is performed once before idle_red is looped again.

The idle animations could be used e.g. for blinking traffic lights.