Rally Driveline Route

The core driveline routing system for rally stages. Merges race pathnodes and pacenote waypoints into a navigable route, tracks the vehicle's position along it, and triggers pacenote audio events base

Constructor

local DrivelineRoute = require('/lua/ge/extensions/gameplay/rally/driveline/drivelineRoute')
local dr = DrivelineRoute()

Public API

Method	Signature	Returns	Description
`init`	`()`	`nil`	Initializes with default state and callback slots
`isLoaded`	`()`	`bool`	Whether the route has been successfully loaded
`loadRouteFromRecordedDriveline`	`(racePath, notebookPath, pointsList)`	`bool`	Loads and builds route from recorded driveline points
`recalculate`	`()`	`bool`	Recalculates the dynamic route from current vehicle position
`setRecalcNeeded`	`()`	`nil`	Flags that a recalculation is needed (e.g., after vehicle reset)
`setVehicleTracker`	`(vehicleTracker)`	`nil`	Sets the vehicle position/speed tracker
`getPacenotes`	`()`	`table`	Returns sorted pacenote list
`getNextPacenote`	`()`	`pacenote`	Returns the next pacenote to evaluate
`getNearestRoutePoint`	`(pos)`	`vec3/nil`	Finds the closest point on the static route
`onUpdate`	`(dtReal, dtSim, dtRaw)`	`nil`	Per-frame update: tracks position, evaluates pacenote triggers
`setTrackMouseLikeVehicle`	`(val)`	`nil`	Enables mouse-based positioning for debugging

Callback Slots

Callback	Parameters	Description
`onPacenoteCsDynamicHit`	`(pacenote, shouldTriggerAudio)`	Dynamic timing trigger (speed-based)
`onPacenoteCsImmediateHit`	`(pacenote, shouldTriggerAudio)`	Immediate trigger (first pacenote)
`onPacenoteCsStaticHit`	`(pacenote, shouldTriggerAudio)`	At corner start position
`onPacenoteCeStaticHit`	`(pacenote, shouldTriggerAudio)`	At corner end position
`onPacenoteCsOffsetHit`	`(pacenote, shouldTriggerAudio, offset)`	At meter offset from CS
`onPacenoteCeOffsetHit`	`(pacenote, shouldTriggerAudio, offset)`	At meter offset from CE
`onPacenoteCornerPercentHit`	`(pacenote, shouldTriggerAudio, percent)`	At percentage between CS and CE

Internals

Route Loading Pipeline (`loadRouteFromRecordedDriveline`)

Race setup: autoConfig() on the race path
Pre-route points: Driveline recording points become the base route
KD-tree build: 3D KD-tree for fast closest-segment lookups
Insert start/stop positions: Start position and stop zone markers
Insert race pathnodes: Checkpoints and split points
Re-index KD-tree: Rebuild after race pathnode insertions
Insert pacenote waypoints: Corner start (CS) and corner end (CE) waypoints
Trim route: Remove points before start and after stop zone
Build dynamic route: raceRoute with metadata merge callbacks
Build static route: Non-recalculating copy for distance lookups
Build static KD-tree: For fast nearest-point queries
Calculate splits: Distance data for each race pathnode
Cache pacenote lengths: Distance between CS and CE for each pacenote

Dynamic Audio Triggering

The evaluatePacenoteEvents method calculates when to trigger audio:

Dynamic trigger: timeToCS < (baseCodriverTiming + scaledAudioLen) × speedMultiplier
- Speed multiplier scales from 1.0 (at 50 mph) to 1.5 (at 90 mph)
- Audio length is scaled by 0.75 factor
Static triggers: Fire when vehicle distance to the point < 0.1m threshold
Events tracked per pacenote: csDynamicHit, csImmediateHit, csStaticHit, ceStaticHit, meter offsets, corner percentages

Key Parameters

Parameter	Default	Description
`defaultCodriverTiming`	`3.0s`	Fallback timing if setting unavailable
`audioLenScaler`	`0.75`	Scales audio length for threshold calculation
`scaleMinSpeedMph`	`50`	Speed where multiplier begins
`scaleMaxSpeedMph`	`90`	Speed where multiplier maxes out
`minMultiplier`	`1.0`	Minimum speed multiplier
`maxMultiplier`	`1.5`	Maximum speed multiplier
`minEvalSpeedMph`	`1.0`	Minimum speed to evaluate pacenotes
`minWaitTimeSinceRecalc`	`2.0s`	Cooldown after recalculation

How It Works

Route is built by inserting race pathnodes and pacenote waypoints into a driveline point list using KD-tree nearest-segment lookup
Two routes are maintained: a dynamic route that shortens as the vehicle progresses, and a static route for fixed distance lookups
On each frame, the vehicle position is tracked along the dynamic route
Pacenotes are evaluated in a sliding window (current + 5 lookbehind)
Audio triggering uses time-to-corner-start based on current speed, with speed-dependent scaling
On vehicle reset, setRecalcNeeded() triggers full route recalculation with event state recovery

Notes

Uses kdtreepoint3d for 3D nearest-point queries and raceRoute for route tracking
Point insertion uses closest line segment detection with a search window of 4
Metadata merge callbacks prevent losing race pathnode or pacenote data when route points are combined
The shouldPointBeFixedForRecalc callback ensures important route points survive recalculation
Split data provides distance labels (km) for UI display

Function	Signature	Returns	Description
`M.enableTriggerLogging`	`()`	nil	enableTriggerLogging
`M.getPacenoteEvent`	`(pacenote)`	nil	getPacenoteEvent
`M.callPacenoteEventCallback`	`(callbackFn, ...)`	nil	callPacenoteEventCallback
`M.getSpeed`	`()`	nil	getSpeed
`M.getPosition`	`()`	nil	getPosition
`M.evaluatePacenotesWindow`	`(speedMs)`	nil	evaluatePacenotesWindow
`M.enableTrackMouseLikeVehicleMovement`	`(val)`	nil	enableTrackMouseLikeVehicleMovement
`M.updateMouseLikeVehicle`	`(dtSim)`	nil	updateMouseLikeVehicle
`M.getFinishLineDistOffset`	`()`	nil	getFinishLineDistOffset
`M.getDistanceMeters`	`()`	nil	getDistanceMeters
`M.getDistanceKmString`	`()`	nil	getDistanceKmString
`M.getRaceCompletionData`	`()`	nil	getRaceCompletionData
`M.getPointDistanceFromStartMeters`	`(point)`	nil	getPointDistanceFromStartMeters
`M.getPointDistanceFromStartKm`	`(point)`	nil	getPointDistanceFromStartKm
`M.drawDebugDrivelineRoute`	`(drawRoute, drawPacenotes, drawLimit, monochrome, static, drawHiddenPathnodes, drawRoutePathnodes, drawPointI, drawPointMetadata, drawPacenoteText)`	nil	drawDebugDrivelineRoute
`M.drawDebugDrivelineRouteShort`	`(dist)`	nil	drawDebugDrivelineRouteShort
`M.buildElevationProfile`	`()`	nil	buildElevationProfile

Constructor

local DrivelineRoute = require('/lua/ge/extensions/gameplay/rally/driveline/drivelineRoute')
local dr = DrivelineRoute()

Public API

Method	Signature	Returns	Description
`init`	`()`	`nil`	Initializes with default state and callback slots
`isLoaded`	`()`	`bool`	Whether the route has been successfully loaded
`loadRouteFromRecordedDriveline`	`(racePath, notebookPath, pointsList)`	`bool`	Loads and builds route from recorded driveline points
`recalculate`	`()`	`bool`	Recalculates the dynamic route from current vehicle position
`setRecalcNeeded`	`()`	`nil`	Flags that a recalculation is needed (e.g., after vehicle reset)
`setVehicleTracker`	`(vehicleTracker)`	`nil`	Sets the vehicle position/speed tracker
`getPacenotes`	`()`	`table`	Returns sorted pacenote list
`getNextPacenote`	`()`	`pacenote`	Returns the next pacenote to evaluate
`getNearestRoutePoint`	`(pos)`	`vec3/nil`	Finds the closest point on the static route
`onUpdate`	`(dtReal, dtSim, dtRaw)`	`nil`	Per-frame update: tracks position, evaluates pacenote triggers
`setTrackMouseLikeVehicle`	`(val)`	`nil`	Enables mouse-based positioning for debugging

Callback Slots

Callback	Parameters	Description
`onPacenoteCsDynamicHit`	`(pacenote, shouldTriggerAudio)`	Dynamic timing trigger (speed-based)
`onPacenoteCsImmediateHit`	`(pacenote, shouldTriggerAudio)`	Immediate trigger (first pacenote)
`onPacenoteCsStaticHit`	`(pacenote, shouldTriggerAudio)`	At corner start position
`onPacenoteCeStaticHit`	`(pacenote, shouldTriggerAudio)`	At corner end position
`onPacenoteCsOffsetHit`	`(pacenote, shouldTriggerAudio, offset)`	At meter offset from CS
`onPacenoteCeOffsetHit`	`(pacenote, shouldTriggerAudio, offset)`	At meter offset from CE
`onPacenoteCornerPercentHit`	`(pacenote, shouldTriggerAudio, percent)`	At percentage between CS and CE

Internals

Route Loading Pipeline (`loadRouteFromRecordedDriveline`)

Race setup: autoConfig() on the race path
Pre-route points: Driveline recording points become the base route
KD-tree build: 3D KD-tree for fast closest-segment lookups
Insert start/stop positions: Start position and stop zone markers
Insert race pathnodes: Checkpoints and split points
Re-index KD-tree: Rebuild after race pathnode insertions
Insert pacenote waypoints: Corner start (CS) and corner end (CE) waypoints
Trim route: Remove points before start and after stop zone
Build dynamic route: raceRoute with metadata merge callbacks
Build static route: Non-recalculating copy for distance lookups
Build static KD-tree: For fast nearest-point queries
Calculate splits: Distance data for each race pathnode
Cache pacenote lengths: Distance between CS and CE for each pacenote

Dynamic Audio Triggering

The evaluatePacenoteEvents method calculates when to trigger audio:

Dynamic trigger: timeToCS < (baseCodriverTiming + scaledAudioLen) × speedMultiplier
- Speed multiplier scales from 1.0 (at 50 mph) to 1.5 (at 90 mph)
- Audio length is scaled by 0.75 factor
Static triggers: Fire when vehicle distance to the point < 0.1m threshold
Events tracked per pacenote: csDynamicHit, csImmediateHit, csStaticHit, ceStaticHit, meter offsets, corner percentages

Key Parameters

Parameter	Default	Description
`defaultCodriverTiming`	`3.0s`	Fallback timing if setting unavailable
`audioLenScaler`	`0.75`	Scales audio length for threshold calculation
`scaleMinSpeedMph`	`50`	Speed where multiplier begins
`scaleMaxSpeedMph`	`90`	Speed where multiplier maxes out
`minMultiplier`	`1.0`	Minimum speed multiplier
`maxMultiplier`	`1.5`	Maximum speed multiplier
`minEvalSpeedMph`	`1.0`	Minimum speed to evaluate pacenotes
`minWaitTimeSinceRecalc`	`2.0s`	Cooldown after recalculation

How It Works

Route is built by inserting race pathnodes and pacenote waypoints into a driveline point list using KD-tree nearest-segment lookup
Two routes are maintained: a dynamic route that shortens as the vehicle progresses, and a static route for fixed distance lookups
On each frame, the vehicle position is tracked along the dynamic route
Pacenotes are evaluated in a sliding window (current + 5 lookbehind)
Audio triggering uses time-to-corner-start based on current speed, with speed-dependent scaling
On vehicle reset, setRecalcNeeded() triggers full route recalculation with event state recovery

Notes

Uses kdtreepoint3d for 3D nearest-point queries and raceRoute for route tracking
Point insertion uses closest line segment detection with a search window of 4
Metadata merge callbacks prevent losing race pathnode or pacenote data when route points are combined
The shouldPointBeFixedForRecalc callback ensures important route points survive recalculation
Split data provides distance labels (km) for UI display

Function	Signature	Returns	Description
`M.enableTriggerLogging`	`()`	nil	enableTriggerLogging
`M.getPacenoteEvent`	`(pacenote)`	nil	getPacenoteEvent
`M.callPacenoteEventCallback`	`(callbackFn, ...)`	nil	callPacenoteEventCallback
`M.getSpeed`	`()`	nil	getSpeed
`M.getPosition`	`()`	nil	getPosition
`M.evaluatePacenotesWindow`	`(speedMs)`	nil	evaluatePacenotesWindow
`M.enableTrackMouseLikeVehicleMovement`	`(val)`	nil	enableTrackMouseLikeVehicleMovement
`M.updateMouseLikeVehicle`	`(dtSim)`	nil	updateMouseLikeVehicle
`M.getFinishLineDistOffset`	`()`	nil	getFinishLineDistOffset
`M.getDistanceMeters`	`()`	nil	getDistanceMeters
`M.getDistanceKmString`	`()`	nil	getDistanceKmString
`M.getRaceCompletionData`	`()`	nil	getRaceCompletionData
`M.getPointDistanceFromStartMeters`	`(point)`	nil	getPointDistanceFromStartMeters
`M.getPointDistanceFromStartKm`	`(point)`	nil	getPointDistanceFromStartKm
`M.drawDebugDrivelineRoute`	`(drawRoute, drawPacenotes, drawLimit, monochrome, static, drawHiddenPathnodes, drawRoutePathnodes, drawPointI, drawPointMetadata, drawPacenoteText)`	nil	drawDebugDrivelineRoute
`M.drawDebugDrivelineRouteShort`	`(dist)`	nil	drawDebugDrivelineRouteShort
`M.buildElevationProfile`	`()`	nil	buildElevationProfile

Rally Driveline Route

Constructor

Public API

Callback Slots

Internals

Route Loading Pipeline (`loadRouteFromRecordedDriveline`)

Dynamic Audio Triggering

Key Parameters

How It Works

Notes

See Also

On this page

Rally Driveline Route

Constructor

Public API

Callback Slots

Internals

Route Loading Pipeline (`loadRouteFromRecordedDriveline`)

Dynamic Audio Triggering

Key Parameters

How It Works

Notes

See Also

On this page