NavigationAgent3D's velocity_computed() is called without set_velocity(new_velocity)

[venilark]

Godot version

4.1.1

System information

Windows 10

Issue description

According to the docs and the examples provided, velocity_computed(safe_velocity) should only be emitted after doing your_navigation_agent_3d.set_velocity(new_velocity) but it is being emitted all the time even with an empty script.

Steps to reproduce

Put a breakpoint inside _on_navigation_agent_3d_velocity_computed() and run the scene.

Minimal reproduction project

test_velocity_computed.zip

[smix8]

The documentation and examples for Godot 4.1+ need to be updated.

Maybe you can link all the doc pages where you found this outdated descriptions and examples and/or make a dedicated issue in the godot-documentation https://github.com/godotengine/godot-docs/issues to better track this.

Starting with Godot 4.1 the emission of the avoidance velocity signal no longer depends on a user script call to NavigationAgent.set_velocity(). As long as NavigationAgent.avoidance_enabled is true and the agent has a navigation map the agent takes part in the avoidance simulation and the callback / signal emission happens after every update.

As part of the simulation the agent affects other agents while also being affected by them. The server agent needs to be processed every update tick regardless of user script velocity input. If pushed by other agents the agent might receive a velocity in the avoidance simulation. As a result the signal is always emitted every update and the SceneTree NavigationAgent needs to be moved accordingly. If this is not done the server agent and the SceneTree NavigationAgent can not stay in sync.

If the user does not want this avoidance velocity the correct way is to disable the avoidance.
The incorrect way is to block the velocity, not use the velocity or disconnect the signal.

That said it is ok to not follow the avoidance velocity to the letter every so often for gameplay reasons. Just be aware that doing it very frequently or making large velocity jumps in unintended directions breaks the avoidance for other agents that expected the agent to not behave erratically. In case of a large jump the set_velocity_forced() function should be called as well as it resets the agents internal velocity completely.

[smix8]

The documentation and examples for Godot 4.1+ need to be updated.

Noticed now that the current master documentation for the NavigationAgent Avoidance already mentions this so closing this issue.

[lucassene]

I'm in 4.2.2-stable and just noticed that the velocity_computed signal is emitted even if avoidance_enabled is false. I'm setting it to false in both the inspector and in the _ready method (just for testing), and the signal is still being emitted.