Unify physics time APIs with Time<Physics> and Time<Substeps>

[Jondolf]

Objective

Currently, bevy_xpbd has the DeltaTime, SubDeltaTime, PhysicsTimestep, PhysicsTimescale and PhysicsLoop resources for managing logic related to time and scheduling. Having so many separate resources can be confusing and inconvenient for users.

The DeltaTime and SubDeltaTime resources also create a contextual divide into two system groups: those that run in the PhysicsSchedule and those that run in the SubstepSchedule. However, a lot of systems aren't necessarily tied to a specific schedule in functionality; what if you wanted to run position integration outside of the substepping loop? It would be better if all of these systems had a shared time resource that could just be interpreted differently based on the schedule.

Solution

Replace DeltaTime, SubDeltaTime, PhysicsTimestep, PhysicsTimescale and PhysicsLoop with Time<Physics> and Time<Substeps> using the new time API in Bevy 0.12.

The generic Time resource is replaced by Time<Physics> in the PhysicsSchedule and Time<Substeps> in the SubstepSchedule. This means that systems are now agnostic over the time resource used, which also reduces cognitive overhead for users, as they can just use Time instead of e.g. DeltaTime in the PhysicsSchedule.

The timestep is still configurable, as Physics contains an TimestepMode enum like the old PhysicsTimestep. To match Bevy's APIs, the timestep also uses a Duration instead of a single scalar value. Physics has helper methods like fixed_hz, fixed_once_hz and variable to reduce the boilerplate a bit.

// Before
app.insert_resource(PhysicsTimestep::Fixed(1.0 / 144.0));

// After
app.insert_resource(Time::new_with(Physics::fixed_hz(1.0 / 144.0)));

The physics loop is now also controlled using Time<Physics> and its properties paused and relative_speed.

---

Migration guide

• Replace every DeltaTime in PhysicsSchedule and every SubDeltaTime in SubstepSchedule with Time, elsewhere explicitly use Time<Physics> and Time<Substep>
• When advancing physics manually, instead of setting DeltaTime, advance the Time<Physics> clock using time.advance_by(...)
• Replace PhysicsTimestep with Time::new_with(Physics::FooBar(...))
• Replace PhysicsLoop::pause/resume with Time::<Physics>::pause/unpause
• Replace PhysicsLoop::step with advancing the physics clock using Time::<Physics>::advance_by
• Replace PhysicsTimescale usage with Time::<Physics>::with/set_relative_speed

Todo

• Add code examples to documentation
• Verify that all timesteps function correctly

Future work

It'd be nice to use Time<Virtual> and Time<Fixed> directly, but this has limitations that currently make it not viable.