# 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>
		
			
				
	
	
		
			186 lines
		
	
	
		
			5.6 KiB
		
	
	
	
		
			Rust
		
	
	
	
	
	
			
		
		
	
	
			186 lines
		
	
	
		
			5.6 KiB
		
	
	
	
		
			Rust
		
	
	
	
	
	
//! Shows how to iterate over combinations of query results.
 | 
						|
 | 
						|
use bevy::{pbr::AmbientLight, prelude::*};
 | 
						|
use rand::{rngs::StdRng, Rng, SeedableRng};
 | 
						|
 | 
						|
fn main() {
 | 
						|
    App::new()
 | 
						|
        .add_plugins(DefaultPlugins)
 | 
						|
        .insert_resource(AmbientLight {
 | 
						|
            brightness: 0.03,
 | 
						|
            ..default()
 | 
						|
        })
 | 
						|
        .insert_resource(ClearColor(Color::BLACK))
 | 
						|
        .add_systems(Startup, generate_bodies)
 | 
						|
        .add_systems(FixedUpdate, (interact_bodies, integrate))
 | 
						|
        .add_systems(Update, look_at_star)
 | 
						|
        .run();
 | 
						|
}
 | 
						|
 | 
						|
const GRAVITY_CONSTANT: f32 = 0.001;
 | 
						|
const NUM_BODIES: usize = 100;
 | 
						|
 | 
						|
#[derive(Component, Default)]
 | 
						|
struct Mass(f32);
 | 
						|
#[derive(Component, Default)]
 | 
						|
struct Acceleration(Vec3);
 | 
						|
#[derive(Component, Default)]
 | 
						|
struct LastPos(Vec3);
 | 
						|
#[derive(Component)]
 | 
						|
struct Star;
 | 
						|
 | 
						|
#[derive(Bundle, Default)]
 | 
						|
struct BodyBundle {
 | 
						|
    pbr: PbrBundle,
 | 
						|
    mass: Mass,
 | 
						|
    last_pos: LastPos,
 | 
						|
    acceleration: Acceleration,
 | 
						|
}
 | 
						|
 | 
						|
fn generate_bodies(
 | 
						|
    time: Res<Time>,
 | 
						|
    mut commands: Commands,
 | 
						|
    mut meshes: ResMut<Assets<Mesh>>,
 | 
						|
    mut materials: ResMut<Assets<StandardMaterial>>,
 | 
						|
) {
 | 
						|
    let mesh = meshes.add(
 | 
						|
        Mesh::try_from(shape::Icosphere {
 | 
						|
            radius: 1.0,
 | 
						|
            subdivisions: 3,
 | 
						|
        })
 | 
						|
        .unwrap(),
 | 
						|
    );
 | 
						|
 | 
						|
    let color_range = 0.5..1.0;
 | 
						|
    let vel_range = -0.5..0.5;
 | 
						|
 | 
						|
    let mut rng = StdRng::seed_from_u64(19878367467713);
 | 
						|
    for _ in 0..NUM_BODIES {
 | 
						|
        let radius: f32 = rng.gen_range(0.1..0.7);
 | 
						|
        let mass_value = radius.powi(3) * 10.;
 | 
						|
 | 
						|
        let position = Vec3::new(
 | 
						|
            rng.gen_range(-1.0..1.0),
 | 
						|
            rng.gen_range(-1.0..1.0),
 | 
						|
            rng.gen_range(-1.0..1.0),
 | 
						|
        )
 | 
						|
        .normalize()
 | 
						|
            * rng.gen_range(0.2f32..1.0).cbrt()
 | 
						|
            * 15.;
 | 
						|
 | 
						|
        commands.spawn(BodyBundle {
 | 
						|
            pbr: PbrBundle {
 | 
						|
                transform: Transform {
 | 
						|
                    translation: position,
 | 
						|
                    scale: Vec3::splat(radius),
 | 
						|
                    ..default()
 | 
						|
                },
 | 
						|
                mesh: mesh.clone(),
 | 
						|
                material: materials.add(
 | 
						|
                    Color::rgb(
 | 
						|
                        rng.gen_range(color_range.clone()),
 | 
						|
                        rng.gen_range(color_range.clone()),
 | 
						|
                        rng.gen_range(color_range.clone()),
 | 
						|
                    )
 | 
						|
                    .into(),
 | 
						|
                ),
 | 
						|
                ..default()
 | 
						|
            },
 | 
						|
            mass: Mass(mass_value),
 | 
						|
            acceleration: Acceleration(Vec3::ZERO),
 | 
						|
            last_pos: LastPos(
 | 
						|
                position
 | 
						|
                    - Vec3::new(
 | 
						|
                        rng.gen_range(vel_range.clone()),
 | 
						|
                        rng.gen_range(vel_range.clone()),
 | 
						|
                        rng.gen_range(vel_range.clone()),
 | 
						|
                    ) * time.delta_seconds(),
 | 
						|
            ),
 | 
						|
        });
 | 
						|
    }
 | 
						|
 | 
						|
    // add bigger "star" body in the center
 | 
						|
    let star_radius = 1.;
 | 
						|
    commands
 | 
						|
        .spawn((
 | 
						|
            BodyBundle {
 | 
						|
                pbr: PbrBundle {
 | 
						|
                    transform: Transform::from_scale(Vec3::splat(star_radius)),
 | 
						|
                    mesh: meshes.add(
 | 
						|
                        Mesh::try_from(shape::Icosphere {
 | 
						|
                            radius: 1.0,
 | 
						|
                            subdivisions: 5,
 | 
						|
                        })
 | 
						|
                        .unwrap(),
 | 
						|
                    ),
 | 
						|
                    material: materials.add(StandardMaterial {
 | 
						|
                        base_color: Color::ORANGE_RED,
 | 
						|
                        emissive: (Color::ORANGE_RED * 2.),
 | 
						|
                        ..default()
 | 
						|
                    }),
 | 
						|
                    ..default()
 | 
						|
                },
 | 
						|
                mass: Mass(500.0),
 | 
						|
                ..default()
 | 
						|
            },
 | 
						|
            Star,
 | 
						|
        ))
 | 
						|
        .with_children(|p| {
 | 
						|
            p.spawn(PointLightBundle {
 | 
						|
                point_light: PointLight {
 | 
						|
                    color: Color::WHITE,
 | 
						|
                    intensity: 400.0,
 | 
						|
                    range: 100.0,
 | 
						|
                    radius: star_radius,
 | 
						|
                    ..default()
 | 
						|
                },
 | 
						|
                ..default()
 | 
						|
            });
 | 
						|
        });
 | 
						|
    commands.spawn(Camera3dBundle {
 | 
						|
        transform: Transform::from_xyz(0.0, 10.5, -30.0).looking_at(Vec3::ZERO, Vec3::Y),
 | 
						|
        ..default()
 | 
						|
    });
 | 
						|
}
 | 
						|
 | 
						|
fn interact_bodies(mut query: Query<(&Mass, &GlobalTransform, &mut Acceleration)>) {
 | 
						|
    let mut iter = query.iter_combinations_mut();
 | 
						|
    while let Some([(Mass(m1), transform1, mut acc1), (Mass(m2), transform2, mut acc2)]) =
 | 
						|
        iter.fetch_next()
 | 
						|
    {
 | 
						|
        let delta = transform2.translation() - transform1.translation();
 | 
						|
        let distance_sq: f32 = delta.length_squared();
 | 
						|
 | 
						|
        let f = GRAVITY_CONSTANT / distance_sq;
 | 
						|
        let force_unit_mass = delta * f;
 | 
						|
        acc1.0 += force_unit_mass * *m2;
 | 
						|
        acc2.0 -= force_unit_mass * *m1;
 | 
						|
    }
 | 
						|
}
 | 
						|
 | 
						|
fn integrate(time: Res<Time>, mut query: Query<(&mut Acceleration, &mut Transform, &mut LastPos)>) {
 | 
						|
    let dt_sq = time.delta_seconds() * time.delta_seconds();
 | 
						|
    for (mut acceleration, mut transform, mut last_pos) in &mut query {
 | 
						|
        // verlet integration
 | 
						|
        // x(t+dt) = 2x(t) - x(t-dt) + a(t)dt^2 + O(dt^4)
 | 
						|
 | 
						|
        let new_pos = transform.translation * 2.0 - last_pos.0 + acceleration.0 * dt_sq;
 | 
						|
        acceleration.0 = Vec3::ZERO;
 | 
						|
        last_pos.0 = transform.translation;
 | 
						|
        transform.translation = new_pos;
 | 
						|
    }
 | 
						|
}
 | 
						|
 | 
						|
fn look_at_star(
 | 
						|
    mut camera: Query<&mut Transform, (With<Camera>, Without<Star>)>,
 | 
						|
    star: Query<&Transform, With<Star>>,
 | 
						|
) {
 | 
						|
    let mut camera = camera.single_mut();
 | 
						|
    let star = star.single();
 | 
						|
    let new_rotation = camera
 | 
						|
        .looking_at(star.translation, Vec3::Y)
 | 
						|
        .rotation
 | 
						|
        .lerp(camera.rotation, 0.1);
 | 
						|
    camera.rotation = new_rotation;
 | 
						|
}
 |