Add time scaling and simplify fixed timestep use

[maniwani]

Objective

• Fill out Time API.
• Make using FixedTimestep less prone to user error.
• Implement time scaling.
• Improve documentation.

Solution

• Ensure the "delta" and "elapsed" methods on Time all have f32, f64, and Duration variants.
  • The f32 and f64 values are cached, but derived from the Duration value to minimize drift from rounding errors.
• Add an explicit FixedTime counterpart to Time for people to use in their fixed timestep systems.
• Remove the FixedTimesteps resource (HashMap<String, FixedTimestepState>).
  • There's only one FixedTimestepState now (only need to read it when you want to interpolate something).
  • Having more than one instance was a big footgun.
• Implement time scaling.
  • Fixed time follows scaled time in fixed increments.

Setting the step rate isn't quite as ergonomic as before but it's still pretty easy to do.

Changelist

• Renamed Time::time_since_startup to Time::elapsed_since_startup.
• Added method to get the Instant of the first Time update (there's some delay after startup).
  • Time::first_update
• Added methods to control time scaling.
  • Time::relative_speed
  • Time::set_relative_speed
• Added methods that ignore time scaling (i.e. for diagnostics).
  • Time::raw_delta
  • Time::raw_elapsed_since_startup
• Added FixedTime resource with similar API.
  • FixedTime::startup (should give same value as Time::startup)
  • FixedTime::first_update
  • FixedTime::last_update
  • FixedTime::delta
  • FixedTime::set_delta
  • FixedTime::steps_per_second
  • FixedTime::set_steps_per_second
  • FixedTime::elasped_since_startup
• Changed FixedTimestepState to be step-size agnostic so it works seamlessly with time scaling.
• Removed FixedTimesteps resource. (explained below)
  • The builtin run criteria is now just FixedTimestep::step. Set the base step size/rate through FixedTime.

Why only one built-in fixed timestep?

tl;dr

• FixedTimestep is for repeatable, deterministic behavior
• having two or more will mess up system ordering, which is non-deterministic and defeats the purpose
• no other engine has this footgun and we don't need to either
• users wanting precise time intervals need to use another thread, FixedTimestep won't work for that

---

A fixed timestep is "context" that wraps a block of systems and sort-of-but-not-really-decouples it from the main frame rate. (It's still inside the frame loop, so nothing is really decoupled.) The systems inside the block use your hardcoded dt value, and FixedTimestep just makes it so the average time between runs is dt. It'll regularly loop several times in a single frame to achieve that.

So your systems always see a constant dt while the actual dt between runs varies wildly. Great for getting consistent game physics, but useless if you wanted an actual fixed frequency (if you need that, your only option is a dedicated thread).

Anyway, FixedTimestep only works correctly when it wraps a single system/stage/sub-schedule. You can't use a bunch of them in different places without running into some subtle side effects.

For example, if you had two of FixedTimestep instances, their steps wouldn't run in a consistent order. E.g. if you had a 50ms timestep A and a 100ms timestep B, you'd probably expect them to interleave like this...

A AB A AB A AB...

...which might often be the case. However, if the app stutters even a little (e.g. one frame takes half a second), A and B would get several steps queued up, and then their order on the next frame would be completely screwed up (because of how they catch up):

AAAAAA BBB...

So a single long frame could cause very subtle bugs.

Note: You can subdivide one timestep into longer ones by counting. For example, you can get a 1 second timestep from a 100ms timestep just by counting to 10 and having run criteria detect that. That gives variable—but still coarse—rate limiting without messing up the system order.

I still left FixedTimestepState pub so people can build their own HashMap<Key, FixedTimestepState> resource if they need it for something exotic.

[djeedai]

This change seem to introduce time scaling. I'd be against doing so, if not at all, at least mixed in this PR with other changes, and instead have a proper discussion about it (apology if I missed it). Time scaling is a very delicate and complex topic, that is likely to break a lot of things, especially any game physics and animation.

[djeedai]

I can't seem to find any accumulated time / fixed time. Is there a reason for that? Unity has Time.time and Time.fixedTime, which are helpful sometimes, as not all logic can reason in terms of deltas. Can we add time() (which is I think last_update() maybe?) and fixed_time() as the accumulated time since startup of those 2 clocks? I expect if not, users will use their own accumulator, and this will end up being duplicated in several systems.

[maniwani]

I can't seem to find any accumulated time / fixed time. Is there a reason for that?

No, I just forgot.

Can we add time()?

That's time.time_since_startup(). It's the accumulated time since startup, equivalent to Unity's Time.time.

Btw, Time.time and Time.fixedTime aren't strictly decoupled. They both derive from Time.deltaTime. The former just adds it directly while the latter accumulates them to update in discrete increments. Just want to make sure that's clear.

[maniwani]

Okay, I made edits to the fn comments, got rid of the "live" getters for the raw, unscaled time, and added a field to track the "current time" of the fixed loop.

Now I'm wondering if separating the fixed stuff into a FixedTime resource might be better. No matter what, it'd be functionally coupled to Time (because of the accumulator), but a system using FixedTime::delta might express intent more clearly than Time::fixed_delta.

AFAIK you wouldn't need both time resources in a single system, so having that split can still have clean ergonomics. Well, UI systems that produce stuff consumed by the fixed-step logic might need both, idk. Something to think about.

[jamesbeilby]

Nice!
Probably FrameTimeDiagnosticsPlugin and LogDiagnosticsPlugin should use raw time?

[Guvante]

I think splitting makes sense, especially since accessing both is a code smell. The overall clock will be the latest but the fixed clock could be arbitrarily behind depending on the situation.

[maniwani]

Decided to go ahead and split things into a separate FixedTime resource, so this could probably use another review.

(Also I messed up merging changes from main and had to rebase. Sorry if anyone was depending on my branch.)

[IceSentry]

Alright, this isn't a complete review. I only looked at the time.rs file, but here's a few things I noticed.

[maniwani]

bors try

[maniwani]

The bpm example may have been a poor example, but it fits for syncing gameplay to music, even if not for coordinating talking to the audio middleware.

Ah, okay. Since you had mentioned bpm, I just assumed it was headed in the direction of "let's use FixedTimestep like a metronome", which just wouldn't work. But yeah, rhythm games and other audio-sensitive mechanics probably need their "time" driven by the audio hardware. Your understanding on how we might map game time to, like, track playback position is probably way better than mine.

In that case, I think that how the fixed timestep works is pretty orthogonal to all that, since regardless of how many there are, they would all derive from Time. Even if it turns out audio engines like Quartz use this same struct internally, I'd imagine we would expose it as a separate type/resource that has no relation to FixedTimestep so we don't confuse users about their respective roles.

Overgeneralizing, fixed updates are for physics/simulation updates, frame updates are for input/rendering.

Yes, this is my rule of thumb as well.

[alice-i-cecile]

This change seems unrelated.

[maniwani]

It was either change this to be an f32 or use time.seconds_since_startup_f64() below. Since this is a user example, I went with the choice that looked better.

[alice-i-cecile]

@maniwani could you split out the relatively uncontroversial changes from this into a smaller PR?

I think the changes to Time (except for relative_speed) can stand alone and will be easy to merge.

[maniwani]

Time scaling added by #5752. I'll add FixedTime in another PR.