2024-02-03 21:40:55 +00:00
|
|
|
//! An example that illustrates how Time is handled in ECS.
|
|
|
|
|
Unify `FixedTime` and `Time` while fixing several problems (#8964)
# Objective
Current `FixedTime` and `Time` have several problems. This pull aims to
fix many of them at once.
- If there is a longer pause between app updates, time will jump forward
a lot at once and fixed time will iterate on `FixedUpdate` for a large
number of steps. If the pause is merely seconds, then this will just
mean jerkiness and possible unexpected behaviour in gameplay. If the
pause is hours/days as with OS suspend, the game will appear to freeze
until it has caught up with real time.
- If calculating a fixed step takes longer than specified fixed step
period, the game will enter a death spiral where rendering each frame
takes longer and longer due to more and more fixed step updates being
run per frame and the game appears to freeze.
- There is no way to see current fixed step elapsed time inside fixed
steps. In order to track this, the game designer needs to add a custom
system inside `FixedUpdate` that calculates elapsed or step count in a
resource.
- Access to delta time inside fixed step is `FixedStep::period` rather
than `Time::delta`. This, coupled with the issue that `Time::elapsed`
isn't available at all for fixed steps, makes it that time requiring
systems are either implemented to be run in `FixedUpdate` or `Update`,
but rarely work in both.
- Fixes #8800
- Fixes #8543
- Fixes #7439
- Fixes #5692
## Solution
- Create a generic `Time<T>` clock that has no processing logic but
which can be instantiated for multiple usages. This is also exposed for
users to add custom clocks.
- Create three standard clocks, `Time<Real>`, `Time<Virtual>` and
`Time<Fixed>`, all of which contain their individual logic.
- Create one "default" clock, which is just `Time` (or `Time<()>`),
which will be overwritten from `Time<Virtual>` on each update, and
`Time<Fixed>` inside `FixedUpdate` schedule. This way systems that do
not care specifically which time they track can work both in `Update`
and `FixedUpdate` without changes and the behaviour is intuitive.
- Add `max_delta` to virtual time update, which limits how much can be
added to virtual time by a single update. This fixes both the behaviour
after a long freeze, and also the death spiral by limiting how many
fixed timestep iterations there can be per update. Possible future work
could be adding `max_accumulator` to add a sort of "leaky bucket" time
processing to possibly smooth out jumps in time while keeping frame rate
stable.
- Many minor tweaks and clarifications to the time functions and their
documentation.
## Changelog
- `Time::raw_delta()`, `Time::raw_elapsed()` and related methods are
moved to `Time<Real>::delta()` and `Time<Real>::elapsed()` and now match
`Time` API
- `FixedTime` is now `Time<Fixed>` and matches `Time` API.
- `Time<Fixed>` default timestep is now 64 Hz, or 15625 microseconds.
- `Time` inside `FixedUpdate` now reflects fixed timestep time, making
systems portable between `Update ` and `FixedUpdate`.
- `Time::pause()`, `Time::set_relative_speed()` and related methods must
now be called as `Time<Virtual>::pause()` etc.
- There is a new `max_delta` setting in `Time<Virtual>` that limits how
much the clock can jump by a single update. The default value is 0.25
seconds.
- Removed `on_fixed_timer()` condition as `on_timer()` does the right
thing inside `FixedUpdate` now.
## Migration Guide
- Change all `Res<Time>` instances that access `raw_delta()`,
`raw_elapsed()` and related methods to `Res<Time<Real>>` and `delta()`,
`elapsed()`, etc.
- Change access to `period` from `Res<FixedTime>` to `Res<Time<Fixed>>`
and use `delta()`.
- The default timestep has been changed from 60 Hz to 64 Hz. If you wish
to restore the old behaviour, use
`app.insert_resource(Time::<Fixed>::from_hz(60.0))`.
- Change `app.insert_resource(FixedTime::new(duration))` to
`app.insert_resource(Time::<Fixed>::from_duration(duration))`
- Change `app.insert_resource(FixedTime::new_from_secs(secs))` to
`app.insert_resource(Time::<Fixed>::from_seconds(secs))`
- Change `system.on_fixed_timer(duration)` to
`system.on_timer(duration)`. Timers in systems placed in `FixedUpdate`
schedule automatically use the fixed time clock.
- Change `ResMut<Time>` calls to `pause()`, `is_paused()`,
`set_relative_speed()` and related methods to `ResMut<Time<Virtual>>`
calls. The API is the same, with the exception that `relative_speed()`
will return the actual last ste relative speed, while
`effective_relative_speed()` returns 0.0 if the time is paused and
corresponds to the speed that was set when the update for the current
frame started.
## Todo
- [x] Update pull name and description
- [x] Top level documentation on usage
- [x] Fix examples
- [x] Decide on default `max_delta` value
- [x] Decide naming of the three clocks: is `Real`, `Virtual`, `Fixed`
good?
- [x] Decide if the three clock inner structures should be in prelude
- [x] Decide on best way to configure values at startup: is manually
inserting a new clock instance okay, or should there be config struct
separately?
- [x] Fix links in docs
- [x] Decide what should be public and what not
- [x] Decide how `wrap_period` should be handled when it is changed
- [x] ~~Add toggles to disable setting the clock as default?~~ No,
separate pull if needed.
- [x] Add tests
- [x] Reformat, ensure adheres to conventions etc.
- [x] Build documentation and see that it looks correct
## Contributors
Huge thanks to @alice-i-cecile and @maniwani while building this pull.
It was a shared effort!
---------
Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
Co-authored-by: Cameron <51241057+maniwani@users.noreply.github.com>
Co-authored-by: Jerome Humbert <djeedai@gmail.com>
2023-10-16 01:57:55 +00:00
|
|
|
use bevy::prelude::*;
|
|
|
|
|
|
|
|
use std::io::{self, BufRead};
|
|
|
|
use std::time::Duration;
|
|
|
|
|
|
|
|
fn banner() {
|
|
|
|
println!("This example is meant to intuitively demonstrate how Time works in Bevy.");
|
|
|
|
println!();
|
|
|
|
println!("Time will be printed in three different schedules in the app:");
|
|
|
|
println!("- PreUpdate: real time is printed");
|
|
|
|
println!("- FixedUpdate: fixed time step time is printed, may be run zero or multiple times");
|
|
|
|
println!("- Update: virtual game time is printed");
|
|
|
|
println!();
|
|
|
|
println!("Max delta time is set to 5 seconds. Fixed timestep is set to 1 second.");
|
|
|
|
println!();
|
|
|
|
}
|
|
|
|
|
|
|
|
fn help() {
|
|
|
|
println!("The app reads commands line-by-line from standard input.");
|
|
|
|
println!();
|
|
|
|
println!("Commands:");
|
|
|
|
println!(" empty line: Run app.update() once on the Bevy App");
|
|
|
|
println!(" q: Quit the app.");
|
|
|
|
println!(" f: Set speed to fast, 2x");
|
|
|
|
println!(" n: Set speed to normal, 1x");
|
2023-10-17 04:51:07 +00:00
|
|
|
println!(" s: Set speed to slow, 0.5x");
|
Unify `FixedTime` and `Time` while fixing several problems (#8964)
# Objective
Current `FixedTime` and `Time` have several problems. This pull aims to
fix many of them at once.
- If there is a longer pause between app updates, time will jump forward
a lot at once and fixed time will iterate on `FixedUpdate` for a large
number of steps. If the pause is merely seconds, then this will just
mean jerkiness and possible unexpected behaviour in gameplay. If the
pause is hours/days as with OS suspend, the game will appear to freeze
until it has caught up with real time.
- If calculating a fixed step takes longer than specified fixed step
period, the game will enter a death spiral where rendering each frame
takes longer and longer due to more and more fixed step updates being
run per frame and the game appears to freeze.
- There is no way to see current fixed step elapsed time inside fixed
steps. In order to track this, the game designer needs to add a custom
system inside `FixedUpdate` that calculates elapsed or step count in a
resource.
- Access to delta time inside fixed step is `FixedStep::period` rather
than `Time::delta`. This, coupled with the issue that `Time::elapsed`
isn't available at all for fixed steps, makes it that time requiring
systems are either implemented to be run in `FixedUpdate` or `Update`,
but rarely work in both.
- Fixes #8800
- Fixes #8543
- Fixes #7439
- Fixes #5692
## Solution
- Create a generic `Time<T>` clock that has no processing logic but
which can be instantiated for multiple usages. This is also exposed for
users to add custom clocks.
- Create three standard clocks, `Time<Real>`, `Time<Virtual>` and
`Time<Fixed>`, all of which contain their individual logic.
- Create one "default" clock, which is just `Time` (or `Time<()>`),
which will be overwritten from `Time<Virtual>` on each update, and
`Time<Fixed>` inside `FixedUpdate` schedule. This way systems that do
not care specifically which time they track can work both in `Update`
and `FixedUpdate` without changes and the behaviour is intuitive.
- Add `max_delta` to virtual time update, which limits how much can be
added to virtual time by a single update. This fixes both the behaviour
after a long freeze, and also the death spiral by limiting how many
fixed timestep iterations there can be per update. Possible future work
could be adding `max_accumulator` to add a sort of "leaky bucket" time
processing to possibly smooth out jumps in time while keeping frame rate
stable.
- Many minor tweaks and clarifications to the time functions and their
documentation.
## Changelog
- `Time::raw_delta()`, `Time::raw_elapsed()` and related methods are
moved to `Time<Real>::delta()` and `Time<Real>::elapsed()` and now match
`Time` API
- `FixedTime` is now `Time<Fixed>` and matches `Time` API.
- `Time<Fixed>` default timestep is now 64 Hz, or 15625 microseconds.
- `Time` inside `FixedUpdate` now reflects fixed timestep time, making
systems portable between `Update ` and `FixedUpdate`.
- `Time::pause()`, `Time::set_relative_speed()` and related methods must
now be called as `Time<Virtual>::pause()` etc.
- There is a new `max_delta` setting in `Time<Virtual>` that limits how
much the clock can jump by a single update. The default value is 0.25
seconds.
- Removed `on_fixed_timer()` condition as `on_timer()` does the right
thing inside `FixedUpdate` now.
## Migration Guide
- Change all `Res<Time>` instances that access `raw_delta()`,
`raw_elapsed()` and related methods to `Res<Time<Real>>` and `delta()`,
`elapsed()`, etc.
- Change access to `period` from `Res<FixedTime>` to `Res<Time<Fixed>>`
and use `delta()`.
- The default timestep has been changed from 60 Hz to 64 Hz. If you wish
to restore the old behaviour, use
`app.insert_resource(Time::<Fixed>::from_hz(60.0))`.
- Change `app.insert_resource(FixedTime::new(duration))` to
`app.insert_resource(Time::<Fixed>::from_duration(duration))`
- Change `app.insert_resource(FixedTime::new_from_secs(secs))` to
`app.insert_resource(Time::<Fixed>::from_seconds(secs))`
- Change `system.on_fixed_timer(duration)` to
`system.on_timer(duration)`. Timers in systems placed in `FixedUpdate`
schedule automatically use the fixed time clock.
- Change `ResMut<Time>` calls to `pause()`, `is_paused()`,
`set_relative_speed()` and related methods to `ResMut<Time<Virtual>>`
calls. The API is the same, with the exception that `relative_speed()`
will return the actual last ste relative speed, while
`effective_relative_speed()` returns 0.0 if the time is paused and
corresponds to the speed that was set when the update for the current
frame started.
## Todo
- [x] Update pull name and description
- [x] Top level documentation on usage
- [x] Fix examples
- [x] Decide on default `max_delta` value
- [x] Decide naming of the three clocks: is `Real`, `Virtual`, `Fixed`
good?
- [x] Decide if the three clock inner structures should be in prelude
- [x] Decide on best way to configure values at startup: is manually
inserting a new clock instance okay, or should there be config struct
separately?
- [x] Fix links in docs
- [x] Decide what should be public and what not
- [x] Decide how `wrap_period` should be handled when it is changed
- [x] ~~Add toggles to disable setting the clock as default?~~ No,
separate pull if needed.
- [x] Add tests
- [x] Reformat, ensure adheres to conventions etc.
- [x] Build documentation and see that it looks correct
## Contributors
Huge thanks to @alice-i-cecile and @maniwani while building this pull.
It was a shared effort!
---------
Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
Co-authored-by: Cameron <51241057+maniwani@users.noreply.github.com>
Co-authored-by: Jerome Humbert <djeedai@gmail.com>
2023-10-16 01:57:55 +00:00
|
|
|
println!(" p: Pause");
|
|
|
|
println!(" u: Unpause");
|
|
|
|
}
|
|
|
|
|
|
|
|
fn runner(mut app: App) {
|
|
|
|
banner();
|
|
|
|
help();
|
|
|
|
let stdin = io::stdin();
|
|
|
|
for line in stdin.lock().lines() {
|
|
|
|
if let Err(err) = line {
|
|
|
|
println!("read err: {:#}", err);
|
|
|
|
break;
|
|
|
|
}
|
|
|
|
match line.unwrap().as_str() {
|
|
|
|
"" => {
|
|
|
|
app.update();
|
|
|
|
}
|
|
|
|
"f" => {
|
|
|
|
println!("FAST: setting relative speed to 2x");
|
|
|
|
app.world
|
|
|
|
.resource_mut::<Time<Virtual>>()
|
|
|
|
.set_relative_speed(2.0);
|
|
|
|
}
|
|
|
|
"n" => {
|
|
|
|
println!("NORMAL: setting relative speed to 1x");
|
|
|
|
app.world
|
|
|
|
.resource_mut::<Time<Virtual>>()
|
|
|
|
.set_relative_speed(1.0);
|
|
|
|
}
|
|
|
|
"s" => {
|
|
|
|
println!("SLOW: setting relative speed to 0.5x");
|
|
|
|
app.world
|
|
|
|
.resource_mut::<Time<Virtual>>()
|
|
|
|
.set_relative_speed(0.5);
|
|
|
|
}
|
|
|
|
"p" => {
|
|
|
|
println!("PAUSE: pausing virtual clock");
|
|
|
|
app.world.resource_mut::<Time<Virtual>>().pause();
|
|
|
|
}
|
|
|
|
"u" => {
|
|
|
|
println!("UNPAUSE: resuming virtual clock");
|
|
|
|
app.world.resource_mut::<Time<Virtual>>().unpause();
|
|
|
|
}
|
|
|
|
"q" => {
|
|
|
|
println!("QUITTING!");
|
|
|
|
break;
|
|
|
|
}
|
|
|
|
_ => {
|
|
|
|
help();
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
fn print_real_time(time: Res<Time<Real>>) {
|
|
|
|
println!(
|
|
|
|
"PreUpdate: this is real time clock, delta is {:?} and elapsed is {:?}",
|
|
|
|
time.delta(),
|
|
|
|
time.elapsed()
|
|
|
|
);
|
|
|
|
}
|
|
|
|
|
|
|
|
fn print_fixed_time(time: Res<Time>) {
|
|
|
|
println!(
|
|
|
|
"FixedUpdate: this is generic time clock inside fixed, delta is {:?} and elapsed is {:?}",
|
|
|
|
time.delta(),
|
|
|
|
time.elapsed()
|
|
|
|
);
|
|
|
|
}
|
|
|
|
|
|
|
|
fn print_time(time: Res<Time>) {
|
|
|
|
println!(
|
|
|
|
"Update: this is generic time clock, delta is {:?} and elapsed is {:?}",
|
|
|
|
time.delta(),
|
|
|
|
time.elapsed()
|
|
|
|
);
|
|
|
|
}
|
|
|
|
|
|
|
|
fn main() {
|
|
|
|
App::new()
|
|
|
|
.add_plugins(MinimalPlugins)
|
|
|
|
.insert_resource(Time::<Virtual>::from_max_delta(Duration::from_secs(5)))
|
|
|
|
.insert_resource(Time::<Fixed>::from_duration(Duration::from_secs(1)))
|
|
|
|
.add_systems(PreUpdate, print_real_time)
|
|
|
|
.add_systems(FixedUpdate, print_fixed_time)
|
|
|
|
.add_systems(Update, print_time)
|
|
|
|
.set_runner(runner)
|
|
|
|
.run();
|
|
|
|
}
|