Skip to content

Proofread the navmesh pathfinding page #939

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
4ian merged 1 commit into from
Aug 11, 2026
Merged

Proofread the navmesh pathfinding page #939

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 32 additions & 24 deletions docs/gdevelop5/behaviors/nav-mesh-pathfinding/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,15 @@ title: Navigation mesh pathfinding
---
# Navigation mesh pathfinding

The **Pathfinding** behavior allows to move objects to a selected destination as well as to flag items as obstacles. Objects that are flagged as obstacles will be avoided by the moving objects.
The **navmesh pathfinding** behaviors move objects to a destination by following walkable floors and going around obstacles. They work in 2D and in 3D, and a whole crowd of characters can move at the same time while avoiding each other.

## Choose which objects to avoid
## Choose the floors and the obstacles

By using the **Obstacle for Pathfinding (navmesh-based)** [behavior](/gdevelop5/behaviors), you can flag any [object](/gdevelop5/objects) to be an obstacle.
By using the **Floor/obstacle for pathfinding (navmesh based)** [behavior](/gdevelop5/behaviors), you can flag any [object](/gdevelop5/objects) as a walkable floor, as an obstacle, or as both.

In 3D, characters walk on the flat surfaces of these objects and go around the steep ones. Add the behavior to the floors and platforms where characters must walk, and to the walls and props they must avoid.

In 2D, objects with this behavior are always obstacles. Characters can only move inside the rectangle that contains all of them, so put obstacles around the area where characters can go.

When the behavior is added to an object, some properties can be modified:

Expand All @@ -16,31 +20,31 @@ When the behavior is added to an object, some properties can be modified:
These properties are only relevant for [3D model](/gdevelop5/objects/3d-model) objects. The 2D collision mask is always used for 2D objects.

* **Shape** – You can choose between using the model shape (**Mesh**) or a bounding box (**Box**).
* **Simplified 3D model** – Models with a lot of polygons can require heavy computations. You can make a simplified version of your model with an external tool and add it in this property to make the obstacle faster to compute.
* **Simplified 3D model** – Models with a lot of polygons can require heavy computations. You can make a simplified version of your model with an external tool and set it in this property to make the obstacle faster to compute.

!!! tip

If you need objects to move in only 4 or 8 direction, you can use the [grid-based pathfinding](/gdevelop5/behaviors/pathfinding) instead.
If you need objects to move in only 4 or 8 directions, you can use the [grid-based pathfinding](/gdevelop5/behaviors/pathfinding) instead.

!!! note

[Tile maps](/gdevelop5/objects/tilemap) can also be used as obstacles: add the **Obstacle for Pathfinding (nav-mesh based)** behavior to a tile map that has collisions, and the moving objects will avoid its tiles.
[Tile maps](/gdevelop5/objects/tilemap) can also be used as obstacles: add the **Floor/obstacle for pathfinding (navmesh based)** behavior to a tile map that has collisions, and the moving objects will avoid its tiles.

## Move objects while avoiding obstacles

The **Pathfinding character (navmesh-based)** behavior allows to compute the shortest path from the object to a destination, and optionally move the object to this destination, while avoiding all objects that have the **Obstacle for Pathfinding (navmesh-based)** behavior.
The **Pathfinding character (navmesh based)** behavior computes the shortest path from the object to a destination and, optionally, moves the object along this path, while avoiding all the objects that have the **Floor/obstacle for pathfinding (navmesh based)** behavior.

After adding the behavior to the object, you can customize some properties:

![](nav-mesh-character-properties.png){ width="387" }

* **Radius** – The half-size of the character. This setting determines how close the object can move to obstacles.
* **Acceleration** – How fast the object accelerates while moving on a path.
* **Max. speed** – The maximum speed the object can reach on the path.
* **Avoidance sight range** – How far ahead the character looks to avoid other characters.
* **Acceleration** – How fast the object is going to accelerate while moving on a path.
* **Max speed** – Maximum speed the object can move on the path.
* **rotate object** – If you don't want the object to rotate while moving on the path, disable the object's rotation.
* **Rotate speed** – The speed of the object's rotation.
* **Angle offset** – In case the sprite is facing the wrong direction, you can fix it with the angle offset
* **Radius** – The radius of the character. This setting determines how close the object can move to obstacles.
* **Angle offset** – In case the sprite is facing the wrong direction, you can fix it with the angle offset.
* **Rotation speed** – The speed of the object's rotation.
* **Rotate object** – Disable it if you don't want the object to rotate while moving on the path.

!!! note

Expand All @@ -58,30 +62,34 @@ or in 3D (using the [3d raycast](/gdevelop5/extensions/raycaster3d) extension):

!!! warning

The **Move to a position** action only needs to be run once. If you run this action without any condition, it will try to compute the path at every frame. This will generate a lot of intensive computations for your device. You can add the **Destination reached** condition or use a [timer](/gdevelop5/all-features/timers-and-time) to solve this.
The **Move to a position** action only needs to be run once. If you run this action without any condition, it will compute the path at every frame, which is very demanding for the device. You can add the **Destination reached** condition or use a [timer](/gdevelop5/all-features/timers-and-time) to solve this.

!!! tip

In an isometric 2D game, set the **Y speed scale** scene property to `0.5` so that characters move slower vertically than horizontally.

## Avoid frame skipping when modifying obstacle
## Avoid frame skipping when obstacles change

When obstacles are moved, created, deleted or their behavior is deactivated or activated back, the navigation mesh is updated for the next frame and it can take more than 1/60 second which leads to frame skipping.
When obstacles are moved, created or deleted, or when their behavior is deactivated or activated again, the navigation mesh is rebuilt on the next frame. This can take more than 1/60 of a second, which leads to frame skipping.

You can reduce this side effect by:

- Making **Cell size** and **Cell depth** bigger in the scene properties.
- Setting a **Simplified 3D model** for obstacles that use a **Mesh** shape. The simplified model should have the least amount of polygons possible. For instance, a ramp often only need 5 faces.
- Making a chunk system that destroys obstacles that are faraway by batch.
- Setting a **Simplified 3D model** for obstacles that use a **Mesh** shape. The simplified model should have as few polygons as possible. For instance, a ramp often only needs 5 faces.
- Making a chunk system that destroys far away obstacles in batches.

## Troubleshoot navigation mesh generation

You can display the generated navigation mesh with the **Draw pathfinding walkable area** action.
You can display the generated navigation mesh with the **Draw pathfinding walkable area** action. The walkable area is drawn in blue.

![](nav-mesh-debug.png)

Try to modify the following scene properties and check the effects on the navigation mesh by running a preview:

* **Max. stair height** – If characters won't climb stairs, try with a greater value.
* **Slope max. angle** – If characters won't walk on steep slopes, try with a greater value.
* **Walkable depth** – If characters won't go under a roof, try with a smaller value.
* **Walkable radius** – If characters won't go on a tight way, try with a smaller value. It's usually better to keep it automatic (`-1`) and change the **Radius** on characters.
* **Max. stair height** – If characters won't climb stairs, try a greater value.
* **Slope max. angle** – If characters won't walk on steep slopes, try a greater value.
* **Walkable depth** – If characters won't go under a roof, try a smaller value.
* **Walkable radius** – If characters won't go through a narrow passage, try a smaller value. It's usually better to keep it automatic (`-1`) and change the **Radius** on characters.

![](nav-mesh-scene-properties.png){ width="382" }

Expand All @@ -100,4 +108,4 @@ Try to modify the following scene properties and check the effects on the naviga

## Reference

All actions, conditions and expressions are listed in [the nav-mesh pathfinding reference page](/gdevelop5/all-features/nav-mesh-pathfinding-behavior/reference/).
All actions, conditions and expressions are listed in [the navmesh pathfinding reference page](/gdevelop5/all-features/nav-mesh-pathfinding/reference/).
16 changes: 8 additions & 8 deletions docs/gdevelop5/behaviors/pathfinding/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,11 @@ title: Grid-based pathfinding
---
# Grid-based pathfinding

The **Pathfinding** behavior allows to move objects to a selected destination as well as to flag items as obstacles. Objects that are flagged as obstacles will be avoided by the moving objects.
The **grid-based pathfinding** behaviors move objects to a selected destination and flag items as obstacles. Objects that are flagged as obstacles will be avoided by the moving objects.

## Choose which objects to avoid: the "Obstacle for Pathfinding" behavior
## Choose which objects to avoid

By using the **Obstacle for Pathfinding (grid-based)** [behavior](/gdevelop5/behaviors), you can flag any [object](/gdevelop5/objects) to be an obstacle.
By using the **Obstacle for pathfinding (grid-based)** [behavior](/gdevelop5/behaviors), you can flag any [object](/gdevelop5/objects) to be an obstacle.

When the behavior is added to an object, some properties can be modified:

Expand All @@ -18,15 +18,15 @@ When the behavior is added to an object, some properties can be modified:

!!! tip

Obstacles may take more space than expected because a box around obstacles is used instead of the [collision mask](/gdevelop5/objects/sprite/collision-mask). The [navigation mesh pathfinding](/gdevelop5/behaviors/nav-mesh-pathfinding) can be used instead to solve this.
Obstacles may take more space than expected because a box around obstacles is used instead of the [collision mask](/gdevelop5/objects/sprite/collision-mask). You can use the [navigation mesh pathfinding](/gdevelop5/behaviors/nav-mesh-pathfinding) instead to solve this.

!!! note

[Tile maps](/gdevelop5/objects/tilemap) can also be used as obstacles: add the **Obstacle for Pathfinding (grid-based)** behavior to a tile map that has collisions, and the moving objects will avoid its tiles.
[Tile maps](/gdevelop5/objects/tilemap) can also be used as obstacles: add the **Obstacle for pathfinding (grid-based)** behavior to a tile map that has collisions, and the moving objects will avoid its tiles.

## Move objects while avoiding obstacles

The **Pathfinding character (grid-based)** behavior allows to compute the shortest path from the object to a destination, and optionally move the object to this destination, while avoiding all objects that have the **Obstacle for Pathfinding (grid-based)** behavior.
The **Pathfinding character (grid-based)** behavior computes the shortest path from the object to a destination and, optionally, moves the object along this path, while avoiding all the objects that have the **Obstacle for pathfinding (grid-based)** behavior.

After adding the behavior to the object, you can customize some properties:

Expand All @@ -45,7 +45,7 @@ After adding the behavior to the object, you can customize some properties:

!!! note

A smaller cell size implies more computations so try to still keep the size as large as possible.
A smaller cell size implies more computations, so try to keep the size as large as possible.

To initiate a pathfinding move, add the action **Move to a position** and specify the location you want the object to move to.
It will move using the characteristics defined in the behavior properties.
Expand All @@ -55,7 +55,7 @@ If you want to change how the object moves during the game, these properties can

!!! warning

The **Move to a position** action only needs to be run once. If you run this action without any condition, it will try to compute the path at every frame. This will generate a lot of intensive computations for your device. You can add the **Destination reached** condition or use a [timer](/gdevelop5/all-features/timers-and-time) to solve this.
The **Move to a position** action only needs to be run once. If you run this action without any condition, it will compute the path at every frame, which is very demanding for the device. You can add the **Destination reached** condition or use a [timer](/gdevelop5/all-features/timers-and-time) to solve this.

## Examples

Expand Down