Damping for 2D and 3D is described incorrectly.

[thygrrr]

Your Godot version: 4.1.2.stable but also 4.2.dev.custombuild

Issue description: The documentation is grossly(!) incorrect in describing the linear and angular damping techniques used. It insinuates a critical spring damper function (sometimes known as smoothdamp), in particular in the language where it says:

Note: Good values are in the range 0 to 1. At value 0 objects will keep moving with the same velocity. Values greater than 1 will aim to reduce the velocity to 0 in less than a second e.g. a value of 2 will aim to reduce the velocity to 0 in half a second.

This is wrong because:

• it's actually implemented as a negative exponential damper, which behaves very differently (and poorly, because this implementation is fully tickrate dependent), this warrants special care to be taken to educate the user of pitfalls
• a value of 1 reduces the magnitude to 0 in more than the described time of 1 second, never less. In fact, it will barely have removed 65% of the speed at that time, and the rate of deceleration is shrinking)
• it's not trying "to stop in D seconds", that may have been the intent of the programmer but it's not what the function does: especially at the 0.1 default value; which will very definitely not have stopped after anywhere near 10 seconds (the sleep threshold of 0.1m/s is crossed after 23 seconds for a low starting speed of 1m/s, and 46 seconds for a speed fo 10m/s, and a whole minute at 40m/s [90 mph / 145 kph])
• 1 is not a good upper bound for this value, it can easily go as high as 10 or 20 and still make perfect sense. In no way is a value betweeen 0 and 1 "good" with this damper, in fact, it's too low for most intentes and leads to floaty physics
• technically, the 2D physics engine supports values as low as -1 and only below this value will start throwing errors.
• the tickrate dependence means that a value of d=65 will stop an object dead immediately (after a distance of 0) at a tickrate of 60 tps, but at 200 tps, it will keep moving for a timespan of a good 20 frames (speed=1) or much more (speed>1, e.g. 10), and after a definitely nonzero distance that grows significantly with higher speed. (too tired to solve the integral right now)

The source code applies the following operation:

real_t damp = 1.0 - p_step * total_linear_damp;
//...
linear_velocity *= damp;

This is, after n physics ticks, equivalent of linear_velocity = linear_velocity_start * pow(1-p_step*total_linear_damp, n)

For a value of 2 at a physics simulation frame rate of 60, this will ACTUALLY result in about 18% remaining velocity after 0.5 seconds, and depending on the starting velocity.

At different physics tick rates, this will also result in different behaviour altogether of the damping function; this would be an issue to fix in the engine repo, however; the correct way to do this would be to peg this "damp" value (I usually call it k) to a reference tick rate; calculating k = (1.0total_linear_damp/reference_rate)^(reference_rate p_step).

Without this correcion, for instance, the remaining speed difference after 0.5 seconds for 60 tps physics vs 200 tps physics is 1:1.45 (+45%))

As for the documentation, before this fix is in, this very crass diffrence in behaviours from something as inoccuous as changing the physics step time (should result in higher precision, not lower precision!) must be mentioned.

URL to the documentation page: https://docs.godotengine.org/en/stable/classes/class_rigidbody3d.html#class-rigidbody3d-property-linear-damp https://docs.godotengine.org/en/stable/classes/class_projectsettings.html#class-projectsettings-property-physics-3d-default-linear-damp https://docs.godotengine.org/en/stable/classes/class_rigidbody2d.html#class-rigidbody2d-property-linear-damp https://docs.godotengine.org/en/stable/classes/class_projectsettings.html#class-projectsettings-property-physics-2d-default-linear-damp

If you know how to fix the issue you are reporting please consider opening a pull request.

I offer to do this later today (the documentation fix).

Further notes:

• negative values are dangerous (should get an engine fix) as the resulting damping factors are never clamped against [0..1], only against 0.
• the damping is combined in different ways for 2D and 3D. Notably, this is a difference between the 3D and 2D physics where the default values are 0.0 and 0.1 respectively, leading to a default (combined) damping of 0.1 for 3D. and 0.2 for 2D

[thygrrr]

If you know how to fix the issue you are reporting please consider opening a pull request.

I offer to do this later today (the documentation fix).

[thygrrr]

These wild and floaty damper functions are also the reason why Godot physics needs that giant default linear velocity sleep threshold of 0.1 - this is offtopic for documentation but the more I read this physics code, the more I'm amazed it stayed like this for 3, 6, even 9 years in some places.

I'll see what I can do to help improve it in a proposal or two (but I'm in the camp "just integrate Jolt, and adapt physics server to its structure, breaking compatibility entirely, but at least have a clean cut").

Physics engines are hard. :) I failed at making two of them myself. ;)