API ReferenceGE Extensionsscenario
Scenario Helper
Utility library for scenario scripting. Provides helper functions to queue Lua commands on vehicles, configure AI behavior, flash UI messages, and measure distances between scene objects.
Utility library for scenario scripting. Provides helper functions to queue Lua commands on vehicles, configure AI behavior, flash UI messages, and measure distances between scene objects.
Public API (Exports)
| Function | Signature | Description |
|---|---|---|
M.queueLuaCommand | (vehicle, command) | Sends a Lua command string to a vehicle object |
M.queueLuaCommandByName | (vehicleName, command) | Sends command to vehicle found by scenetree name |
M.getVehicleByName | (name) | Returns scenetree.findObject(name) |
M.breakBreakGroup | (vehicleName, group) | Breaks a break group on the vehicle |
M.triggerDeformGroup | (vehicleName, group) | Triggers a deform group (e.g., break a window) |
M.trackVehicle | (vehicleName, trackingName) | Enables map tracking for a vehicle |
M.setAiMode | (vehicleName, mode, targetVehicleName?) | Sets AI mode, optionally with a target vehicle |
M.setAiAggression | (vehicleName, aggression) | Sets AI aggression multiplier |
M.setAiAggressionMode | (vehicleName, aggrMode) | Sets dynamic aggression mode (e.g., "rubberBand") |
M.setAiTarget | (vehicleName, target) | Sets AI pursuit/flee target |
M.setAiAvoidCars | (vehicleName, value) | Enables/disables AI car avoidance ("on"/"off") |
M.setAiRoute | (vehicleName, waypoints) | Sets AI route from waypoint list |
M.setAiPath | (arg) | Full AI path configuration (see below) |
M.setCutOffDrivability | (vehicleName, drivability) | Sets AI road drivability cutoff |
M.flashUiMessage | (msg, duration, useBiggerText?) | Shows a flash message on screen |
M.realTimeUiDisplay | (msg) | Shows a persistent real-time display message |
M.getDistanceBetweenSceneObjects | (sceneObjectName1, sceneObjectName2) | Returns distance between two scene objects (-1 if not found) |
setAiPath - Full AI Configuration
scenario_scenariohelper.setAiPath({
vehicleName = "ai_vehicle1",
waypoints = {"wp1", "wp2", "wp3", "wp1"}, -- required
routeSpeed = 15, -- m/s speed limit
routeSpeedMode = 'limit', -- 'limit' or 'set'
driveInLane = 'on', -- stay in lane
lapCount = 3, -- circuit laps
aggression = 1.2, -- aggression multiplier (max 2)
aggressionMode = 'rubberBand', -- distance-based aggression
resetLearning = true, -- reset traction learning
avoidCars = 'on', -- car avoidance
speeds = {} -- per-waypoint speeds
})How It Works
- All AI functions serialize Lua commands as strings and send via
vehicle:queueLuaCommand() - AI state changes are also forwarded to
scenario_scenarios.updateVehicleAiState()for persistence across resets setAiPathis the most comprehensive function - saves the full configuration tocore_checkpointsfor vehicle reset restorationflashUiMessagetriggersScenarioFlashMessagewith{{msg, duration, soundCmd, bigText}}
Usage Example
local helper = require('scenario/scenariohelper')
-- Simple AI setup
helper.setAiMode("traffic_car", "span")
helper.setAiAggression("racer1", 1.5)
-- Send custom Lua to a vehicle
helper.queueLuaCommandByName("scenario_player0", "electrics.toggle_left_signal()")
-- Flash a message
helper.flashUiMessage("Get Ready!", 3, true)
-- Measure distance
local dist = helper.getDistanceBetweenSceneObjects("wp_start", "wp_finish")Key Notes
- Used extensively by
scenarios.luafor AI initialization setAiPathstores args incore_checkpointsso AI paths survive vehicle resets- All functions are synchronous (queue commands, don't wait for results)
aggressionMode = 'rubberBand'makes AI less aggressive when close to opponent
Additional Exports
M.setAiTargetVehicle- (undocumented)
See Also
- Scenario Bus Driver - Bus Route Scenario Logic - Related reference
- Scenario Damage Goal - Damage-Based Win/Fail Condition - Related reference
- Scenario Demolition Derby - Last Vehicle Moving Wins - Related reference
- Scenario System Guide - Guide
Race UI
Manages the in-game HUD for race scenarios - tracks waypoint progress, lap changes, and checkpoint time comparisons. Sends data to the UI via `guihooks.trigger`.
Scenario Engine
The main scenario engine. Manages the entire scenario lifecycle: loading, state transitions, countdown, racing, finishing, multiseat, vehicle processing, waypoint processing, and UI coordination. This