Police Traffic Role

Reference for the police traffic role, which implements pursuit behavior including chasing suspects, managing sirens, avoiding head-on collisions, setting up roadblocks, and coordinating with the police system.

Role Properties

Actions

Key Methods

checkTarget() → id|nil

Scans all traffic vehicles for the best pursuit target (highest pursuit score, non-police).

onRefresh()

Re-evaluates targets on refresh. If a pursuit target exists, restarts pursuit. Checks roadblock distance to avoid re-triggering.

onTrafficTick(dt)

• Updates validTargets table with distance, interactive distance, and visibility for each potential target
• Tracks police visibility for pursuit score counting
• Manages lane-change behavior during chase (exits lane mode when target is visible)
• Triggers crash avoidance when approaching target head-on at combined speed ≥ avoidSpeed
• Auto-disables if vehicle takes critical damage
• Controls traffic signal freezing when lightbar is active

onUpdate(dt, dtSim)

• Manages siren pulse logic (passive mode → intermittent sirens → full sirens if target accelerates)
• Handles cooldown timer after pursuit ends
• Chase state machine: pulls over when near slow target, resumes chase when target moves
• Exits roadblock mode when target evades or drives away

Internals

Pursuit Modes (from target vehicle)

State Flow

none → pursuitStart → (chase ↔ follow ↔ flee ↔ pullOver) → pursuitEnd → disabled → (cooldown) → none

Cooldown

After a pursuit ends, the police vehicle enters a cooldown period (arrestTime + 5 seconds minimum 10s) during which it won't pursue new targets.

Usage Example

-- Police vehicles are auto-assigned this role based on config type
-- Manual assignment:
local veh = gameplay_traffic.getTrafficData()[vehId]
veh:setRole('police')

-- Start pursuit programmatically
veh.role:setTarget(suspectId)
veh.role:setAction('pursuitStart', {targetId = suspectId})

See Also

• gameplay/traffic/roles/empty - Empty Traffic Role - Related reference
• gameplay/traffic/roles/standard - Standard Civilian Traffic Role - Related reference
• gameplay/traffic/roles/suspect - Suspect Traffic Role - Related reference
• Gameplay Systems Guide - Guide