Traffic Vehicle
Reference for the traffic vehicle class (`gameplay/traffic/vehicle`), instantiated for each vehicle in the traffic system. Manages per-vehicle state including position tracking, damage detection, coll
Reference for the traffic vehicle class (gameplay/traffic/vehicle), instantiated for each vehicle in the traffic system. Manages per-vehicle state including position tracking, damage detection, collision handling, driving tracking, offense detection, respawning, and role delegation.
Constructor
local veh = require('gameplay/traffic/vehicle')({id = vehicleId})Returns the vehicle object if valid (car/truck/automation/traffic/proptraffic/player type), or nil if invalid.
Key Properties
| Property | Type | Description |
|---|---|---|
id | number | Vehicle object ID |
pos, dirVec, vel | vec3 | Position, direction, velocity (from map.objects) |
speed | number | Current speed (m/s) |
damage | number | Current damage value |
state | string | "reset", "active", "fadeIn", "fadeOut", "queued", "locked" |
role | object | Current driver role (standard/police/suspect/empty) |
roleName | string | Name of current role |
pursuit | table | Pursuit state (mode, score, offenses, timers) |
tracking | table | Driving tracking (speed, direction, signals, collisions) |
respawn | table | Respawn parameters (spawnValue, activeRadius, etc.) |
isAi | bool | Whether vehicle has AI enabled |
model | string | JBeam model name |
modelName | string | Display name (Brand + Name) |
Key Methods
State Management
| Method | Description |
|---|---|
resetAll() | Resets pursuit, tracking, values, and collisions |
resetPursuit() | Clears pursuit state to mode 0 |
resetTracking() | Resets driving score, direction score, speed score |
resetValues() | Resets respawn parameters and queued functions |
resetElectrics() | Turns off lightbar, warning signal, horn |
Role & AI
| Method | Description |
|---|---|
setRole(roleName?) | Sets driver role (loads constructor, calls lifecycle hooks) |
setAiMode(mode?, ignoreParams?) | Sets AI mode with automatic parameters |
setAiParameters(params?) | Sets aggression, speed limit, awareness |
Respawn & Pooling
| Method | Description |
|---|---|
updateActiveRadius(tickTime) | Shrinks active radius over time; affected by occlusion |
tryRespawn() | Tests if vehicle is out of range and ready to respawn |
modifyRespawnValues(addActive?, addInner?) | Temporarily increases respawn resistance |
onRespawn() | Post-respawn setup: random paint, increment counter |
onRefresh() | Full refresh: reset state, reapply role, check headlights |
fade(rate, isFadeOut) | Gradually shows/hides vehicle mesh |
Tracking & Detection
| Method | Description |
|---|---|
trackDriving(dt) | Tracks road alignment, speed compliance, wrong-way, and signal violations |
checkCollisions() | Detects and creates collision tables for contacting vehicles |
trackCollision(otherId, dt) | Updates collision state (active → resolved/abandoned → cleared) |
checkOffenses() | Tests for police offenses: speeding, racing, reckless, wrongWay, intersection, hitPolice, hitTraffic |
triggerOffense(data) | Records an offense and fires onPursuitOffense hook |
Utilities
| Method | Description |
|---|---|
getInteractiveDistance(pos, squared?) | Distance from look-ahead point to position |
getBrakingDistance(speed?, accel?) | Estimated braking distance |
checkRayCast(startPos?, endPos?) | Static raycast visibility check |
honkHorn(duration?) | Horn with auto-off |
useSiren(duration?, disable?) | Lightbar siren with auto-off |
checkTimeOfDay() | Returns true if daytime |
Internals
Damage Limits
| Level | Threshold | Purpose |
|---|---|---|
| Minor | 50 | Triggers tracking |
| Stop | 1,000 | Standard role pulls over |
| Major | 30,000 | Vehicle disabled |
Respawn System
Vehicles maintain an activeRadius that shrinks over time. When focusDist > finalRadius:
- Check all non-traffic vehicles aren't within
innerRadius - Turn off headlights, enter
fadeOutstate - Fade mesh to invisible → enter
queuedstate - Traffic system repositions vehicle ahead of player
Driving Score Tracking
- speedScore: Decreases when driving 20%+ over speed limit
- directionScore: Decreases when wrong-way driving
- driveScore: Decreases when rapidly switching sides of road
- signalFault: Set when running a red light or stop sign
Offense Detection
Offenses require policeVars.strictness > 0 and are scored:
| Offense | Score | Condition |
|---|---|---|
| speeding | 100 | ≥120% speed limit AND ≥60 km/h |
| racing | 200 | ≥200% speed limit AND ≥100 km/h |
| reckless | 250 | driveScore below strictness threshold |
| wrongWay | 150 | directionScore below threshold |
| intersection | 200 | Red light or stop sign violation |
| hitPolice | 200 | Collision with police vehicle |
| hitTraffic | 100 | Collision during pursuit or hit-and-run |
Usage Example
-- Access a traffic vehicle
local veh = gameplay_traffic.getTrafficData()[vehId]
log("I", "", veh.modelName .. " at " .. tostring(veh.speed) .. " m/s")
log("I", "", "Role: " .. veh.roleName)
log("I", "", "Pursuit mode: " .. veh.pursuit.mode)
-- Modify respawn behavior
veh:modifyRespawnValues(500) -- keep active longer
veh.enableRespawn = false -- prevent respawning entirelySee Also
- gameplay/traffic/baseRole - Traffic Role Base Class - Related reference
- gameplay/traffic/trafficUtils - Traffic Utility Functions - Related reference
- Gameplay Systems Guide - Guide
Traffic Utilities
Reference for `gameplay_traffic_trafficUtils`, a collection of utility functions used by the traffic system for spawn point finding, vehicle group creation, road validation, and role loading.
Empty Traffic Role
Reference for the `empty` traffic role, a minimal role that prevents extra actions or AI logic from being applied to a vehicle. Used when a vehicle needs to be in the traffic system but should not hav