Any further questions?
Join our discordOur documentation is currently incomplete and undergoing active development. If you have any questions or feedback, please visit this forum thread.
BeamNGWaypoint is a lightweight scene object used as a named point in the level. It is commonly used by AI/navigation systems, missions, triggers, races, checkpoints, and manual navigation graph setup.
Waypoints are not visible during normal gameplay unless debug drawing is enabled or the object is selected in the World Editor.
Example BeamNGWaypoint in items.level.json:
{
"class": "BeamNGWaypoint",
"name": "wp_tunnel_01",
"position": [100, 200, 5],
"rotationMatrix": [1, 0, 0, 0, 1, 0, 0, 0, 1],
"scale": [5, 5, 5],
"drawDebug": false,
"directionalWaypoint": false,
"excludeFromMap": false
}
| Field | Type | Description |
|---|---|---|
class |
string | Must be "BeamNGWaypoint". |
name |
string | Waypoint name. Important for references from missions, scripts, and map.json. |
position |
array[3] | World position. |
rotationMatrix |
array[9] | Object rotation as a 3×3 matrix. Mainly relevant for directional waypoints. |
scale |
array[3] | Waypoint radius/size. Internally treated as uniform. |
drawDebug |
bool | Draws a debug sphere at the waypoint position. |
directionalWaypoint |
bool | Makes the waypoint directional, using a half-space/flat plane style detection instead of a simple sphere. |
excludeFromMap |
bool | Excludes this waypoint from AI/navigation map generation. |
The name field is very important.
Example:
"name": "tunnel_A_01"
Waypoint names are used by:
map.json manual navigation segmentsUse stable, descriptive names. Avoid renaming waypoints after other files already reference them.
Good examples:
wp_city_start
tunnel_A_01
bridge_exit_02
race_checkpoint_05
Avoid:
Waypoint1
test
new
abc
position defines the waypoint center in world space.
"position": [100, 200, 5]
For navigation and route tools, place the waypoint near the center of the intended path or road.
For checkpoints, place it where the vehicle should pass through.
Waypoints use scale as their effective radius/size.
"scale": [5, 5, 5]
The engine treats waypoint scaling as uniform. If one axis changes, the waypoint applies that value uniformly.
For example, setting:
"scale": [8, 1, 1]
will effectively behave as a uniform radius/scale change rather than a true non-uniform volume.
"drawDebug": true
When enabled, the waypoint draws a debug sphere in the editor/viewport.
Waypoints are also drawn when:
This is useful for checking waypoint position and size.
"directionalWaypoint": true
A directional waypoint behaves differently from a simple spherical waypoint.
When enabled, the waypoint is cut by a directional plane, giving it a directional/flat detection surface. This is useful for checkpoints where direction matters.
Directional waypoints are commonly useful for:
The waypoint orientation comes from its transform/rotation.
"excludeFromMap": true
When enabled, the waypoint is ignored by the AI/navigation map system.
Use this for waypoints that are only meant for missions or scripts and should not become navigation nodes.
Example use cases:
If excludeFromMap is false, the waypoint may be included as a manual navigation node.
BeamNGWaypoint is often used together with map.json.
Example waypoint:
{
"class": "BeamNGWaypoint",
"name": "Bridge1_A",
"position": [0, 0, 0],
"scale": [6, 6, 6],
"excludeFromMap": false
}
Example map.json segment referencing it:
{
"segments": {
"bridge1": {
"nodes": ["Bridge1_A", "Bridge1_B"],
"drivability": 1
}
}
}
If a waypoint referenced by map.json does not exist, the segment cannot be linked correctly.
excludeFromMap to true for waypoints that are referenced by map.json as navigation nodes.When a waypoint is added, removed, moved, or edited, the engine notifies the Lua map system.
This allows the navigation graph to be refreshed when editing waypoints.
Events include:
In editor workflows, map reloads may be delayed slightly to avoid rebuilding the navigation graph every frame while an object is being moved.
Waypoints are commonly used by gameplay and mission systems.
Examples:
For checkpoint-like use, set an appropriate scale so the waypoint is large enough for vehicles to pass through reliably.
For directional checkpoints, use directionalWaypoint.
When drawn, a waypoint appears as a translucent orange sphere.
If directionalWaypoint is enabled, additional debug visualization is drawn:
This helps verify the waypoint direction and trigger/checkpoint behavior.
{
"class": "BeamNGWaypoint",
"name": "road_node_01",
"position": [0, 0, 0],
"scale": [5, 5, 5],
"excludeFromMap": false
}
Use this for navigation graph nodes or map.json references.
{
"class": "BeamNGWaypoint",
"name": "mission_marker_01",
"position": [50, 100, 2],
"scale": [10, 10, 10],
"drawDebug": false,
"excludeFromMap": true
}
Use this for mission/script references that should not affect AI navigation.
{
"class": "BeamNGWaypoint",
"name": "checkpoint_01",
"position": [100, 200, 5],
"rotationMatrix": [0, -1, 0, 1, 0, 0, 0, 0, 1],
"scale": [12, 12, 12],
"directionalWaypoint": true,
"excludeFromMap": true
}
Use this for checkpoint-style logic where passing direction matters.
excludeFromMap: true for mission-only waypoints.excludeFromMap: false for waypoints used by map.json.directionalWaypoint for directional checkpoints.drawDebug only when needed.Possible causes:
drawDebug is falsePossible causes:
items.level.jsonexcludeFromMap is trueCheck:
"excludeFromMap": false
Also verify that the waypoint is connected through map.json or a valid road graph source.
Use:
"directionalWaypoint": true
and verify the waypoint rotation.
Use uniform scale:
"scale": [8, 8, 8]
Avoid non-uniform scale for waypoints.
BeamNGWaypoint is a named spatial marker used by navigation, missions, checkpoints, scripts, and editor tools.
It can act as:
map.json node referenceUse excludeFromMap to control whether it contributes to navigation, and use directionalWaypoint when direction-sensitive detection is needed.
Was this article helpful?