Race Path

Core class representing a complete race path. Contains sorted lists of pathnodes, segments, start positions, and pacenotes. Handles auto-configuration, AI path generation, serialization, and importing

Constructor

local Path = require('/lua/ge/extensions/gameplay/race/path')
local path = Path("My Race")

Public API

Method	Signature	Returns	Description
`init`	`(name)`	`nil`	Initializes path with sorted lists and default fields
`autoConfig`	`()`	`nil`	Builds graph of segments with successors, predecessors, visibility info
`findSegments`	`(from, to)`	`table`	Finds segments matching from/to node IDs
`getAiPath`	`(verbose)`	`aiPath, aiDetailedPath`	Generates AI navigation path from navgraph
`findStartPositionByName`	`(name)`	`startPos/nil`	Looks up a start position by name
`onSerialize`	`()`	`table`	Full serialization of path data
`onDeserialized`	`(data)`	`nil`	Restores path from serialized data
`reverse`	`()`	`nil`	Swaps start/end nodes and reverses all segments
`classify`	`()`	`table`	Returns classification: `{closed, branching, reversible, allowRollingStart}`
`fromLapConfig`	`(lapConfig, closed)`	`nil`	Imports from scenario lap config
`fromCheckpointList`	`(list, closed)`	`nil`	Imports from scene checkpoint objects
`fromTrack`	`(trackInfo, usePrefabs)`	`bool`	Imports from track info with optional prefab spawning
`recalculateSegments`	`()`	`nil`	Rebuilds segments from sequential pathnodes
`getLastPathnode`	`()`	`pathnode`	Returns the last sorted pathnode
`drawDebug`	`(drawMode)`	`nil`	Draws all pathnodes, segments, start positions, pacenotes
`getNextUniqueIdentifier`	`()`	`number`	Returns next unique ID for child objects

Internals

Field	Type	Description
`pathnodes`	`sortedList`	Managed list of pathnode objects
`segments`	`sortedList`	Managed list of segment objects
`startPositions`	`sortedList`	Managed list of start position objects
`pacenotes`	`sortedList`	Managed list of pacenote objects
`startNode`	`number`	ID of the starting pathnode
`endNode`	`number`	ID of the ending pathnode
`defaultStartPosition`	`number`	ID of the default start position
`config`	`table`	Auto-generated graph config (see below)
`defaultLaps`	`number`	Default number of laps
`hideMission`	`bool`	Whether to hide the mission marker

Config Structure (from `autoConfig`)

Field	Type	Description
`startNode`	`number`	Start pathnode ID
`startSegments`	`table`	Segment IDs starting from start node
`finalSegments`	`table`	Segment IDs that end a lap
`graph`	`table`	Per-segment graph data (successors, predecessors, visibility)
`closed`	`bool`	Whether path loops back to start
`branching`	`bool`	Whether path has branches
`linearSegments`	`table`	Ordered pathnode IDs for non-branching paths
`segmentToPacenotes`	`table`	Map of segment ID → pacenote IDs

How It Works

Path contains sorted lists of pathnodes, segments, start positions, and pacenotes
autoConfig() builds a directed graph from segments, computing successors, predecessors, and visibility coloring
Visibility "coloring" propagates backwards from visible pathnodes to mark which upcoming checkpoints are visible from each segment
getAiPath() converts pathnodes to navgraph waypoints for AI driving using map.findClosestRoad
Import methods (fromTrack, fromLapConfig, etc.) convert legacy formats into the path structure

Usage Examples

-- Create and configure a path
local path = Path("Circuit Race")
local pn1 = path.pathnodes:create("Start")
pn1:setManual(vec3(0,0,0), 10, vec3(0,1,0))
local pn2 = path.pathnodes:create("Turn 1")
pn2:setManual(vec3(100,0,0), 10, nil)

local seg = path.segments:create("Seg 1")
seg:setFrom(pn1.id)
seg:setTo(pn2.id)

path:autoConfig()

-- Save to file
jsonWriteFile("myrace.path.json", path:onSerialize(), true)

Notes

Child objects (pathnodes, segments, etc.) use sortedList from gameplay/util/sortedList
The _uid counter provides unique IDs across all child object types
Prefab fields (prefabs, forwardPrefabs, reversePrefabs) store paths to decorative prefabs

Function	Signature	Returns	Description
`M.drawAiRouteDebug`	`()`	nil	drawAiRouteDebug
`M.copy`	`()`	nil	copy
`M.init`	`(name)`	nil	init

Constructor

local Path = require('/lua/ge/extensions/gameplay/race/path')
local path = Path("My Race")

Public API

Method	Signature	Returns	Description
`init`	`(name)`	`nil`	Initializes path with sorted lists and default fields
`autoConfig`	`()`	`nil`	Builds graph of segments with successors, predecessors, visibility info
`findSegments`	`(from, to)`	`table`	Finds segments matching from/to node IDs
`getAiPath`	`(verbose)`	`aiPath, aiDetailedPath`	Generates AI navigation path from navgraph
`findStartPositionByName`	`(name)`	`startPos/nil`	Looks up a start position by name
`onSerialize`	`()`	`table`	Full serialization of path data
`onDeserialized`	`(data)`	`nil`	Restores path from serialized data
`reverse`	`()`	`nil`	Swaps start/end nodes and reverses all segments
`classify`	`()`	`table`	Returns classification: `{closed, branching, reversible, allowRollingStart}`
`fromLapConfig`	`(lapConfig, closed)`	`nil`	Imports from scenario lap config
`fromCheckpointList`	`(list, closed)`	`nil`	Imports from scene checkpoint objects
`fromTrack`	`(trackInfo, usePrefabs)`	`bool`	Imports from track info with optional prefab spawning
`recalculateSegments`	`()`	`nil`	Rebuilds segments from sequential pathnodes
`getLastPathnode`	`()`	`pathnode`	Returns the last sorted pathnode
`drawDebug`	`(drawMode)`	`nil`	Draws all pathnodes, segments, start positions, pacenotes
`getNextUniqueIdentifier`	`()`	`number`	Returns next unique ID for child objects

Internals

Field	Type	Description
`pathnodes`	`sortedList`	Managed list of pathnode objects
`segments`	`sortedList`	Managed list of segment objects
`startPositions`	`sortedList`	Managed list of start position objects
`pacenotes`	`sortedList`	Managed list of pacenote objects
`startNode`	`number`	ID of the starting pathnode
`endNode`	`number`	ID of the ending pathnode
`defaultStartPosition`	`number`	ID of the default start position
`config`	`table`	Auto-generated graph config (see below)
`defaultLaps`	`number`	Default number of laps
`hideMission`	`bool`	Whether to hide the mission marker

Config Structure (from `autoConfig`)

Field	Type	Description
`startNode`	`number`	Start pathnode ID
`startSegments`	`table`	Segment IDs starting from start node
`finalSegments`	`table`	Segment IDs that end a lap
`graph`	`table`	Per-segment graph data (successors, predecessors, visibility)
`closed`	`bool`	Whether path loops back to start
`branching`	`bool`	Whether path has branches
`linearSegments`	`table`	Ordered pathnode IDs for non-branching paths
`segmentToPacenotes`	`table`	Map of segment ID → pacenote IDs

How It Works

Path contains sorted lists of pathnodes, segments, start positions, and pacenotes
autoConfig() builds a directed graph from segments, computing successors, predecessors, and visibility coloring
Visibility "coloring" propagates backwards from visible pathnodes to mark which upcoming checkpoints are visible from each segment
getAiPath() converts pathnodes to navgraph waypoints for AI driving using map.findClosestRoad
Import methods (fromTrack, fromLapConfig, etc.) convert legacy formats into the path structure

Usage Examples

-- Create and configure a path
local path = Path("Circuit Race")
local pn1 = path.pathnodes:create("Start")
pn1:setManual(vec3(0,0,0), 10, vec3(0,1,0))
local pn2 = path.pathnodes:create("Turn 1")
pn2:setManual(vec3(100,0,0), 10, nil)

local seg = path.segments:create("Seg 1")
seg:setFrom(pn1.id)
seg:setTo(pn2.id)

path:autoConfig()

-- Save to file
jsonWriteFile("myrace.path.json", path:onSerialize(), true)

Notes

Child objects (pathnodes, segments, etc.) use sortedList from gameplay/util/sortedList
The _uid counter provides unique IDs across all child object types
Prefab fields (prefabs, forwardPrefabs, reversePrefabs) store paths to decorative prefabs

Function	Signature	Returns	Description
`M.drawAiRouteDebug`	`()`	nil	drawAiRouteDebug
`M.copy`	`()`	nil	copy
`M.init`	`(name)`	nil	init

Race Path

Constructor

Public API

Internals

Config Structure (from `autoConfig`)

How It Works

Usage Examples

Notes

See Also

On this page

Race Path

Constructor

Public API

Internals

Config Structure (from `autoConfig`)

How It Works

Usage Examples

Notes

See Also

On this page