Breaking changes to frame time APIs (if any)

[cspotcode]

trafficstars

From @einarf's 3.0 wishlist:

Frame time support in arcade is still very lacking

To limit scope of 3.0, let's focus on breaking API changes if any. But it requires a broader conversation about our time APIs.

Q: What breaking changes -- if any -- can we make in 3.0 to enable improved time APIs in the future?

Right now, most update and on_update functions accept a float delta_time. Should they accept a richer time object? <-- breaking Should we add a time object to Window? <-- not breaking

Past discussions:

https://github.com/pythonarcade/arcade/issues/1795 https://github.com/pythonarcade/arcade/pull/1543 https://discord.com/channels/458662222697070613/1110676843763335200

[DragonMoffon]

I don't know if detla_time should be changed away from being a float. Arcade is supposed to be beginner friendly, so leaving it as a float is for them.

[DragonMoffon]

I left a detailed comment on an implimentation idea in issue #1795. I think arcade should provide its own clock so we can get it working exactly how we want it. Though this could certainly be a 3.1 implementation.

Secondly, all this time stuff has made me want to look into a fixed update method for arcade. Not like having a fixed dt, but rather a "catch-up" method that will call enough times that the simulated time equals the time passed. It's vital for good quality physics.

[gran4]

I don't know if detla_time should be changed away from being a float. Arcade is supposed to be beginner friendly, so leaving it as a float is for them.

I agree about that. However, I am still split about arcade having its own clock. On the pro, piglet's implementation is buggy, although we must factor that it will take maintenance to create a custom clock for arcade.

[cspotcode]

The API changes for 3.0, precursor to future enhancements to time handling:

• accept a delta_time for PhysicsEnginePlatformer.update and PhysicsEngineSimple.update
• add PymunkPhysicsEngine.update alias to PymunkPhysicsEngine.step, for consistency
• remove Sprite.on_update or alias it to Sprite.update
• remove SpriteList.on_update or alias it to Sprite.update
• fix Sprite.update and SpriteList.update to:
  • accept and use delta-time
  • interpret sprite velocity as pixels per second, not pixels per frame
• rename parameter to all sprite movement functions from speed to distance since they do not accept a speed, they accept the distance to be teleported on that tick (example)

For any update methods with optional delta_time parameter, the default value comes from the current window's current delta_time. If called from outside of on_update -- keyboard event, mouse event, etc -- where the concept of delta_time does not make sense -- will raise an exception. Workaround is to pass a delta_time value.

[cspotcode]

Note to self: capture summary of conversation started here: https://discord.com/channels/458662222697070613/458662458198982676/1145119205771976724

[einarf]

We unified update and on_update and added delta time anywhere it was needed including *args, **kwargs for passing arbitrary arguments. The physicsengines however don't like variable rates at all but we do have on_fixed_update for that now