Freeroam Drag Race

Manages a quarter-mile drag race against an AI opponent in freeroam mode. Handles staging lights, countdown tree, start detection, finish timing, displays, and opponent AI behavior.

Internal State

Field	Type	Description
`M.onUpdate`	varies	Assigned as `onUpdate`

Public API

Function	Signature	Returns	Description
`M.accept`	`()`	`nil`	Opens the drag race overview/config UI
`M.exit`	`()`	`nil`	Exits drag race, deletes opponent
`M.selectOpponent`	`(selection)`	`nil`	Spawns a chosen opponent vehicle
`M.selectRandomOpponent`	`(sameClass)`	`table`	Picks a random opponent config; optionally same performance class
`M.restartRace`	`()`	`nil`	Quick-resets both vehicles
`M.closeOverview`	`()`	`nil`	Closes the results overview UI
`M.enableCinematicCam`	`(value)`	`boolean`	Gets/sets cinematic camera mode
`M.enableProTree`	`(val)`	`boolean`	Gets/sets pro tree countdown mode
`M.setLevel`	`(lvl)`	`nil`	Sets the drag race level (e.g., `gridmap_v2`)
`M.resetLights`	`()`	`nil`	Hides all Christmas tree lights
`M.onExtensionUnloaded`	`()`	-
`M.onClientEndMission`	`()`	-
`M.setupPrestage`	`()`	-
`M.setupStage`	`()`	-

Hooks

Hook	Purpose
`M.onPreRender`	Runs countdown timer, staging logic, distance checks
`M.onBeamNGTrigger`	Handles trigger enter/exit events for staging and finish
`M.onVehicleSpawned`	Sets up opponent AI after spawn
`M.onVehicleResetted`	Re-positions opponent after reset
`M.onVehicleDestroyed`	Cleans up vehicle references
`M.onExtensionLoaded`	Initializes lights, displays, triggers for current level

Race Flow

Trigger Entry: Player drives into dragTrigger, dialogue appears
Opponent Selection: Player selects or random-picks an opponent vehicle
Pre-stage: AI drives to start line; pre-stage lights illuminate
Stage: Both vehicles aligned; stage lights on
Countdown: Pro tree (all ambers simultaneous) or standard tree (sequential)
Start: Green light, AI freeze released, JATO/NOS activated
Finish: endTrigger records time and speed for each lane
Results: Overview UI displays with optional cinematic camera

Jump Start Detection

If the player crosses the start line before green, red lights illuminate, race is disqualified, and opponent stops.

Display System

7-segment displays use TSStatic shape swapping (display_0.dae through display_9.dae) for time (3 decimal) and speed (2 decimal) readouts.

Supported Levels

west_coast_usa - Full cinematic cam support
gridmap_v2 - Simplified layout, no cinematic cam

Notes

Opponent AI uses setAiPath with waypoints for positioning
Speed displayed in mph (factor 2.2369)
Opponent named drag_opponent in scene tree
Supports JATO and nitrous oxide activation for AI

Additional Exports

M.startRace - (undocumented)

Internal State

Field	Type	Description
`M.onUpdate`	varies	Assigned as `onUpdate`

Public API

Function	Signature	Returns	Description
`M.accept`	`()`	`nil`	Opens the drag race overview/config UI
`M.exit`	`()`	`nil`	Exits drag race, deletes opponent
`M.selectOpponent`	`(selection)`	`nil`	Spawns a chosen opponent vehicle
`M.selectRandomOpponent`	`(sameClass)`	`table`	Picks a random opponent config; optionally same performance class
`M.restartRace`	`()`	`nil`	Quick-resets both vehicles
`M.closeOverview`	`()`	`nil`	Closes the results overview UI
`M.enableCinematicCam`	`(value)`	`boolean`	Gets/sets cinematic camera mode
`M.enableProTree`	`(val)`	`boolean`	Gets/sets pro tree countdown mode
`M.setLevel`	`(lvl)`	`nil`	Sets the drag race level (e.g., `gridmap_v2`)
`M.resetLights`	`()`	`nil`	Hides all Christmas tree lights
`M.onExtensionUnloaded`	`()`	-
`M.onClientEndMission`	`()`	-
`M.setupPrestage`	`()`	-
`M.setupStage`	`()`	-

Hooks

Hook	Purpose
`M.onPreRender`	Runs countdown timer, staging logic, distance checks
`M.onBeamNGTrigger`	Handles trigger enter/exit events for staging and finish
`M.onVehicleSpawned`	Sets up opponent AI after spawn
`M.onVehicleResetted`	Re-positions opponent after reset
`M.onVehicleDestroyed`	Cleans up vehicle references
`M.onExtensionLoaded`	Initializes lights, displays, triggers for current level