Rally Driveline V3

Third-generation driveline system for rally stages. Loads recorded driveline data from recce sessions, simplifies it using RDP algorithm, generates smooth Catmull-Rom splines, and produces final drive

Constructor

local DrivelineV3 = require('/lua/ge/extensions/gameplay/rally/driveline/drivelineV3')
local dv3 = DrivelineV3(missionDir)

Public API

Method	Signature	Returns	Description
`init`	`(missionDir)`	`nil`	Initializes with mission directory
`loadFromRecording`	`()`	`bool`	Full pipeline: load → simplify → smooth → finalize
`loadRecceRecording`	`()`	`bool`	Loads raw driveline points from recce recording
`loadFinalDrivelineFromFile`	`()`	`bool`	Loads a pre-saved final driveline JSON
`convertDrivelineToSpline`	`(drivelinePoints?)`	`bool`	RDP-simplifies points into a spline structure
`updateSplineGeometry`	`()`	`bool`	Computes smooth Catmull-Rom subdivisions
`createDrivelineFromSpline`	`()`	`bool`	Generates final points from spline
`getFinalPointList`	`()`	`PointList/nil`	Returns final points as a PointList object
`deepCopySpline`	`()`	`table/nil`	Deep copies spline data (for undo/redo)
`getSpeedLimitKph`	`()`	`number`	Returns configured speed limit (default 100)
`calculateDistanceBetweenPoints`	`(p1, p2)`	`number`	Distance along the final driveline between two world positions
`renderRawDriveline`	`()`	`nil`	Draws raw points as pink cylinders
`renderSmoothCurve`	`()`	`nil`	Draws subdivided spline as blue cylinders
`renderFinalDriveline`	`()`	`nil`	Draws final points as red cylinders
`renderSpline`	`(selectedNodeIdx)`	`nil`	Draws editable spline nodes

Internals

Field	Type	Description
`missionDir`	`string`	Mission directory path
`rawDrivelinePoints`	`table/nil`	Original recorded driveline points
`spline`	`table/nil`	Editable spline structure (nodes, widths, normals, subdivisions)
`finalDrivelinePoints`	`table/nil`	Generated output points
`simplificationTolerance`	`number`	RDP tolerance (default 1.0)
`properties.speedLimitKph`	`number`	Speed limit for the driveline (default 100)

Processing Pipeline

Load: loadRecceRecording() reads recorded points from the mission's recce directory
Simplify: convertDrivelineToSpline() applies RDP (Ramer-Douglas-Peucker) algorithm to reduce node count while preserving shape
Smooth: updateSplineGeometry() runs geom.catmullRomRaycast to generate subdivided points with terrain conformance
Finalize: createDrivelineFromSpline() converts subdivided positions to full point structures with quaternions, normals, and linked-list relationships

Final Point Structure

Each final point contains: pos, quat, ts, normal, prev, next, id, pacenoteDistances, cachedPacenotes

How It Works

Raw driveline is recorded during recce (driving the stage slowly)
RDP simplification reduces thousands of points to key shape-defining nodes
Catmull-Rom spline interpolation creates smooth subdivisions between nodes
Terrain raycasting (catmullRomRaycast) snaps subdivisions to ground height
Final points get direction quaternions and terrain-aligned normals
The result can be saved as JSON or used directly by DrivelineRoute

Usage Examples

-- Full loading pipeline
local dv3 = DrivelineV3("/levels/west_coast/rally/stage1/")
if dv3:loadFromRecording() then
  local pointList = dv3:getFinalPointList()
  -- use with DrivelineRoute
end

-- Load pre-saved final driveline
local dv3 = DrivelineV3(missionDir)
if dv3:loadFinalDrivelineFromFile() then
  -- ready to use
end

-- Calculate distance between two positions along the driveline
local dist = dv3:calculateDistanceBetweenPoints(posA, posB)

Notes

Uses editor/toolUtilities/rdp for RDP simplification
Uses editor/toolUtilities/geom for Catmull-Rom spline computation
Default simplification tolerance: 1.0 meters (configurable)
Minimum spline divisions: 10; minimum spacing: 2.0 meters
calculateDistanceBetweenPoints uses xnorm projection for sub-segment precision
Rendering methods use debugDrawer for visualization in the editor

Function	Signature	Returns	Description
`M.createDrivelinePointsFromPositions`	`(positions)`	nil	createDrivelinePointsFromPositions

Constructor

local DrivelineV3 = require('/lua/ge/extensions/gameplay/rally/driveline/drivelineV3')
local dv3 = DrivelineV3(missionDir)

Public API

Method	Signature	Returns	Description
`init`	`(missionDir)`	`nil`	Initializes with mission directory
`loadFromRecording`	`()`	`bool`	Full pipeline: load → simplify → smooth → finalize
`loadRecceRecording`	`()`	`bool`	Loads raw driveline points from recce recording
`loadFinalDrivelineFromFile`	`()`	`bool`	Loads a pre-saved final driveline JSON
`convertDrivelineToSpline`	`(drivelinePoints?)`	`bool`	RDP-simplifies points into a spline structure
`updateSplineGeometry`	`()`	`bool`	Computes smooth Catmull-Rom subdivisions
`createDrivelineFromSpline`	`()`	`bool`	Generates final points from spline
`getFinalPointList`	`()`	`PointList/nil`	Returns final points as a PointList object
`deepCopySpline`	`()`	`table/nil`	Deep copies spline data (for undo/redo)
`getSpeedLimitKph`	`()`	`number`	Returns configured speed limit (default 100)
`calculateDistanceBetweenPoints`	`(p1, p2)`	`number`	Distance along the final driveline between two world positions
`renderRawDriveline`	`()`	`nil`	Draws raw points as pink cylinders
`renderSmoothCurve`	`()`	`nil`	Draws subdivided spline as blue cylinders
`renderFinalDriveline`	`()`	`nil`	Draws final points as red cylinders
`renderSpline`	`(selectedNodeIdx)`	`nil`	Draws editable spline nodes

Internals

Field	Type	Description
`missionDir`	`string`	Mission directory path
`rawDrivelinePoints`	`table/nil`	Original recorded driveline points
`spline`	`table/nil`	Editable spline structure (nodes, widths, normals, subdivisions)
`finalDrivelinePoints`	`table/nil`	Generated output points
`simplificationTolerance`	`number`	RDP tolerance (default 1.0)
`properties.speedLimitKph`	`number`	Speed limit for the driveline (default 100)

Processing Pipeline

Load: loadRecceRecording() reads recorded points from the mission's recce directory
Simplify: convertDrivelineToSpline() applies RDP (Ramer-Douglas-Peucker) algorithm to reduce node count while preserving shape
Smooth: updateSplineGeometry() runs geom.catmullRomRaycast to generate subdivided points with terrain conformance
Finalize: createDrivelineFromSpline() converts subdivided positions to full point structures with quaternions, normals, and linked-list relationships

Final Point Structure

Each final point contains: pos, quat, ts, normal, prev, next, id, pacenoteDistances, cachedPacenotes

How It Works

Raw driveline is recorded during recce (driving the stage slowly)
RDP simplification reduces thousands of points to key shape-defining nodes
Catmull-Rom spline interpolation creates smooth subdivisions between nodes
Terrain raycasting (catmullRomRaycast) snaps subdivisions to ground height
Final points get direction quaternions and terrain-aligned normals
The result can be saved as JSON or used directly by DrivelineRoute

Usage Examples

-- Full loading pipeline
local dv3 = DrivelineV3("/levels/west_coast/rally/stage1/")
if dv3:loadFromRecording() then
  local pointList = dv3:getFinalPointList()
  -- use with DrivelineRoute
end

-- Load pre-saved final driveline
local dv3 = DrivelineV3(missionDir)
if dv3:loadFinalDrivelineFromFile() then
  -- ready to use
end

-- Calculate distance between two positions along the driveline
local dist = dv3:calculateDistanceBetweenPoints(posA, posB)

Notes

Uses editor/toolUtilities/rdp for RDP simplification
Uses editor/toolUtilities/geom for Catmull-Rom spline computation
Default simplification tolerance: 1.0 meters (configurable)
Minimum spline divisions: 10; minimum spacing: 2.0 meters
calculateDistanceBetweenPoints uses xnorm projection for sub-segment precision
Rendering methods use debugDrawer for visualization in the editor

Function	Signature	Returns	Description
`M.createDrivelinePointsFromPositions`	`(positions)`	nil	createDrivelinePointsFromPositions

Rally Driveline V3

Constructor

Public API

Internals

Processing Pipeline

Final Point Structure

How It Works

Usage Examples

Notes

See Also

On this page

Rally Driveline V3

Constructor

Public API

Internals

Processing Pipeline

Final Point Structure

How It Works

Usage Examples

Notes

See Also

On this page