 3d79dc4cdc
			
		
	
	
		3d79dc4cdc
		
			
		
	
	
	
	
		
			
			# 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>
		
			
				
	
	
		
			85 lines
		
	
	
		
			2.7 KiB
		
	
	
	
		
			Rust
		
	
	
	
	
	
			
		
		
	
	
			85 lines
		
	
	
		
			2.7 KiB
		
	
	
	
		
			Rust
		
	
	
	
	
	
| use crate::{
 | |
|     extract_resource::ExtractResource,
 | |
|     prelude::Shader,
 | |
|     render_resource::{ShaderType, UniformBuffer},
 | |
|     renderer::{RenderDevice, RenderQueue},
 | |
|     Extract, ExtractSchedule, Render, RenderApp, RenderSet,
 | |
| };
 | |
| use bevy_app::{App, Plugin};
 | |
| use bevy_asset::{load_internal_asset, Handle};
 | |
| use bevy_core::FrameCount;
 | |
| use bevy_ecs::prelude::*;
 | |
| use bevy_reflect::Reflect;
 | |
| use bevy_time::Time;
 | |
| 
 | |
| pub const GLOBALS_TYPE_HANDLE: Handle<Shader> = Handle::weak_from_u128(17924628719070609599);
 | |
| 
 | |
| pub struct GlobalsPlugin;
 | |
| 
 | |
| impl Plugin for GlobalsPlugin {
 | |
|     fn build(&self, app: &mut App) {
 | |
|         load_internal_asset!(app, GLOBALS_TYPE_HANDLE, "globals.wgsl", Shader::from_wgsl);
 | |
|         app.register_type::<GlobalsUniform>();
 | |
| 
 | |
|         if let Ok(render_app) = app.get_sub_app_mut(RenderApp) {
 | |
|             render_app
 | |
|                 .init_resource::<GlobalsBuffer>()
 | |
|                 .init_resource::<Time>()
 | |
|                 .add_systems(ExtractSchedule, (extract_frame_count, extract_time))
 | |
|                 .add_systems(
 | |
|                     Render,
 | |
|                     prepare_globals_buffer.in_set(RenderSet::PrepareResources),
 | |
|                 );
 | |
|         }
 | |
|     }
 | |
| }
 | |
| 
 | |
| fn extract_frame_count(mut commands: Commands, frame_count: Extract<Res<FrameCount>>) {
 | |
|     commands.insert_resource(**frame_count);
 | |
| }
 | |
| 
 | |
| fn extract_time(mut commands: Commands, time: Extract<Res<Time>>) {
 | |
|     commands.insert_resource(**time);
 | |
| }
 | |
| 
 | |
| /// Contains global values useful when writing shaders.
 | |
| /// Currently only contains values related to time.
 | |
| #[derive(Default, Clone, Resource, ExtractResource, Reflect, ShaderType)]
 | |
| #[reflect(Resource)]
 | |
| pub struct GlobalsUniform {
 | |
|     /// The time since startup in seconds.
 | |
|     /// Wraps to 0 after 1 hour.
 | |
|     time: f32,
 | |
|     /// The delta time since the previous frame in seconds
 | |
|     delta_time: f32,
 | |
|     /// Frame count since the start of the app.
 | |
|     /// It wraps to zero when it reaches the maximum value of a u32.
 | |
|     frame_count: u32,
 | |
|     /// WebGL2 structs must be 16 byte aligned.
 | |
|     #[cfg(all(feature = "webgl", target_arch = "wasm32"))]
 | |
|     _wasm_padding: f32,
 | |
| }
 | |
| 
 | |
| /// The buffer containing the [`GlobalsUniform`]
 | |
| #[derive(Resource, Default)]
 | |
| pub struct GlobalsBuffer {
 | |
|     pub buffer: UniformBuffer<GlobalsUniform>,
 | |
| }
 | |
| 
 | |
| fn prepare_globals_buffer(
 | |
|     render_device: Res<RenderDevice>,
 | |
|     render_queue: Res<RenderQueue>,
 | |
|     mut globals_buffer: ResMut<GlobalsBuffer>,
 | |
|     time: Res<Time>,
 | |
|     frame_count: Res<FrameCount>,
 | |
| ) {
 | |
|     let buffer = globals_buffer.buffer.get_mut();
 | |
|     buffer.time = time.elapsed_seconds_wrapped();
 | |
|     buffer.delta_time = time.delta_seconds();
 | |
|     buffer.frame_count = frame_count.0;
 | |
| 
 | |
|     globals_buffer
 | |
|         .buffer
 | |
|         .write_buffer(&render_device, &render_queue);
 | |
| }
 |