Ground Markers

Renders navigation ground-decal arrows and floating 3D arrows along a computed route path. The primary navigation display system used by freeroam GPS and missions.

Public API

Function	Signature	Description
`M.setPath`	`(wp, options?)`	Sets the navigation target. `wp` can be a waypoint name, position vec3, or array of them. Options: `step`, `color`, `cutOffDrivability`, `penaltyAboveCutoff`, `penaltyBelowCutoff`, `renderDecals`, `clearPathOnReachingTarget`.
`M.resetAll`	`()`	Clears path, decals, arrows, and all navigation state.
`M.getPathLength`	`() → number`	Returns total route distance in meters, or 0 if no path.
`M.currentlyHasTarget`	`() → bool`	Returns `true` if a navigation target is set.
`M.getTargetPos`	`() → any\|nil`	Returns the first target waypoint/position.
`M.generateRouteDecals`	`(startPos)`	Regenerates ground decals and floating arrows from current path.
`M.sendToApp`	`()`	Sends route marker positions to UI via `NavigationGroundMarkersUpdate`.
`M.setFocus`	`(...)`	Deprecated - use `setPath` instead.

Hooks

Function	Description
`M.onPreRender`	Per-frame: tracks vehicle, regenerates decals when player moves >1 m, renders decals.
`M.onClientEndMission`	Clears all navigation state.
`M.onExtensionUnloaded`	Clears all navigation state.
`M.onSerialize`	Clears arrows before serialization.
`M.onSettingsChanged`	Reacts to `showNavigationArrows` and `showNavigationGroundmarkers` setting changes.
`M.onAnyMissionChanged`	Resets on mission start/stop.

Module Fields

Field	Default	Description
`M.routePlanner`	route instance	The route planner object from `gameplay/route/route`.
`M.colorSet`	`'blue'`	Active color set name.
`M.colorSets`	table	Predefined color sets with `decals` and `arrows` RGB arrays.
`M.decalDrawingDistance`	120	Max decal rendering distance (meters).
`M.decalBlendStart`	10	Distance where decals start fading in.
`M.decalBlendEnd`	100	Distance where decals start fading out.
`M.debugPath`	Boolean. Enables debug path rendering (default `false`).
`M.decalBlendOffset`	Number. Blend offset in meters for ground decals (default `1`).
`M.decalPool`	Table. Pool of reusable decal objects.
`M.decalPoolCount`	Number. Current count of decals in the pool.
`M.dependencies`	Table. Required extensions: `{'core_groundMarkerArrows'}`

Color Sets

Set	Decal Color	Arrow Color
`blue`	`{0, 0.4, 1}`	`{0, 0.48, 0.77}`
`green`	`{0, 1, 0}`	`{0, 1, 0}`

Module State

Variable	Type	Default
`dependencies`	`table`	`{'core_groundMarkerArrows'}`
`debugPath`	`boolean`	`false`
`decalPool`	`table`	`{}` - pooled decal data objects
`decalPoolCount`	`number`	`0`
`decalDrawingDistance`	`number`	`120`
`decalBlendOffset`	`number`	`1`
`decalBlendStart`	`number`	`10`
`decalBlendEnd`	`number`	`100`
`activeDecalCount`	`number`	`0`
`endWP`	`table\|nil`	`nil` - current navigation target(s)
`stepDistance`	`number`	`3` (set via options)
`floatingArrowColor`	`table`	Arrow color RGB from active color set
`routePathTmp`	`table`	Multi-waypoint path array

Usage Example

-- Navigate to a waypoint position
core_groundMarkers.setPath(vec3(100, 200, 50), {
  step = 3,
  color = {1, 0.5, 0},
})

-- Navigate through multiple waypoints
core_groundMarkers.setPath({"wp_start", "wp_mid", "wp_end"})

-- Clear navigation
core_groundMarkers.resetAll()

Key Internals

Ground decals use Engine.Render.DynamicDecalMgr.addDecals() with pooled decal data.
Floating arrows are delegated to core_groundMarkerArrows.
Route computation uses M.routePlanner:setupPathMulti() for multi-waypoint paths.
Respects showNavigationGroundmarkers and showNavigationArrows settings.

Ground Markers

Renders navigation ground-decal arrows and floating 3D arrows along a computed route path. The primary navigation display system used by freeroam GPS and missions.

Public API

Function	Signature	Description
`M.setPath`	`(wp, options?)`	Sets the navigation target. `wp` can be a waypoint name, position vec3, or array of them. Options: `step`, `color`, `cutOffDrivability`, `penaltyAboveCutoff`, `penaltyBelowCutoff`, `renderDecals`, `clearPathOnReachingTarget`.
`M.resetAll`	`()`	Clears path, decals, arrows, and all navigation state.
`M.getPathLength`	`() → number`	Returns total route distance in meters, or 0 if no path.
`M.currentlyHasTarget`	`() → bool`	Returns `true` if a navigation target is set.
`M.getTargetPos`	`() → any\|nil`	Returns the first target waypoint/position.
`M.generateRouteDecals`	`(startPos)`	Regenerates ground decals and floating arrows from current path.
`M.sendToApp`	`()`	Sends route marker positions to UI via `NavigationGroundMarkersUpdate`.
`M.setFocus`	`(...)`	Deprecated - use `setPath` instead.

Hooks

Function	Description
`M.onPreRender`	Per-frame: tracks vehicle, regenerates decals when player moves >1 m, renders decals.
`M.onClientEndMission`	Clears all navigation state.
`M.onExtensionUnloaded`	Clears all navigation state.
`M.onSerialize`	Clears arrows before serialization.
`M.onSettingsChanged`	Reacts to `showNavigationArrows` and `showNavigationGroundmarkers` setting changes.
`M.onAnyMissionChanged`	Resets on mission start/stop.

Module Fields

Field	Default	Description
`M.routePlanner`	route instance	The route planner object from `gameplay/route/route`.
`M.colorSet`	`'blue'`	Active color set name.
`M.colorSets`	table	Predefined color sets with `decals` and `arrows` RGB arrays.
`M.decalDrawingDistance`	120	Max decal rendering distance (meters).
`M.decalBlendStart`	10	Distance where decals start fading in.
`M.decalBlendEnd`	100	Distance where decals start fading out.
`M.debugPath`	Boolean. Enables debug path rendering (default `false`).
`M.decalBlendOffset`	Number. Blend offset in meters for ground decals (default `1`).
`M.decalPool`	Table. Pool of reusable decal objects.
`M.decalPoolCount`	Number. Current count of decals in the pool.
`M.dependencies`	Table. Required extensions: `{'core_groundMarkerArrows'}`

Color Sets

Set	Decal Color	Arrow Color
`blue`	`{0, 0.4, 1}`	`{0, 0.48, 0.77}`
`green`	`{0, 1, 0}`	`{0, 1, 0}`

Module State

Variable	Type	Default
`dependencies`	`table`	`{'core_groundMarkerArrows'}`
`debugPath`	`boolean`	`false`
`decalPool`	`table`	`{}` - pooled decal data objects
`decalPoolCount`	`number`	`0`
`decalDrawingDistance`	`number`	`120`
`decalBlendOffset`	`number`	`1`
`decalBlendStart`	`number`	`10`
`decalBlendEnd`	`number`	`100`
`activeDecalCount`	`number`	`0`
`endWP`	`table\|nil`	`nil` - current navigation target(s)
`stepDistance`	`number`	`3` (set via options)
`floatingArrowColor`	`table`	Arrow color RGB from active color set
`routePathTmp`	`table`	Multi-waypoint path array

Usage Example

-- Navigate to a waypoint position
core_groundMarkers.setPath(vec3(100, 200, 50), {
  step = 3,
  color = {1, 0.5, 0},
})

-- Navigate through multiple waypoints
core_groundMarkers.setPath({"wp_start", "wp_mid", "wp_end"})

-- Clear navigation
core_groundMarkers.resetAll()

Key Internals

Ground decals use Engine.Render.DynamicDecalMgr.addDecals() with pooled decal data.
Floating arrows are delegated to core_groundMarkerArrows.
Route computation uses M.routePlanner:setupPathMulti() for multi-waypoint paths.
Respects showNavigationGroundmarkers and showNavigationArrows settings.

Ground Markers

Public API

Hooks

Module Fields

Color Sets

Module State

Usage Example

Key Internals

On this page

Ground Markers

Public API

Hooks

Module Fields

Color Sets

Module State

Usage Example

Key Internals

On this page