API ReferenceGE Extensionsgameplay
Gameplay Police
Manages police pursuit logic including suspect tracking, arrest/evade timers, roadblock placement, and pursuit mode escalation. Tightly integrated with the traffic system.
Manages police pursuit logic including suspect tracking, arrest/evade timers, roadblock placement, and pursuit mode escalation. Tightly integrated with the traffic system.
Public API
| Function | Signature | Returns | Description |
|---|---|---|---|
M.setPursuitMode | (mode, targetId, policeIds) | nil | Sets pursuit mode: -1=busted, 0=off, 1-3=pursuit level |
M.setPursuitVars | (data) | nil | Merges a table of pursuit config overrides; nil resets to defaults |
M.getPursuitVars | () | table | Returns the current pursuit variables |
M.getPursuitData | (id?) | table | Returns pursuit data for a vehicle (defaults to player) |
M.getPoliceVehicles | () | table | Returns map of police vehicle IDs → traffic data |
M.getNearestPoliceVehicle | (targetId, isVisible, isUsable) | id, dist, interDist | Nearest active police vehicle to a target |
M.isVehicleInPursuit | (id, targetId?) | state, isPolice | Whether vehicle is in active pursuit |
M.setSuspect | (id) | nil | Changes a traffic vehicle's role to suspect |
M.setSuspectTimer | (time?) | nil | Sets time until next suspect is queued |
M.arrestVehicle | (id, showMessages) | nil | Instantly arrests a vehicle |
M.evadeVehicle | (id, showMessages) | nil | Instantly marks a vehicle as evaded |
M.releaseVehicle | (id, showMessages) | nil | Unfreezes a vehicle after arrest |
M.setupPursuitGameplay | (suspectId, policeIds, options) | bool | Helper to configure pursuit gameplay scenario |
M.insertProp | (propId) | nil | Adds a prop vehicle for roadblocks |
M.removeProp | (propId) | nil | Removes a prop from the roadblock pool |
M.setPropsActive | (active, reset) | nil | Activates/deactivates all police props |
M.checkRoadblock | (vehIds, rbWidth, useLength) | validIds, totalLength | Checks which vehicles fit in a roadblock |
M.placeRoadblock | (vehIds, pos, rot, placeData) | nil | Places a roadblock with vehicle transforms |
Hooks
| Hook | Purpose |
|---|---|
M.onTrafficAction | Tracks police role changes |
M.onTrafficVehicleAdded | Registers new police vehicles |
M.onTrafficVehicleRemoved | Unregisters removed police vehicles |
M.onTrafficStarted | Logs police/prop count at traffic start |
M.onTrafficStopped | Clears police vehicle table |
M.onVehicleSwitched | Transfers pursuit state when switching vehicles |
M.onVehicleResetted | Manages random suspect spawning on vehicle reset |
M.onClientEndMission | Clears state on mission end |
M.onUpdate | Main per-frame pursuit logic |
M.onSerialize / M.onDeserialized | Persistence of pursuit vars and props |
M.getPoliceVars | () |
M.setPoliceVars | (data) |
Internals
Default Pursuit Variables
| Variable | Default | Description |
|---|---|---|
scoreLevels | {100, 500, 2000} | Score thresholds for pursuit levels 1-3 |
strictness | 0.5 | Detection sensitivity for infractions |
arrestTime | 5 | Seconds stationary near police to arrest |
evadeTime | 45 | Seconds out of range to evade |
arrestRadius | 20 | Distance for arrest check |
evadeRadius | 80 | Distance for evade check |
suspectFrequency | 0.5 | Rate of random suspect spawning |
roadblockFrequency | 0.5 | Roadblock spawn rate (0 disables) |
useVisibility | true | Enable line-of-sight checks |
autoRelease | true | Auto-release after arrest countdown |
How It Works
- Sight tracking: Each frame,
sightValueaccumulates based on nearest police distance andstrictness;policeVisibleflips at 0.5 - Score escalation: Pursuit score increases from infractions and time in pursuit; crossing
scoreLevelsthresholds escalatespursuit.mode - Arrest: When both suspect and nearest police are stopped within
arrestRadiusforarrestTimeseconds, the suspect is arrested - Evade: When suspect is beyond
evadeRadiusforevadeTimeseconds, they evade - Roadblocks: At pursuit level 3, out-of-sight police are repositioned ahead of the suspect using
placeRoadblock - Random suspects: AI vehicles are periodically tagged as suspects based on
suspectFrequencyand a cooldown timer
Usage Examples
-- Start a pursuit against the player at level 2
gameplay_police.setPursuitMode(2)
-- Customize pursuit variables
gameplay_police.setPursuitVars({ arrestTime = 10, evadeTime = 30 })
-- Setup a scripted pursuit with specific vehicles
gameplay_police.setupPursuitGameplay(suspectId, {policeId1, policeId2}, { pursuitMode = 3 })
-- Check if player is being pursued
local inPursuit, isPolice = gameplay_police.isVehicleInPursuit()Notes
M.enabledfield can be set tofalseto disable all runtime police logicsetPoliceVars/getPoliceVarsare aliases forsetPursuitVars/getPursuitVars- Pursuit hooks:
onPursuitAction(targetId, action, pursuit)andonPursuitModeUpdate(targetId, {mode})
See Also
- Gameplay Achievement - Related reference
- Gameplay City - Related reference
- discover - Discover / Experience System - Related reference
- Gameplay Systems Guide - Guide
Gameplay Playmode Markers
Clusters POI data into playmode marker groups (missions, parking, zones, walking, gas stations, drift lines, etc.) and provides spatial queries via a KD-tree for efficient visibility lookups.
Gameplay Rally
Main extension for the rally gameplay system. Manages rally mission loading/unloading, co-driver timing, recce app, rally toolbox debug UI, and integration with race pathnode events.