Traffic & AI System

BeamNG includes a full traffic simulation and AI driving system. Whether you want ambient traffic for immersion, police chases for gameplay, or scripted vehicle paths for scenarios, the traffic and AI APIs give you control over it all.

Traffic Manager Overview

The traffic system is managed by the gameplay_traffic GE extension. It handles spawning, despawning, focus tracking, and per-vehicle AI behavior. Traffic state progresses through: "off" → "loading" → "spawning" → "on".

Spawning Traffic

Quick Setup

-- Spawn default traffic (uses map-appropriate vehicles)
gameplay_traffic.setupTraffic(10)

-- With a police ratio (0.0 to 1.0)
gameplay_traffic.setupTraffic(10, 0.2)

Custom Traffic

-- Spawn with custom parameters
gameplay_traffic.setupCustomTraffic(8, {
  -- custom params
})

-- Or use the lower-level spawn
gameplay_traffic.spawnTraffic(5, groupData, options)

Control

gameplay_traffic.activate()          -- Activate traffic AI
gameplay_traffic.deactivate()        -- Deactivate (optionally stop AI)
gameplay_traffic.toggle()            -- Toggle on/off

-- Set traffic variables
gameplay_traffic.setTrafficVars({
  activeAmount = 15,
  speedLimit = 60,
  aiMode = "traffic"
})

Focus Modes

Traffic clusters around a focus point — where the action is:

-- Follow the camera (default)
gameplay_traffic.setFocus("camera")

-- Follow a specific vehicle
gameplay_traffic.setFocus("vehicle", {vehicleId = vehId})

-- Custom position
gameplay_traffic.setFocus("custom", {pos = vec3(100, 200, 50)})

Vehicles too far from the focus are despawned or teleported to maintain the illusion of a populated world.

Teleportation and Scattering

-- Teleport a specific vehicle to a new position
gameplay_traffic.forceTeleport(vehicleId, pos, dir, minDist, maxDist)

-- Scatter all traffic to new positions
gameplay_traffic.scatterTraffic()

AI Modes

Each traffic vehicle has an AI mode controlling its driving behavior:

Set AI mode per vehicle:

-- In Vehicle-Lua context
ai.setMode('chase')

-- From GE, on a specific vehicle
local veh = scenetree.findObject("vehicleName")
if veh then
  veh:queueLuaCommand("ai.setMode('flee')")
end

Players can also set AI modes quickly via the radial menu (E key).

Roles

Each traffic vehicle has a role that defines its behavioral personality:

Standard Role

The default civilian driver. Follows traffic laws, has randomized personality traits (aggression, patience, bravery) that influence driving style.

Police Role

Law enforcement behavior with full pursuit logic. Police vehicles detect offenses, initiate pursuits, and coordinate with the traffic system. They can freeze traffic signals for emergency response.

Suspect Role

Fleeing behavior for vehicles being pursued. Used during active police chases.

Empty Role

A no-op role for parked or inactive vehicles.

-- Set a traffic vehicle's role (from the traffic vehicle object)
trafficVehicle:setRole("police")
trafficVehicle:setRole("standard")
trafficVehicle:setRole(nil)  -- clears role

Traffic Vehicle States

Each vehicle in the traffic system has a state:

Querying Traffic Data

-- Get all traffic data
local data = gameplay_traffic.getTrafficData()

-- Get list of traffic vehicle IDs
local list = gameplay_traffic.getTrafficList()

-- Get count (optionally active-only)
local count = gameplay_traffic.getTrafficAmount(true)

-- Get system state ("off", "loading", "spawning", "on")
local state = gameplay_traffic.getState()

Save and Restore

-- Freeze the current traffic state (for save systems)
gameplay_traffic.freezeState()

-- Restore the frozen state
gameplay_traffic.unfreezeState()

ScriptAI — Recorded Paths

For scenarios requiring exact vehicle paths, use the ScriptAI Editor (World Editor → Tools):

Time-Based Mode (T-Based)

Waypoints are stamped with time values. The AI follows positions precisely. Enable the "AI Assistant" checkbox for centimeter-scale accuracy. Best for cinematic sequences.

Velocity-Based Mode (V-Based)

Waypoints are stamped with speed values (e.g., "reach this point at max 30 kph"). Time-independent and handles obstructions gracefully. More realistic for gameplay scenarios.

Script AI Manager

Record paths by driving the route yourself, then replay with AI. Supports multiple vehicles for synchronized scenarios — useful for scripted crashes, convoys, or traffic scenes. Access via World Editor → Tools → Gameplay.

Debug Mode

-- Enable traffic debug visualization
gameplay_traffic.setDebugMode(true)

See Also

• Traffic Manager API — Full traffic manager API reference
• Traffic Vehicle API — Per-vehicle traffic object
• Traffic Roles — Role base class and personality system
• Police Role — Police pursuit logic
• Flowgraph Visual Scripting — Visual scripting for scenarios