Gameplay Race Route

Extended version of `route.lua` designed for racing. Adds metadata support, callbacks for route events, original position tracking for re-routing, and merge-priority handling for close waypoints.

Extended version of route.lua designed for racing. Adds metadata support, callbacks for route events, original position tracking for re-routing, and merge-priority handling for close waypoints.

Constructor

local RaceRoute = require('gameplay/route/raceRoute')
local route = RaceRoute(removeFirst, useMapPathfinding, closeDistSquared, logTag)

Parameter	Type	Default	Description
`removeFirst`	bool?	`true`	Remove first node when on-path
`useMapPathfinding`	bool?	`true`	Use map A* pathfinding
`closeDistSquared`	number?	`1`	Squared distance for node merging

Methods

Method	Signature	Returns	Description
`setRouteParams`	`(cutOff, dirMult, penAbove, penBelow, wD, wZ)`	`nil`	Set pathfinding weights
`setupPath`	`(fromPos, toPos)`	`nil`	Create route between two positions
`setupPathMulti`	`(positions)`	`nil`	Create route through multiple vec3 positions
`setupPathMultiWithMetadata`	`(positions)`	`nil`	Create route with metadata per position
`setupPathMultiWaypoints`	`(wpList)`	`nil`	Create route using map waypoint names
`calcDistance`	`()`	`number`	Recalculate `distToTarget` for all nodes
`stepAhead`	`(stepDist, reset)`	`table?`	Get position at distance along route
`getPositionOffset`	`(currentPos)`	`idx, minDist`	Find closest segment index
`shortenPath`	`(idx)`	`nil`	Remove passed nodes from front
`trackVehicle`	`(veh)`	`idx, minDist`	Update route for vehicle position
`trackPosition`	`(pos)`	`idx, minDist`	Update route for arbitrary position
`recalculateRoute`	`(startPos)`	`nil`	Recalculate from position using remaining fixed points
`recalculateRouteWithOriginalPositions`	`(startPos)`	`nil`	Recalculate using original fixed positions
`clear`	`()`	`nil`	Clear all path data

Callbacks

route.callbacks = {
  onPointProcessed = function(point) end,        -- called for each point after setup
  shouldPointBeFixedForRecalc = function(wp) end, -- filter points during recalc
  onRouteShortened = function(removed) end,        -- when nodes are removed
  onMetadataMerge = function(i, last, cur) end,    -- custom merge logic for close nodes
}

How It Works

setupPathMultiWithMetadata builds a route through fixed positions using map.getPointToPointPath
Intermediate map nodes are inserted between fixed waypoints
Start/end of each segment are adjusted via fixStartEnd for smooth transitions
Nodes closer than closeDistSquared are merged (metadata merge via callback)
updatePathForPos tracks movement - shortens path and recalculates when off-route
originalFixedPositions preserves the initial waypoints for full re-routing

local route = RaceRoute(true, true, 1)
route:setRouteParams(0.5, 1e3)

-- Setup with metadata
route:setupPathMultiWithMetadata({
  { pos = vec3(0, 0, 0) },
  { pos = vec3(100, 0, 0), metadata = { stableId = "wp1" } },
  { pos = vec3(200, 50, 0), metadata = { stableId = "wp2" } },
})

-- Track vehicle
local idx, dist = route:trackVehicle(be:getPlayerVehicle(0))
if route.done then print("Route complete!") end

Dependencies

map - getPointToPointPath, getMap, getNodeLinkCount
extensions.hook('onRecalculatedRoute') - fires on recalculation

Function	Signature	Returns	Description
`M.getNextFixedWP`	`()`	nil	getNextFixedWP
`M.trackCamera`	`()`	nil	trackCamera

Constructor

local RaceRoute = require('gameplay/route/raceRoute')
local route = RaceRoute(removeFirst, useMapPathfinding, closeDistSquared, logTag)

Parameter	Type	Default	Description
`removeFirst`	bool?	`true`	Remove first node when on-path
`useMapPathfinding`	bool?	`true`	Use map A* pathfinding
`closeDistSquared`	number?	`1`	Squared distance for node merging

Methods

Method	Signature	Returns	Description
`setRouteParams`	`(cutOff, dirMult, penAbove, penBelow, wD, wZ)`	`nil`	Set pathfinding weights
`setupPath`	`(fromPos, toPos)`	`nil`	Create route between two positions
`setupPathMulti`	`(positions)`	`nil`	Create route through multiple vec3 positions
`setupPathMultiWithMetadata`	`(positions)`	`nil`	Create route with metadata per position
`setupPathMultiWaypoints`	`(wpList)`	`nil`	Create route using map waypoint names
`calcDistance`	`()`	`number`	Recalculate `distToTarget` for all nodes
`stepAhead`	`(stepDist, reset)`	`table?`	Get position at distance along route
`getPositionOffset`	`(currentPos)`	`idx, minDist`	Find closest segment index
`shortenPath`	`(idx)`	`nil`	Remove passed nodes from front
`trackVehicle`	`(veh)`	`idx, minDist`	Update route for vehicle position
`trackPosition`	`(pos)`	`idx, minDist`	Update route for arbitrary position
`recalculateRoute`	`(startPos)`	`nil`	Recalculate from position using remaining fixed points
`recalculateRouteWithOriginalPositions`	`(startPos)`	`nil`	Recalculate using original fixed positions
`clear`	`()`	`nil`	Clear all path data

Callbacks

route.callbacks = {
  onPointProcessed = function(point) end,        -- called for each point after setup
  shouldPointBeFixedForRecalc = function(wp) end, -- filter points during recalc
  onRouteShortened = function(removed) end,        -- when nodes are removed
  onMetadataMerge = function(i, last, cur) end,    -- custom merge logic for close nodes
}

How It Works

setupPathMultiWithMetadata builds a route through fixed positions using map.getPointToPointPath
Intermediate map nodes are inserted between fixed waypoints
Start/end of each segment are adjusted via fixStartEnd for smooth transitions
Nodes closer than closeDistSquared are merged (metadata merge via callback)
updatePathForPos tracks movement - shortens path and recalculates when off-route
originalFixedPositions preserves the initial waypoints for full re-routing

local route = RaceRoute(true, true, 1)
route:setRouteParams(0.5, 1e3)

-- Setup with metadata
route:setupPathMultiWithMetadata({
  { pos = vec3(0, 0, 0) },
  { pos = vec3(100, 0, 0), metadata = { stableId = "wp1" } },
  { pos = vec3(200, 50, 0), metadata = { stableId = "wp2" } },
})

-- Track vehicle
local idx, dist = route:trackVehicle(be:getPlayerVehicle(0))
if route.done then print("Route complete!") end

Dependencies

map - getPointToPointPath, getMap, getNodeLinkCount
extensions.hook('onRecalculatedRoute') - fires on recalculation

Function	Signature	Returns	Description
`M.getNextFixedWP`	`()`	nil	getNextFixedWP
`M.trackCamera`	`()`	nil	trackCamera

Gameplay Race Route

Constructor

Methods

Callbacks

How It Works

Dependencies

See Also

On this page

Gameplay Race Route

Constructor

Methods

Callbacks

How It Works

Dependencies

See Also

On this page