Race Pathnode

Object class representing a checkpoint (pathnode) along a race path. Defines a trigger sphere with optional directional normal, side padding, visibility, and recovery positions.

Constructor

local Pathnode = require('/lua/ge/extensions/gameplay/race/pathnode')
local pn = Pathnode(path, name, forceId)

Public API

Method	Signature	Returns	Description
`init`	`(path, name, forceId)`	`nil`	Initializes pathnode with defaults
`setNormal`	`(normal)`	`nil`	Sets directional normal; nil clears it
`setManual`	`(pos, radius, normal)`	`nil`	Sets manual position, radius, and normal
`setNavgraph`	`(navgraphName, fallback)`	`nil`	Sets position from navgraph node
`setNavRadiusScale`	`(scl)`	`nil`	Scales navgraph radius
`inside`	`(pos)`	`bool`	Tests if position is within trigger sphere
`intersectCorners`	`(fromCorners, toCorners)`	`hit, t`	Ray-sphere/plane intersection for vehicle corners
`getRecovery`	`()`	`startPos`	Returns linked recovery start position
`getReverseRecovery`	`()`	`startPos`	Returns linked reverse recovery start position
`getPaddedCenter`	`()`	`pos, midWidth`	Returns padded center position and width
`getSideTransforms`	`(posOffset, rotOffset, sclOffset, alignMode)`	`table`	Raycasts for side decoration transforms
`setRoutePoint` / `getRoutePoint`	`(rp)`	`rp`	Dynamic route point reference
`setStaticRoutePoint` / `getStaticRoutePoint`	`(rp)`	`rp`	Static route point reference
`onSerialize` / `onDeserialized`			Serialization support
`drawDebug`	`(drawMode, clr, extraText)`	`nil`	Debug visualization

Internals

Field	Type	Description
`path`	`Path`	Parent path reference
`id`	`number`	Unique ID within path
`mode`	`string`	`"manual"` or `"navgraph"`
`pos`	`vec3`	World position
`radius`	`number`	Trigger sphere radius
`normal`	`vec3/nil`	Directional normal
`hasNormal`	`bool`	Whether normal is active
`visible`	`bool`	Whether this is a visible checkpoint
`useAsSplit`	`bool`	Whether used as a split time point
`recovery`	`number`	ID of recovery start position
`reverseRecovery`	`number`	ID of reverse recovery start position
`sidePadding`	`vec3`	Left/right padding for gate width
`customFields`	`CustomFields`	Extensible custom data (e.g., `aiAggression`)

How It Works

A pathnode defines a checkpoint trigger as a sphere with optional directional half-plane
inside() checks distance, and if hasNormal, also checks the dot product with the normal
intersectCorners() tests ray-sphere for non-directional nodes, or ray-sphere + ray-plane for directional nodes
getSideTransforms() raycasts downward from the left and right edges to place side decorations (aligned to terrain, pathnode, or absolute)
customFields allows arbitrary per-node data (used by the editor for AI aggression values, etc.)

Usage Examples

-- Create a directional checkpoint
local pn = Pathnode(path, "Hairpin")
pn:setManual(vec3(100, 200, 0), 15, vec3(0, 1, 0))
pn.visible = true
pn.useAsSplit = true

-- Test if vehicle passed through
local hit, t = pn:intersectCorners(prevCorners, currCorners)
if hit then
  print("Checkpoint reached at t=" .. t)
end

Notes

Non-visible pathnodes act as invisible segment connectors (still track progress but don't trigger events)
navRadiusScale allows scaling the radius when using navgraph-sourced positions
customFields is initialized from gameplay/sites/customFields module

Function	Signature	Returns	Description
`M.convertRayHitToTransform`	`(hit, pRot, zOff, scl, side, alignMode)`	nil	convertRayHitToTransform

Constructor

local Pathnode = require('/lua/ge/extensions/gameplay/race/pathnode')
local pn = Pathnode(path, name, forceId)

Public API

Method	Signature	Returns	Description
`init`	`(path, name, forceId)`	`nil`	Initializes pathnode with defaults
`setNormal`	`(normal)`	`nil`	Sets directional normal; nil clears it
`setManual`	`(pos, radius, normal)`	`nil`	Sets manual position, radius, and normal
`setNavgraph`	`(navgraphName, fallback)`	`nil`	Sets position from navgraph node
`setNavRadiusScale`	`(scl)`	`nil`	Scales navgraph radius
`inside`	`(pos)`	`bool`	Tests if position is within trigger sphere
`intersectCorners`	`(fromCorners, toCorners)`	`hit, t`	Ray-sphere/plane intersection for vehicle corners
`getRecovery`	`()`	`startPos`	Returns linked recovery start position
`getReverseRecovery`	`()`	`startPos`	Returns linked reverse recovery start position
`getPaddedCenter`	`()`	`pos, midWidth`	Returns padded center position and width
`getSideTransforms`	`(posOffset, rotOffset, sclOffset, alignMode)`	`table`	Raycasts for side decoration transforms
`setRoutePoint` / `getRoutePoint`	`(rp)`	`rp`	Dynamic route point reference
`setStaticRoutePoint` / `getStaticRoutePoint`	`(rp)`	`rp`	Static route point reference
`onSerialize` / `onDeserialized`			Serialization support
`drawDebug`	`(drawMode, clr, extraText)`	`nil`	Debug visualization

Internals

Field	Type	Description
`path`	`Path`	Parent path reference
`id`	`number`	Unique ID within path
`mode`	`string`	`"manual"` or `"navgraph"`
`pos`	`vec3`	World position
`radius`	`number`	Trigger sphere radius
`normal`	`vec3/nil`	Directional normal
`hasNormal`	`bool`	Whether normal is active
`visible`	`bool`	Whether this is a visible checkpoint
`useAsSplit`	`bool`	Whether used as a split time point
`recovery`	`number`	ID of recovery start position
`reverseRecovery`	`number`	ID of reverse recovery start position
`sidePadding`	`vec3`	Left/right padding for gate width
`customFields`	`CustomFields`	Extensible custom data (e.g., `aiAggression`)

How It Works

A pathnode defines a checkpoint trigger as a sphere with optional directional half-plane
inside() checks distance, and if hasNormal, also checks the dot product with the normal
intersectCorners() tests ray-sphere for non-directional nodes, or ray-sphere + ray-plane for directional nodes
getSideTransforms() raycasts downward from the left and right edges to place side decorations (aligned to terrain, pathnode, or absolute)
customFields allows arbitrary per-node data (used by the editor for AI aggression values, etc.)

Usage Examples

-- Create a directional checkpoint
local pn = Pathnode(path, "Hairpin")
pn:setManual(vec3(100, 200, 0), 15, vec3(0, 1, 0))
pn.visible = true
pn.useAsSplit = true

-- Test if vehicle passed through
local hit, t = pn:intersectCorners(prevCorners, currCorners)
if hit then
  print("Checkpoint reached at t=" .. t)
end

Notes

Non-visible pathnodes act as invisible segment connectors (still track progress but don't trigger events)
navRadiusScale allows scaling the radius when using navgraph-sourced positions
customFields is initialized from gameplay/sites/customFields module

Function	Signature	Returns	Description
`M.convertRayHitToTransform`	`(hit, pRot, zOff, scl, side, alignMode)`	nil	convertRayHitToTransform

Race Pathnode

Constructor

Public API

Internals

How It Works

Usage Examples

Notes

See Also

On this page

Race Pathnode

Constructor

Public API

Internals

How It Works

Usage Examples

Notes

See Also

On this page