Simplify dt handling in space.step() to encourage a stable dt value

[viblo]

Many users that are not experienced with physics engines will believe that the best design is to pass in the frame time (the actual time that passed since the last time step was called) as dt in space.step(dt). However, in Pymunk (and others) its much better if the dt value used is stable, a fixed value. With a stable dt it will be easier for the engine to create a realistic and stable simulation.

However, as of Pymunk 6.x the API of Pymunk does not make this clear, the user should pass in a dt value every time step(dt) is called, and can easy get the impression that it is good if it changes according to actual time passed.

I have two ideas:

1. Add a default for dt of 1/60.0: def step(self, dt=1/60.0). Minimal changes to the API, should help the user a bit.
2. Move the dt value to a property on the Space. So you do space = pymunk.Space(dt=1/60), or later `space.dt = 1/60), just like how you deal with gravity.

[aatle]

In my opinion, there is no good library-end solution to this; users must code responsibly and use a stable dt.
I think the current API is best.

For the first idea, a default dt can lead to delta time bugs when a user has their FPS anything other than 60. I think most users would also just pass in dt anyway, because of that. The default value makes the code more implicit but doesn't make the code simpler.

The second idea would solve the mentioned issue but has a subtle yet significant consequence.
Essentially, pymunk doesn't have the "authority" or power to independently store a persistent delta time. (Only the game loop can.)
By storing the dt, the pymunk space partially assumes responsibility for delta time; it is no longer just a consumer. But this conflicts with the game loop's control of the delta time, even for a fixed dt: the space has to stay synchronized with the game loop which can be inconvenient or defeat the purpose of space.dt, and potentially leads to stale or duplicate data.
(if this is unclear, I can explain further)

This is probably why every physics library I've seen so far is documented to work better with a stable dt but still requires an explicit dt for every step call.
The burden lies on the user to avoid the issue.

[viblo]

The 1/60 default idea I got from Rapier, a Rust physics library. But you are right of course that it wont fit all cases.

Another thought is if some ideas from https://gafferongames.com/post/fix_your_timestep/ could be included somehow... but not easy when its final solution require you to interpolate the rendered positions/velocities..

There could be some warning if dt varies between frames maybe? On the other hand you might want to actually vary it and then they will be very annoying.

Regardless, the reason I put this up here is that I do think this is one of the things easiest to get wrong, and when it goes wrong its difficult to solve.

[aatle]

The fixed-step, variable-dt game loop is also out of scope of pymunk; the program must implement it.

A runtime warning is definitely too disruptive.

Indeed, this issue goes for all physics engines, but as there is no suitable fix, the library just has to assume that the user is knowledgeable: user's responsibility.
The only improvement I can see is to turn the notice in the space.step() into a Note so it is more obvious.

Libraries like pybox2d, panda3d, nova physics, pychrono, and of course chipmunk: they all just document this and then take an explicit dt for stepping.
The only libraries I would imagine do this differently are game engines that have more control.