AI Module Reference

Module defined in `lua/vehicle/ai.lua`. This module handles high-level artificial intelligence behaviors, including pathfinding, traffic simulation, and reactive driving modes (chase, flee, follow).

Module defined in lua/vehicle/ai.lua. This module handles high-level artificial intelligence behaviors, including pathfinding, traffic simulation, and reactive driving modes (chase, flee, follow).

State Fields

Variable	Description
`cutOffDrivability`	The minimum drivability score required for a road to be considered by the AI's pathfinding logic.
`debugMode`	Controls the level of visual debugging (e.g., "off", "target", "route", "speeds", "trajectory").
`driveInLaneFlag`	Current status of the lane-keeping flag ("on"/"off").
`extAggression`	The user-controlled aggression level (0.3 to 1.0).
`extAvoidCars`	User-controlled traffic awareness setting ("on", "off", "auto").
`manualTargetName`	The name of the current waypoint being targeted in manual mode.
`mode`	The current behavioral state (e.g., "disabled", "traffic", "manual", "flee", "chase", "follow", "span", "stop"). Switching modes often affects the Main Controller.
`pullOver`	A flag that, when true, commands the AI to find a safe spot on the side of the road and stop.
`routeSpeed`	The target cruising speed in m/s.
`targetObjectID`	The vehicle ID being targeted for "chase", "follow", or "flee" modes.
`speedMode`	Current speed logic setting ("limit", "set", "legal").

Public API

Function	Signature	Description
`debugDraw`	`(focusPos)`	Visualizes AI paths, destination targets, and candidate trajectories in the 3D world.
`driveInLane`	`(value)`	Toggles lane-keeping behavior. When "on", the AI attempts to stay on the correct side of the road and respects lane data.
`driveUsingPath`	`(arg)`	Command the AI to follow predefined waypoint lists, shortest paths between targets, or raw position scripts.
`dumpCurrentRoute`	`()`	Serializes and prints the internal data structure of the current AI route to the console.
`dumpParameters`	`()`	Prints all current AI fine-tuning parameters to the console.
`getEdgeLaneConfig`	`(fromNode, toNode)`	Analyzes JBeam map data to determine the lane string (e.g., "---++") for a specific road edge. Returns `edge.inNode == fromNode and lanes or flipLanes(lanes) -- flip lanes string based on inNode data`.
`getParameters`	`()`	Returns the current table of internal AI steering and braking parameters.
`getState`	`()`	Returns the public module table (M), giving access to current modes and settings.
`isDriving`	`()`	Returns true if the AI is currently controlling the vehicle's inputs.
`laneChange`	`(plan, dist, signedDisp)`	Manually forces a lateral displacement into the current AI driving plan.
`onDeserialized`	`(v)`	Restores AI state after a vehicle reload or script deserialization.
`reset`	`()`	Fully resets AI logic, clearing the current route, internal states, and returning to "disabled" mode.
`roadNaturalContinuation`	`(wp1, wp2)`	Predicts the most likely "straight ahead" exit from a junction based on road angles and drivability.
`scriptState`	`()`	Returns status information if the AI is currently following a recorded script.
`scriptStop`	`(...)`	Immediately stops script following and returns to manual/disabled control.
`setAggression`	`(value)`	Sets the `extAggression` variable and triggers a state update.
`setAggressionMode`	`(mode)`	Configures how aggression is adjusted during chase/flee scenarios.
`setAvoidCars`	`(v)`	Toggles whether the AI should steer and brake to avoid colliding with other vehicles.
`setCutOffDrivability`	`(drivability)`	Updates the minimum road quality threshold.
`setMode`	`(mode)`	Switches the AI behavioral mode. Automatically handles JBeam reloading, map requests, and main controller freezing.
`setParameters`	`(data)`	Merges a table of fine-tuning values into the current AI configuration.
`setPath`	`(path)`	Commands the AI to follow an exact sequence of waypoints.
`setPullOver`	`(val)`	Triggers or cancels the pull-over behavior.
`setRacing`	`(val)`	Enables performance-oriented pathing and disables certain traffic filters.
`setRecoverOnCrash`	`(val)`	If true, the AI will automatically attempt to teleport back to the road if it gets stuck or crashes.
`setScriptDebugMode`	`(mode)`	Enables debug visualizations specifically for the ScriptAI submodule.
`setSpeed`	`(speed)`	Sets the target cruising speed.
`setSpeedMode`	`(speedMode)`	Configures how the AI determines its target velocity.
`setSpeedProfileMode`	`(mode)`	Selects the algorithm used to integrate acceleration limits along the path.
`setState`	`(newState)`	Bulk updates AI settings and triggers mode transitions.
`setStopPoint`	`(plan, dist, args)`	Commands the AI to come to a stop at a specific distance.
`setTarget`	`(wp)`	Sets a single navigation target and calculates a shortest-path route.
`setTargetObjectID`	`(id)`	Sets the vehicle ID to be targeted for "chase", "follow", or "flee" modes.
`setTractionModel`	`(model_index)`	Sets how the AI estimates maximum cornering and braking forces.
`setTrafficFilter`	`(val)`	Enables or disables traffic filtering logic.
`setVdraw`	`(val)`	Enables visualization of the traffic filtering radiuses.
`setVehicleDebugMode`	`(newMode)`	Bulk sets multiple debug flags.
`spanMap`	`(cutOffDrivability)`	Activates "span" mode to drive across every road on the map.
`startFollowing`	`(...)`	Begins following a recorded path script.
`startRecording`	`(recordSpeed)`	Starts recording vehicle position and velocity.
`startStopDataLog`	`(name)`	Toggles CSV data logging.
`stateChanged`	`()`	Triggers an AIStateChange UI event.
`stopFollowing`	`(...)`	Stops script playback.
`stopRecording`	`()`	Finalizes the current recording and returns the raw script data.
`toggleTrafficMode`	`()`	Quick toggle between "traffic" mode and "disabled".
`updateGFX`	`(dt)`	Main per-frame update. Handles state monitoring and input generation.

Usage Example

-- Set the AI to drive to a specific waypoint
ai.setMode("manual")
ai.setTarget("gasStation_01")
ai.setSpeed(15)  -- 15 m/s (~54 km/h)
ai.driveInLane("on")

-- Make a vehicle chase the player
ai.setMode("chase")
ai.setTargetObjectID(playerId)
ai.setAggression(0.8)

-- Put AI into traffic mode
ai.setMode("traffic")
ai.setAvoidCars("on")

-- Span the entire map (drive every road)
ai.spanMap(0.5)  -- min drivability 0.5

AI Module Reference

Module defined in `lua/vehicle/ai.lua`. This module handles high-level artificial intelligence behaviors, including pathfinding, traffic simulation, and reactive driving modes (chase, flee, follow).

Module defined in lua/vehicle/ai.lua. This module handles high-level artificial intelligence behaviors, including pathfinding, traffic simulation, and reactive driving modes (chase, flee, follow).

State Fields

Variable	Description
`cutOffDrivability`	The minimum drivability score required for a road to be considered by the AI's pathfinding logic.
`debugMode`	Controls the level of visual debugging (e.g., "off", "target", "route", "speeds", "trajectory").
`driveInLaneFlag`	Current status of the lane-keeping flag ("on"/"off").
`extAggression`	The user-controlled aggression level (0.3 to 1.0).
`extAvoidCars`	User-controlled traffic awareness setting ("on", "off", "auto").
`manualTargetName`	The name of the current waypoint being targeted in manual mode.
`mode`	The current behavioral state (e.g., "disabled", "traffic", "manual", "flee", "chase", "follow", "span", "stop"). Switching modes often affects the Main Controller.
`pullOver`	A flag that, when true, commands the AI to find a safe spot on the side of the road and stop.
`routeSpeed`	The target cruising speed in m/s.
`targetObjectID`	The vehicle ID being targeted for "chase", "follow", or "flee" modes.
`speedMode`	Current speed logic setting ("limit", "set", "legal").

Public API

Function	Signature	Description
`debugDraw`	`(focusPos)`	Visualizes AI paths, destination targets, and candidate trajectories in the 3D world.
`driveInLane`	`(value)`	Toggles lane-keeping behavior. When "on", the AI attempts to stay on the correct side of the road and respects lane data.
`driveUsingPath`	`(arg)`	Command the AI to follow predefined waypoint lists, shortest paths between targets, or raw position scripts.
`dumpCurrentRoute`	`()`	Serializes and prints the internal data structure of the current AI route to the console.
`dumpParameters`	`()`	Prints all current AI fine-tuning parameters to the console.
`getEdgeLaneConfig`	`(fromNode, toNode)`	Analyzes JBeam map data to determine the lane string (e.g., "---++") for a specific road edge. Returns `edge.inNode == fromNode and lanes or flipLanes(lanes) -- flip lanes string based on inNode data`.
`getParameters`	`()`	Returns the current table of internal AI steering and braking parameters.
`getState`	`()`	Returns the public module table (M), giving access to current modes and settings.
`isDriving`	`()`	Returns true if the AI is currently controlling the vehicle's inputs.
`laneChange`	`(plan, dist, signedDisp)`	Manually forces a lateral displacement into the current AI driving plan.
`onDeserialized`	`(v)`	Restores AI state after a vehicle reload or script deserialization.
`reset`	`()`	Fully resets AI logic, clearing the current route, internal states, and returning to "disabled" mode.
`roadNaturalContinuation`	`(wp1, wp2)`	Predicts the most likely "straight ahead" exit from a junction based on road angles and drivability.
`scriptState`	`()`	Returns status information if the AI is currently following a recorded script.
`scriptStop`	`(...)`	Immediately stops script following and returns to manual/disabled control.
`setAggression`	`(value)`	Sets the `extAggression` variable and triggers a state update.
`setAggressionMode`	`(mode)`	Configures how aggression is adjusted during chase/flee scenarios.
`setAvoidCars`	`(v)`	Toggles whether the AI should steer and brake to avoid colliding with other vehicles.
`setCutOffDrivability`	`(drivability)`	Updates the minimum road quality threshold.
`setMode`	`(mode)`	Switches the AI behavioral mode. Automatically handles JBeam reloading, map requests, and main controller freezing.
`setParameters`	`(data)`	Merges a table of fine-tuning values into the current AI configuration.
`setPath`	`(path)`	Commands the AI to follow an exact sequence of waypoints.
`setPullOver`	`(val)`	Triggers or cancels the pull-over behavior.
`setRacing`	`(val)`	Enables performance-oriented pathing and disables certain traffic filters.
`setRecoverOnCrash`	`(val)`	If true, the AI will automatically attempt to teleport back to the road if it gets stuck or crashes.
`setScriptDebugMode`	`(mode)`	Enables debug visualizations specifically for the ScriptAI submodule.
`setSpeed`	`(speed)`	Sets the target cruising speed.
`setSpeedMode`	`(speedMode)`	Configures how the AI determines its target velocity.
`setSpeedProfileMode`	`(mode)`	Selects the algorithm used to integrate acceleration limits along the path.
`setState`	`(newState)`	Bulk updates AI settings and triggers mode transitions.
`setStopPoint`	`(plan, dist, args)`	Commands the AI to come to a stop at a specific distance.
`setTarget`	`(wp)`	Sets a single navigation target and calculates a shortest-path route.
`setTargetObjectID`	`(id)`	Sets the vehicle ID to be targeted for "chase", "follow", or "flee" modes.
`setTractionModel`	`(model_index)`	Sets how the AI estimates maximum cornering and braking forces.
`setTrafficFilter`	`(val)`	Enables or disables traffic filtering logic.
`setVdraw`	`(val)`	Enables visualization of the traffic filtering radiuses.
`setVehicleDebugMode`	`(newMode)`	Bulk sets multiple debug flags.
`spanMap`	`(cutOffDrivability)`	Activates "span" mode to drive across every road on the map.
`startFollowing`	`(...)`	Begins following a recorded path script.
`startRecording`	`(recordSpeed)`	Starts recording vehicle position and velocity.
`startStopDataLog`	`(name)`	Toggles CSV data logging.
`stateChanged`	`()`	Triggers an AIStateChange UI event.
`stopFollowing`	`(...)`	Stops script playback.
`stopRecording`	`()`	Finalizes the current recording and returns the raw script data.
`toggleTrafficMode`	`()`	Quick toggle between "traffic" mode and "disabled".
`updateGFX`	`(dt)`	Main per-frame update. Handles state monitoring and input generation.

Usage Example

-- Set the AI to drive to a specific waypoint
ai.setMode("manual")
ai.setTarget("gasStation_01")
ai.setSpeed(15)  -- 15 m/s (~54 km/h)
ai.driveInLane("on")

-- Make a vehicle chase the player
ai.setMode("chase")
ai.setTargetObjectID(playerId)
ai.setAggression(0.8)

-- Put AI into traffic mode
ai.setMode("traffic")
ai.setAvoidCars("on")

-- Span the entire map (drive every road)
ai.spanMap(0.5)  -- min drivability 0.5

AI Module Reference

See Also

State Fields

Public API

Usage Example

On this page

AI Module Reference

See Also

State Fields

Public API

Usage Example

On this page